examples/widgets/doc/src/imagecomposition.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/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 painting/imagecomposition
  30     \title Image Composition Example
  31
  32     \brief The Image Composition example lets the user combine images
  33     together using any composition mode supported by QPainter, described
  34     in detail in \l{QPainter#Composition Modes}{Composition Modes}.
  35
  36     \image imagecomposition-example.png
  37
  38     \section1 Setting Up The Resource File
  39
  40     The Image Composition example requires two source images,
  41     \e butterfly.png and \e checker.png that are embedded within
  42     \e imagecomposition.qrc. The file contains the following code:
  43
  44     \quotefile painting/imagecomposition/imagecomposition.qrc
  45
  46     For more information on resource files, see \l{The Qt Resource System}.
  47
  48     \section1 ImageComposer Class Definition
  49
  50     The \c ImageComposer class is a subclass of QWidget that implements three
  51     private slots, \c chooseSource(), \c chooseDestination(), and
  52     \c recalculateResult().
  53
  54     \snippet painting/imagecomposition/imagecomposer.h 0
  55
  56     In addition, \c ImageComposer consists of five private functions,
  57     \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and
  58     \c imagePos(), as well as private instances of QToolButton, QComboBox,
  59     QLabel, and QImage.
  60
  61     \snippet painting/imagecomposition/imagecomposer.h 1
  62
  63     \section1 ImageComposer Class Implementation
  64
  65     We declare a QSize object, \c resultSize, as a static constant with width
  66     and height equal to 200.
  67
  68     \snippet painting/imagecomposition/imagecomposer.cpp 0
  69
  70     Within the constructor, we instantiate a QToolButton object,
  71     \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize}
  72     property to \c resultSize. The \c operatorComboBox is instantiated and
  73     then populated using the \c addOp() function. This function accepts a
  74     QPainter::CompositionMode, \a mode, and a QString, \a name, representing
  75     the name of the composition mode.
  76
  77     \snippet painting/imagecomposition/imagecomposer.cpp 1
  78
  79     The \c destinationButton is instantiated and its
  80     \l{QAbstractButton::setIconSize()}{iconSize} property is set to
  81     \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel
  82     are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()}
  83     {minimumWidth} is set.
  84
  85     \snippet painting/imagecomposition/imagecomposer.cpp 2
  86
  87     We connect the following signals to their corresponding slots:
  88     \list
  89         \li \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is
  90             connected to \c chooseSource(),
  91         \li \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()}
  92             signal is connected to \c recalculateResult(), and
  93         \li \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal
  94             is connected to \c chooseDestination().
  95     \endlist
  96
  97     \snippet painting/imagecomposition/imagecomposer.cpp 3
  98
  99     A QGridLayout, \c mainLayout, is used to place all the widgets. Note
 100     that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint}
 101     property is set to QLayout::SetFixedSize, which means that
 102     \c{ImageComposer}'s size cannot be resized at all.
 103
 104     \snippet painting/imagecomposition/imagecomposer.cpp 4
 105
 106     We create a QImage, \c resultImage, and we invoke \c loadImage() twice
 107     to load both the image files in our \e imagecomposition.qrc file. Then,
 108     we set the \l{QWidget::setWindowTitle()}{windowTitle} property to
 109     "Image Composition".
 110
 111     \snippet painting/imagecomposition/imagecomposer.cpp 5
 112
 113     The \c chooseSource() and \c chooseDestination() functions are
 114     convenience functions that invoke \c chooseImage() with specific
 115     parameters.
 116
 117     \snippet painting/imagecomposition/imagecomposer.cpp 6
 118     \codeline
 119     \snippet painting/imagecomposition/imagecomposer.cpp 7
 120
 121     The \c chooseImage() function loads an image of the user's choice,
 122     depending on the \a title, \a image, and \a button.
 123
 124     \snippet painting/imagecomposition/imagecomposer.cpp 10
 125
 126     The \c recalculateResult() function is used to calculate amd display the
 127     result of combining the two images together with the user's choice of
 128     composition mode.
 129
 130     \snippet painting/imagecomposition/imagecomposer.cpp 8
 131
 132     The \c addOp() function adds an item to the \c operatorComboBox using
 133     \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function
 134     accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The
 135     rectangle is filled with Qt::Transparent and both the \c sourceImage and
 136     \c destinationImage are painted, before displaying it on \c resultLabel.
 137
 138     \snippet painting/imagecomposition/imagecomposer.cpp 9
 139
 140     The \c loadImage() function paints a transparent background using
 141     \l{QPainter::fillRect()}{fillRect()} and draws \c image in a
 142     centralized position using \l{QPainter::drawImage()}{drawImage()}.
 143     This \c image is then set as the \c{button}'s icon.
 144
 145     \snippet painting/imagecomposition/imagecomposer.cpp 11
 146
 147     The \c currentMode() function returns the composition mode currently
 148     selected in \c operatorComboBox.
 149
 150     \snippet painting/imagecomposition/imagecomposer.cpp 12
 151
 152     We use the \c imagePos() function to ensure that images loaded onto the
 153     QToolButton objects, \c sourceButton and \c destinationButton, are
 154     centralized.
 155
 156     \snippet painting/imagecomposition/imagecomposer.cpp 13
 157
 158     \section1 The \c main() Function
 159
 160     The \c main() function instantiates QApplication and \c ImageComposer
 161     and invokes its \l{QWidget::show()}{show()} function.
 162
 163     \snippet painting/imagecomposition/main.cpp 0
 164
 165     */