← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to examples/widgets/doc/src/screenshot.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

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