src/main/proto/search/now/ui/piet/styles.proto

// 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/binding_refs.proto";
import "src/main/proto/search/now/ui/piet/gradients.proto";
import "src/main/proto/search/now/ui/piet/images.proto";
import "src/main/proto/search/now/ui/piet/media_queries.proto";
import "src/main/proto/search/now/ui/piet/rounded_corners.proto";
import "src/main/proto/search/now/ui/piet/shadows.proto";

option java_package = "com.google.search.now.ui.piet";
option java_outer_classname = "StylesProto";
option cc_enable_arenas = true;

// A Style is a reusable specification of visual layout that can be applied to
// any Piet visual element.
//
// Styles can be applied to visual elements at multiple levels of the visual
// hierarchy. Only those attributes that make sense for a visual element will be
// applied. Implementations MUST ignore attributes that cannot be meaningfully
// applied to a visual element and MUST NOT issue any warnings or errors, to
// allow for the same style to be reused in other places where those attributes
// are relevant. E.g. for any style applied to an image-like element, font
// should be ignored.

// A stack of style_ids used to evaluate the style of an element. The final
// applicable style is computed by proto-merging each style one by one, in order
// starting from the first. Later attributes override earlier attributes. If a
// style_id cannot be found, ERR_MISSING_STYLE is raised.
//
// After the style_ids are merged, in case a bound_style is given, its values
// override the ones produced by the merge.
message StyleIdsStack {
  // Style IDs that are proto-merged in order from first to last.
  repeated string style_ids = 1;

  // Optional style binding that override the styles in the given style_ids.
  // See message comment for exact use.
  optional StyleBindingRef style_binding = 2;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;
}

// A collection of attributes describing an element’s visual properties.
// NextId: 25
message Style {
  // Every style must have a name that is unique within the StyleSheet. But
  // don’t go overboard in naming these with namespaced constructs because
  // longer strings lead to more bytes on the wire.
  optional string style_id = 1;

  // This Style is only eligible to be used if *all* the conditions
  // enumerated below are met. Multiple styles can have the same style id if
  // their conditions are disjoint.
  repeated MediaQueryCondition conditions = 16;

  // Foreground color for text elements.

  // When applied to an image, this will replace all non-transparent pixels with
  // the specified color. This is used for changing the color of icons which are
  // provided as a monochrome bitmap. If this optional field is not provided,
  // the image will not be modified.
  optional fixed32 color = 2 [default = 0xDE000000];

  // Defines the background fill, either as a solid color, or a gradient.
  optional Fill background = 3;

  // Configuration for image loading behavior (such as fading in)
  optional ImageLoadingSettings image_loading_settings = 17;

  // Font information applicable to text elements.
  optional Font font = 4;

  // Text alignment
  optional TextAlignmentHorizontal text_alignment_horizontal = 21
      [default = TEXT_ALIGNMENT_START];
  optional TextAlignmentVertical text_alignment_vertical = 22
      [default = TEXT_ALIGNMENT_TOP];

  // Margins (if given) are outside the specified width/height.
  // The background fills all the area up to the margin, excluding the margin.
  //
  //    +--------SpecifiedWidth---------+
  //    |                               |
  //
  // +-------------------------------------+
  // |               Margin                |
  // |  +-------------------------------+  |  --+
  // |  |ooooooooooo.Border.oooooooooooo|  |    |
  // |  |o+---------------------------+o|  |    |
  // |  |o|          Padding          |o|  |    |
  // |  |o|  +---------------------+  |o|  |    |
  // |  |o|  |                     |  |o|  |    |
  // |  |o|  |       Content       |  |o|  |    +-- SpecifiedHeight
  // |  |o|  |                     |  |o|  |    |
  // |  |o|  +---------------------+  |o|  |    |
  // |  |o|                           |o|  |    |
  // |  |o+---------------------------+o|  |    |
  // |  |ooooooooooooooooooooooooooooooo|  |    |
  // |  +-------------------------------+  |  --+
  // |                                     |
  // +-------------------------------------+

  // Margins around the item
  optional EdgeWidths margins = 5;

  // Borders
  optional Borders borders = 6;

  // Padding around the item
  optional EdgeWidths padding = 7;

  // This Element's requested width.
  // If this is not set, use the parent container's default child width.
  oneof width_spec {
    // Width of an element.
    uint32 width = 8;

    // Width relative to content or parent Element
    RelativeSize relative_width = 23;
  }

  // This Element's requested height.
  // If this is not set, use the parent container's default child height.
  oneof height_spec {
    // Constant height in DP
    uint32 height = 9;

    // Height relative to content or parent Element
    RelativeSize relative_height = 24;
  }

  // Minimum height for an element.
  optional uint32 min_height = 10;

  // Maximum number of text lines to display
  optional uint32 max_lines = 11;

  // If there is a background fill, allow the background (including borders) to
  // have rounded corners.
  optional RoundedCorners rounded_corners = 12;

  // Opacity. This affects the element with the current style, and also all its
  // descendants. For example, Opacity of a GridRow will affect all the
  // GridCells under it, and their descendants. This value comes on top of the
  // alpha value of colors.
  // Values between [0..1] are valid; those outside this range will be clamped.
  optional float opacity = 13 [default = 1.0];

  // Defines a shadow for an element.
  optional Shadow shadow = 14;

  // Scale type for images
  // This may not be supported for images in ChunkedText for all platforms.
  optional Image.ScaleType scale_type = 18 [default = CENTER_INSIDE];

  // Horizontal gravity of this element's content within the parent container
  // Not respected in GridRow
  optional GravityHorizontal gravity_horizontal = 19;

  // Vertical gravity of this element's content within the parent container
  // Not respected in ElementList
  optional GravityVertical gravity_vertical = 20;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;
}

// Various configuration parameters for image loading
message ImageLoadingSettings {
  // If this is set, images will fade in after loading asynchronously.
  // May not be supported on all platforms.
  optional bool fade_in_image_on_load = 1;

  oneof preload {
    // Defines a placeholder fill applied before an image loads.
    // This will be replaced by the Image when it loads asynchronously.
    // Not relevant for platforms where image loading is synchronous.
    Fill pre_load_fill = 2;

    // Defines a placeholder image applied before an image loads.
    // This will be replaced by the Image when it loads asynchronously.
    // This should be an on-device asset; it doesn't make sense to have the pre-
    // load image also load asynchronously.
    // Not relevant for platforms where image loading is synchronous.
    Image pre_load_image = 3;
  }
}

// Style that can be bound to an element. Not all style attributes can be bound
// due to performance (specifically, this affects view recycling).
//
// PLEASE NOTE: Field names inside this message should bear the exact same names
//     as their counterparts in the Style message.
// LINT.IfChange
message BoundStyle {
  // See comments for Style.color.
  optional fixed32 color = 1;

  // See comments for Style.background.
  optional Fill background = 2;

  // See comments for Style.image_loading_settings
  optional ImageLoadingSettings image_loading_settings = 4;

  // See comments for Style.scale_type
  optional Image.ScaleType scale_type = 5;
}
// LINT.ThenChange

// Set a dimension relative to content or parent.
// If a parent's size is set to FIT_CONTENT, and the child's size is
// set to FILL_PARENT, the resulting size of the child should be the size of
// the child's content.
enum RelativeSize {
  // Undefined behavior; use the default dimensions specified by the parent
  // container.
  RELATIVE_SIZE_UNDEFINED = 0;

  // Make this Element request just as much space as its content requires.
  FIT_CONTENT = 1;

  // Make this Element request to fill whatever space is allocated to it.
  FILL_PARENT = 2;
}

// Horizontal alignment of text within a TextElement.
enum TextAlignmentHorizontal {
  // This value should never be used.
  TEXT_ALIGNMENT_HORIZONTAL_UNSPECIFIED = 0;

  // Align with the start side (left in LTR layouts)
  TEXT_ALIGNMENT_START = 1;

  // Align with the end side (right in LTR layouts)
  TEXT_ALIGNMENT_END = 2;

  // Align centered
  TEXT_ALIGNMENT_CENTER = 3;
}

// Vertical alignment of text within a TextElement.
enum TextAlignmentVertical {
  // This value should never be used.
  TEXT_ALIGNMENT_VERTICAL_UNSPECIFIED = 0;

  // Align top edge of text to top edge of element
  TEXT_ALIGNMENT_TOP = 1;

  // Align bottom edge of text to bottom edge of element
  TEXT_ALIGNMENT_BOTTOM = 2;

  // Align centered vertically
  TEXT_ALIGNMENT_MIDDLE = 3;
}

// Font definitions for text elements. In the interest of preserving
// consistency, feature authors are highly encouraged to use Fonts as part of a
// Style, instead of applying font definitions to individual elements.
message Font {
  // The size of the text in scaled pixels (sp). For devices with a scaling
  // factor of 1.0, this size is equivalent to display pixels.
  // Certain OS-level accessibility features allow users to increase/decrease
  // font size by a scaling factor (e.g. iOS > Dynamic Type, or Android Settings
  // > Font Size, or Android > Accessibility > Large Text). If the user has
  // turned on text scaling, the Host App should apply that scaling factor to
  // this numeric font size before rendering.
  // Note that other related metrics such as width and height are NOT
  // automatically scaled, but line height does scale.
  optional int32 size = 1 [default = 14];

  // Line height, expressed as a multiple of size (hence the `_ratio` suffix).
  // The default value of 1.2 is intended to work well for most scenarios
  // without requiring feature authors to specify this explicitly.
  // Behavior matches that of CSS: extra space appears between lines and evenly
  // split above and below a block of text.
  // For example, if the ratio is 2.0 and the text is 12pt tall, there will be
  // 12pt of space between each pair of lines, and 6pt of space above and below
  // the block of text.
  // This field is deprecated. Please use line_height instead.
  // TODO Remove this field once the transition to line_height
  // is complete.
  optional float line_height_ratio = 2 [default = 1.2, deprecated = true];

  // Line height, expressed as scale-independent pixels (sp), meaning that it
  // scales with accessibility settings. If no line height is specified, the
  // default spacing for that font will be used. This is usually
  // approximately 1.2 times the height of the text, and should work well for
  // most platforms. Using the default does not guarantee the same height across
  // platforms; if that is needed, an explicit line height should be set.
  // Because line_height_ratio is deprecated, if both are specified, only
  // line_height will be used.
  optional uint32 line_height = 7;

  // Material Design specifies six weights for a font, in order from thinnest
  // stroke to thickest stroke. Orthogonal to weight, a font can be either
  // normal or italic. Not all weights may be supported by every typeface or
  // every platform; see [INTERNAL LINK]
  enum FontWeight {
    // Unspecified font weight.
    FONT_WEIGHT_UNSPECIFIED = 0;

    // Thinnest font weight.
    THIN = 1;

    // Light font weight.
    LIGHT = 2;

    // Regular font weight (this is the default).
    REGULAR = 3;

    // Medium font weight.
    MEDIUM = 4;

    // Bold font weight.
    BOLD = 5;

    // Black (extra-bold) font weight.
    BLACK = 6;
  }

  // The font weight (boldness) to apply to the text.
  // This field is deprecated. Please use a Typeface, and either choose a
  // CommonFont, which has the weight built in, or include the weight as part of
  // the style definition for a custom_font.
  optional FontWeight weight = 3 [default = REGULAR, deprecated = true];

  // Apply the italic style to the Font.
  optional bool italic = 4;

  // Sets text letter spacing in dp. This indicates how much space will be
  // added between characters. Negative values tighten text, whereas positive
  // values increase space between letters. Also known as “tracking” in
  // typography, or “character spacing” in image editing tools.
  optional float letter_spacing_dp = 9;

  // The typeface to use, e.g. "roboto", "open-sans", or "product-sans".
  // Multiple typefaces can be specified by the server, and the first one that
  // is available on the client will be used. If none match, or if no typefaces
  // are specified, then ERR_FONT_UNAVAILABLE is raised, and the system default
  // typeface on each platform will be used. Each typeface’s name is a custom
  // string, and should be negotiated between server and client to ensure that
  // typefaces requested by the server are available on the client. Piet
  // provides no way to request that a particular font face be downloaded at
  // runtime; this should be done out-of-band if required.
  // This field is deprecated. Please use the typeface field that uses a
  // Typeface message instead.
  repeated string typefaces = 6 [deprecated = true];

  // The typeface to use. Each typeface specified can either be a CommonTypeface
  // or a string naming a custom typeface. The CommonTypeface actually pairs
  // commonly-used typefaces with weights. The custom one can be used to
  // identify any typeface. Multiple typefaces can be specified by the server,
  // and the first one that is available on the client will be used. If none
  // match, or if no typefaces are specified, then ERR_FONT_UNAVAILABLE is
  // raised, and the system default typeface on each platform will be used. Piet
  // provides no way to request that a particular font face be downloaded at
  // runtime; this should be done out-of-band if required.
  repeated Typeface typeface = 8;

  // Deprecated field IDs, do not reuse.
  reserved 5;
}

message Typeface {
  // Defines a commonly-used typeface, paired with a weight. "PLATFORM_DEFAULT_"
  // uses the system default typeface on each platform, and sets the weight.
  // Google Sans is a cross-platform typeface that should render well on all
  // platforms. Note that Google Sans will only work if the client has bundled
  // it in properly.
  enum CommonTypeface {
    // The same as PLATFORM_DEFAULT_REGULAR.
    UNDEFINED = 0;

    PLATFORM_DEFAULT_LIGHT = 1;

    PLATFORM_DEFAULT_REGULAR = 2;

    PLATFORM_DEFAULT_MEDIUM = 3;

    GOOGLE_SANS_REGULAR = 4;

    GOOGLE_SANS_MEDIUM = 5;
  }

  oneof typeface_specifier {
    // Commonly used typefaces (with weights).
    CommonTypeface common_typeface = 1;

    // Any typeface needed that is not included in CommonTypeface should be
    // specified as a string here. Piet does not provide these typefaces, or any
    // way to download them at runtime. The host is meant to perform the lookup
    // and provide the correct typeface to Piet for rendering. If
    // platform-specific typefaces are needed, the string can be an identifier
    // (i.e. "group_of_typefaces_for_feature"), and each platform can look up
    // what that translates to. Piet will NOT parse the custom_typeface string
    // to set attributes such as font weight.
    string custom_typeface = 2;
  }
}

// Definition of a Border.
message Border {
  option deprecated = true;

  // The color of the border.
  optional fixed32 color = 1;

  // The thickness of the border in DP.
  optional int32 width = 2;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;
}

// A set of four Borders for all four edges of a view.
// NextId: 8
message Borders {
  enum Edges {
    // If unspecified, then all edges will have borders.
    EDGES_UNSPECIFIED = 0;

    // Indicates that the start side of the item should have a border
    START = 0x1;

    // Indicates that the top side of the item should have a border
    TOP = 0x2;

    // Indicates that the end side of the item should have a border
    END = 0x4;

    // Indicates that the bottom side of the item should have a border
    BOTTOM = 0x8;
  }

  // A bitmask representing which sides should have borders. Bit values are
  // defined by the `Edges` enum. If no sides are specified (the default), then
  // all sides will have a border.
  //
  // NOTICE: having a rounded corner with a border only on one side is strongly
  // discouraged as it leads to undefined and inconsistent behavior across
  // platforms.
  optional int32 bitmask = 5;

  // The color of the border.
  optional fixed32 color = 6;

  // Width of the border.
  optional int32 width = 7;

  // Top border.
  optional Border top = 1 [deprecated = true];

  // Bottom border.
  optional Border bottom = 2 [deprecated = true];

  // Border for leading edge (left for LTR languages; right for RTL).
  optional Border start = 3 [deprecated = true];

  // Border for trailing edge (right for LTR languages; left for RTL).
  optional Border end = 4 [deprecated = true];

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;
}

// A set of four values for widths of the edges of a view, used for
// paddings/margins.
message EdgeWidths {
  // Top boundary.
  optional uint32 top = 1;

  // Bottom boundary.
  optional uint32 bottom = 2;

  // Boundary for leading edge (left for LTR languages; right for RTL).
  optional uint32 start = 3;

  // Boundary for trailing edge (right for LTR languages; left for RTL).
  optional uint32 end = 4;
}

// Specifies gravity on the horizontal axis.
enum GravityHorizontal {
  GRAVITY_HORIZONTAL_UNSPECIFIED = 0;

  // Align with the start side (left in LTR layouts)
  GRAVITY_START = 1;

  // Align with the end side (right in LTR layouts)
  GRAVITY_END = 2;

  // Align centered
  GRAVITY_CENTER = 3;
}

// Specifies gravity on the vertical axis.
enum GravityVertical {
  GRAVITY_VERTICAL_UNSPECIFIED = 0;

  // Align with the top side
  GRAVITY_TOP = 1;

  // Align vertically centered
  GRAVITY_MIDDLE = 2;

  // Align with the bottom side
  GRAVITY_BOTTOM = 3;
}