blob: ed01b3c5a3b32cec7b47896f8c8de3e9cc4b5b87 [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 "mojo/common/string16.mojom";
import "ui/events/mojo/event.mojom";
import "ui/gfx/image/mojo/image.mojom";
// The types of menu items shown in shelf context and application list menus.
// These values roughly match ui::MenuModel::ItemType (sans TYPE_BUTTON_ITEM).
enum MenuItemType {
COMMAND, // An item that performs an action when selected.
CHECK, // An item that can be selected/checked to toggle a boolean state.
RADIO, // An item that can be selected/checked among a group of choices.
SEPARATOR, // An item that shows a horizontal line separator.
SUBMENU, // An item that presents a submenu within another menu.
};
// 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.
};
// 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 {
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.
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 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);
// 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);
};
// 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();
};
// MenuItems are used to populate application menus for shelf items.
// Note: Some menus only support a subset of these item features (eg. no icons).
struct MenuItem {
MenuItemType type; // The type of the menu item.
int64 command_id; // The client's arbitrary item command id.
mojo.common.mojom.String16 label; // The string label, may be empty.
gfx.mojom.ImageSkia? 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.
int64 radio_group_id; // The radio group id.
};
// 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.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 prefs,
// the user cannot un-pin these items.
};