[2] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[846] | 3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[561] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation (qt-info@nokia.com)
|
---|
[2] | 6 | **
|
---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
| 8 | **
|
---|
[846] | 9 | ** $QT_BEGIN_LICENSE:FDL$
|
---|
[2] | 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
[846] | 13 | ** Software or, alternatively, in accordance with the terms contained in a
|
---|
| 14 | ** written agreement between you and Nokia.
|
---|
[2] | 15 | **
|
---|
[846] | 16 | ** GNU Free Documentation License
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
---|
| 20 | ** file.
|
---|
[2] | 21 | **
|
---|
[561] | 22 | ** If you have questions regarding the use of this file, please contact
|
---|
| 23 | ** Nokia at qt-info@nokia.com.
|
---|
[2] | 24 | ** $QT_END_LICENSE$
|
---|
| 25 | **
|
---|
| 26 | ****************************************************************************/
|
---|
| 27 |
|
---|
| 28 | /*!
|
---|
| 29 | \example draganddrop/dropsite
|
---|
| 30 | \title Drop Site Example
|
---|
| 31 |
|
---|
| 32 | 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 | \o \l{QWidget::dragEnterEvent()}{dragEnterEvent()}
|
---|
| 57 | \o \l{QWidget::dragMoveEvent()}{dragMoveEvent()}
|
---|
| 58 | \o \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()}
|
---|
| 59 | \o \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 | \o If \c mimeData contains an image, we display it in \c DropArea with
|
---|
| 112 | \l{QLabel::setPixmap()}{setPixmap()}.
|
---|
| 113 | \o 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 | \o 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 | \o 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 | \snippet doc/src/snippets/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 {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 | */
|
---|