source: trunk/doc/src/examples/systray.qdoc@ 109

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example desktop/systray
    \title System Tray Icon Example


    The System Tray Icon example shows how to add an icon with a menu
    and popup messages to a desktop environment's system tray.

    \image systemtray-example.png Screenshot of the System Tray Icon.

    Modern operating systems usually provide a special area on the
    desktop, called the system tray or notification area, where
    long-running applications can display icons and short messages.

    This example consists of one single class, \c Window, providing
    the main application window (i.e., an editor for the system tray
    icon) and the associated icon.

    \image systemtray-editor.png

    The editor allows the user to choose the preferred icon as well as
    set the balloon message's type and duration. The user can also
    edit the message's title and body. Finally, the editor provide a
    checkbox controlling whether the icon is actually shown in the
    system tray, or not.

    \section1 Window Class Definition

    The \c Window class inherits QWidget:

    \snippet examples/desktop/systray/window.h 0

    We implement several private slots to respond to user
    interaction. The other private functions are only convenience
    functions provided to simplify the constructor.

    The tray icon is an instance of the QSystemTrayIcon class. To
    check whether a system tray is present on the user's desktop, call
    the static QSystemTrayIcon::isSystemTrayAvailable()
    function. Associated with the icon, we provide a menu containing
    the typical \gui minimize, \gui maximize, \gui restore and \gui
    quit actions. We reimplement the QWidget::setVisible() function to
    update the tray icon's menu whenever the editor's appearance
    changes, e.g., when maximizing or minimizing the main application
    window.

    Finally, we reimplement QWidget's \l {QWidget::}{closeEvent()}
    function to be able to inform the user (when closing the editor
    window) that the program will keep running in the system tray
    until the user chooses the \gui Quit entry in the icon's context
    menu.

    \section1 Window Class Implementation

    When constructing the editor widget, we first create the various
    editor elements before we create the actual system tray icon:

    \snippet examples/desktop/systray/window.cpp 0

    We ensure that the application responds to user input by
    connecting most of the editor's input widgets (including the
    system tray icon) to the application's private slots. But note the
    visibility checkbox; its \l {QCheckBox::}{toggled()} signal is
    connected to the \e {icon}'s \l {QSystemTrayIcon::}{setVisible()}
    function instead.

    \snippet examples/desktop/systray/window.cpp 3

    The \c setIcon() slot is triggered whenever the current index in
    the icon combobox changes, i.e., whenever the user chooses another
    icon in the editor. Note that it is also called when the user
    activates the tray icon with the left mouse button, triggering the
    icon's \l {QSystemTrayIcon::}{activated()} signal. We will come
    back to this signal shortly.

    The QSystemTrayIcon::setIcon() function sets the \l
    {QSystemTrayIcon::}{icon} property that holds the actual system
    tray icon. On Windows, the system tray icon size is 16x16; on X11,
    the preferred size is 22x22. The icon will be scaled to the
    appropriate size as necessary.

    Note that on X11, due to a limitation in the system tray
    specification, mouse clicks on transparent areas in the icon are
    propagated to the system tray. If this behavior is unacceptable,
    we suggest using an icon with no transparency.

    \snippet examples/desktop/systray/window.cpp 4

    Whenever the user activates the system tray icon, it emits its \l
    {QSystemTrayIcon::}{activated()} signal passing the triggering
    reason as parameter. QSystemTrayIcon provides the \l
    {QSystemTrayIcon::}{ActivationReason} enum to describe how the
    icon was activated.

    In the constructor, we connected our icon's \l
    {QSystemTrayIcon::}{activated()} signal to our custom \c
    iconActivated() slot: If the user has clicked the icon using the
    left mouse button, this function changes the icon image by