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
|
// 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.
#ifndef CHROME_BROWSER_UI_USER_EDUCATION_SHOW_PROMO_IN_PAGE_H_
#define CHROME_BROWSER_UI_USER_EDUCATION_SHOW_PROMO_IN_PAGE_H_
#include <optional>
#include <string>
#include "base/callback_list.h"
#include "base/functional/callback_forward.h"
#include "base/functional/callback_helpers.h"
#include "base/memory/weak_ptr.h"
#include "base/time/time.h"
#include "chrome/browser/ui/user_education/user_education_types.h"
#include "components/user_education/common/help_bubble/help_bubble_params.h"
#include "ui/base/interaction/element_identifier.h"
#include "url/gurl.h"
namespace user_education {
class HelpBubble;
} // namespace user_education
class Browser;
// Utility for opening a page (optionally) and showing a help bubble on a
// predetermined element. The object exists only as long as the operation
// is in progress or the help bubble is visible. If a `target_url` is
// defined in the parameters, this page will be opened. If `target_url`
// is omitted, the current page will be used to look for the anchor.
//
// Example:
//
// // Open security settings page and show a help bubble promoting the
// // "Enhanced Protection" user setting.
// ShowPromoInPage::Params params;
//
// // This WebUI page must be instrumented for help bubbles; see
// // components/user_education/webui/README.md
// params.target_url = "chrome://settings/security";
//
// // This specifies what will be shown in the help bubble and how and where
// // it will be positioned.
// params.bubble_anchor_id = kEnhancedSecuritySettingElementId;
// params.bubble_arrow = user_education::HelpBubbleArrow::kBottomLeft;
// params.bubble_text =
// l10n_util::GetStringUTF16(IDS_ENABLE_ENHANCED_PROTECTION_PROMO);
//
// // Log whenever a user actually sees the promo.
// params.callback = base::BindOnce(&::MaybeLogEnhancedSecurityPromoShown);
//
// // Shows the page and the bubble. Because we did not specify
// // |params.page_open_mode|, the settings page will be opened in a
// // new tab in |browser_| rather than the current tab.
// ShowPromoInPage::Start(browser_, std::move(params));
//
class ShowPromoInPage {
public:
// Called when the help bubble is shown or if it fails/times out. On failure,
// `source` is destroyed immediately after this call.
using Callback =
base::OnceCallback<void(ShowPromoInPage* source, bool success)>;
struct Params {
Params();
Params(Params&& other) noexcept;
Params& operator=(Params&& other) noexcept;
~Params();
// The page to open. If not specified, the current page will be used.
std::optional<GURL> target_url = std::nullopt;
// How the page should be opened. Default is kNewForegroundTab as most
// promos are expected to be opened in new tabs to avoid disrupting the
// user's flow in the current tab and potentially lose what they had open.
user_education::PageOpenMode page_open_mode =
user_education::PageOpenMode::kNewForegroundTab;
// The element to anchor to. See //components/user_education/webui/README.md
// for an explanation on how to instrument a WebUI page for Help Bubbles and
// how to associated a ui::ElementIdentifier with an HTML element.
ui::ElementIdentifier bubble_anchor_id;
// How the help bubble should anchor to the anchor element.
user_education::HelpBubbleArrow bubble_arrow;
// The text of the help bubble.
std::u16string bubble_text;
// The id of the text that should be used for the accessibility label of the
// help bubble's close button. The localized string will be looked up using
// this identifier.
std::optional<int> close_button_alt_text_id;
// Callback that notifies whether the page loaded and the bubble was
// displayed successfully. Typically used for testing or metrics collection.
// If the page load is aborted or the anchor not found within a reasonable
// amount of time, is called with `success` = false.
Callback callback = base::DoNothing();
// Overrides the default timeout for the bubble to be shown; only use for
// integration testing.
std::optional<base::TimeDelta> timeout_override_for_testing;
};
ShowPromoInPage(const ShowPromoInPage&) = delete;
virtual ~ShowPromoInPage();
void operator=(const ShowPromoInPage&) = delete;
// Opens the page in `browser` and displays a Help Bubble as described by
// `params`. This method must be called on the UI thread.
static base::WeakPtr<ShowPromoInPage> Start(Browser* browser, Params params);
// Returns the help bubble if one was created.
virtual user_education::HelpBubble* GetHelpBubbleForTesting() = 0;
protected:
ShowPromoInPage();
};
#endif // CHROME_BROWSER_UI_USER_EDUCATION_SHOW_PROMO_IN_PAGE_H_
|
