blob: b232dc9f621382590e44833680119b2c9beed82f [file] [log] [blame]
// Copyright 2018 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 "components/sync/mojo/syncer.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/content/public/mojom/navigable_contents_factory.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";
import "ui/gfx/image/mojo/image.mojom";
import "ui/gfx/range/mojo/range.mojom";
import "url/mojom/url.mojom";
// A structure holding the common information which is sent between ash and,
// chrome representing an app list item.
// This structure should be kept as small as possible so that minimum data
// is sent via mojo calls when an item is moved or reparented.
struct AppListItemMetadata {
string id; // The id of the app list item.
string name; // The corresponding app or folder's name of the item.
string short_name; // The corresponding app's short name of the item. It's
// empty if the app doesn't have one or it's a folder.
string folder_id; // The id of the item's folder.
syncer.mojom.StringOrdinal position; // The position of the item.
bool is_folder; // Whether this item is a folder.
bool is_persistent; // Whether this folder is allowed to contain 1 item.
gfx.mojom.ImageSkia? icon; // The icon of this item.
bool is_page_break; // Whether this item is a "page break" item.
// A structure holding the common information which is sent from chrome to ash,
// representing a search result.
struct SearchResultMetadata {
string id; // The id of the result.
mojo_base.mojom.String16 title; // The title of the result, e.g. an app's
// name, an autocomplete query, etc.
mojo_base.mojom.String16 details; // A detail string of this result.
mojo_base.mojom.String16 accessible_name;
// An text to be announced by a screen
// reader app.
array<SearchResultTag> title_tags; // How the title matches the query. See
// the SearchResultTag section for
// more details.
array<SearchResultTag> details_tags; // How the details match the query. See
// the SearchResultTag section for
// more details.
array<SearchResultAction> actions; // Actions that can be performed on this
// result. See the SearchResultAction
// section for more details.
float rating = -1.0; // The average rating score of the app
// corresponding to this result, ranged from 0 to
// 5. It's negative if there's no rating for the
// result.
mojo_base.mojom.String16 formatted_price; // A formatted price string, e.g.
// "$7.09", "HK$3.94", etc.
SearchResultType result_type; // The type of this result.
SearchResultDisplayType display_type = kList;
// How this result is displayed.
double display_score; // A score to determine the result display order.
bool is_omnibox_search; // Whether this result is searched from Omnibox.
bool is_installing; // Whether this result is installing.
url.mojom.Url? query_url; // A query URL associated with this result. The
// meaning and treatment of the URL
// (e.g. displaying inline web contents) is
// dependent on the result type.
string? equivalent_result_id; // An optional id that identifies an equivalent
// result to this result. Answer card result
// has this set to remove the equivalent
// omnibox search-what-you-typed result when
// there is an answer card for the query.
gfx.mojom.ImageSkia? icon; // The icon of this result.
gfx.mojom.ImageSkia? chip_icon; // The icon of this result in a smaller
// dimension to be rendered in suggestion
// chip view.
gfx.mojom.ImageSkia? badge_icon; // The badge icon of this result that
// indicates its type, e.g. installable from
// PlayStore, installable from WebStore,
// etc.
// If set to true, whether or not to send visibility updates through to to
// the chrome side when this result is set visible/invisible.
bool notify_visibility_change;
// All possible states of the app list.
enum AppListState {
kStateApps = 0,
// The status of the app list model.
enum AppListModelStatus {
kStatusSyncing, // Syncing apps or installing synced apps.
// The UI component the user launched the app from. Must match
// chrome/browser/ui/app_list/app_launch_event_logger.proto.
enum AppListLaunchedFrom {
kLaunchedFromGrid = 1,
// How the result should be displayed. Do not change the order of these as
// they are used for metrics.
enum SearchResultDisplayType {
kNone = 0,
// Add new values here.
// Type of the search result, which is set in Chrome.
enum SearchResultType {
kInstalledApp, // Installed apps.
kPlayStoreApp, // Installable apps from PlayStore.
kInstantApp, // Instant apps.
kInternalApp, // Chrome OS apps.
kWebStoreApp, // Installable apps from WebStore.
kWebStoreSearch, // A search query in WebStore.
kOmnibox, // Results from Omninbox.
kLauncher, // Results from launcher search (currently only from Files).
kAnswerCard, // WebContents based answer card.
kPlayStoreReinstallApp, // Reinstall recommendations from PlayStore.
kArcAppShortcut, // ARC++ app shortcuts.
// Add new values here.
// A tagged range in search result text.
struct SearchResultTag {
// Similar to ACMatchClassification::Style, the style values are not
// mutually exclusive.
int16 styles;
gfx.mojom.Range range;
// Data representing an action that can be performed on a search result.
// An action could be represented as an image button, it will be always visibe
// if |visible_on_hover| is false; otherwise how it is visible only when
// when its associated search result is hovered.
struct SearchResultAction {
mojo_base.mojom.String16 tooltip_text;
gfx.mojom.ImageSkia image;
bool visible_on_hover;
// The Chrome app list (aka Launcher), is the place where user can find and
// organize all installed apps, or search for various types of information.
// For apps:
// The app list displays apps synced across devices based on a user account, in
// an order that can be modified by the user. It supports up-to-3-layer app
// organization, the root app list, folders, and apps:
// - Each app can stay in the root app list or a folder.
// - Each folder holds more than one apps, which means it'll automatically get
// removed when there's only one app left in it.
// - The OEM folder is a special folder where we cannot move items to/from it.
// And we cannot rename it.
// - Other folders are renamable.
// - Folders cannot hold folders.
// - Different items/folders never have a same GUID.
// - Every item/folder has a same GUID on different devices.
// For searching:
// The app list supports various kinds of searching (e.g. apps, onmibox, etc).
// And search results can be displayed in different formats (e.g. tiles, cards).
// - Result ids are url like string, e.g.
// "chrome-extension://mgndgikekgjfcpckkfioiadnlibdjbkf/",
// "play://hhbckbkcbnemggclionhhgaceohjfdkl", etc.
// - Different search results never have a same id.
// - Every search result has a same id on different devices.
// - Every search result can have a list of actions (e.g. install), see
// app_list::SearchResult::Action.
// Users can long press on any app list item or search result to show a context
// menu. A context menu has a list of commands (e.g. open, uninstall, etc.).
// - Different items/results may have different command lists.
// - Each item/result usually has a same command list, but not always. Consider
// when we pin an app to the shelf and when we unpin it, the context menu
// looks different.
// - Inside each command list, each command has its own unique command id.
// - A same command in different command lists has a unique command id, see
// app_list::AppContextMenu::CommandId.
// The Chrome app list has its UI running in Ash, and everything else running in
// Chrome (e.g. syncing, user profile, etc). This controller is implemented in
// Ash to handle calls from Chrome. These include:
// - When app list data changes in Chrome, it should notifies the UI models and
// views in Ash to get updated. This can happen while syncing, searching, etc.
// - When Chrome needs real-time UI information from Ash. This can happen while
// calculating recommended search results based on the app list item order.
// - When app list states in Chrome change that require UI's response. This can
// happen while installing/uninstalling apps and the app list gets toggled.
interface AppListController {
// Sets a client to handle calls from Ash.
SetClient(AppListClient client);
// Interfaces that come from AppListModelUpdater:
// The following interfaces are called to update the app list model in Ash,
// including both the app list item model, search result model and search box
// model.
// Adds an item to AppListModel.
AddItem(AppListItemMetadata app_item);
// Adds an item into a certain folder in AppListModel.
AddItemToFolder(AppListItemMetadata app_item, string folder_id);
// Removes an item by its id from AppListModel.
RemoveItem(string id);
// Removes an item by its id, and also cleans up if its parent folder has a
// single child left.
RemoveUninstalledItem(string id);
// Moves the item with |id| to the folder with |folder_id|.
MoveItemToFolder(string id, string folder_id);
// Tells Ash what the current status of AppListModel should be,
// e.g. the model is under synchronization or in normal status.
SetStatus(AppListModelStatus status);
// Tells Ash what the current state of the app list should be,
// e.g. the user is searching for something, or showing apps, etc.
SetState(AppListState state);
// Highlights the given item in the app list. If not present and it is later
// added, the item will be highlighted after being added.
HighlightItemInstalledFromUI(string id);
// Sets whether the search engine is Google or not.
SetSearchEngineIsGoogle(bool is_google);
// Sets the text for screen readers on the search box, and updates the
// accessible names.
mojo_base.mojom.String16 tablet_accessible_name,
mojo_base.mojom.String16 clamshell_accessible_name);
// Sets the hint text to display when there is in input.
SetSearchHintText(mojo_base.mojom.String16 hint_text);
// Sets the text for the search box's Textfield and the voice search flag.
UpdateSearchBox(mojo_base.mojom.String16 text, bool initiated_by_user);
// Publishes search results to Ash to render them.
PublishSearchResults(array<SearchResultMetadata> results);
// Update the whole model, usually when profile changes happen in Chrome.
SetModelData(array<AppListItemMetadata> apps,
bool is_search_engine_google);
// Interfaces only used by ChromeAppListItem:
// These interfaces are called when an item's data is updated in Chrome.
// Updates an item's metadata (e.g. name, position, etc).
SetItemMetadata(string id, AppListItemMetadata metadata);
// Updates an item's icon.
SetItemIcon(string id, gfx.mojom.ImageSkia? icon);
// Updates whether an item is installing.
SetItemIsInstalling(string id, bool is_installing);
// Updates the downloaded percentage of an item.
SetItemPercentDownloaded(string id, int32 percent_downloaded);
// Interfaces for item querying:
// Returns a map from each item's id to its shown index in the app list.
GetIdToAppListIndexMap() => (map<string, uint16> indices);
// Interfaces for AppListSyncableService:
// These interfaces are called while dealing with the OEM folder in the
// AppListSyncableService in Chrome.
// Finds the OEM folder or creates one if it doesn't exist.
// |oem_folder_name|: the expected name of the OEM folder while creating.
// |preferred_oem_position|: the preferred position of the OEM folder while
// creating; if it's invalid then the final position
// is determined in Ash.
// |oem_folder|: the meta data of the existing/created OEM folder.
string oem_folder_name,
syncer.mojom.StringOrdinal preferred_oem_position)
=> (AppListItemMetadata oem_folder);
// Resolves the position of the OEM folder.
// |preferred_oem_position|: the preferred position of the OEM folder; if it's
// invalid then the final position is determined in
// Ash.
// |oem_folder|: the meta data of the OEM folder, or null if it doesn't exist.
syncer.mojom.StringOrdinal preferred_oem_position)
=> (AppListItemMetadata? oem_folder);
// Interfaces for ChromeSearchReult:
SetSearchResultMetadata(SearchResultMetadata metadata);
SetSearchResultIsInstalling(string result_id, bool is_installing);
SetSearchResultPercentDownloaded(string result_id, int32 percent_downloaded);
NotifySearchResultItemInstalled(string result_id);
// Interfaces for views:
// Dismisses the app list.
// Returns bounds of a rectangle to show an AppInfo dialog.
GetAppInfoDialogBounds() => (gfx.mojom.Rect bounds);
// Shows the app list and switches to |state|.
ShowAppListAndSwitchToState(AppListState state);
// Shows the app list.
// In contrast to AppListController, this client is implemented in Chrome to
// handle calls from Ash. These include:
// - When Chrome components are needed to get involved in the user's actions on
// app list views. This can happen while the user is searching, clicking on
// any app list item, etc.
// - When view changes in Ash and we want to notify Chrome. This can happen
// while app list is performing animations.
// - When a user action on views need information from Chrome to complete. This
// can happen while populating context menu models, which depends on item data
// in Chrome.
interface AppListClient {
// Interfaces on searching:
// Triggers a search query.
// |trimmed_query|: the trimmed input texts from the search text field.
StartSearch(mojo_base.mojom.String16 trimmed_query);
// Opens a search result when its view is clicked or pressed.
// |result_id|: the id of the search result the user wants to open.
OpenSearchResult(string result_id, int32 event_flags);
// Logs a click on the search result.
// |result_id|: the id of the search result that was clicked on.
// |suggestion_index|: the position of the result in the suggestion chip.
// |launched_from|: where the app was launched.
string result_id,
int32 suggestion_index,
AppListLaunchedFrom launched_from);
// Invokes a custom action on a result with |result_id|.
// |action_index| corresponds to the index of an action on the search result,
// for example, installing. They are stored in SearchResult::actions_.
InvokeSearchResultAction(string result_id,
int32 action_index,
int32 event_flags);
// Returns the context menu model for the search result with |result_id|, or
// an empty array if there is currently no menu for the result.
GetSearchResultContextMenuModel(string result_id) => (array<MenuItem> items);
// Invoked when a context menu item of a search result is clicked.
// |result_id|: the clicked search result's id.
// |command_id|: the clicked menu item's command id.
// |event_flags|: flags from the event which triggered this command.
SearchResultContextMenuItemSelected(string result_id,
int32 command_id,
int32 event_flags);
// Interfaces on the app list UI:
// Invoked when the app list is shown in the display with |display_id|.
ViewShown(int64 display_id);
// Invoked when the app list is closed.
// Notifies target visibility changes of the app list.
OnAppListTargetVisibilityChanged(bool visible);
// Notifies visibility changes of the app list.
OnAppListVisibilityChanged(bool visible);
// Interfaces on app list items:
// Activates (opens) the item with |id|.
ActivateItem(string id, int32 event_flags);
// Returns the context menu model for the item with |id|, or an empty array if
// there is currently no menu for the item (e.g. during install).
GetContextMenuModel(string id) => (array<MenuItem> items);
// Invoked when a context menu item of an app list item is clicked.
// |id|: the clicked AppListItem's id.
// |command_id|: the clicked menu item's command id.
// |event_flags|: flags from the event which triggered this command.
ContextMenuItemSelected(string id, int32 command_id, int32 event_flags);
// Invoked when a folder is created in Ash (e.g. merge items into a folder).
OnFolderCreated(AppListItemMetadata folder);
// Invoked when a folder has only one item left and so gets removed.
OnFolderDeleted(AppListItemMetadata folder);
// Invoked when user changes a folder's name or an item's position.
OnItemUpdated(AppListItemMetadata folder);
// Invoked when a "page break" item is added with |id| and |position|.
OnPageBreakItemAdded(string id, syncer.mojom.StringOrdinal position);
// Invoked when a "page break" item with |id| is deleted.
OnPageBreakItemDeleted(string id);
// Updated when item with |id| is set to |visible|. Only sent if
// |notify_visibility_change| was set on the SearchResultMetadata.
OnSearchResultVisibilityChanged(string id, bool visibility);
// Acquires a NavigableContentsFactory (indirectly) from the Content Service
// to allow the app list to display embedded web contents. Currently used only
// for answer card search results.
pending_receiver<content.mojom.NavigableContentsFactory> receiver);