doc/src/examples/systray.qdoc

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