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

**

** Copyright (C) 2010 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/fridgemagnets

    \title Fridge Magnets Example

    The Fridge Magnets example shows how to supply more than one type

    of MIME-encoded data with a drag and drop operation.

    \image fridgemagnets-example.png

    With this application the user can play around with a collection

    of fridge magnets, using drag and drop to form new sentences from

    the words on the magnets. The example consists of two classes:

    \list

        \o \c DragLabel is a custom widget representing one

           single fridge magnet.

        \o \c DragWidget provides the main application window.

    \endlist

    We will first take a look at the \c DragLabel class, then we will

    examine the \c DragWidget class.

    \section1 DragLabel Class Definition

    Each fridge magnet is represented by an instance of the \c

    DragLabel class:

    \snippet examples/draganddrop/fridgemagnets/draglabel.h 0

    Each instance of this QLabel subclass will be used to display an

    pixmap generated from a text string. Since we cannot store both

    text and a pixmap in a standard label, we declare a private variable

    to hold the original text, and we define an additional member

    function to allow it to be accessed.

    \section1 DragLabel Class Implementation

    In the \c DragLabel constructor, we first create a QImage object

    on which we will draw the fridge magnet's text and frame:

    \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 0

    Its size depends on the current font size, and its format is

    QImage::Format_ARGB32_Premultiplied; i.e., the image is stored

    using a premultiplied 32-bit ARGB format (0xAARRGGBB).

    We then construct a font object that uses the application's

    default font, and set its style strategy. The style strategy tells

    the font matching algorithm what type of fonts should be used to

    find an appropriate default family. The QFont::ForceOutline forces

    the use of outline fonts.

    To draw the text and frame onto the image, we use the QPainter

    class. QPainter provides highly optimized methods to do most of

    the drawing GUI programs require. It can draw everything from

    simple lines to complex shapes like pies and chords. It can also

    draw aligned text and pixmaps.

    \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 1

    A painter can be activated by passing a paint device to the

    constructor, or by using the \l{QPainter::}{begin()} method as we

    do in this example. The \l{QPainter::}{end()} method deactivates

    it. Note that the latter function is called automatically upon

    destruction when the painter is actived by its constructor. The

    QPainter::Antialiasing render hint ensures that the paint engine

    will antialias the edges of primitives if possible.

    When the painting is done, we convert our image to a pixmap using

    QPixmap's \l {QPixmap::}{fromImage()} method. This method also

    takes an optional flags argument, and converts the given image to

    a pixmap using the specified flags to control the conversion (the

    flags argument is a bitwise-OR of the Qt::ImageConversionFlags;

    passing 0 for flags sets all the default options).

    \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 2

    Finally, we set the label's \l{QLabel::pixmap}{pixmap property}

    and store the label's text for later use.

    \e{Note that setting the pixmap clears any previous content, including

    any text previously set using QLabel::setText(), and disables

    the label widget's buddy shortcut, if any.}

    \section1 DragWidget Class Definition

    The \c DragWidget class inherits QWidget, providing support for

    drag and drop operations:

    \snippet examples/draganddrop/fridgemagnets/dragwidget.h 0

    To make the widget responsive to drag and drop operations, we simply

    reimplement the \l{QWidget::}{dragEnterEvent()},

    \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event

    handlers inherited from QWidget.

    We also reimplement \l{QWidget::}{mousePressEvent()} to make the

    widget responsive to mouse clicks. This is where we will write code

    to start drag and drop operations.

    \section1 DragWidget Class Implementation

    In the constructor, we first open the file containing the words on

    our fridge magnets:

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 0

    QFile is an I/O device for reading and writing text and binary

    files and resources, and may be used by itself or in combination

    with QTextStream or QDataStream. We have chosen to read the

    contents of the file using the QTextStream class that provides a

    convenient interface for reading and writing text.

    We then create the fridge magnets. As long as there is data (the

    QTextStream::atEnd() method returns true if there is no more data

    to be read from the stream), we read one line at a time using

    QTextStream's \l {QTextStream::}{readLine()} method.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 1

    For each line, we create a \c DragLabel object using the read line

    as text, we calculate its position and ensure that it is visible by

    calling the QWidget::show() method. We set the Qt::WA_DeleteOnClose

    attribute on each label to ensure that any unused labels will be

    deleted; we will need to create new labels and delete old ones when

    they are dragged around, and this ensures that the example does not

    leak memory.

    We also set the \c FridgeMagnets widget's palette, minimum size

    and window title.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 2

    Finally, to enable our user to move the fridge magnets around, we

    must also set the \c FridgeMagnets widget's

    \l{QWidget::acceptDrops}{acceptDrops} property.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 3

    Setting this property to true announces to the system that this

    widget \e may be able to accept drop events (events that are sent

    when drag and drop actions are completed). Later, we will

    implement the functions that ensure that the widget accepts the

    drop events it is interested in.

    \section2 Dragging

    Let's take a look at the \l{QWidget::}{mousePressEvent()} event

    handler, where drag and drop operations begin:

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 13

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 14

    Mouse events occur when a mouse button is pressed or released

    inside a widget, or when the mouse cursor is moved. By

    reimplementing the \l{QWidget::}{mousePressEvent()} method we

    ensure that we will receive mouse press events for the widget

    containing the fridge magnets.

    Whenever we receive such an event, we first check to see if the

    position of the click coincides with one of the labels. If not,

    we simply return.

    If the user clicked a label, we determine the position of the

    \e{hot spot} (the position of the click relative to the top-left

    corner of the label). We create a byte array to store the label's

    text and the hot spot, and we use a QDataStream object to stream

    the data into the byte array.

    With all the information in place, we create a new QMimeData object.

    As mentioned above, QMimeData objects associate the data that they

    hold with the corresponding MIME types to ensure that information

    can be safely transferred between applications. The

    \l{QMimeData::}{setData()} method sets the data associated with a

    given MIME type. In our case, we associate our item data with the

    custom \c application/x-fridgemagnet type.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 15

    Note that we also associate the magnet's text with the

    \c text/plain MIME type using QMimeData's \l{QMimeData::}{setText()}

    method. Below, we will see how our widget detects both these MIME

    types with its event handlers.

    Finally, we create a QDrag object. It is the QDrag class that

    handles most of the details of a drag and drop operation,

    providing support for MIME-based drag and drop data transfer. The

    data to be transferred by the drag and drop operation is contained

    in a QMimeData object. When we call QDrag's

    \l{QDrag::}{setMimeData()} method the ownership of our item data is

    transferred to the QDrag object.

    We call the \l{QDrag::}{setPixmap()} function to set the pixmap used

    to represent the data during the drag and drop operation.

    Typically, this pixmap shows an icon that represents the MIME type

    of the data being transferred, but any pixmap can be used. In this

    example, we simply use the pixmap used by the label itself to make

    it look like the fridge magnet itself is being moved.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 16

    We also specify the cursor's hot spot, its position relative to the

    top-level corner of the drag pixmap, to be the point we calculated

    above. This makes the process of dragging the label feel more natural

    because the cursor always points to the same place on the label

    during the drag operation. 

    We start the drag operation using QDrag's \l{QDrag::}{exec()} function,

    requesting that the magnet is copied when the drag is completed.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 17

    The function returns the drop action actually performed by the user

    (this can be either a copy or a move action in this case); if this

    action is equal to Qt::MoveAction we will close the activated

    fridge magnet widget because we will create a new one to replace it

    (see the \l{drop}{dropEvent()} implementation). Otherwise, if

    the drop is outside our main widget, we simply show the widget in

    its original position.

    \section2 Dropping

    When a a drag and drop action enters our widget, we will receive a

    drag enter \e event. QDragEnterEvent inherits most of its

    functionality from QDragMoveEvent, which in turn inherits most of

    its functionality from QDropEvent. Note that we must accept this

    event in order to receive the drag move events that are sent while

    the drag and drop action is in progress. The drag enter event is

    always immediately followed by a drag move event.

    In our \c dragEnterEvent() implementation, we first determine

    whether we support the event's MIME type or not:

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 4

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 5

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 6

    If the type is \c application/x-fridgemagnet and the event

    origins from any of this application's fridge magnet widgets, we

    first set the event's drop action using the

    QDropEvent::setDropAction() method. An event's drop action is the

    action to be performed on the data by the target. Qt::MoveAction

    indicates that the data is moved from the source to the target.

    Then we call the event's \l {QDragMoveEvent::}{accept()} method to

    indicate that we have handled the event. In general, unaccepted

    events might be propagated to the parent widget. If the event

    origins from any other widget, we simply accept the proposed

    action.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 7

    We also accept the proposed action if the event's MIME type is \c

    text/plain, i.e., if QMimeData::hasText() returns true. If the

    event has any other type, on the other hand, we call the event's

    \l {QDragMoveEvent::}{ignore()} method allowing the event to be

    propagated further.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 8

    Drag move events occur when the cursor enters a widget, when it

    moves within the widget, and when a modifier key is pressed on the

    keyboard while the widget has focus. Our widget will receive drag

    move events repeatedly while a drag is within its boundaries. We

    reimplement the \l {QWidget::}{dragMoveEvent()} method, and

    examine the event in the exact same way as we did with drag enter

    events.

    Note that the \l{QWidget::}{dropEvent()} event handler behaves

    slightly differently: We first get hold of the event's MIME

    data.

    \target drop

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 9

    The QMimeData class provides a container for data that

    records information about its MIME type. QMimeData objects

    associate the data that they hold with the corresponding MIME

    types to ensure that information can be safely transferred between

    applications, and copied around within the same application.

    We retrieve the data associated with the \c application/x-fridgemagnet

    MIME type using a data stream in order to create a new \c DragLabel

    object.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 10

    The QDataStream class provides serialization of binary data to a

    QIODevice (a data stream is a binary stream of encoded information

    which is completely independent of the host computer's operating

    system, CPU or byte order).

    Finally, we create a label and move it to the event's position:

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 11

    If the source of the event is also the widget receiving the

    drop event, we set the event's drop action to Qt::MoveAction and

    call the event's \l{QDragMoveEvent::}{accept()}

    method. Otherwise, we simply accept the proposed action. This

    means that labels are moved rather than copied in the same

    window. However, if we drag a label to a second instance of the

    Fridge Magnets example, the default action is to copy it, leaving

    the original in the first instance.

    If the event's MIME type is \c text/plain (i.e., if

    QMimeData::hasText() returns true) we retrieve its text and split

    it into words. For each word we create a new \c DragLabel action,

    and show it at the event's position plus an offset depending on

    the number of words in the text. In the end we accept the proposed

    action. This lets the user drop selected text from a text editor or

    Web browser onto the widget to add more fridge magnets.

    \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 12

    If the event has any other type, we call the event's

    \l{QDragMoveEvent::}{ignore()} method allowing the event to be

    propagated further.

    \section1 Summary

    We set our main widget's \l{QWidget::}{acceptDrops} property

    and reimplemented QWidget's \l{QWidget::}{dragEnterEvent()},

    \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event

    handlers to support content dropped on our widget.

    In addition, we reimplemented the \l{QWidget::}{mousePressEvent()}

    function to let the user pick up fridge magnets in the first place.

    Because data is communicated using drag and drop operations and

    encoded using MIME types, you can run more than one instance of this

    example, and transfer magnets between them.

*/