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