main/proto/modifiers.proto

// Modifiers for composable layout elements.
syntax = "proto3";

package androidx.wear.protolayout.proto;

import "action.proto";
import "animation_parameters.proto";
import "color.proto";
import "dimension.proto";
import "types.proto";

option java_package = "androidx.wear.protolayout.proto";
option java_outer_classname = "ModifiersProto";

// A modifier for an element which can have associated Actions for click events.
// When an element with a ClickableModifier is clicked it will fire the
// associated action.
message Clickable {
  // The ID associated with this action.
  string id = 1;

  // The action to perform when the element this modifier is attached to is
  // clicked.
  Action on_click = 2;

  // The minimum width of the clickable area.
  //
  // The default value is 48dp, following the Material design accessibility
  // guideline. Note that this value does not affect the layout, so the minimum
  // clickable width is not guaranteed unless there is enough space around the
  // element within its parent bounds.
  DpProp minimum_clickable_width = 3;

  // The minimum height of the clickable area.
  //
  // The default value is 48dp, following the Material design accessibility
  // guideline. Note that this value does not affect the layout, so the minimum
  // clickable height is not guaranteed unless there is enough space around the
  // element within its parent bounds.
  DpProp minimum_clickable_height = 4;

  oneof optional_visual_feedback_enabled {
    // Whether the click visual feedback (such as a ripple) should be enabled.
    // Defaults to true.
    bool visual_feedback_enabled = 5;
  }
}

// The type of user interface element. Accessibility services might use this to
// describe the element or do customizations.
enum SemanticsRole {
  // Role is undefined. It may be automatically populated.
  SEMANTICS_ROLE_NONE = 0;

  // The element is an image.
  SEMANTICS_ROLE_IMAGE = 1;

  // The element is a Button control.
  SEMANTICS_ROLE_BUTTON = 2;

  // The element is a Checkbox which is a component that represents two states
  // (checked / unchecked).
  SEMANTICS_ROLE_CHECKBOX = 3;

  // The element is a Switch which is a two state toggleable component that
  // provides on/off like options.
  SEMANTICS_ROLE_SWITCH = 4;

  // This element is a RadioButton which is a component to represent two states,
  // selected and not selected.
  SEMANTICS_ROLE_RADIOBUTTON = 5;
}

// A modifier for an element which has accessibility semantics associated with
// it. This should generally be used sparingly, and in most cases should only be
// applied to the top-level layout element or to Clickables.
message Semantics {
  // The content description associated with this element. This will be dictated
  // when the element is focused by the screen reader.
  // @deprecated Use content_description instead.
  string obsolete_content_description = 1;

  // The content description associated with this element. This will be dictated
  // when the element is focused by the screen reader.
  //
  // While this field is statically accessible from 1.0, it's only bindable
  // since version 1.2 and renderers supporting version 1.2 will use the dynamic
  // value (if set).
  StringProp content_description = 4;

  // The type of user interface element. Accessibility services might use this
  // to describe the element or do customizations.
  SemanticsRole role = 2;

  // The localized state description of the semantics node.
  // For example: "on" or "off". This will be dictated when the element is
  // focused by the screen reader.
  //
  // This field is bindable and will use the dynamic value (if set).
  StringProp state_description = 3;
}

// A modifier to apply padding around an element.
message Padding {
  // The padding on the end of the content, depending on the layout direction,
  // in DP and the value of "rtl_aware".
  DpProp end = 1;

  // The padding on the start of the content, depending on the layout direction,
  // in DP and the value of "rtl_aware".
  DpProp start = 2;

  // The padding at the top, in DP.
  DpProp top = 3;

  // The padding at the bottom, in DP.
  DpProp bottom = 4;

  // Whether the start/end padding is aware of RTL support. If true, the values
  // for start/end will follow the layout direction (i.e. start will refer to
  // the right hand side of the container if the device is using an RTL locale).
  // If false, start/end will always map to left/right, accordingly.
  BoolProp rtl_aware = 5;
}

// A modifier to apply a border around an element.
message Border {
  // The width of the border, in DP.
  DpProp width = 1;

  // The color of the border.
  //
  // While this field is statically accessible from 1.0, it's only bindable
  // since version 1.2 and renderers supporting version 1.2 will use the dynamic
  // value (if set).
  ColorProp color = 2;
}

// A radius for either circular or elliptical shapes.
message CornerRadius {
  // The radius value in dp on the horizontal axis.
  DpProp x = 1;
  // The radius value in dp on the vertical axis.
  DpProp y = 2;
}

// The corner of a Box element.
message Corner {
  // The radius of the corner in DP.
  // <p>The shape for a specific corner can be overridden by setting that corner separately.
  DpProp radius = 1;

  // The radius for the top-left corner of either circular or elliptical shapes.
  // If not set, defaults to radius for both horizontal and vertical
  // axes when radius is set; or defaults to zeros when radius is also not set.
  CornerRadius top_left_radius = 2;

  // The radius for the top-right corner of either circular or elliptical shapes.
  // If not set, defaults to radius for both horizontal and vertical
  // axes when radius is set; or defaults to zeros when radius is also not set.
  CornerRadius top_right_radius = 3;

  // The radius for the bottom-right corner of either circular or elliptical shapes.
  // If not set, defaults to radius for both horizontal and vertical
  // axes when radius is set; or defaults to zeros when radius is also not set.
  CornerRadius bottom_right_radius = 4;

  // The radius for the bottom-left corner of either circular or elliptical shapes.
  // If not set, defaults to radius for both horizontal and vertical
  // axes when radius is set; or defaults to zeros when radius is also not set.
  CornerRadius bottom_left_radius = 5;
}

// A modifier to apply a background to an element.
message Background {
  // The background color for this element. If not defined, defaults to being
  // transparent.
  //
  // While this field is statically accessible from 1.0, it's only bindable
  // since version 1.2 and renderers supporting version 1.2 will use the dynamic
  // value (if set).
  //
  // If a brush is set, this color will only be used if brush is not supported
  // by the renderer (versions below 1.5).
  ColorProp color = 1;

  // The corner properties of this element. This only affects the drawing of
  // this element if it has a background color or border. If not defined,
  // defaults to having a square corner.
  Corner corner = 2;

  // A brush used to draw the background. If set and supported, the brush will be
  // used instead of the color provided in {@code setColor()}.
  //
  // Only LinearGradient is supported.
  Brush brush = 3;
}

// Metadata about an element. For use by libraries building higher-level
// components only. This can be used to track component metadata.
message ElementMetadata {
  // Property describing the element with which it is associated. For use by
  // libraries building higher-level components only. This can be used to track
  // component metadata.
  bytes tag_data = 1;
}

// A modifier to apply transformations to the element. All of these
// transformations can be animated by setting dynamic values.
// This modifier is not layout affecting.
message Transformation {
  // The horizontal offset of this element relative to the location where the
  // element's layout placed it.
  DpProp translation_x = 1;

  // The vertical offset of this element in addition to the location where the
  // element's layout placed it.
  DpProp translation_y = 2;

  // The scale of this element in the x direction around the pivot point, as a
  // proportion of the element's unscaled width .
  FloatProp scale_x = 3;

  // The scale of this element in the y direction around the pivot point, as a
  // proportion of the element's unscaled height.
  FloatProp scale_y = 4;

  // The clockwise degrees that the element is rotated around the pivot point.
  DegreesProp rotation = 5;

  // The horizontal location of the point around which the element is rotated
  // and scaled. With type DpProp, it is the offset from the element center;
  // otherwise with type BoundingBoxRatio, it is the location proportional to
  // the bounding box width.
  PivotDimension pivot_x = 6;

  // The vertical location of the point around which the element is rotated and
  // scaled. With type DpProp, it is the offset from the element center;
  // otherwise with type BoundingBoxRatio, it is the location proportional to
  // the bounding box height.
  PivotDimension pivot_y = 7;
}

// Modifiers for an element. These may change the way they are drawn (e.g.
// Padding or Background), or change their behaviour (e.g. Clickable, or
// Semantics).
message Modifiers {
  // The clickable property of the modified element. It allows its wrapped
  // element to have actions associated with it, which will be executed when the
  // element is tapped.
  Clickable clickable = 1;

  // The semantics of the modified element. This can be used to add metadata to
  // the modified element (eg. screen reader content descriptions).
  Semantics semantics = 2;

  // The padding of the modified element.
  Padding padding = 3;

  // The border of the modified element.
  Border border = 4;

  // The background (with optional corner radius) of the modified element.
  Background background = 5;

  // Metadata about an element. For use by libraries building higher-level
  // components only. This can be used to track component metadata
  ElementMetadata metadata = 6;

  // The content transition of an element. Any update to the element or its
  // children will trigger this animation for this element and everything
  // underneath it.
  AnimatedVisibility content_update_animation = 7;

  // Whether the attached element is hidden, or visible. If the element is
  // hidden, then it will still consume space in the layout, but will not render
  // any contents, nor will any children render any contents.
  //
  // Note that a hidden element also cannot be clickable (i.e. a Clickable
  // modifier would be ignored).
  //
  // Defaults to false (i.e. not hidden).
  // This field is deprecated and is only kept for backward compatibility.
  BoolProp hidden = 8;

  // The optional identifier for the layout element.
  string id = 9;

  // Whether the attached element is visible, or hidden. If the element is
  // hidden, then it will still consume space in the layout, but will not render
  // any contents, nor will any children render any contents. Defaults to
  // visible.
  //
  // Note that a hidden element also cannot be clickable (i.e. a Clickable
  // modifier would be ignored).
  BoolProp visible = 10;

  // The transformation applied to the element post-layout
  Transformation transformation = 11;

  // The opacity of the element with a value from 0 to 1, where 0 means
  // the element is completely transparent and 1 means the element is
  // completely opaque. Defaults to 1.
  FloatProp opacity = 12;
}

// The content transition of an element. Any update to the element or its
// children will trigger this animation for this element and everything
// underneath it.
message AnimatedVisibility {
  // The content transition that is triggered when element enters the layout.
  EnterTransition enter_transition = 1;

  // The content transition that is triggered when element exits the layout.
  // Note that indefinite exit animations are ignored.
  ExitTransition exit_transition = 2;
}

// The content transition that is triggered when element enters the layout.
message EnterTransition {
  // The fading in animation for content transition of an element and its
  // children happening when entering the layout.
  FadeInTransition fade_in = 1;

  // The sliding in animation for content transition of an element and its
  // children happening when entering the layout.
  SlideInTransition slide_in = 2;
}

// The fading animation for content transition of an element and its children,
// from the specified starting alpha to fully visible.
message FadeInTransition {
  // The starting alpha of the fade in transition. It should be between 0 and 1.
  // If not set, defaults to fully transparent, i.e. 0.
  float initial_alpha = 1;

  // The animation parameters for duration, delay, etc.
  androidx.wear.protolayout.expression.proto.AnimationSpec animation_spec = 2;
}

// The sliding in animation for content transition of an element and its
// children.
message SlideInTransition {
  // The slide direction used for slide animations on any element, from the
  // specified point to its destination in the layout. If not set, defaults to
  // horizontal from left to the right.
  SlideDirection direction = 1;

  // The initial offset for animation. By default the transition starts from the
  // left parent boundary for horizontal orientation and from the top for
  // vertical orientation. Note that sliding from the screen boundaries can only
  // be achieved if all parent's sizes are big enough to accommodate it.
  SlideBound initial_slide_bound = 2;

  // The animation parameters for duration, delay, etc.
  androidx.wear.protolayout.expression.proto.AnimationSpec animation_spec = 3;
}

// The content transition that is triggered when element exits the layout.
message ExitTransition {
  // The fading out animation for content transition of an element and its
  // children happening when exiting the layout.
  FadeOutTransition fade_out = 1;

  // The sliding out animation for content transition of an element and its
  // children happening when exiting the layout.
  SlideOutTransition slide_out = 2;
}

// The fading animation for content transition of an element and its children,
// from fully visible to the specified target alpha.
message FadeOutTransition {
  // The target alpha of the fade out transition. It should be between 0 and 1.
  // If not set, defaults to fully invisible, i.e. 0.
  float target_alpha = 1;

  // The animation parameters for duration, delay, etc.
  androidx.wear.protolayout.expression.proto.AnimationSpec animation_spec = 2;
}

// The sliding out animation for content transition of an element and its
// children.
message SlideOutTransition {
  // The slide direction used for slide animations on any element, from its
  // destination in the layout to the specified point. If not set, defaults to
  // horizontal from right to the left.
  SlideDirection direction = 1;

  // The target offset for animation. By default the transition will end at the
  // left parent boundary for horizontal orientation and at the top for
  // vertical orientation. Note that sliding from the screen boundaries can only
  // be achieved if all parent's sizes are big enough to accommodate it.
  SlideBound target_slide_bound = 2;

  // The animation parameters for duration, delay, etc.
  androidx.wear.protolayout.expression.proto.AnimationSpec animation_spec = 3;
}

// The boundary that a Slide animation will use for start/end.
message SlideBound {
  oneof inner {
    SlideParentBound parent_bound = 1;
    SlideLinearBound linear_bound = 2;
  }
}

// The slide animation will animate from/to the parent elements boundaries.
message SlideParentBound {
  // The snap options to use when sliding using parent boundaries. Defaults to
  // SLIDE_PARENT_SNAP_TO_INSIDE if not specified.
  SlideParentSnapOption snap_to = 1;
}

// The snap options to use when sliding using parent boundaries.
enum SlideParentSnapOption {
  // The undefined snapping option.
  SLIDE_PARENT_SNAP_UNDEFINED = 0;

  // The option that snaps insides of the element and its parent at start/end.
  SLIDE_PARENT_SNAP_TO_INSIDE = 1;

  // The option that snaps outsides of the element and its parent at start/end.
  SLIDE_PARENT_SNAP_TO_OUTSIDE = 2;
}

// The slide animation will use the explicit offset for the animation boundary.
message SlideLinearBound {
  // The absolute delta linear distance to animate from/to. A direction will be
  // defined by SlideDirection and this value should be a positive offset.
  float offset_dp = 1;
}

// The slide direction used for slide animations on any element, from the
// specified point to its destination in the layout for in animation or reverse
// for out animation.
enum SlideDirection {
  // The undefined sliding orientation.
  SLIDE_DIRECTION_UNDEFINED = 0;

  // The sliding orientation that moves an element horizontally from left to the
  // right.
  SLIDE_DIRECTION_LEFT_TO_RIGHT = 1;

  // The sliding orientation that moves an element horizontally from right to
  // the left.
  SLIDE_DIRECTION_RIGHT_TO_LEFT = 2;

  // The sliding orientation that moves an element vertically from top to the
  // bottom.
  SLIDE_DIRECTION_TOP_TO_BOTTOM = 3;

  // The sliding orientation that moves an element vertically from bottom to the
  // top.
  SLIDE_DIRECTION_BOTTOM_TO_TOP = 4;
}

// Modifiers that can be used with ArcLayoutElements. These may change the way
// they are drawn, or change their behaviour.
message ArcModifiers {
  // Allows its wrapped element to have actions associated with it, which will
  // be executed when the element is tapped.
  Clickable clickable = 1;

  // Adds metadata for the modified element, for example, screen reader content
  // descriptions.
  Semantics semantics = 2;

  // The opacity of the element with a value from 0 to 1, where 0 means
  // the element is completely transparent and 1 means the element is
  // completely opaque. Defaults to 1.
  FloatProp opacity = 4;

  reserved 3;
}

// Modifiers that can be used with Span elements. These may change the way
// they are drawn, or change their behaviour.
message SpanModifiers {
  // Allows its wrapped element to have actions associated with it, which will
  // be executed when the element is tapped.
  Clickable clickable = 1;
}

// The shadow definition. The shadow is drawn as a blur region around the
// element.
message Shadow {
  // The blur radius of the shadow. It controls the size of the blur that is
  // drawn. When set to zero, the shadow is not drawn. Defaults to zero.
  DpProp blur_radius = 1;

  // The color used in the shadow. Defaults to Black.
  ColorProp color = 2;
}