--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/basicdrawing.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,468 @@
+/****************************************************************************
+**
+** 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 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.
+*/