| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.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. |
| |
| \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 \l{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 |
| */ |