| // 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; |
| |
| // Data used for logging info sent to the host. |
| optional LogData log_data = 12; |
| |
| // Please use CL numbers you own for extension numbers. |
| extensions 10000 to max; |
| |
| // Deprecated field IDs. |
| reserved 6, 9, 8; |
| } |
| |
| // 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; |
| } |