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 "mojo/common/string16.mojom";
import "skia/public/interfaces/bitmap.mojom";
import "ui/events/mojo/event.mojom";

// 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.
};

// These values match ash::ShelfAlignment.
enum ShelfAlignment { BOTTOM, LEFT, RIGHT, BOTTOM_LOCKED, };

// These values match ash::ShelfAutoHideBehavior.
enum ShelfAutoHideBehavior { ALWAYS, NEVER, HIDDEN, };

// 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.
  ACTIVE,     // An active shelf item that has focus.
  ATTENTION,  // A shelf item that needs user's attention.
};

// The type of a shelf item.
// These values match ash::ShelfItemType.
enum ShelfItemType {
  PANEL,      // A running app panel.
  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.
  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 outside the app list.
  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.
};

// 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);

  // Set the shelf alignment and auto-hide behavior. See WmShelf for details.
  SetAlignment(ShelfAlignment alignment, int64 display_id);
  SetAutoHideBehavior(ShelfAutoHideBehavior auto_hide, int64 display_id);

  // Pin and unpin items on the shelf, or update shelf item images.
  PinItem(ShelfItem item, associated ShelfItemDelegate delegate);
  UnpinItem(string app_id);
  SetItemImage(string app_id, skia.mojom.Bitmap image);
};

// ShelfObserver is notified on shelf changes; used to persist profile settings.
interface ShelfObserver {
  OnShelfCreated(int64 display_id);
  OnAlignmentChanged(ShelfAlignment alignment, int64 display_id);
  OnAutoHideBehaviorChanged(ShelfAutoHideBehavior auto_hide, int64 display_id);
};

// 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(msw): Remove |display_id| once panels are removed. crbug.com/691099
  ItemSelected(ui.mojom.Event event,
               int64 display_id,
               ShelfLaunchSource source) => (ShelfAction action,
                                             array<MenuItem>? menu_items);

  // Called on invocation of a shelf item's context or application menu command.
  ExecuteCommand(uint32 command_id, int32 event_flags);

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

// MenuItems are used to populate application menus for shelf items.
// Note: Some menus only support a subset of these item features (eg. no icons).
// Note: These are not yet used for shelf item or ash shell context menus.
struct MenuItem {
  enum Type { ITEM, CHECK, RADIO, SEPARATOR, SUBMENU };

  Type type;                         // The type of the menu item.
  uint32 command_id;                 // The client's arbitrary item command id.
  mojo.common.mojom.String16 label;  // The string label, may be empty.
  skia.mojom.Bitmap image;           // The image icon, may be null.
  array<MenuItem>? submenu;          // The optional nested submenu item list.
  bool enabled;                      // The enabled state.
  bool checked;                      // The checked state.
  uint32 radio_group_id;             // The radio group id.
};

// ShelfItems are used to populate the shelf.
// This structure matches ash::ShelfItem.
struct ShelfItem {
  ShelfItemType type;       // The type of the shelf item.
  skia.mojom.Bitmap image;  // An icon image Bitmap, shown on the shelf.
  int64 shelf_id;           // A shelf model ID used by the shelf and clients.
  ShelfItemStatus status;   // The running/closed/etc. status of the item.
  string app_id;            // An app id string, used to match app windows.
  string launch_id;         // A string used to support multiple items per app.
                            // (eg. Citrix may use 'Word' or 'Excel' launch ids)
  mojo.common.mojom.String16 title;  // The title to display for tooltips, etc.
  bool shows_tooltip;       // Whether the tooltip should be shown on hover.
  bool pinned_by_policy;    // Whether the item is pinned by policy preferences,
                            // the user cannot un-pin these items.
};