// Copyright 2013 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// Sync protocol datatype extension for the app list (aka app launcher).

// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}.

syntax = "proto2";

option go_package = "./sync_pb";

option java_multiple_files = true;
option java_package = "org.chromium.components.sync.protocol";

option optimize_for = LITE_RUNTIME;

package sync_pb;

// Properties of app list objects.
message AppListSpecifics {
  // Unique identifier for the item:
  // * TYPE_FOLDER: Folder id (generated)
  // * TYPE_APP: App Id
  optional string item_id = 1;

  // What type of item this is.
  enum AppListItemType {
    // An app, whether a web app, Android app, etc.
    //
    // For bookmark apps (URL shortcuts), additional information such as their
    // URLs are kept in the AppSpecifics.bookmark_app_foobar fields.
    TYPE_APP = 1;
    // A request to remove any matching default installed apps.
    TYPE_REMOVE_DEFAULT_APP = 2;
    // A folder containing entries whose |parent_id| matches |item_id|.
    TYPE_FOLDER = 3;
    // Obsolete type, intended for URL shortcuts, that was never implemented.
    TYPE_OBSOLETE_URL = 4;
    // A "page break" item (Indicate creation of a new page in app list).
    TYPE_PAGE_BREAK = 5;
  }
  optional AppListItemType item_type = 2;

  // Item name (FOLDER).
  optional string item_name = 3;

  // Id of the parent (folder) item.
  optional string parent_id = 4;

  // Marked OBSOLETE because this is unused for the app list.
  // Which page this item will appear on in the app list.
  optional string OBSOLETE_page_ordinal = 5 [deprecated = true];

  // Where on a page this item will appear.
  optional string item_ordinal = 6;

  // Where on a shelf this item will appear.
  // Note that not all apps are pinned to the shelf by the user -- some might
  // originate from the PinnedLauncherApps policy. See `is_user_pinned` for more
  // details.
  optional string item_pin_ordinal = 7;

  // The color groups used for grouping together icons by colors.
  enum ColorGroup {
    COLOR_EMPTY = 0;
    COLOR_WHITE = 1;
    COLOR_RED = 2;
    COLOR_ORANGE = 3;
    COLOR_YELLOW = 4;
    COLOR_GREEN = 5;
    COLOR_BLUE = 6;
    COLOR_MAGENTA = 7;
    COLOR_BLACK = 8;
  }

  message IconColor {
    // The item icon's background color.
    optional ColorGroup background_color = 1;

    // The item icon's hue.
    optional int32 hue = 2;
  }
  optional IconColor item_color = 8;

  // Whether the app was pinned to shelf by the user or not (apps can also be
  // pinned by other means such as enterprise policies).
  // The eventual consistency (a sufficient amount of time after the rollout)
  // promise here is for this field to be synced with the pin ordinal:
  // `item_pin_ordinal.IsValid() <=> is_user_pinned.has_value()`.
  // However, it's okay for this contract to be violated in the meantine.
  //
  //  * missing value indicates that either `item_pin_ordinal` is invalid or
  //    this field is new and hasn't yet been processed by sync.
  //  * `true` means that the app was pinned by the user.
  //    This definition is used in a relaxed way -- for instance, default
  //    OS apps that are shown in the shelf (like Chrome itself) also have this
  //    value set to true.
  //  * `false` means that the app was pinned by PinnedLauncherApps policy.
  //    Note that user pin has priority: if an app was first pinned by the user
  //    and then additionally specified in PinnedLauncherApps, this value will
  //    be set to true.
  optional bool is_user_pinned = 9;

  // Identifier for the app package of the item. Package Ids are stable and
  // globally unique across app platforms, whereas App Id stored in item_id is
  // not.
  optional string promise_package_id = 10;
}