doc/src/examples/dropsite.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://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 http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example draganddrop/dropsite
  30     \title Drop Site Example
  31
  32     \brief The Drop Site 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 */