1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example draganddrop/dropsite

    44     \title Drop Site Example

    45 

    46     The example shows how to distinguish the various MIME formats available

    47     in a drag and drop operation.

    48 

    49     \image dropsite-example.png Screenshot of the Drop Site example

    50 

    51     The Drop Site example accepts drops from other applications, and displays

    52     the MIME formats provided by the drag object.

    53 

    54     There are two classes, \c DropArea and \c DropSiteWindow, and a \c main()

    55     function in this example. A \c DropArea object is instantiated in

    56     \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the

    57     \c main() function.

    58 

    59     \section1 DropArea Class Definition

    60 

    61     The \c DropArea class is a subclass of QLabel with a public slot,

    62     \c clear(), and a \c changed() signal.

    63 

    64     \snippet draganddrop/dropsite/droparea.h DropArea header part1

    65 

    66     In addition, \c DropArea also contains a private instance of QLabel and

    67     reimplementations of four \l{QWidget} event handlers:

    68 

    69     \list 1

    70         \o \l{QWidget::dragEnterEvent()}{dragEnterEvent()}

    71         \o \l{QWidget::dragMoveEvent()}{dragMoveEvent()}

    72         \o \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()}

    73         \o \l{QWidget::dropEvent()}{dropEvent()}

    74     \endlist

    75 

    76     These event handlers are further explained in the implementation of the

    77     \c DropArea class.

    78 

    79     \snippet draganddrop/dropsite/droparea.h DropArea header part2

    80 

    81     \section1 DropArea Class Implementation

    82 

    83     In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()}

    84     {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()}

    85     {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align

    86     its contents to the center.

    87 

    88     \snippet draganddrop/dropsite/droparea.cpp DropArea constructor

    89 

    90     Also, we enable drop events in \c DropArea by setting the

    91     \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then,

    92     we enable the \l{QWidget::autoFillBackground()}{autoFillBackground}

    93     property and invoke the \c clear() function.

    94 

    95     The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is

    96     called when a drag is in progress and the mouse enters the \c DropArea

    97     object. For the \c DropSite example, when the mouse enters \c DropArea,

    98     we set its text to "<drop content>" and highlight its background.

    99 

   100     \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function

   101 

   102     Then, we invoke \l{QDropEvent::acceptProposedAction()}

   103     {acceptProposedAction()} on \a event, setting the drop action to the one

   104     proposed. Lastly, we emit the \c changed() signal, with the data that was

   105     dropped and its MIME type information as a parameter.

   106 

   107     For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the

   108     proposed QDragMoveEvent object, \a event, with

   109     \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}.

   110 

   111     \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function

   112 

   113     The \c DropArea class's implementation of \l{QWidget::dropEvent()}

   114     {dropEvent()} extracts the \a{event}'s mime data and displays it

   115     accordingly.

   116 

   117     \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1

   118 

   119     The \c mimeData object can contain one of the following objects: an image,

   120     HTML text, plain text, or a list of URLs.

   121 

   122     \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2

   123 

   124     \list

   125         \o If \c mimeData contains an image, we display it in \c DropArea with

   126            \l{QLabel::setPixmap()}{setPixmap()}.

   127         \o If \c mimeData contains HTML, we display it with

   128            \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format

   129            as Qt::RichText.

   130         \o If \c mimeData contains plain text, we display it with

   131            \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format

   132            as Qt::PlainText. In the event that \c mimeData contains URLs, we

   133            iterate through the list of URLs to display them on individual

   134            lines.

   135         \o If \c mimeData contains other types of objects, we set

   136            \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to

   137            "Cannot display data" to inform the user.

   138     \endlist

   139 

   140     We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to

   141     QPalette::Dark and we accept \c{event}'s proposed action.

   142 

   143     \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3

   144 

   145     The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is

   146     called when a drag is in progress and the mouse leaves the widget.

   147 

   148     \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function

   149 

   150     For \c{DropArea}'s implementation, we clear invoke \c clear() and then

   151     accept the proposed event.

   152 

   153     The \c clear() function sets the text in \c DropArea to "<drop content>"

   154     and sets the \l{QWidget::backgroundRole()}{backgroundRole} to

   155     QPalette::Dark. Lastly, it emits the \c changed() signal.

   156 

   157     \snippet draganddrop/dropsite/droparea.cpp clear() function

   158 

   159     \section1 DropSiteWindow Class Definition

   160 

   161     The \c DropSiteWindow class contains a constructor and a public slot,

   162     \c updateFormatsTable().

   163 

   164     \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header

   165 

   166     The class also contains a private instance of \c DropArea, \c dropArea,

   167     QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox,

   168     \c buttonBox, and two QPushButton objects, \c clearButton and

   169     \c quitButton.

   170 

   171     \section1 DropSiteWindow Class Implementation

   172 

   173     In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel

   174     and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We

   175     also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust

   176     \c{abstractLabel}'s size according to its contents.

   177 

   178     \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1

   179 

   180     Then we instantiate \c dropArea and connect its \c changed() signal to

   181     \c{DropSiteWindow}'s \c updateFormatsTable() slot.

   182 

   183     \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2

   184 

   185     We now set up the QTableWidget object, \c formatsTable. Its

   186     horizontal header is set using a QStringList object, \c labels. The number

   187     of columms are set to two and the table is not editable. Also, the

   188     \c{formatTable}'s horizontal header is formatted to ensure that its second

   189     column stretches to occupy additional space available.

   190 

   191     \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3

   192 

   193     Two QPushButton objects, \c clearButton and \c quitButton, are instantiated

   194     and added to \c buttonBox - a QDialogButtonBox object. We use

   195     QDialogButtonBox here to ensure that the push buttons are presented in a

   196     layout that conforms to the platform's style.

   197 

   198     \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4

   199 

   200     The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and

   201     \c clearButton are connected to \l{QWidget::close()}{close()} and

   202     \c clear(), respectively.

   203 

   204     For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets

   205     vertically. We also set the window title to "Drop Site" and the minimum

   206     size to 350x500 pixels.

   207 

   208     \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5

   209 

   210     We move on to the \c updateFormatsTable() function. This function updates

   211     the \c formatsTable, displaying the MIME formats of the object dropped onto

   212     the \c DropArea object. First, we set \l{QTableWidget}'s

   213     \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate

   214     to ensure that the QMimeData object passed in is a valid object.

   215 

   216     \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1

   217 

   218     Once we are sure that \c mimeData is valid, we iterate through its

   219     supported formats using the \l{The foreach Keyword}{foreach keyword}.

   220     This keyword has the following format:

   221 

   222     \snippet doc/src/snippets/code/doc_src_examples_dropsite.qdoc 0

   223 

   224     In our example, \c format is the \a variable and the \a container is a

   225     QStringList, obtained from \c mimeData->formats().

   226 

   227     \note The \l{QMimeData::formats()}{formats()} function returns a

   228     QStringList object, containing all the formats supported by the

   229     \c mimeData.

   230 

   231     \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2

   232 

   233     Within each iteration, we create a QTableWidgetItem, \c formatItem and we

   234     set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and

   235     its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop

   236     and Qt::AlignLeft.

   237 

   238     A QString object, \c text, is customized to display data according to the

   239     contents of \c format. We invoke {QString}'s \l{QString::simplified()}

   240     {simplified()} function on \c text, to obtain a string that has no

   241     additional space before, after or in between words.

   242 

   243     \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3

   244 

   245     If \c format contains a list of URLs, we iterate through them, using spaces

   246     to separate them. On the other hand, if \c format contains an image, we

   247     display the data by converting the text to hexadecimal.

   248 

   249     \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4

   250 

   251     Once \c text has been customized to contain the appropriate data, we insert

   252     both \c format and \c text into \c formatsTable with

   253     \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke

   254     \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on

   255     \c{formatsTable}'s first column.

   256 

   257     \section1 The main() Function

   258 

   259     Within the \c main() function, we instantiate \c DropSiteWindow and invoke

   260     its \l{QWidget::show()}{show()} function.

   261 

   262     \snippet draganddrop/dropsite/main.cpp main() function

   263 */