examples/widgets/doc/src/screenshot.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example desktop/screenshot
  30     \title Screenshot Example
  31
  32     \brief The Screenshot example shows how to take a screenshot of the
  33     desktop using QApplication and QDesktopWidget. It also shows how
  34     to use QTimer to provide a single-shot timer, and how to
  35     reimplement the QWidget::resizeEvent() event handler to make sure
  36     that an application resizes smoothly and without data loss.
  37
  38     \image screenshot-example.png
  39
  40     With the application the users can take a screenshot of their
  41     desktop. They are provided with a couple of options:
  42
  43     \list
  44     \li Delaying the screenshot, giving them time to rearrange
  45        their desktop.
  46     \li Hiding the application's window while the screenshot is taken.
  47     \endlist
  48
  49     In addition the application allows the users to save their
  50     screenshot if they want to.
  51
  52     \section1 Screenshot Class Definition
  53
  54     \snippet desktop/screenshot/screenshot.h 0
  55
  56     The \c Screenshot class inherits QWidget and is the application's
  57     main widget. It displays the application options and a preview of
  58     the screenshot.
  59
  60     We reimplement the QWidget::resizeEvent() function to make sure
  61     that the preview of the screenshot scales properly when the user
  62     resizes the application widget. We also need several private slots
  63     to facilitate the options:
  64
  65     \list
  66     \li The \c newScreenshot() slot prepares a new screenshot.
  67     \li The \c saveScreenshot() slot saves the last screenshot.
  68     \li The \c shootScreen() slot takes the screenshot.
  69     \li The \c updateCheckBox() slot enables or disables the
  70        \uicontrol {Hide This Window} option.
  71     \endlist
  72
  73     We also declare some private functions: We use the \c
  74     createOptionsGroupBox(), \c createButtonsLayout() and \c
  75     createButton() functions when we construct the widget. And we call
  76     the private \c updateScreenshotLabel() function whenever a new
  77     screenshot is taken or when a resize event changes the size of the
  78     screenshot preview label.
  79
  80     In addition we need to store the screenshot's original pixmap. The
  81     reason is that when we display the preview of the screenshot, we
  82     need to scale its pixmap, storing the original we make sure that
  83     no data are lost in that process.
  84
  85     \section1 Screenshot Class Implementation
  86
  87     \snippet desktop/screenshot/screenshot.cpp 0
  88
  89     In the constructor we first create the QLabel displaying the
  90     screenshot preview.
  91
  92     We set the QLabel's size policy to be QSizePolicy::Expanding both
  93     horizontally and vertically. This means that the QLabel's size
  94     hint is a sensible size, but the widget can be shrunk and still be
  95     useful. Also, the widget can make use of extra space, so it should
  96     get as much space as possible. Then we make sure the QLabel is
  97     aligned in the center of the \c Screenshot widget, and set its
  98     minimum size.
  99
 100     We create the applications's buttons and the group box containing
 101     the application's options, and put it all into a main
 102     layout. Finally we take the initial screenshot, and set the initial
 103     delay and the window title, before we resize the widget to a
 104     suitable size.
 105
 106     \snippet desktop/screenshot/screenshot.cpp 1
 107
 108     The \c resizeEvent() function is reimplemented to receive the
 109     resize events dispatched to the widget. The purpose is to scale
 110     the preview screenshot pixmap without deformation of its content,
 111     and also make sure that the application can be resized smoothly.
 112
 113     To achieve the first goal, we scale the screenshot pixmap using
 114     Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large
 115     as possible inside the current size of the screenshot preview
 116     label, preserving the aspect ratio. This means that if the user
 117     resizes the application window in only one direction, the preview
 118     screenshot keeps the same size.
 119
 120     To reach our second goal, we make sure that the preview screenshot
 121     only is repainted (using the private \c updateScreenshotLabel()
 122     function) when it actually changes its size.
 123
 124     \snippet desktop/screenshot/screenshot.cpp 2
 125
 126     The private \c newScreenshot() slot is called when the user
 127     requests a new screenshot; but the slot only prepares a new
 128     screenshot.
 129
 130     First we see if the \uicontrol {Hide This Window} option is checked, if
 131     it is we hide the \c Screenshot widget. Then we disable the \uicontrol
 132     {New Screenshot} button, to make sure the user only can request
 133     one screenshot at a time.
 134
 135     We create a timer using the QTimer class which provides repetitive
 136     and single-shot timers. We set the timer to time out only once,
 137     using the static QTimer::singleShot() function. This function
 138     calls the private \c shootScreen() slot after the time interval
 139     specified by the \uicontrol {Screenshot Delay} option. It is \c
 140     shootScreen() that actually performs the screenshot.
 141
 142     \snippet desktop/screenshot/screenshot.cpp 3
 143
 144     The \c saveScreenshot() slot is called when the user push the \uicontrol
 145     Save button, and it presents a file dialog using the QFileDialog
 146     class.
 147
 148     QFileDialog enables a user to traverse the file system in order to
 149     select one or many files or a directory. The easiest way to create
 150     a QFileDialog is to use the convenience static
 151     functions.
 152
 153     We define the default file format to be png, and we make the file
 154     dialog's initial path the path the application is run from. We
 155     create the file dialog using the static
 156     QFileDialog::getSaveFileName() function which returns a file name
 157     selected by the user. The file does not have to exist. If the file
 158     name is valid, we use the QPixmap::save() function to save the
 159     screenshot's original pixmap in that file.
 160
 161     \snippet desktop/screenshot/screenshot.cpp 4
 162
 163     The \c shootScreen() slot is called to take the screenshot. If the
 164     user has chosen to delay the screenshot, we make the application
 165     beep when the screenshot is taken using the static
 166     QApplication::beep() function.
 167
 168     The QApplication class manages the GUI application's control flow
 169     and main settings. It contains the main event loop, where all
 170     events from the window system and other sources are processed and
 171     dispatched.
 172
 173     \snippet desktop/screenshot/screenshot.cpp 5
 174
 175     Using the static function QApplication::primaryScreen(), we
 176     obtain the QScreen object for the application's main screen.
 177
 178     We take the screenshot using the QScreen::grabWindow()
 179     function. The function grabs the contents of the window passed as
 180     an argument, makes a pixmap out of it and returns that pixmap.
 181     The window id can be obtained with QWidget::winId() or QWindow::winId().
 182     Here, however, we just pass 0 as the window id, indicating that we
 183     want to grab the entire screen.
 184
 185     We update the screenshot preview label using the private \c
 186     updateScreenshotLabel() function. Then we enable the \uicontrol {New
 187     Screenshot} button, and finally we make the \c Screenshot widget
 188     visible if it was hidden during the screenshot.
 189
 190     \snippet desktop/screenshot/screenshot.cpp 6
 191
 192     The \uicontrol {Hide This Window} option is enabled or disabled
 193     depending on the delay of the screenshot. If there is no delay,
 194     the application window cannot be hidden and the option's checkbox
 195     is disabled.
 196
 197     The \c updateCheckBox() slot is called whenever the user changes
 198     the delay using the \uicontrol {Screenshot Delay} option.
 199
 200     \snippet desktop/screenshot/screenshot.cpp 7
 201
 202     The private \c createOptionsGroupBox() function is called from the
 203     constructor.
 204
 205     First we create a group box that will contain all of the options'
 206     widgets. Then we create a QSpinBox and a QLabel for the \uicontrol
 207     {Screenshot Delay} option, and connect the spinbox to the \c
 208     updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol
 209     {Hide This Window} option, add all the options' widgets to a
 210     QGridLayout and install the layout on the group box.
 211
 212     Note that we don't have to specify any parents for the widgets
 213     when we create them. The reason is that when we add a widget to a
 214     layout and install the layout on another widget, the layout's
 215     widgets are automatically reparented to the widget the layout is
 216     installed on.
 217
 218     \snippet desktop/screenshot/screenshot.cpp 8
 219
 220     The private \c createButtonsLayout() function is called from the
 221     constructor. We create the application's buttons using the private
 222     \c createButton() function, and add them to a QHBoxLayout.
 223
 224     \snippet desktop/screenshot/screenshot.cpp 9
 225
 226     The private \c createButton() function is called from the \c
 227     createButtonsLayout() function. It simply creates a QPushButton
 228     with the provided text, connects it to the provided receiver and
 229     slot, and returns a pointer to the button.
 230
 231     \snippet desktop/screenshot/screenshot.cpp 10
 232
 233     The private \c updateScreenshotLabel() function is called whenever
 234     the screenshot changes, or when a resize event changes the size of
 235     the screenshot preview label. It updates the screenshot preview's
 236     label using the QLabel::setPixmap() and QPixmap::scaled()
 237     functions.
 238
 239     QPixmap::scaled() returns a copy of the given pixmap scaled to a
 240     rectangle of the given size according to the given
 241     Qt::AspectRatioMode and Qt::TransformationMode.
 242
 243     We scale the original pixmap to fit the current screenshot label's
 244     size, preserving the aspect ratio and giving the resulting pixmap
 245     smoothed edges.
 246 */
 247