ash/public/interfaces/shelf.mojom

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module ash.mojom;

import "ash/public/interfaces/menu.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "ui/events/mojo/event.mojom";
import "ui/gfx/image/mojo/image.mojom";

// These values match ash::ShelfAutoHideBehavior.
enum ShelfAutoHideBehavior {
  SHELF_AUTO_HIDE_BEHAVIOR_ALWAYS,  // Always auto-hide.
  SHELF_AUTO_HIDE_BEHAVIOR_NEVER,   // Never auto-hide.
  SHELF_AUTO_HIDE_ALWAYS_HIDDEN,    // Always hide.
};

// The actions that may be performed when a shelf item is selected.
// These values match ash::ShelfAction.
enum ShelfAction {
  NONE,              // No action was taken.
  WINDOW_CREATED,    // A new window was created.
  WINDOW_ACTIVATED,  // An existing inactive window was activated.
  WINDOW_MINIMIZED,  // The currently active window was minimized.
  APP_LIST_SHOWN,    // The app list launcher menu was shown.
  APP_LIST_DISMISSED,// The app list launcher menu was dismissed.
};

// Represents the status of items in the shelf.
// These values match ash::ShelfItemStatus.
enum ShelfItemStatus {
  CLOSED,     // A closed shelf item, i.e. has no live instance.
  RUNNING,    // A shelf item that has live instance.
  ATTENTION,  // A shelf item that needs user's attention.
};

// The type of a shelf item.
// These values match ash::ShelfItemType.
enum ShelfItemType {
  PINNED_APP,  // A pinned app, which may be running or not.
  APP_LIST,    // An item that toggles visiblity of the app list.
  BROWSER,     // The browser shortcut, the browser may be running or not.
  APP,         // An unpinned running app window. Supports these app types:
               // - Extension "V1" (legacy packaged and hosted) apps,
               // - Extension "V2" (platform) apps,
               // - ARC (App Runtime for Chrome - Android Play Store) apps.
  DIALOG,      // An open dialog.
  BACK_BUTTON, // The back button, which is shown in tablet mode.
  UNDEFINED,   // Default value.
};

// Source of the launch or activation request, for tracking.
// These values match ash::ShelfLaunchSource.
enum ShelfLaunchSource {
  UNKNOWN,          // The item was launched from elsewhere.
  APP_LIST,         // The item was launched from a generic app list view.
  APP_LIST_SEARCH,  // The item was launched from an app list search view.
  SHELF,            // The item was launched from the shelf.
};

// The Shelf controller allows clients (eg. Chrome) to control the ash shelf.
interface ShelfController {
  // Observers are immediately notified of the current shelf states when added.
  AddObserver(associated ShelfObserver observer);

  // Note: ShelfObservers are not notified of ShelfModel changes made by the
  // ShelfItem functions below. Chrome is the solitary ShelfObserver and client
  // of these functions, so notifications would be cyclical and problematic.

  // Add |item| at |index|, which is clamped to be greater than 0 (AppList's
  // index) and not exceeding the item count. Use a negative |index| to append.
  AddShelfItem(int32 index, ShelfItem item);
  // Remove the item with |id|. Bails if |id| is unknown or for the AppList.
  RemoveShelfItem(ShelfID id);
  // Moves item with |id| to |index|, which is in terms of the model after the
  // item is removed, and is clamped to be greater than 0 (AppList's index) and
  // not exceeding the item count. Bails if |id| is unknown or for the AppList.
  MoveShelfItem(ShelfID id, int32 target_index);
  // Updates |item| via ShelfID. Bails if the id is unknown or for the AppList.
  // Clients may pass null images to signal no change and avoid transport costs.
  UpdateShelfItem(ShelfItem item);
  // Sets the |delegate| for the item with |id|.
  SetShelfItemDelegate(ShelfID id, ShelfItemDelegate delegate);
  // Returns the auto hide behavior. For testing only.
  // |display_id| represents the display that contains the shelf. |display_id|
  // must be valid.
  GetAutoHideBehaviorForTesting(int64 display_id)
                                => (ShelfAutoHideBehavior behavior);
  // Sets the auto hide behavior. For testing only.
  // |display_id| represents the display that contains the shelf. |display_id|
  // must be valid.
  // |behavior| is the new behavior.
  SetAutoHideBehaviorForTesting(int64 display_id,
                                ShelfAutoHideBehavior behavior) => ();
};

// A Shelf observer, used to persist profile settings and cache a ShelfModel.
interface ShelfObserver {
  // Called when the |item| has been added at |index|.
  // This passes null images to avoid transport costs; clients don't use images.
  OnShelfItemAdded(int32 index, ShelfItem item);
  // Called when the item with |id| has been removed.
  OnShelfItemRemoved(ShelfID id);
  // Called when the item with |id| has been moved to |index|.
  OnShelfItemMoved(ShelfID id, int32 index);
  // Called when the |item| with matching ShelfID has been updated.
  // This passes null images to avoid transport costs; clients don't use images.
  OnShelfItemUpdated(ShelfItem item);
  // Called when |delegate| for the item with |id| has been changed.
  OnShelfItemDelegateChanged(ShelfID id, ShelfItemDelegate delegate);
};

// ShelfItemDelegate handles shelf item selection, menu command execution, etc.
interface ShelfItemDelegate {
  // Called when the user selects a shelf item. The event, display, and source
  // info should be provided if known; some implementations use these arguments.
  // Defaults: (nullptr, kInvalidDisplayId, LAUNCH_FROM_UNKNOWN)
  // The callback reports the action taken and any app menu items to show.
  //
  // NOTE: This codepath is not currently used for context menu triggering.
  // TODO(crbug.com/691099): Remove |display_id| once panels are removed.
  ItemSelected(ui.mojom.Event event,
               int64 display_id,
               ShelfLaunchSource source) => (ShelfAction action,
                                             array<MenuItem>? menu_items);

  // Called when spawning a shelf item context menu, returns custom menu items.
  // TODO(mash): Clients should push context menu items to Ash's shelf model.
  GetContextMenuItems(int64 display_id) => (array<MenuItem> items);

  // Called on invocation of a shelf item's context or application menu command.
  // |from_context_menu| is true if the command came from a context menu, or
  // false if the command came from an application menu. If the |display_id| is
  // unknown or irrelevant, callers may pass |display::kInvalidDisplayId|.
  ExecuteCommand(bool from_context_menu,
                 int64 command_id,
                 int32 event_flags,
                 int64 display_id);

  // Closes all windows associated with this shelf item.
  Close();
};

// Identifier for shelf items and their windows.
// This structure matches ash::ShelfID.
struct ShelfID {
  string app_id;            // An app id string, used to match app windows.
                            // (eg. extension ids, arc ids, "AppList", etc.)
  string launch_id;         // A string used to support multiple items per app.
                            // (eg. Citrix may use 'Word' or 'Excel' launch ids)
};

// ShelfItems are used to populate the shelf.
// This structure matches ash::ShelfItem.
struct ShelfItem {
  ShelfItemType type;          // The type of the shelf item.
  gfx.mojom.ImageSkia? image;  // The icon shown on the shelf; null for updates
                               // with no icon change, null for ShelfObservers.
  ShelfItemStatus status;      // The running/closed/etc. status of the item.
  ShelfID shelf_id;            // The id for the shelf item and its windows.
  mojo_base.mojom.String16 title;  // The title to display for tooltips, etc.
  bool pinned_by_policy;       // Whether the item is pinned by policy prefs,
                               // the user cannot un-pin these items.
};