--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/systray.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,197 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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
+ incrementing the icon combobox's current index, triggering the \c
+ setIcon() slot as mentioned above. If the user activates the icon
+ using the middle mouse button, it calls the custom \c
+ showMessage() slot:
+
+ \snippet examples/desktop/systray/window.cpp 5
+
+ When the \e showMessage() slot is triggered, we first retrieve the
+ message icon depending on the currently chosen message type. The
+ QSystemTrayIcon::MessageIcon enum describes the icon that is shown
+ when a balloon message is displayed. Then we call
+ QSystemTrayIcon's \l {QSystemTrayIcon::}{showMessage()} function
+ to show the message with the title, body, and icon for the time
+ specified in milliseconds.
+
+ Mac OS X users note: The Growl notification system must be
+ installed for QSystemTrayIcon::showMessage() to display messages.
+
+ QSystemTrayIcon also has the corresponding, \l {QSystemTrayIcon::}
+ {messageClicked()} signal, which is emitted when the user clicks a
+ message displayed by \l {QSystemTrayIcon::}{showMessage()}.
+
+ \snippet examples/desktop/systray/window.cpp 6
+
+ In the constructor, we connected the \l
+ {QSystemTrayIcon::}{messageClicked()} signal to our custom \c
+ messageClicked() slot that simply displays a message using the
+ QMessageBox class.
+
+ QMessageBox provides a modal dialog with a short message, an icon,
+ and buttons laid out depending on the current style. It supports
+ four severity levels: "Question", "Information", "Warning" and
+ "Critical". The easiest way to pop up a message box in Qt is to
+ call one of the associated static functions, e.g.,
+ QMessageBox::information().
+
+ As we mentioned earlier, we reimplement a couple of QWidget's
+ virtual functions:
+
+ \snippet examples/desktop/systray/window.cpp 1
+
+ Our reimplementation of the QWidget::setVisible() function updates
+ the tray icon's menu whenever the editor's appearance changes,
+ e.g., when maximizing or minimizing the main application window,
+ before calling the base class implementation.
+
+ \snippet examples/desktop/systray/window.cpp 2
+
+ We have reimplemented the QWidget::closeEvent() event handler to
+ receive widget close events, showing the above message to the
+ users when they are closing the editor window.
+
+ In addition to the functions and slots discussed above, we have
+ also implemented several convenience functions to simplify the
+ constructor: \c createIconGroupBox(), \c createMessageGroupBox(),
+ \c createActions() and \c createTrayIcon(). See the \l
+ {desktop/systray/window.cpp}{window.cpp} file for details.
+*/