Debian Codegraph @

examples/widgets/desktop/systray/doc/src/systray.qdoc

raw
1 /****************************************************************************
2 **
3 ** Copyright (C) 2016 The Qt Company Ltd.
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see https://www.qt.io/terms-conditions. For further
15 ** information use the contact form at https://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file. Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \example desktop/systray
30 \title System Tray Icon Example
31 \ingroup examples-widgets
32 \brief The System Tray Icon example shows how to add an icon with a menu
33 and popup messages to a desktop environment's system tray.
34
35 \borderedimage systemtray-example.png
36 \caption Screenshot of the System Tray Icon
37
38 Modern operating systems usually provide a special area on the
39 desktop, called the system tray or notification area, where
40 long-running applications can display icons and short messages.
41
42 This example consists of one single class, \c Window, providing
43 the main application window (i.e., an editor for the system tray
44 icon) and the associated icon.
45
46 \borderedimage systemtray-editor.png
47
48 The editor allows the user to choose the preferred icon as well as
49 set the balloon message's type and duration. The user can also
50 edit the message's title and body. Finally, the editor provides a
51 checkbox controlling whether the icon is actually shown in the
52 system tray, or not.
53
54 \section1 Window Class Definition
55
56 The \c Window class inherits QWidget:
57
58 \snippet desktop/systray/window.h 0
59
60 We implement several private slots to respond to user
61 interaction. The other private functions are only convenience
62 functions provided to simplify the constructor.
63
64 The tray icon is an instance of the QSystemTrayIcon class. To
65 check whether a system tray is present on the user's desktop, call
66 the static QSystemTrayIcon::isSystemTrayAvailable()
67 function. Associated with the icon, we provide a menu containing
68 the typical \uicontrol minimize, \uicontrol maximize, \uicontrol restore and
69 \uicontrol quit actions. We reimplement the QWidget::setVisible() function to
70 update the tray icon's menu whenever the editor's appearance
71 changes, e.g., when maximizing or minimizing the main application
72 window.
73
74 Finally, we reimplement QWidget's \l {QWidget::}{closeEvent()}
75 function to be able to inform the user (when closing the editor
76 window) that the program will keep running in the system tray
77 until the user chooses the \uicontrol Quit entry in the icon's context
78 menu.
79
80 \section1 Window Class Implementation
81
82 When constructing the editor widget, we first create the various
83 editor elements before we create the actual system tray icon:
84
85 \snippet desktop/systray/window.cpp 0
86
87 We ensure that the application responds to user input by
88 connecting most of the editor's input widgets (including the
89 system tray icon) to the application's private slots. But note the
90 visibility checkbox; its \l {QCheckBox::}{toggled()} signal is
91 connected to the \e {icon}'s \l {QSystemTrayIcon::}{setVisible()}
92 function instead.
93
94 \snippet desktop/systray/window.cpp 3
95
96 The \c setIcon() slot is triggered whenever the current index in
97 the icon combobox changes, i.e., whenever the user chooses another
98 icon in the editor. Note that it is also called when the user
99 activates the tray icon with the left mouse button, triggering the
100 icon's \l {QSystemTrayIcon::}{activated()} signal. We will come
101 back to this signal shortly.
102
103 The QSystemTrayIcon::setIcon() function sets the \l
104 {QSystemTrayIcon::}{icon} property that holds the actual system
105 tray icon. On Windows, the system tray icon size is 16x16; on X11,
106 the preferred size is 22x22. The icon will be scaled to the
107 appropriate size as necessary.
108
109 Note that on X11, due to a limitation in the system tray
110 specification, mouse clicks on transparent areas in the icon are
111 propagated to the system tray. If this behavior is unacceptable,
112 we suggest using an icon with no transparency.
113
114 \snippet desktop/systray/window.cpp 4
115
116 Whenever the user activates the system tray icon, it emits its \l
117 {QSystemTrayIcon::}{activated()} signal passing the triggering
118 reason as parameter. QSystemTrayIcon provides the \l
119 {QSystemTrayIcon::}{ActivationReason} enum to describe how the
120 icon was activated.
121
122 In the constructor, we connected our icon's \l
123 {QSystemTrayIcon::}{activated()} signal to our custom \c
124 iconActivated() slot: If the user has clicked the icon using the
125 left mouse button, this function changes the icon image by
126 incrementing the icon combobox's current index, triggering the \c
127 setIcon() slot as mentioned above. If the user activates the icon
128 using the middle mouse button, it calls the custom \c
129 showMessage() slot:
130
131 \snippet desktop/systray/window.cpp 5
132
133 When the \e showMessage() slot is triggered, we first retrieve the
134 message icon depending on the currently chosen message type. The
135 QSystemTrayIcon::MessageIcon enum describes the icon that is shown
136 when a balloon message is displayed. Then we call
137 QSystemTrayIcon's \l {QSystemTrayIcon::}{showMessage()} function
138 to show the message with the title, body, and icon for the time
139 specified in milliseconds.
140
141 \macos users note: The Growl notification system must be
142 installed for QSystemTrayIcon::showMessage() to display messages.
143
144 QSystemTrayIcon also has the corresponding, \l {QSystemTrayIcon::}
145 {messageClicked()} signal, which is emitted when the user clicks a
146 message displayed by \l {QSystemTrayIcon::}{showMessage()}.
147
148 \snippet desktop/systray/window.cpp 6
149
150 In the constructor, we connected the \l
151 {QSystemTrayIcon::}{messageClicked()} signal to our custom \c
152 messageClicked() slot that simply displays a message using the
153 QMessageBox class.
154
155 QMessageBox provides a modal dialog with a short message, an icon,
156 and buttons laid out depending on the current style. It supports
157 four severity levels: "Question", "Information", "Warning" and
158 "Critical". The easiest way to pop up a message box in Qt is to
159 call one of the associated static functions, e.g.,
160 QMessageBox::information().
161
162 As we mentioned earlier, we reimplement a couple of QWidget's
163 virtual functions:
164
165 \snippet desktop/systray/window.cpp 1
166
167 Our reimplementation of the QWidget::setVisible() function updates
168 the tray icon's menu whenever the editor's appearance changes,
169 e.g., when maximizing or minimizing the main application window,
170 before calling the base class implementation.
171
172 \snippet desktop/systray/window.cpp 2
173
174 We have reimplemented the QWidget::closeEvent() event handler to
175 receive widget close events, showing the above message to the
176 users when they are closing the editor window. On \macos we need to
177 avoid showing the message and accepting the close event when the
178 user really intends to quit the application, that is, when the
179 user has triggered "Quit" in the menu bar or pressed the Command+Q
180 shortcut.
181
182 In addition to the functions and slots discussed above, we have
183 also implemented several convenience functions to simplify the
184 constructor: \c createIconGroupBox(), \c createMessageGroupBox(),
185 \c createActions() and \c createTrayIcon(). See the \c
186 {desktop/systray/window.cpp} file for details.
187 */