blob: 9ca03f85f54d8fe70b4e6b6f5ce62bb59016e16f [file] [log] [blame]
// 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 {
// 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( 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.
// 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.