blob: 0baa7eb95fcc8c8818e9af1c7d964ccba6d6844d [file] [log] [blame]
// Copyright 2018 The Feed Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto2";
package search.now.ui.piet;
option optimize_for=LITE_RUNTIME;
import "src/main/proto/search/now/ui/piet/actions.proto";
import "src/main/proto/search/now/ui/piet/elements.proto";
import "src/main/proto/search/now/ui/piet/log_data.proto";
import "src/main/proto/search/now/ui/piet/media_queries.proto";
import "src/main/proto/search/now/ui/piet/styles.proto";
option java_package = "com.google.search.now.ui.piet";
option java_outer_classname = "PietProto";
option cc_enable_arenas = true;
// Piet • [INTERNAL LINK] • [INTERNAL LINK]
//
// Piet is a declarative UI rendering spec with a set of cross-platform
// libraries that can render the same exact proto on Android, iOS and Web to
// generate similar visual layouts.
// DOCS
//
// Before using Piet, make sure to read the following docs:
// - Core Design: [INTERNAL LINK]
// - Client Support: [INTERNAL LINK]
// - Error Handling: [INTERNAL LINK]
//
// IDs
//
// Every field that ends in `_id` must be unique within its containing message.
// Examples:
// - Style.style_id must be unique within a Stylesheet.
// - Stylesheet.stylesheet_id must be unique within PietSharedState.
// - Template.template_id must be unique within PietSharedState.
// - BindingRef.binding_id must be unique within its containing Template.
// etc.
//
// TAG
//
// Fields named `tag` are open-ended and never used for any processing. Servers,
// Clients, and Hosts may use these fields as they see fit, mostly for debugging
// purposes.
//
// COLORS
//
// - Although colors are expressed as 32-bit ARGB (Alpha, Red, Green, Blue)
// channels, not all platforms may support alpha.
// - Colors have no meaningful default and must be specified explicitly wherever
// needed.
// - If a platform requires an alternate representation for convenience, (e.g.
// CSS-style #000000 format), such representations should be segregated in
// platform-specific support protos, e.g. `piet_web_support.proto`.
//
// DIMENSIONS
//
// - All measurements are in dp (display pixels) unless otherwise specified.
// - Negative values are officially unsupported, though they may happen to work
// in certain circumstances. Unless explicitly documented otherwise, do not
// assume that they will continue to work the same way across multiple client
// implementations or versions.
//
// -----------------------------------------------------------------------------
// A Frame is the top-level UI construct in Piet. Every layout is contained
// within a Frame. Each frame defines the contents displayed to the user as a
// single view, which may contain a complex set of child views.
// NextId: 13
message Frame {
// A string tag for the frame, currently used for debugging purposes. Need not
// be unique.
optional string tag = 1;
// UI Elements in a Frame use a Stylesheet to resolve the Styles that define
// their appearance. This Stylesheet can either be provided directly inlined
// in every Frame, or via a lookup in the global shared state in
// PietSharedState.
//
// NOTE: Styles from this Stylesheet are not available to Templates; they can
// only be used by Elements defined directly in this Frame itself, such as
// non-template Content, or ElementLists bound to Templates. This limitation
// is a performance optimization that makes view recycling efficient. This
// applies to both the inlined Stylesheet and stylesheet_id's referencing a
// PietSharedState Stylesheet.
//
// DEPRECATED: Use stylesheets field instead. If that field is set, these
// deprecated fields will be ignored.
oneof frame_style_scope {
// If this is defined, the Stylesheet for the Frame is found by a lookup
// in PietSharedState.Stylesheets. If the stylesheet_id cannot be found,
// ERR_MISSING_STYLESHEET is raised.
// DEPRECATED: use stylesheets field instead.
string stylesheet_id = 2 [deprecated = true];
// A local Stylesheet that provides styles used by Elements in this Frame.
// DEPRECATED: use stylesheets field instead.
Stylesheet stylesheet = 3 [deprecated = true];
}
// Defines the Stylesheets used by this Frame.
//
// NOTE: Styles from this Stylesheet are not available to Templates; they can
// only be used by Elements defined directly in this Frame itself, such as
// non-template Content. This limitation is a performance optimization that
// makes view recycling efficient. This applies to both the inlined
// Stylesheets and stylesheet_id's referencing a PietSharedState Stylesheet.
optional Stylesheets stylesheets = 11;
// Styles applied to this Frame. If any style_ids cannot be found,
// ERR_MISSING_STYLES is raised.
optional StyleIdsStack style_references = 4;
// Templates that are available for use within the scope of this Frame.
repeated Template templates = 5;
// Content that makes up this Frame.
//
// There are a few differences in the use of Content here vs. elsewhere:
// - These Contents are arranged in a vertical list layout.
// - Bindings are not supported in these Contents, since there is no
// BindingContext available at the Frame level.
// - These Contents support sharding: each of these Contents can be recycled
// as it leaves the screen, to reduce memory usage when scrolling a very
// long Frame.
repeated Content contents = 10;
// Actions associated with the full Frame.
optional Actions actions = 7;
// A Base64-encoded serialized ClickTrackingCGI proto that identifies the
// logged Visual Element corresponding to this Frame.
optional string ved = 8 [deprecated = true];
//
optional LogData log_data = 12;
// Please use CL numbers you own for extension numbers.
extensions 10000 to max;
// Deprecated field IDs.
reserved 6, 9;
}
// UI Elements in a Frame or Template use a Stylesheet to resolve the Styles
// that define their appearance. The Stylesheet is constructed by combining
// Styles from any Stylesheets referenced here; Stylesheets can by directly
// inlined, or referenced from the global shared state in PietSharedState.
// Piet will report ERR_DUPLICATE_STYLE if multiple Styles across any of the
// Stylesheets have the same style id (after MediaQueryCondition filtering).
message Stylesheets {
// Stylesheets to be fetched from the global PietSharedState.
// If a stylesheet_id cannot be found, ERR_MISSING_STYLESHEET is raised.
repeated string stylesheet_ids = 1;
// Inline Stylesheets. These can be filtered by MediaQueryCondition.
repeated Stylesheet stylesheets = 2;
}
// A set of Styles; each Style must have a style_id that is unique within this
// Stylesheet. If the same style_id is found twice, ERR_DUPLICATE_STYLES is
// raised. Stylesheet is scoped to Frames or Templates. When a UI element uses a
// Style, it is looked up in the Stylesheet within scope. If the style cannot be
// found, ERR_MISSING_STYLES is raised.
message Stylesheet {
// A string uniquely identifying this Stylesheet within the PietSharedState in
// which it is used. If two Stylesheets with the same stylesheet_id are found
// in a PietSharedState, ERR_DUPLICATE_STYLESHEET is raised. This
// `stylesheet_id` is used to select this Stylesheet using
// Frame.stylesheet_id.
optional string stylesheet_id = 1;
// Styles available in this Stylesheet.
repeated Style styles = 2;
// This Stylesheet is only eligible to be used if *all* the conditions
// enumerated below are met. If even one condition is unsatisfied,
// this Stylesheet is treated as if it was never sent, which may cause
// ERR_STYLESHEET_NOT_FOUND.
repeated MediaQueryCondition conditions = 3;
}
// A Template defines a reusable ElementList. The content is data-bound from
// Bindings in the TemplateInvocation. Templates allow consistent creation of
// elements using bound data. For example, table rows with different values, or
// GridCells with different data values.
message Template {
// A unique identifier for this template. If two Templates with the same
// template_id are found in a PietSharedState, ERR_DUPLICATE_TEMPLATE is
// raised.
optional string template_id = 1;
// The Stylesheet used within this Template's scope.
// - Styles from the Frame CANNOT be referenced from within a Template.
// - Styles from the PietSharedState CAN be referenced, only if the
// stylesheet_id is defined by the Template.
//
// DEPRECATED: Use stylesheets field instead. If that field is set, these
// deprecated fields will be ignored.
oneof template_stylesheet {
// If defined, the Stylesheet for this Template is looked up in
// PietSharedState.Stylesheets. If the stylesheet_id cannot be found,
// ERR_MISSING_STYLESHEET is raised.
// DEPRECATED: use stylesheets field instead.
string stylesheet_id = 2 [deprecated = true];
// A local Stylesheet. Styles in this Stylesheet will only be available to
// elements defined in this Template.
// DEPRECATED: use stylesheets field instead.
Stylesheet stylesheet = 3 [deprecated = true];
}
// The Stylesheets used within this Template's scope.
// - Styles from the Frame CANNOT be referenced from within a Template.
// - Styles from the PietSharedState CAN be referenced, only if the
// stylesheet_id is defined by the Template.
optional Stylesheets stylesheets = 11;
// Styles applied to all child views of this Template.
optional StyleIdsStack child_default_style_ids = 4 [deprecated = true];
// Content defined by this Template.
optional Element element = 6;
// This Template is only eligible to be used if *all* the conditions
// enumerated below are met. If even one condition is unsatisfied, this
// Template is treated as if it was never sent, which may cause
// ERR_TEMPLATE_NOT_FOUND.
repeated MediaQueryCondition conditions = 8;
// Please use CL numbers you own for extension numbers.
extensions 10000 to max;
// Deprecated field IDs.
reserved 5;
}
// State shared among multiple Frame instances. This is a top-level object,
// defined outside individual Frame instances.
message PietSharedState {
// Stylesheet definitions that can be reused across Frames.
// Stylesheet.stylesheet_id must be unique within the List, otherwise
// ERR_DUPLICATE_STYLESHEET is raised.
repeated Stylesheet stylesheets = 1;
// Template definitions that can be reused across Frames. Each Template may
// define their own Stylesheet, or can access a Stylesheet defined in this
// PietSharedState. If two or more Templates with the same template_id are
// found, then ERR_DUPLICATE_TEMPLATE is raised.
repeated Template templates = 2;
}