source: trunk/doc/src/examples/basicdrawing.qdoc

/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example painting/basicdrawing
    \title Basic Drawing Example

    The Basic Drawing example shows how to display basic graphics
    primitives in a variety of styles using the QPainter class.

    QPainter performs low-level painting on widgets and other paint
    devices. The class can draw everything from simple lines to
    complex shapes like pies and chords. It can also draw aligned text
    and pixmaps. Normally, it draws in a "natural" coordinate system,
    but it can in addition do view and world transformation.

    \image basicdrawing-example.png

    The example provides a render area, displaying the currently
    active shape, and lets the user manipulate the rendered shape and
    its appearance using the QPainter parameters: The user can change
    the active shape (\gui Shape), and modify the QPainter's pen (\gui
    {Pen Width}, \gui {Pen Style}, \gui {Pen Cap}, \gui {Pen Join}),
    brush (\gui {Brush Style}) and render hints (\gui
    Antialiasing). In addition the user can rotate a shape (\gui
    Transformations); behind the scenes we use QPainter's ability to
    manipulate the coordinate system to perform the rotation.

    The Basic Drawing example consists of two classes:

    \list
    \o \c RenderArea is a custom widget that renders multiple
       copies of the currently active shape.
    \o \c Window is the application's main window displaying a
       \c RenderArea widget in addition to several parameter widgets.
    \endlist

    First we will review the \c Window class, then we will take a
    look at the \c RenderArea class.

    \section1 Window Class Definition

    The Window class inherits QWidget, and is the application's main
    window displaying a \c RenderArea widget in addition to several
    parameter widgets.

    \snippet examples/painting/basicdrawing/window.h 0

    We declare the various widgets, and three private slots updating
    the \c RenderArea widget: The \c shapeChanged() slot updates the
    \c RenderArea widget when the user changes the currently active
    shape. We call the \c penChanged() slot when either of the
    QPainter's pen parameters changes. And the \c brushChanged() slot
    updates the \c RenderArea widget when the user changes the
    painter's brush style.

    \section1 Window Class Implementation

    In the constructor we create and initialize the various widgets
    appearing in the main application window.

    \snippet examples/painting/basicdrawing/window.cpp 1

    First we create the \c RenderArea widget that will render the
    currently active shape. Then we create the \gui Shape combobox,
    and add the associated items (i.e. the different shapes a QPainter
    can draw).

    \snippet examples/painting/basicdrawing/window.cpp 2

    QPainter's pen is a QPen object; the QPen class defines how a
    painter should draw lines and outlines of shapes. A pen has
    several properties: Width, style, cap and join.

    A pen's width can be \e zero or greater, but the most common width
    is zero. Note that this doesn't mean 0 pixels, but implies that
    the shape is drawn as smoothly as possible although perhaps not
    mathematically correct.

    We create a QSpinBox for the \gui {Pen Width} parameter.

    \snippet examples/painting/basicdrawing/window.cpp 3

    The pen style defines the line type. The default style is solid
    (Qt::SolidLine). Setting the style to none (Qt::NoPen) tells the
    painter to not draw lines or outlines.  The pen cap defines how
    the end points of lines are drawn.  And the pen join defines how
    two lines join when multiple connected lines are drawn. The cap
    and join only apply to lines with a width of 1 pixel or greater.

    We create \l {QComboBox}es for each of the \gui {Pen Style}, \gui
    {Pen Cap} and \gui {Pen Join} parameters, and adds the associated
    items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and
    Qt::PenJoinStyle enums respectively).

    \snippet examples/painting/basicdrawing/window.cpp 4

    The QBrush class defines the fill pattern of shapes drawn by a
    QPainter. The default brush style is Qt::NoBrush. This style tells
    the painter to not fill shapes. The standard style for filling is
    Qt::SolidPattern.

    We create a QComboBox for the \gui {Brush Style} parameter, and add
    the associated items (i.e. the values of the Qt::BrushStyle enum).

    \snippet examples/painting/basicdrawing/window.cpp 5
    \snippet examples/painting/basicdrawing/window.cpp 6

    Antialiasing is a feature that "smoothes" the pixels to create
    more even and less jagged lines, and can be applied using
    QPainter's render hints. QPainter::RenderHints are used to specify
    flags to QPainter that may or may not be respected by any given
    engine.

    We simply create a QCheckBox for the \gui Antialiasing option.

    \snippet examples/painting/basicdrawing/window.cpp 7

    The \gui Transformations option implies a manipulation of the
    coordinate system that will appear as if the rendered shape is
    rotated in three dimensions.

    We use the QPainter::translate(), QPainter::rotate() and
    QPainter::scale() functions to implement this feature represented
    in the main application window by a simple QCheckBox.

    \snippet examples/painting/basicdrawing/window.cpp 8

    Then we connect the parameter widgets with their associated slots
    using the static QObject::connect() function, ensuring that the \c
    RenderArea widget is updated whenever the user changes the shape,
    or any of the other parameters.

    \snippet examples/painting/basicdrawing/window.cpp 9
    \snippet examples/painting/basicdrawing/window.cpp 10

    Finally, we add the various widgets to a layout, and call the \c
    shapeChanged(), \c penChanged(), and \c brushChanged() slots to
    initialize the application. We also turn on antialiasing.

    \snippet examples/painting/basicdrawing/window.cpp 11

    The \c shapeChanged() slot is called whenever the user changes the
    currently active shape.

    First we retrieve the shape the user has chosen using the
    QComboBox::itemData() function. This function returns the data for
    the given role in the given index in the combobox. We use
    QComboBox::currentIndex() to retrieve the index of the shape, and
    the role is defined by the Qt::ItemDataRole enum; \c IdRole is an
    alias for Qt::UserRole.

    Note that Qt::UserRole is only the first role that can be used for
    application-specific purposes. If you need to store different data
    in the same index, you can use different roles by simply
    incrementing the value of Qt::UserRole, for example: 'Qt::UserRole
    + 1' and 'Qt::UserRole + 2'. However, it is a good programming
    practice to give each role their own name: 'myFirstRole =
    Qt::UserRole + 1' and 'mySecondRole = Qt::UserRole + 2'. Even
    though we only need a single role in this particular example, we
    add the following line of code to the beginning of the \c
    window.cpp file.

    \snippet examples/painting/basicdrawing/window.cpp 0

    The QComboBox::itemData() function returns the data as a QVariant,
    so we need to cast the data to \c RenderArea::Shape. If there is
    no data for the given role, the function returns
    QVariant::Invalid.

    In the end we call the \c RenderArea::setShape() slot to update
    the \c RenderArea widget.

    \snippet examples/painting/basicdrawing/window.cpp 12

    We call the \c penChanged() slot whenever the user changes any of
    the pen parameters. Again we use the QComboBox::itemData()
    function to retrieve the parameters, and then we call the \c
    RenderArea::setPen() slot to update the \c RenderArea widget.

    \snippet examples/painting/basicdrawing/window.cpp 13

    The brushChanged() slot is called whenever the user changes the
    brush parameter which we retrieve using the QComboBox::itemData()
    function as before.

    \snippet examples/painting/basicdrawing/window.cpp 14

    If the brush parameter is a gradient fill, special actions are
    required.

    The QGradient class is used in combination with QBrush to specify
    gradient fills. Qt currently supports three types of gradient
    fills: linear, radial and conical. Each of these is represented by
    a subclass of QGradient: QLinearGradient, QRadialGradient and
    QConicalGradient.

    So if the brush style is Qt::LinearGradientPattern, we first
    create a QLinearGradient object with interpolation area between
    the coordinates passed as arguments to the constructor. The
    positions are specified using logical coordinates. Then we set the
    gradient's colors using the QGradient::setColorAt() function. The
    colors is defined using stop points which are composed by a
    position (between 0 and 1) and a QColor. The set of stop points
    describes how the gradient area should be filled. A gradient can
    have an arbitrary number of stop points.

    In the end we call \c RenderArea::setBrush() slot to update the \c
    RenderArea widget's brush with the QLinearGradient object.

    \snippet examples/painting/basicdrawing/window.cpp 15

    A similar pattern of actions, as the one used for QLinearGradient,
    is used in the cases of Qt::RadialGradientPattern and
    Qt::ConicalGradientPattern.

    The only difference is the arguments passed to the constructor:
    Regarding the QRadialGradient constructor the first argument is
    the center, and the second the radial gradient's radius. The third
    argument is optional, but can be used to define the focal point of
    the gradient inside the circle (the default focal point is the
    circle center).  Regarding the QConicalGradient constructor, the
    first argument specifies the center of the conical, and the second
    specifies the start angle of the interpolation.

    \snippet examples/painting/basicdrawing/window.cpp 16

    If the brush style is Qt::TexturePattern we create a QBrush from a
    QPixmap. Then we call \c RenderArea::setBrush() slot to update the
    \c RenderArea widget with the newly created brush.

    \snippet examples/painting/basicdrawing/window.cpp 17

    Otherwise we simply create a brush with the given style and a
    green color, and then call \c RenderArea::setBrush() slot to
    update the \c RenderArea widget with the newly created brush.

    \section1 RenderArea Class Definition

    The \c RenderArea class inherits QWidget, and renders multiple
    copies of the currently active shape using a QPainter.

    \snippet examples/painting/basicdrawing/renderarea.h 0

    First we define a public \c Shape enum to hold the different
    shapes that can be rendered by the widget (i.e the shapes that can
    be rendered by a QPainter). Then we reimplement the constructor as
    well as two of QWidget's public functions: \l
    {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l
    {QWidget::sizeHint()}{sizeHint()}.

    We also reimplement the QWidget::paintEvent() function to be able
    to draw the currently active shape according to the specified
    parameters.

    We declare several private slots: The \c setShape() slot changes
    the \c RenderArea's shape, the \c setPen() and \c setBrush() slots
    modify the widget's pen and brush, and the \c setAntialiased() and
    \c setTransformed() slots modify the widget's respective
    properties.

    \section1 RenderArea Class Implementation

    In the constructor we initialize some of the widget's variables.

    \snippet examples/painting/basicdrawing/renderarea.cpp 0

    We set its shape to be a \gui Polygon, its antialiased property to
    be false and we load an image into the widget's pixmap
    variable. In the end we set the widget's background role, defining
    the brush from the widget's \l {QWidget::palette}{palette} that
    will be used to render the background. QPalette::Base is typically
    white.

    \snippet examples/painting/basicdrawing/renderarea.cpp 2

    The \c RenderArea inherits QWidget's \l
    {QWidget::sizeHint()}{sizeHint} property holding the recommended
    size for the widget. If the value of this property is an invalid
    size, no size is recommended.

    The default implementation of the QWidget::sizeHint() function
    returns an invalid size if there is no layout for the widget, and
    returns the layout's preferred size otherwise.

    Our reimplementation of the function returns a QSize with a 400
    pixels width and a 200 pixels height.

    \snippet examples/painting/basicdrawing/renderarea.cpp 1

    \c RenderArea also inherits QWidget's
    \l{QWidget::minimumSizeHint()}{minimumSizeHint} property holding
    the recommended minimum size for the widget. Again, if the value
    of this property is an invalid size, no size is recommended.

    The default implementation of QWidget::minimumSizeHint() returns
    an invalid size if there is no layout for the widget, and returns
    the layout's minimum size otherwise.

    Our reimplementation of the function returns a QSize with a 100
    pixels width and a 100 pixels height.

    \snippet examples/painting/basicdrawing/renderarea.cpp 3
    \codeline
    \snippet examples/painting/basicdrawing/renderarea.cpp 4
    \codeline
    \snippet examples/painting/basicdrawing/renderarea.cpp 5

    The public \c setShape(), \c setPen() and \c setBrush() slots are
    called whenever we want to modify a \c RenderArea widget's shape,
    pen or brush. We set the shape, pen or brush according to the
    slot parameter, and call QWidget::update() to make the changes
    visible in the \c RenderArea widget.

    The QWidget::update() slot does not cause an immediate
    repaint; instead it schedules a paint event for processing when Qt
    returns to the main event loop.

    \snippet examples/painting/basicdrawing/renderarea.cpp 6
    \codeline
    \snippet examples/painting/basicdrawing/renderarea.cpp 7

    With the \c setAntialiased() and \c setTransformed() slots we
    change the state of the properties according to the slot
    parameter, and call the QWidget::update() slot to make the changes
    visible in the \c RenderArea widget.

    \snippet examples/painting/basicdrawing/renderarea.cpp 8

    Then we reimplement the QWidget::paintEvent() function. The first
    thing we do is to create the graphical objects we will need to
    draw the various shapes.

    We create a vector of four \l {QPoint}s. We use this vector to
    render the \gui Points, \gui Polyline and \gui Polygon
    shapes. Then we create a QRect, defining a rectangle in the plane,
    which we use as the bounding rectangle for all the shapes excluding
    the \gui Path and the \gui Pixmap.

    We also create a QPainterPath. The QPainterPath class provides a
    container for painting operations, enabling graphical shapes to be
    constructed and reused. A painter path is an object composed of a
    number of graphical building blocks, such as rectangles, ellipses,
    lines, and curves. For more information about the QPainterPath
    class, see the \l {painting/painterpaths}{Painter Paths}
    example. In this example, we create a painter path composed of one
    straight line and a Bezier curve.

    In addition we define a start angle and an arc length that we will
    use when drawing the \gui Arc, \gui Chord and \gui Pie shapes.

    \snippet examples/painting/basicdrawing/renderarea.cpp 9

    We create a QPainter for the \c RenderArea widget, and set the
    painters pen and brush according to the \c RenderArea's pen and
    brush. If the \gui Antialiasing parameter option is checked, we
    also set the painter's render hints. QPainter::Antialiasing
    indicates that the engine should antialias edges of primitives if
    possible.

    \snippet examples/painting/basicdrawing/renderarea.cpp 10

    Finally, we render the multiple copies of the \c RenderArea's
    shape. The number of copies is depending on the size of the \c
    RenderArea widget, and we calculate their positions using two \c
    for loops and the widgets height and width.

    For each copy we first save the current painter state (pushes the
    state onto a stack). Then we translate the coordinate system,
    using the QPainter::translate() function, to the position
    determined by the variables of the \c for loops. If we omit this
    translation of the coordinate system all the copies of the shape
    will be rendered on top of each other in the top left cormer of
    the \c RenderArea widget.

    \snippet examples/painting/basicdrawing/renderarea.cpp 11

    If the \gui Transformations parameter option is checked, we do an
    additional translation of the coordinate system before we rotate
    the coordinate system 60 degrees clockwise using the
    QPainter::rotate() function and scale it down in size using the
    QPainter::scale() function. In the end we translate the coordinate
    system back to where it was before we rotated and scaled it.

    Now, when rendering the shape, it will appear as if it was rotated
    in three dimensions.

    \snippet examples/painting/basicdrawing/renderarea.cpp 12

    Next, we identify the \c RenderArea's shape, and render it using
    the associated QPainter drawing function:

    \list
        \o QPainter::drawLine(),
        \o QPainter::drawPoints(),
        \o QPainter::drawPolyline(),
        \o QPainter::drawPolygon(),
        \o QPainter::drawRect(),
        \o QPainter::drawRoundedRect(),
        \o QPainter::drawEllipse(),
        \o QPainter::drawArc(),
        \o QPainter::drawChord(),
        \o QPainter::drawPie(),
        \o QPainter::drawPath(),
        \o QPainter::drawText() or
        \o QPainter::drawPixmap()
    \endlist

    Before we started rendering, we saved the current painter state
    (pushes the state onto a stack). The rationale for this is that we
    calculate each shape copy's position relative to the same point in
    the coordinate system. When translating the coordinate system, we
    lose the knowledge of this point unless we save the current
    painter state \e before we start the translating process.

    \snippet examples/painting/basicdrawing/renderarea.cpp 13

    Then, when we are finished rendering a copy of the shape we can
    restore the original painter state, with its associated coordinate
    system, using the QPainter::restore() function. In this way we
    ensure that the next shape copy will be rendered in the correct
    position.

    We could translate the coordinate system back using
    QPainter::translate() instead of saving the painter state. But
    since we in addition to translating the coordinate system (when
    the \gui Transformation parameter option is checked) both rotate
    and scale the coordinate system, the easiest solution is to save
    the current painter state.
*/