path: root/examples/widgets/doc/src/screenshot.qdoc
diff options
authorFrederik Gladhorn <>2012-09-18 20:32:53 +0200
committerThe Qt Project <>2012-09-21 19:59:06 +0200
commitd16c565ca6a55788435c52ad45647eda67854d80 (patch)
tree17e2c192b412e4959d422c1691e74ad172601ff7 /examples/widgets/doc/src/screenshot.qdoc
parent53373bdd9faf343611796e401805327e6de47586 (diff)
Move opengl/wid/net example docs to proper folders.
Change-Id: I846439a9cf7ad965ed27a00f98dbc4ff97abe73b Reviewed-by: Jerome Pasion <> Reviewed-by: Martin Smith <>
Diffstat (limited to 'examples/widgets/doc/src/screenshot.qdoc')
1 files changed, 247 insertions, 0 deletions
diff --git a/examples/widgets/doc/src/screenshot.qdoc b/examples/widgets/doc/src/screenshot.qdoc
new file mode 100644
index 0000000000..2d41cf0d85
--- /dev/null
+++ b/examples/widgets/doc/src/screenshot.qdoc
@@ -0,0 +1,247 @@
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact:
+** This file is part of the documentation of the Qt Toolkit.
+** GNU Free Documentation License
+** 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.
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+ \example desktop/screenshot
+ \title Screenshot Example
+ The Screenshot example shows how to take a screenshot of the
+ desktop using QApplication and QDesktopWidget. 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.
+ \image screenshot-example.png
+ With the application the users can take a screenshot of their
+ desktop. They are provided with a couple of options:
+ \list
+ \li Delaying the screenshot, giving them time to rearrange
+ their desktop.
+ \li Hiding the application's window while the screenshot is taken.
+ \endlist
+ In addition the application allows the users to save their
+ screenshot if they want to.
+ \section1 Screenshot Class Definition
+ \snippet desktop/screenshot/screenshot.h 0
+ The \c Screenshot class inherits QWidget and is the application's
+ main widget. It displays the application options and a preview of
+ the screenshot.
+ We reimplement the QWidget::resizeEvent() function to make sure
+ that the preview of the screenshot scales properly when the user
+ resizes the application widget. We also need several private slots
+ to facilitate the options:
+ \list
+ \li The \c newScreenshot() slot prepares a new screenshot.
+ \li The \c saveScreenshot() slot saves the last screenshot.
+ \li The \c shootScreen() slot takes the screenshot.
+ \li The \c updateCheckBox() slot enables or disables the
+ \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.
+ In addition we need to store the screenshot's original pixmap. The
+ reason is that when we display the preview of the screenshot, we
+ need to scale its pixmap, storing the original we make sure that
+ no data are lost in that process.
+ \section1 Screenshot Class Implementation
+ \snippet desktop/screenshot/screenshot.cpp 0
+ In the constructor we first create the QLabel displaying the
+ screenshot preview.
+ We set the QLabel's size policy to be QSizePolicy::Expanding both
+ horizontally and vertically. This means that the QLabel's size
+ hint is a sensible size, but the widget can be shrunk and still be
+ useful. Also, the widget can make use of extra space, so it should
+ get as much space as possible. Then we make sure the QLabel is
+ aligned in the center of the \c Screenshot widget, and set its
+ minimum size.
+ 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.
+ \snippet desktop/screenshot/screenshot.cpp 1
+ The \c resizeEvent() function is reimplemented to receive the
+ resize events dispatched to the widget. The purpose is to scale
+ the preview screenshot pixmap without deformation of its content,
+ and also make sure that the application can be resized smoothly.
+ To achieve the first goal, we scale the screenshot pixmap using
+ Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large
+ as possible inside the current size of the screenshot preview
+ label, preserving the aspect ratio. This means that if the user
+ resizes the application window in only one direction, the preview
+ screenshot keeps the same size.
+ To reach our second goal, we make sure that the preview screenshot
+ only is repainted (using the private \c updateScreenshotLabel()
+ function) when it actually changes its size.
+ \snippet desktop/screenshot/screenshot.cpp 2
+ The private \c newScreenshot() slot is called when the user
+ requests a new screenshot; but the slot only prepares a new
+ screenshot.
+ First we see if the \uicontrol {Hide This Window} option is checked, if
+ it is we hide the \c Screenshot widget. Then we disable the \uicontrol
+ {New Screenshot} button, to make sure the user only can request
+ one screenshot at a time.
+ We create a timer using the QTimer class which provides repetitive
+ and single-shot timers. We set the timer to time out only once,
+ using the static QTimer::singleShot() function. This function
+ calls the private \c shootScreen() slot after the time interval
+ specified by the \uicontrol {Screenshot Delay} option. It is \c
+ shootScreen() that actually performs the screenshot.
+ \snippet desktop/screenshot/screenshot.cpp 3
+ The \c saveScreenshot() slot is called when the user push the \uicontrol
+ Save button, and it presents a file dialog using the QFileDialog
+ class.
+ 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.
+ 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
+ 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.
+ \snippet desktop/screenshot/screenshot.cpp 5
+ Using the static function QApplication::primaryScreen(), we
+ obtain the QScreen object for the application's main screen.
+ We 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().
+ Here, however, we just pass 0 as the window id, indicating that we
+ want to grab the entire screen.
+ We update the screenshot preview label using the private \c
+ updateScreenshotLabel() function. Then we enable the \uicontrol {New
+ Screenshot} button, and finally we make the \c Screenshot widget
+ visible if it was hidden during the screenshot.
+ \snippet desktop/screenshot/screenshot.cpp 6
+ The \uicontrol {Hide This Window} option is enabled or disabled
+ depending on the delay of the screenshot. If there is no delay,
+ the application window cannot be hidden and the option's checkbox
+ is disabled.
+ 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
+ the screenshot changes, or when a resize event changes the size of
+ the screenshot preview label. It updates the screenshot preview's
+ label using the QLabel::setPixmap() and QPixmap::scaled()
+ functions.
+ QPixmap::scaled() returns a copy of the given pixmap scaled to a
+ rectangle of the given size according to the given
+ Qt::AspectRatioMode and Qt::TransformationMode.
+ We scale the original pixmap to fit the current screenshot label's
+ size, preserving the aspect ratio and giving the resulting pixmap
+ smoothed edges.