1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
// 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);
};
|
