doc/src/examples/delayedencoding.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/delayedencoding
  30     \title Delayed Encoding Example
  31
  32     \brief The Delayed Encoding example shows how to delay preparing of data
  33     for drag and drop operations until a drop target is found.
  34
  35     \image delayedecoding-example.png
  36
  37     The \gui Export push button is pressed down to start the drag.
  38     The data for the drag and drop operation is not processed until
  39     the user of the application has found a valid drop target. This
  40     removes redundant processing if the operation is aborted. In our
  41     case, we have an SVG image that we wish to send as the \c {
  42     "image/png" } MIME type. It is the conversion from SVG to PNG we
  43     wish to delay - it can be quite expensive.
  44
  45     The example is implemented in two classes: \c SourceWidget and \c
  46     MimeData. The \c SourceWidget class sets up the GUI and starts the
  47     drag operation on request. The \c MimeData class, which inherits
  48     QMimeData, sends a signal when a drop target is found. This signal
  49     is connected to a slot in \c SourceWidget, which does the
  50     conversion from SVG to PNG.
  51
  52     \section1 SourceWidget Class Definition
  53
  54     The \c SourceWidget class starts drag and drop operations and also
  55     does the image conversion.
  56
  57     \snippet examples/draganddrop/delayedencoding/sourcewidget.h 0
  58
  59     The \gui Export push button is connected to the \c startDrag()
  60     slot. The \c createData() slot will be invoked when data for the
  61     drag and drop operation is to be created.
  62
  63     \section1 SourceWidget Class Implementation
  64
  65     Let's start our code tour with a look at the \c startDrag() slot.
  66
  67     \snippet examples/draganddrop/delayedencoding/sourcewidget.cpp 0
  68
  69     We emit \c dataRequested() from \c MimeData when the operation has
  70     found a valid drop target.
  71
  72     We gallop along to \c createData():
  73
  74     \snippet examples/draganddrop/delayedencoding/sourcewidget.cpp 1
  75
  76     Fortunately, Qt provides QSvgRenderer, which can render the SVG
  77     image to any QPaintDevice. Also, QImage has no problems saving to
  78     the PNG format.
  79
  80     Finally, we can give the data to \c MimeData.
  81
  82     \section1 MimeData Class Definition
  83
  84     The \c MimeData class inherits QMimeData and makes it possible to
  85     delay preparing of the data for a drag and drop operation.
  86
  87     \snippet examples/draganddrop/delayedencoding/mimedata.h 0
  88
  89     We will look closer at \c retrieveData() and \c formats() in the
  90     next section.
  91
  92     \section1 MimeData Class Implementation
  93
  94     \snippet examples/draganddrop/delayedencoding/mimedata.cpp 0
  95
  96     In the \c formats() function, we return the format of the
  97     data we provide. This is the \c { image/png } MIME type.
  98
  99     \snippet examples/draganddrop/delayedencoding/mimedata.cpp 1
 100
 101     \c retrieveData() is reimplemented from QMimeData and is
 102     called when the data is requested by the drag and drop
 103     operation. Fortunately for us, this happens when the operation
 104     is finishing, i.e., when a drop target has been found.
 105
 106     We emit the \c dataRequested() signal, which is picked up by
 107     \c SourceWidget. The \c SourceWidget (as already explained)
 108     sets the data on \c MimeData with \l{QMimeData::}{setData()}.
 109
 110 */
 111