// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
module help_bubble.mojom;
import "mojo/public/mojom/base/time.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
// Contains IPC calls that allow the HelpBubbleFactory system to connect to
// the HelpBubbleMixin and HelpBubbleElement component.
//
// The calls here allow User Education systems that use the HelpBubble
// architecture to display help bubbles in WebUI surfaces (including pages like
// Settings and secondary UI elements such as the Sidebar).
//
// Systems expected to use this IPC include FeaturePromo and Tutorials. For
// more detailed usage information, see README.md.
// Where the help bubble floats relative to its anchor.
enum HelpBubbleArrowPosition {
TOP_LEFT,
TOP_CENTER,
TOP_RIGHT,
BOTTOM_LEFT,
BOTTOM_CENTER,
BOTTOM_RIGHT,
LEFT_TOP,
LEFT_CENTER,
LEFT_BOTTOM,
RIGHT_TOP,
RIGHT_CENTER,
RIGHT_BOTTOM,
};
// Reason for dismissing a help bubble
enum HelpBubbleClosedReason {
// page navigated away, anchor disappeared, etc.
kPageChanged,
// user dismissed via button or close-icon
kDismissedByUser,
// timeout reached
kTimedOut,
};
// Simplified version of user_education::HelpBubbleButtonParams.
struct HelpBubbleButtonParams {
string text;
bool is_default = false;
};
// Progress indicator for tutorial bubbles.
struct Progress {
uint8 current;
uint8 total;
};
// Simplified version of user_education::HelpBubbleParams.
struct HelpBubbleParams {
// Holds the name of the ElementIdentifier used to identify the help bubble's
// anchor in C++ code. The HelpBubbleMixin then maps this to a specific HTML
// element ID.
string native_identifier;
HelpBubbleArrowPosition position = HelpBubbleArrowPosition.TOP_CENTER;
string? title_text;
string body_text;
string close_button_alt_text;
string? body_icon_name;
string body_icon_alt_text;
Progress? progress;
array<HelpBubbleButtonParams> buttons;
// The caller can specify a preference for the bubble taking focus (true), or
// not taking focus (false). This is just a hint and does not force the bubble
// to take or not take focus; the bubble may choose to ignore the hint to
// avoid potential accessibility issues.
//
// See also: user_education::HelpBubbleParams::focus_on_show_hint
bool? focus_on_show_hint;
// Auto-dismiss timeout as TimeDelta
mojo_base.mojom.TimeDelta? timeout;
};
// Used by the controller to bootstrap IPC. Any WebUIController can implement
// this interface to use help bubbles; see README.md for more information.
interface HelpBubbleHandlerFactory {
// This method is called on bootstrap to create the browser-side handler.
CreateHelpBubbleHandler(
pending_remote<HelpBubbleClient> client,
pending_receiver<HelpBubbleHandler> handler);
};
// Object which handles the C++/browser side of help bubble management for a
// WebUIController.
//
// Help bubbles are anchored to specific elements in the UI, identified by
// ui::ElementIdentifiers. The HelpBubbleMixin maps this to an HTML id within
// its component.
//
// We always use the name of the ElementIdentifier (`native_identifier`) when
// showing a help bubble or when communicating events back to the handler on the
// browser side, because HTML ids can be ambiguous within a document with shadow
// DOMs.
//
// TODO(crbug.com/40243115): consider splitting into ElementTrackerHandler and
// HelpBubbleHandler, with the previous handling show/hide/activated/custom
// events and the latter handling the help bubble itself.
interface HelpBubbleHandler {
// Indicates that the visibility of the element that the help bubble could be
// anchored to has changed.
HelpBubbleAnchorVisibilityChanged(string native_identifier,
bool visible,
gfx.mojom.RectF rect);
// Notifies that a specific element tagged as a help bubble anchor has been
// activated, which will in turn be propagated through the ui::ElementTracker
// system as an EventType::kActivated.
//
// As with the above methods, the ui::ElementIdentifier will be generated from
// `native_identifier`.
HelpBubbleAnchorActivated(string native_identifier);
// Notifies that a custom event has occurred associated with a particular help
// bubble anchor, which will in turn be propagated through the
// ui::ElementTracker system as an EventType::kCustomEvent.
//
// As with the above methods, the ui::ElementIdentifier will be generated from
// `native_identifier` and the ui::CustomElementEventType will be generated
// from `custom_event_name`.
HelpBubbleAnchorCustomEvent(string native_identifier,
string custom_event_name);
// Notifies that a button on the help bubble anchored to `native_identifier`
// has been pressed and the help bubble is closing as a result. The
// `buttonIndex` parameter will be set to the (0-indexed) index of the button
// as it was specified in the `HelpBubbleParams.buttons` used to show the help
// bubble.
HelpBubbleButtonPressed(string native_identifier, uint8 button_index);
// Called when the help bubble anchored to `native_identifier` is closed,
// either because the element it is associated with goes away, the user
// canceled it (e.g. pressed the [x] button), or the timeout was reached.
HelpBubbleClosed(string native_identifier, HelpBubbleClosedReason reason);
};
// Represents WebUI component that can display help bubbles. The implementing UI
// should use a HelpBubbleMixin; see README.md for detailed instructions.
interface HelpBubbleClient {
// Shows a help bubble with parameters defined by `params` attached to
// `target`.
ShowHelpBubble(HelpBubbleParams params);
// Toggles focus to the help bubble anchored to `native_identifier` or to its
// anchor element.
ToggleFocusForAccessibility(string native_identifier);
// Invoked to hide the help bubble anchored to `native_identifier` if it
// should no longer be shown.
HideHelpBubble(string native_identifier);
// Notifies the client that an external help bubble (i.e. one owned/displayed
// by the handler) anchored to `native_identifier` has been shown or hidden.
// The client may change the visual appearance of the anchor as a result.
ExternalHelpBubbleUpdated(string native_identifier, bool shown);
};
Codebase Browser
chromium