← Back to branch summary

~gabriel1984sibiu/minitube/qt5.6

« back to all changes in this revision

Viewing changes to examples/widgets/doc/dropsite.qdoc

  • Committer: Grevutiu Gabriel
  • Date: 2017-06-13 08:43:17 UTC
  • Revision ID: gabriel1984sibiu@gmail.com-20170613084317-ek0zqe0u9g3ocvi8
Original upstream code

Show diffs side-by-side

added added

removed removed

Lines of Context:
examples/widgets/doc/dropsite.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2016 The Qt Company Ltd.
 
4
** Contact: https://www.qt.io/licensing/
 
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 The Qt Company. For licensing terms
 
14
** and conditions see https://www.qt.io/terms-conditions. For further
 
15
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
    \example draganddrop/dropsite
 
30
    \title Drop Site Example
 
31
 
 
32
    \brief The example shows how to distinguish the various MIME formats available
 
33
    in a drag and drop operation.
 
34
 
 
35
    \image dropsite-example.png Screenshot of the Drop Site example
 
36
 
 
37
    The Drop Site example accepts drops from other applications, and displays
 
38
    the MIME formats provided by the drag object.
 
39
 
 
40
    There are two classes, \c DropArea and \c DropSiteWindow, and a \c main()
 
41
    function in this example. A \c DropArea object is instantiated in
 
42
    \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the
 
43
    \c main() function.
 
44
 
 
45
    \section1 DropArea Class Definition
 
46
 
 
47
    The \c DropArea class is a subclass of QLabel with a public slot,
 
48
    \c clear(), and a \c changed() signal.
 
49
 
 
50
    \snippet draganddrop/dropsite/droparea.h DropArea header part1
 
51
 
 
52
    In addition, \c DropArea also contains a private instance of QLabel and
 
53
    reimplementations of four \l{QWidget} event handlers:
 
54
 
 
55
    \list 1
 
56
        \li \l{QWidget::dragEnterEvent()}{dragEnterEvent()}
 
57
        \li \l{QWidget::dragMoveEvent()}{dragMoveEvent()}
 
58
        \li \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()}
 
59
        \li \l{QWidget::dropEvent()}{dropEvent()}
 
60
    \endlist
 
61
 
 
62
    These event handlers are further explained in the implementation of the
 
63
    \c DropArea class.
 
64
 
 
65
    \snippet draganddrop/dropsite/droparea.h DropArea header part2
 
66
 
 
67
    \section1 DropArea Class Implementation
 
68
 
 
69
    In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()}
 
70
    {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()}
 
71
    {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align
 
72
    its contents to the center.
 
73
 
 
74
    \snippet draganddrop/dropsite/droparea.cpp DropArea constructor
 
75
 
 
76
    Also, we enable drop events in \c DropArea by setting the
 
77
    \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then,
 
78
    we enable the \l{QWidget::autoFillBackground()}{autoFillBackground}
 
79
    property and invoke the \c clear() function.
 
80
 
 
81
    The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is
 
82
    called when a drag is in progress and the mouse enters the \c DropArea
 
83
    object. For the \c DropSite example, when the mouse enters \c DropArea,
 
84
    we set its text to "<drop content>" and highlight its background.
 
85
 
 
86
    \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function
 
87
 
 
88
    Then, we invoke \l{QDropEvent::acceptProposedAction()}
 
89
    {acceptProposedAction()} on \a event, setting the drop action to the one
 
90
    proposed. Lastly, we emit the \c changed() signal, with the data that was
 
91
    dropped and its MIME type information as a parameter.
 
92
 
 
93
    For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the
 
94
    proposed QDragMoveEvent object, \a event, with
 
95
    \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}.
 
96
 
 
97
    \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function
 
98
 
 
99
    The \c DropArea class's implementation of \l{QWidget::dropEvent()}
 
100
    {dropEvent()} extracts the \a{event}'s mime data and displays it
 
101
    accordingly.
 
102
 
 
103
    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1
 
104
 
 
105
    The \c mimeData object can contain one of the following objects: an image,
 
106
    HTML text, plain text, or a list of URLs.
 
107
 
 
108
    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2
 
109
 
 
110
    \list
 
111
        \li If \c mimeData contains an image, we display it in \c DropArea with
 
112
           \l{QLabel::setPixmap()}{setPixmap()}.
 
113
        \li If \c mimeData contains HTML, we display it with
 
114
           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
 
115
           as Qt::RichText.
 
116
        \li If \c mimeData contains plain text, we display it with
 
117
           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
 
118
           as Qt::PlainText. In the event that \c mimeData contains URLs, we
 
119
           iterate through the list of URLs to display them on individual
 
120
           lines.
 
121
        \li If \c mimeData contains other types of objects, we set
 
122
           \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to
 
123
           "Cannot display data" to inform the user.
 
124
    \endlist
 
125
 
 
126
    We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to
 
127
    QPalette::Dark and we accept \c{event}'s proposed action.
 
128
 
 
129
    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3
 
130
 
 
131
    The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is
 
132
    called when a drag is in progress and the mouse leaves the widget.
 
133
 
 
134
    \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function
 
135
 
 
136
    For \c{DropArea}'s implementation, we clear invoke \c clear() and then
 
137
    accept the proposed event.
 
138
 
 
139
    The \c clear() function sets the text in \c DropArea to "<drop content>"
 
140
    and sets the \l{QWidget::backgroundRole()}{backgroundRole} to
 
141
    QPalette::Dark. Lastly, it emits the \c changed() signal.
 
142
 
 
143
    \snippet draganddrop/dropsite/droparea.cpp clear() function
 
144
 
 
145
    \section1 DropSiteWindow Class Definition
 
146
 
 
147
    The \c DropSiteWindow class contains a constructor and a public slot,
 
148
    \c updateFormatsTable().
 
149
 
 
150
    \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header
 
151
 
 
152
    The class also contains a private instance of \c DropArea, \c dropArea,
 
153
    QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox,
 
154
    \c buttonBox, and two QPushButton objects, \c clearButton and
 
155
    \c quitButton.
 
156
 
 
157
    \section1 DropSiteWindow Class Implementation
 
158
 
 
159
    In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel
 
160
    and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We
 
161
    also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust
 
162
    \c{abstractLabel}'s size according to its contents.
 
163
 
 
164
    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1
 
165
 
 
166
    Then we instantiate \c dropArea and connect its \c changed() signal to
 
167
    \c{DropSiteWindow}'s \c updateFormatsTable() slot.
 
168
 
 
169
    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2
 
170
 
 
171
    We now set up the QTableWidget object, \c formatsTable. Its
 
172
    horizontal header is set using a QStringList object, \c labels. The number
 
173
    of columms are set to two and the table is not editable. Also, the
 
174
    \c{formatTable}'s horizontal header is formatted to ensure that its second
 
175
    column stretches to occupy additional space available.
 
176
 
 
177
    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3
 
178
 
 
179
    Two QPushButton objects, \c clearButton and \c quitButton, are instantiated
 
180
    and added to \c buttonBox - a QDialogButtonBox object. We use
 
181
    QDialogButtonBox here to ensure that the push buttons are presented in a
 
182
    layout that conforms to the platform's style.
 
183
 
 
184
    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4
 
185
 
 
186
    The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and
 
187
    \c clearButton are connected to \l{QWidget::close()}{close()} and
 
188
    \c clear(), respectively.
 
189
 
 
190
    For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets
 
191
    vertically. We also set the window title to "Drop Site" and the minimum
 
192
    size to 350x500 pixels.
 
193
 
 
194
    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5
 
195
 
 
196
    We move on to the \c updateFormatsTable() function. This function updates
 
197
    the \c formatsTable, displaying the MIME formats of the object dropped onto
 
198
    the \c DropArea object. First, we set \l{QTableWidget}'s
 
199
    \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate
 
200
    to ensure that the QMimeData object passed in is a valid object.
 
201
 
 
202
    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1
 
203
 
 
204
    Once we are sure that \c mimeData is valid, we iterate through its
 
205
    supported formats using the \l{The foreach Keyword}{foreach keyword}.
 
206
    This keyword has the following format:
 
207
 
 
208
    \include code/doc_src_examples_dropsite.qdoc 0
 
209
 
 
210
    In our example, \c format is the \a variable and the \a container is a
 
211
    QStringList, obtained from \c mimeData->formats().
 
212
 
 
213
    \note The \l{QMimeData::formats()}{formats()} function returns a
 
214
    QStringList object, containing all the formats supported by the
 
215
    \c mimeData.
 
216
 
 
217
    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2
 
218
 
 
219
    Within each iteration, we create a QTableWidgetItem, \c formatItem and we
 
220
    set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and
 
221
    its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop
 
222
    and Qt::AlignLeft.
 
223
 
 
224
    A QString object, \c text, is customized to display data according to the
 
225
    contents of \c format. We invoke \l{QString}'s \l{QString::simplified()}
 
226
    {simplified()} function on \c text, to obtain a string that has no
 
227
    additional space before, after or in between words.
 
228
 
 
229
    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3
 
230
 
 
231
    If \c format contains a list of URLs, we iterate through them, using spaces
 
232
    to separate them. On the other hand, if \c format contains an image, we
 
233
    display the data by converting the text to hexadecimal.
 
234
 
 
235
    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4
 
236
 
 
237
    Once \c text has been customized to contain the appropriate data, we insert
 
238
    both \c format and \c text into \c formatsTable with
 
239
    \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke
 
240
    \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on
 
241
    \c{formatsTable}'s first column.
 
242
 
 
243
    \section1 The main() Function
 
244
 
 
245
    Within the \c main() function, we instantiate \c DropSiteWindow and invoke
 
246
    its \l{QWidget::show()}{show()} function.
 
247
 
 
248
    \snippet draganddrop/dropsite/main.cpp main() function
 
249
*/