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