| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example painting/basicdrawing |
| \title Basic Drawing Example |
| \ingroup examples-painting |
| \brief The Basic Drawing example shows how to display basic |
| graphics primitives in a variety of styles using the QPainter |
| class. |
| |
| \brief 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 (\uicontrol Shape), and modify the QPainter's pen (\uicontrol |
| {Pen Width}, \uicontrol {Pen Style}, \uicontrol {Pen Cap}, \uicontrol {Pen Join}), |
| brush (\uicontrol {Brush Style}) and render hints (\uicontrol |
| Antialiasing). In addition the user can rotate a shape (\uicontrol |
| 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 |
| \li \c RenderArea is a custom widget that renders multiple |
| copies of the currently active shape. |
| \li \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 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 painting/basicdrawing/window.cpp 1 |
| |
| First we create the \c RenderArea widget that will render the |
| currently active shape. Then we create the \uicontrol Shape combobox, |
| and add the associated items (i.e. the different shapes a QPainter |
| can draw). |
| |
| \snippet 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 \uicontrol {Pen Width} parameter. |
| |
| \snippet 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 \uicontrol {Pen Style}, \uicontrol |
| {Pen Cap} and \uicontrol {Pen Join} parameters, and adds the associated |
| items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and |
| Qt::PenJoinStyle enums respectively). |
| |
| \snippet 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 \uicontrol {Brush Style} parameter, and add |
| the associated items (i.e. the values of the Qt::BrushStyle enum). |
| |
| \snippet painting/basicdrawing/window.cpp 5 |
| \snippet 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 \uicontrol Antialiasing option. |
| |
| \snippet painting/basicdrawing/window.cpp 7 |
| |
| The \uicontrol 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 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 painting/basicdrawing/window.cpp 9 |
| \snippet 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 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 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 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 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 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 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 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 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 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 painting/basicdrawing/renderarea.cpp 0 |
| |
| We set its shape to be a \uicontrol 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 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 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 painting/basicdrawing/renderarea.cpp 3 |
| \codeline |
| \snippet painting/basicdrawing/renderarea.cpp 4 |
| \codeline |
| \snippet 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 painting/basicdrawing/renderarea.cpp 6 |
| \codeline |
| \snippet 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 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 \uicontrol Points, \uicontrol Polyline and \uicontrol 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 \uicontrol Path and the \uicontrol 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 \uicontrol Arc, \uicontrol Chord and \uicontrol Pie shapes. |
| |
| \snippet 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 \uicontrol 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 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 painting/basicdrawing/renderarea.cpp 11 |
| |
| If the \uicontrol 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 painting/basicdrawing/renderarea.cpp 12 |
| |
| Next, we identify the \c RenderArea's shape, and render it using |
| the associated QPainter drawing function: |
| |
| \list |
| \li QPainter::drawLine(), |
| \li QPainter::drawPoints(), |
| \li QPainter::drawPolyline(), |
| \li QPainter::drawPolygon(), |
| \li QPainter::drawRect(), |
| \li QPainter::drawRoundedRect(), |
| \li QPainter::drawEllipse(), |
| \li QPainter::drawArc(), |
| \li QPainter::drawChord(), |
| \li QPainter::drawPie(), |
| \li QPainter::drawPath(), |
| \li QPainter::drawText() or |
| \li 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 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 \uicontrol Transformation parameter option is checked) both rotate |
| and scale the coordinate system, the easiest solution is to save |
| the current painter state. |
| */ |