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