diff options
Diffstat (limited to 'examples/widgets/doc')
| -rw-r--r-- | examples/widgets/doc/images/systemtray-editor.png | bin | 0 -> 18147 bytes | |||
| -rw-r--r-- | examples/widgets/doc/images/systemtray-example.png | bin | 0 -> 47588 bytes | |||
| -rw-r--r-- | examples/widgets/doc/src/icons.qdoc | 117 | ||||
| -rw-r--r-- | examples/widgets/doc/src/imageviewer.qdoc | 11 | ||||
| -rw-r--r-- | examples/widgets/doc/src/screenshot.qdoc | 90 | ||||
| -rw-r--r-- | examples/widgets/doc/src/systray.qdoc | 179 | ||||
| -rw-r--r-- | examples/widgets/doc/src/tetrix.qdoc | 2 |
7 files changed, 301 insertions, 98 deletions
diff --git a/examples/widgets/doc/images/systemtray-editor.png b/examples/widgets/doc/images/systemtray-editor.png Binary files differnew file mode 100644 index 0000000000..fb15dea8cb --- /dev/null +++ b/examples/widgets/doc/images/systemtray-editor.png diff --git a/examples/widgets/doc/images/systemtray-example.png b/examples/widgets/doc/images/systemtray-example.png Binary files differnew file mode 100644 index 0000000000..98b5c8133e --- /dev/null +++ b/examples/widgets/doc/images/systemtray-example.png diff --git a/examples/widgets/doc/src/icons.qdoc b/examples/widgets/doc/src/icons.qdoc index 5a902e1d98..16cdb5abd0 100644 --- a/examples/widgets/doc/src/icons.qdoc +++ b/examples/widgets/doc/src/icons.qdoc @@ -254,6 +254,21 @@ generated pixmaps corresponding to an icon's possible states and modes at a given size. + \snippet widgets/icons/iconpreviewarea.cpp 42 + + We would like the table columns to be in the order QIcon::Normal, + QIcon::Active, QIcon::Disabled, QIcon::Selected and the rows in the order + QIcon::Off, QIcon::On, which does not match the enumeration. The above code + provides arrays allowing to map from enumeration value to row/column + (by using QVector::indexOf()) and back by using the array index and lists + of the matching strings. Qt's containers can be easily populated by + using C++ 11 initializer lists. If the compiler does not provide that feature, + a pattern like + + \snippet widgets/icons/iconpreviewarea.cpp 43 + + can be used. + We need two public functions to set the current icon and the icon's size. In addition the class has three private functions: We use the \c createHeaderLabel() and \c createPixmapLabel() @@ -326,7 +341,12 @@ For each mode, and for each state, we retrieve a pixmap using the QIcon::pixmap() function, which generates a pixmap corresponding - to the given state, mode and size. + to the given state, mode and size. We pass the QWindows instance + obtained by calling QWidget::windowHandle() on the top level + widget (QWidget::nativeParentWidget()) in order to retrieve + the pixmap that matches best. + We format a tooltip displaying size, actual size and device pixel + ratio. \section2 MainWindow Class Definition @@ -347,8 +367,14 @@ \li The \c changeSize() slot changes the size of the preview area's icon. \li The \c changeIcon() slot updates the set of pixmaps available to the icon displayed in the preview area. - \li The \c addImage() slot allows the user to load a new image into the - application. + \li The \c addSampleImages() slot allows the user to load a new image + from the samples provided into the application. + \li The \c addOtherImages() slot allows the user to load a new image from + the directory obtained by calling + QStandardPaths::standardLocations(QStandardPaths::PicturesLocation). + \li The \c screenChanged() updates the display in the \uicontrol{High DPI} + group box to correctly display the parameters of the current screen + the window is located on. \endlist In addition we declare several private functions to simplify the @@ -362,8 +388,7 @@ widget and its child widgets, and put them in a grid layout. Then we create the menus with their associated entries and actions. - Before we resize the application window to a suitable size, we set - the window title and determine the current style for the + We set the window title and determine the current style for the application. We also enable the icon size spin box by clicking the associated radio button, making the current value of the spin box the icon's initial size. @@ -421,21 +446,27 @@ The \c changeSize() slot sets the size for the preview area's icon. - To determine the new size we first check if the spin box is + It is invoked by the QButtonGroup whose members are radio buttons for + controlling the icon size. In \c createIconSizeGroupBox(), each button is + assigned a QStyle::PixelMetric value as an id, which is passed as a + parameter to the slot. + + The special value \c OtherSize indicates that the spin box is enabled. If it is, we extract the extent of the new size from the - box. If it's not, we search through the predefined size options, - extract the QStyle::PixelMetric and use the QStyle::pixelMetric() - function to determine the extent. Then we create a QSize object - based on the extent, and use that object to set the size of the - preview area's icon. + box. If it's not, we query the style for the metric. Then we create + a QSize object based on the extent, and use that object to set the + size of the preview area's icon. \snippet widgets/icons/mainwindow.cpp 12 - The first thing we do when the \c addImage() slot is called, is to - show a file dialog to the user. The easiest way to create a file - dialog is to use QFileDialog's static functions. Here we use the - \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function - that will return one or more existing files selected by the user. + The function \c addImages() is called by the slot addSampleImages() + passing the samples directory, or by the slot addOtherImages() + passing the directory obtained by querying + QStandardPaths::standardLocations(). + + The first thing we do is to show a file dialog to the user. + We initialize it to show the filters returned by + QImageReader::supportedMimeTypes(). For each of the files the file dialog returns, we add a row to the table widget. The table widget is listing the images the user has @@ -446,9 +477,13 @@ We retrieve the image name using the QFileInfo::baseName() function that returns the base name of the file without the path, - and create the first table widget item in the row. Then we add the - file's complete name to the item's data. Since an item can hold - several information pieces, we need to assign the file name a role + and create the first table widget item in the row. + We check if a high resolution version of the image exists (identified by + the suffix \c @2x on the base name) and display that along with the size + in the tooltip. + + We add the file's complete name to the item's data. Since an item can + hold several information pieces, we need to assign the file name a role that will distinguish it from other data. This role can be Qt::UserRole or any value above it. @@ -465,7 +500,7 @@ contains "_act", "_dis", or "_sel", the modes are changed to Active, Disabled, or Selected. And if the file name contains "_on", the state is changed to On. The sample files in the - example's \c images subdirectory respect this naming convension. + example's \c images subdirectory respect this naming convention. \snippet widgets/icons/mainwindow.cpp 18 \snippet widgets/icons/mainwindow.cpp 19 @@ -482,7 +517,6 @@ make sure that the new image's check box is enabled. \snippet widgets/icons/mainwindow.cpp 6 - \snippet widgets/icons/mainwindow.cpp 7 The \c changeIcon() slot is called when the user alters the set of images listed in the QTableWidget, to update the QIcon object @@ -562,7 +596,7 @@ \snippet widgets/icons/mainwindow.cpp 25 At the end, we connect the QTableWidget::itemChanged() signal to - the \c changeIcon() slot to ensuret that the preview area is in + the \c changeIcon() slot to ensure that the preview area is in sync with the image table. \image icons_size_groupbox.png Screenshot of the icon size group box @@ -574,7 +608,14 @@ \snippet widgets/icons/mainwindow.cpp 26 First we create a group box that will contain all the widgets; - then we create the radio buttons and the spin box. + then we create the radio buttons and the spin box. We add the + radio buttons to an instance of QButtonGroup, using the value + of the QStyle::PixelMetric they represent as an integer id. + + \snippet widgets/icons/mainwindow.cpp 40 + + We introduce an enumeration constant \c OtherSize to represent + a custom size. The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. The \c IconSizeSpinBox class inherits QSpinBox and reimplements @@ -602,19 +643,16 @@ In particular we create the \c styleActionGroup based on the currently available GUI styles using QStyleFactory. QStyleFactory::keys() returns a list of valid keys, - typically including "windows", "cleanlooks" and - "plastique". Depending on the platform, "windowsxp", "windowsvista", "gtk" and - "macintosh" may be available. + typically including "windows" and "fusion". Depending on the platform, + "windowsvista" and "macintosh" may be available. We create one action for each key, and adds the action to the action group. Also, for each action, we call QAction::setData() with the style name. We will retrieve it later using QAction::data(). - \snippet widgets/icons/mainwindow.cpp 29 - - In the \c createMenu() function, we add the previously created - actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. + As we go along, we create the \uicontrol File, \uicontrol View and + \uicontrol Help menus and add the actions to them. The QMenu class provides a menu widget for use in menu bars, context menus, and other popup menus. We put each menu in the @@ -656,6 +694,13 @@ Q_ASSERT() macro to make sure that QStyleFactory::create() returned a valid pointer. + \snippet widgets/icons/mainwindow.cpp 44 + + We overload the show() function to set up the updating of the + current screen in \c screenChanged(). After calling QWidget::show(), + the QWindow associated with the QWidget is created and we can + connect to its QWindow::screenChanged() signal. + \section2 IconSizeSpinBox Class Definition \snippet widgets/icons/iconsizespinbox.h 0 @@ -690,7 +735,7 @@ reimplement the \c valueFromText() function to interpret the parameter text and return the associated int value. - We parse the text using a regular expression (a QRegExp). We + We parse the text using a regular expression (a QRegularExpression). We define an expression that matches one or several digits, optionally followed by whitespace, an "x" or the times symbol, whitespace and one or several digits again. @@ -748,7 +793,7 @@ index for editing. The parent widget and style option are used to control the appearance of the editor widget. - Our reimplementation create and populate a combobox instead of + Our reimplementation creates and populates a combobox instead of the default line edit. The contents of the combobox depends on the column in the table for which the editor is requested. Column 1 contains the QIcon modes, whereas column 2 contains the QIcon @@ -786,4 +831,12 @@ triggered the slot. This signal must be emitted when the editor widget has completed editing the data, and wants to write it back into the model. + + \section2 The Implementation of the Function main() + + \snippet widgets/icons/main.cpp 45 + + We use QCommandLineParser to handle any command line options or parameters + passed to the application. Then, we resize the main window according + to the available screen geometry and show it. */ diff --git a/examples/widgets/doc/src/imageviewer.qdoc b/examples/widgets/doc/src/imageviewer.qdoc index 91ae56b5d7..4457da9d6f 100644 --- a/examples/widgets/doc/src/imageviewer.qdoc +++ b/examples/widgets/doc/src/imageviewer.qdoc @@ -287,7 +287,8 @@ \snippet widgets/imageviewer/imageviewer.cpp 18 In the private \c createAction() function, we create the - actions providing the application features. + actions providing the application features and populate + a menu with them. We assign a short-cut key to each action and connect them to the appropriate slots. We only enable the \c openAct and \c exitAct at @@ -295,16 +296,10 @@ been loaded into the application. In addition we make the \c fitToWindowAct \l {QAction::checkable}{checkable}. - \snippet widgets/imageviewer/imageviewer.cpp 19 - \snippet widgets/imageviewer/imageviewer.cpp 20 - - In the private \c createMenu() function, we add the previously - created actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. - The QMenu class provides a menu widget for use in menu bars, context menus, and other popup menus. The QMenuBar class provides a horizontal menu bar that consists of a list of pull-down menu - items. So at the end we put the menus in the \c {ImageViewer}'s + items. So we put the menus in the \c {ImageViewer}'s menu bar which we retrieve with the QMainWindow::menuBar() function. diff --git a/examples/widgets/doc/src/screenshot.qdoc b/examples/widgets/doc/src/screenshot.qdoc index 32c4df9ec2..b376b6ce0e 100644 --- a/examples/widgets/doc/src/screenshot.qdoc +++ b/examples/widgets/doc/src/screenshot.qdoc @@ -33,7 +33,7 @@ desktop. \brief The Screenshot example shows how to take a screenshot of the - desktop using QApplication and QDesktopWidget. It also shows how + desktop using QScreen. It also shows how to use QTimer to provide a single-shot timer, and how to reimplement the QWidget::resizeEvent() event handler to make sure that an application resizes smoothly and without data loss. @@ -73,12 +73,9 @@ \uicontrol {Hide This Window} option. \endlist - We also declare some private functions: We use the \c - createOptionsGroupBox(), \c createButtonsLayout() and \c - createButton() functions when we construct the widget. And we call - the private \c updateScreenshotLabel() function whenever a new - screenshot is taken or when a resize event changes the size of the - screenshot preview label. + We also declare the private function \c updateScreenshotLabel() which + is called whenever a new screenshot is taken or when a resize event + changes the size of the screenshot preview label. In addition we need to store the screenshot's original pixmap. The reason is that when we display the preview of the screenshot, we @@ -100,11 +97,18 @@ aligned in the center of the \c Screenshot widget, and set its minimum size. + Next, we create a group box that will contain all of the options' + widgets. Then we create a QSpinBox and a QLabel for the \uicontrol + {Screenshot Delay} option, and connect the spinbox to the \c + updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol + {Hide This Window} option, add all the options' widgets to a + QGridLayout installed on the group box. + We create the applications's buttons and the group box containing the application's options, and put it all into a main layout. Finally we take the initial screenshot, and set the initial delay and the window title, before we resize the widget to a - suitable size. + suitable size depending on the screen geometry. \snippet desktop/screenshot/screenshot.cpp 1 @@ -151,34 +155,37 @@ QFileDialog enables a user to traverse the file system in order to select one or many files or a directory. The easiest way to create a QFileDialog is to use the convenience static - functions. + functions. Here, we instantiate the dialog on the stack in order + to be able to set up the supported mime types of QImageWriter, + allowing the user to save in a variety of formats. We define the default file format to be png, and we make the file - dialog's initial path the path the application is run from. We - create the file dialog using the static - QFileDialog::getSaveFileName() function which returns a file name - selected by the user. The file does not have to exist. If the file + dialog's initial path the location of pictures as obtained from + QStandardPaths, defaulting to the path the application is run from. + + We run the dialog by invoking QDialog::exec() and return if the + user canceled the dialog. If the dialog has been accepted, we + obtain a file name by calling QFileDialog::selectedFiles(). + The file does not have to exist. If the file name is valid, we use the QPixmap::save() function to save the screenshot's original pixmap in that file. \snippet desktop/screenshot/screenshot.cpp 4 - The \c shootScreen() slot is called to take the screenshot. If the - user has chosen to delay the screenshot, we make the application - beep when the screenshot is taken using the static - QApplication::beep() function. - - The QApplication class manages the GUI application's control flow - and main settings. It contains the main event loop, where all - events from the window system and other sources are processed and - dispatched. + The \c shootScreen() slot is called to take the screenshot. - \snippet desktop/screenshot/screenshot.cpp 5 + First, we find the instance of QScreen the window is located + by retrieving the QWindow and its QScreen, defaulting + to the primary screen. If no screen can be found, we return. + Although this is unlikely to happen, applications should check + for null pointers since there might be situations in which no + screen is connected. - Using the static function QApplication::primaryScreen(), we - obtain the QScreen object for the application's main screen. + If the user has chosen to delay the screenshot, we make the application + beep when the screenshot is taken using the static + QApplication::beep() function. - We take the screenshot using the QScreen::grabWindow() + We then take the screenshot using the QScreen::grabWindow() function. The function grabs the contents of the window passed as an argument, makes a pixmap out of it and returns that pixmap. The window id can be obtained with QWidget::winId() or QWindow::winId(). @@ -200,37 +207,6 @@ The \c updateCheckBox() slot is called whenever the user changes the delay using the \uicontrol {Screenshot Delay} option. - \snippet desktop/screenshot/screenshot.cpp 7 - - The private \c createOptionsGroupBox() function is called from the - constructor. - - First we create a group box that will contain all of the options' - widgets. Then we create a QSpinBox and a QLabel for the \uicontrol - {Screenshot Delay} option, and connect the spinbox to the \c - updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol - {Hide This Window} option, add all the options' widgets to a - QGridLayout and install the layout on the group box. - - Note that we don't have to specify any parents for the widgets - when we create them. The reason is that when we add a widget to a - layout and install the layout on another widget, the layout's - widgets are automatically reparented to the widget the layout is - installed on. - - \snippet desktop/screenshot/screenshot.cpp 8 - - The private \c createButtonsLayout() function is called from the - constructor. We create the application's buttons using the private - \c createButton() function, and add them to a QHBoxLayout. - - \snippet desktop/screenshot/screenshot.cpp 9 - - The private \c createButton() function is called from the \c - createButtonsLayout() function. It simply creates a QPushButton - with the provided text, connects it to the provided receiver and - slot, and returns a pointer to the button. - \snippet desktop/screenshot/screenshot.cpp 10 The private \c updateScreenshotLabel() function is called whenever diff --git a/examples/widgets/doc/src/systray.qdoc b/examples/widgets/doc/src/systray.qdoc new file mode 100644 index 0000000000..b05f999dfa --- /dev/null +++ b/examples/widgets/doc/src/systray.qdoc @@ -0,0 +1,179 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example desktop/systray + \title System Tray Icon Example + \ingroup examples-widgets + \brief 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 provides 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 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 \uicontrol minimize, \uicontrol maximize, \uicontrol restore and + \uicontrol 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 \uicontrol 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 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 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 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 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. + + QSystemTrayIcon also has the corresponding, \l {QSystemTrayIcon::} + {messageClicked()} signal, which is emitted when the user clicks a + message displayed by \l {QSystemTrayIcon::}{showMessage()}. + + \snippet 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 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 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. +*/ diff --git a/examples/widgets/doc/src/tetrix.qdoc b/examples/widgets/doc/src/tetrix.qdoc index f74d3c14d5..6050fe2356 100644 --- a/examples/widgets/doc/src/tetrix.qdoc +++ b/examples/widgets/doc/src/tetrix.qdoc @@ -108,7 +108,7 @@ We connect \l{QAbstractButton::}{clicked()} signals from the \uicontrol{Start} and \uicontrol{Pause} buttons to the board, and from the \uicontrol{Quit} button to the - application's \l{QApplication::}{quit()} slot. + application's \l{QCoreApplication::quit()} slot. \snippet widgets/tetrix/tetrixwindow.cpp 4 \snippet widgets/tetrix/tetrixwindow.cpp 5 |
