| 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 |
*/ |