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
|
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example webenginewidgets/notifications
\title WebEngine Notifications Example
\ingroup webengine-widgetexamples
\brief Demonstrates how to pass HTML5 web notifications to users.
\image notifications-example.png
\e {\WebEngine Notifications} demonstrates how to use the
\l QWebEngineProfile::setNotificationPresenter() method and
\l QWebEngineNotification class to show an HTML5 web
notification to the user.
\include examples-run.qdocinc
\section1 HTML Page
In this example, we create an internal HTML page that is added through
a resource collection file (.qrc). The page displays buttons for requesting
permissions and contains necessary JavaScript code to trigger this request:
\quotefromfile webenginewidgets/notifications/data/index.html
\skipto Notification.requestPermission
\printline requestPermission
\skipuntil resetPermission
\printuntil /\}\)$/
Also page contains a button for creating a notification. The following
JavaScript constructions are executed on the press event:
\quotefromfile webenginewidgets/notifications/data/index.html
\skipto createNotification()
\printuntil new Notification
\skipuntil Notification was created
\printline }
\section1 Main Function
In the \c main function, we instantiate a QWebEngineView, load our internal
HTML page, and set up the required callbacks for notifications handling.
\section2 Requesting Feature Permissions
We then use the \l QWebEnginePage::featurePermissionRequested() call to
request the user's permission to show notifications on their device.
\quotefromfile webenginewidgets/notifications/main.cpp
\skipto featurePermissionRequested
\printuntil });
\section2 Handling New Notifications
We then construct a \c NotificationPopup that encapsulates
the data of the HTML web notification. We also use the
\l QWebEngineProfile::setNotificationPresenter() call to set
our handler, which we use in conjunction with our \c popup
to handle all new notifications.
\skipto popup
\printuntil });
\section1 Presenting Notifications to Users
The \c NotificationPopup class in this example is a simple
QWidget-based class that uses multiple QLabel instances
for displaying the notification's title, message, and icon.
\quotefromfile webenginewidgets/notifications/notificationpopup.h
\skipto class NotificationPopup
\printto public:
\section2 Presenting Notifications
Inside the \c present method, we first close and release the previous
notification if we have one and then take ownership of a new notification
by calling the \c std::unique_ptr::swap method on our internal notification
instance.
\skipto present
\printto m_title
Then we query the notification instance for a title, a message,
and an icon by calling \l QWebEngineNotification::title(),
\l QWebEngineNotification::message(), \l QWebEngineNotification::icon()
and set up the appropriate labels in our popup.
\printuntil m_icon
After that we are ready to display our notification to the user
by calling the \l QWidget::show() method. On this step we also call the
\l QWebEngineNotification::show() method to notify \c JavaScript code
about our \e show event.
\printuntil notification->show
Finally, we set up a callback to handle the \e close event from the
\c JavaScript side by connecting to the \l QWebEngineNotification::closed()
signal. We also schedule a timer event to close our active notification
automatically.
\skipto QWebEngineNotification::closed
\printuntil QTimer
\skipto /\}/
\printline /\}/
\section2 Closing Active Notification
We execute the \e close step for the currently active notification either by
timeout or by handling the \c JavaScript event. First, we hide the popup
widget itself by calling \l QWidget::hide(). Then, we notify the \c JavaScript
code by calling the \l QWebEngineNotification::close() method. Finally, we
destroy the notification object through the \c std::unique_ptr::reset() method.
\skipto onClosed
\printuntil }
\section2 Implementing User Interaction
To implement the \e click step for a notification, we handle mouse interaction
through \l QWidget::mouseReleaseEvent(). On this event, the \c JavaScript code
is notified by calling the \l QWebEngineNotification::click() method.
Then we automatically perform the \e close step as a notification is
considered fully handled and no longer needed, and therefore can be destroyed.
\skipto mouseReleaseEvent
\printuntil onClosed
\printline /\}$/
\printline /\}$/
*/
|
