1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 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 */