src/main/proto/search/now/ui/piet/text.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";

import "src/main/proto/search/now/ui/piet/actions.proto";
import "src/main/proto/search/now/ui/piet/binding_refs.proto";
import "src/main/proto/search/now/ui/piet/images.proto";
import "src/main/proto/search/now/ui/piet/styles.proto";

package search.now.ui.piet;

option optimize_for=LITE_RUNTIME;

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

// ParameterizedText allows strings to be constructed on the client based on
// rapidly-changing information for which a server round-trip is not
// appropriate. Clients will build a string at runtime by combining the
// parameterized string with the values of the evaluated parameters.
message ParameterizedText {
  // A string that may (but need not always) include placeholders for
  // parameters.
  //
  // If parameters are specified, placeholders use the simplest standard C or
  // Java string format specifier: "%s". All other instances of the "%"
  // character must be escaped with another "%" character. If there are no
  // parameters, this string is used directly, without replacements. The number
  // of placeholders must correspond to the number of parameters provided. The
  // order of `parameters` is significant; parameters are replaced in the string
  // in the order specified.
  //
  // The server is responsible for localizing this string for the target locale;
  // the client expects to receive only a single string for the current locale.
  // Any pluralization (["zero" | "one" | "two" | "few" | "many" | "other"])
  // should be done by the server at serving time, and is not handled by the
  // client.
  optional string text = 1;

  // Strings are considered to be plain text by default, for performance
  // reasons. A string is parsed as HTML if and only if this field is explicitly
  // set to true.
  // TODO: Document the white-listed set of tags, and ensure this
  // content is correctly sanitized on all supported platforms.
  optional bool is_html = 2 [default = false];

  // A parameter to be substituted in the ParameterizedText. Every type of
  // parameter depends on some information only available on the client at
  // rendering time, and not on the server at card and string creation time. In
  // particular, if the value can be determined on the server, it should be
  // inlined in the string on the server.
  message Parameter {
    // The parameter type.
    oneof parameter_types {
      // An absolute timestamp in seconds since the Unix epoch.
      int64 timestamp_seconds = 1;

      // A location to be used for computing relative distances or travel times.
      Location location = 2;
    }
  }

  // An ordered list of parameters.
  repeated Parameter parameters = 3;
}

// A location, expressed as a { latitude, longitude } tuple. This is used to
// generate a string that describes the distance between the user’s current
// location and the specified location in relative terms, e.g. “10 meters away”,
// or “20 minutes away”.
//
// Since Piet is a presentational language (not semantic), this Location should
// only contain the fields necessary for accurate display. Specifically, other
// fields such as physical addresses, labels, titles, or feature names should
// not be added here.
//
// Both latitude and longitude are specified as double-precision floats. The
// worst case real-world distance expressed in this format is ~1-4 meters at the
// equator.
message Location {
  // Latitude for this location.
  optional double latitude = 1;

  // Longitude for this location.
  optional double longitude = 2;
}

// ChunkedText allows composing a single string of multiple chunks with
// different formatting. In addition to this, a chunk can also be composed of an
// image that gets inlined with the surrounding text chunks. Image chunks are
// aligned to the text baseline. Chunked text flows independently from the
// chunked regions. Line wrapping is supported across different chunks. For
// example a string composed of three chunks that needs to be wrapped in two
// lines will be wrapped as follows:
// [[chunk a] [image] [chunk]]
// [[b]]
message ChunkedText {
  // The set of chunks that compose this chunked text.
  repeated Chunk chunks = 1;
}

// A single region of content within a ChunkedText. A chunk can either be
// composed of an image or a styled text chunk.
message Chunk {
  // The content of the Chunk.
  oneof content {
    // A styled piece of text content.
    StyledTextChunk text_chunk = 1;

    // A styled piece of image content.
    StyledImageChunk image_chunk = 2;
  }

  // Defines Actions that may be associated with this chunk, e.g. for creating
  // clickable links or images within text. The server is responsible for
  // ensuring that the size of this content is large enough to present a clear
  // click target for the user.
  // NOTE: on_partial_view is not supported for Chunks.
  oneof actions_data {
    // Inlined actions.
    Actions actions = 3;

    // Actions from a template, bound at runtime.
    ActionsBindingRef actions_binding = 4;
  }
}

// A single region of image content that has a particular style applied to it.
message StyledImageChunk {
  // Styles applied to this chunk.
  optional StyleIdsStack style_references = 1;

  // Content for this StyledImageChunk.
  oneof content {
    // The binding to the BindingValue for an Image.
    ImageBindingRef image_binding = 2;

    // The image to be displayed.
    Image image = 3;
  }

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

// A single region of text content that has styles applied to it.
message StyledTextChunk {
  // Styles applied to this chunk.
  optional StyleIdsStack style_references = 1;

  // Content for this StyledTextChunk.
  oneof content {
    // The binding to the BindingValue for a ParameterizedText.
    ParameterizedTextBindingRef parameterized_text_binding = 2;

    // The text to display.
    ParameterizedText parameterized_text = 3;
  }

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