/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example draganddrop/dropsite

    \title Drop Site Example

    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

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

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

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

        \o \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

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

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

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

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

           as Qt::RichText.

        \o 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.

        \o 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 doc/src/snippets/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

*/