blob: 5f8debf124e5b43720a67ae1067ec67894ec7784 [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/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;
}