| /**************************************************************************** |
| ** |
| ** 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 widgets/analogclock |
| \title Analog Clock Example |
| \ingroup examples-widgets |
| \brief The Analog Clock example shows how to draw the contents of a |
| custom widget. |
| |
| \borderedimage analogclock-example.png |
| \caption Screenshot of the Analog Clock example |
| |
| This example also demonstrates how the transformation and scaling |
| features of QPainter can be used to make drawing custom widgets |
| easier. |
| |
| \section1 AnalogClock Class Definition |
| |
| The \c AnalogClock class provides a clock widget with hour and minute |
| hands that is automatically updated every few seconds. |
| We subclass \l QWidget and reimplement the standard |
| \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face: |
| |
| \snippet widgets/analogclock/analogclock.h 0 |
| |
| \section1 AnalogClock Class Implementation |
| |
| \snippet widgets/analogclock/analogclock.cpp 1 |
| |
| When the widget is constructed, we set up a one-second timer to |
| keep track of the current time, and we connect it to the standard |
| \l{QWidget::update()}{update()} slot so that the clock face is |
| updated when the timer emits the \l{QTimer::timeout()}{timeout()} |
| signal. |
| |
| Finally, we resize the widget so that it is displayed at a |
| reasonable size. |
| |
| \snippet widgets/analogclock/analogclock.cpp 8 |
| \snippet widgets/analogclock/analogclock.cpp 10 |
| |
| The \c paintEvent() function is called whenever the widget's |
| contents need to be updated. This happens when the widget is |
| first shown, and when it is covered then exposed, but it is also |
| executed when the widget's \l{QWidget::update()}{update()} slot |
| is called. Since we connected the timer's |
| \l{QTimer::timeout()}{timeout()} signal to this slot, it will be |
| called at least once every five seconds. |
| |
| Before we set up the painter and draw the clock, we first define |
| two lists of \l {QPoint}s and two \l{QColor}s that will be used |
| for the hour and minute hands. The minute hand's color has an |
| alpha component of 191, meaning that it's 75% opaque. |
| |
| We also determine the length of the widget's shortest side so that we |
| can fit the clock face inside the widget. It is also useful to determine |
| the current time before we start drawing. |
| |
| \snippet widgets/analogclock/analogclock.cpp 11 |
| \snippet widgets/analogclock/analogclock.cpp 12 |
| \snippet widgets/analogclock/analogclock.cpp 13 |
| \snippet widgets/analogclock/analogclock.cpp 14 |
| |
| The contents of custom widgets are drawn with a QPainter. |
| Painters can be used to draw on any QPaintDevice, but they are |
| usually used with widgets, so we pass the widget instance to the |
| painter's constructor. |
| |
| We call QPainter::setRenderHint() with QPainter::Antialiasing to |
| turn on antialiasing. This makes drawing of diagonal lines much |
| smoother. |
| |
| The translation moves the origin to the center of the widget, and |
| the scale operation ensures that the following drawing operations |
| are scaled to fit within the widget. We use a scale factor that |
| let's us use x and y coordinates between -100 and 100, and that |
| ensures that these lie within the length of the widget's shortest |
| side. |
| |
| To make our code simpler, we will draw a fixed size clock face that will |
| be positioned and scaled so that it lies in the center of the widget. |
| |
| The painter takes care of all the transformations made during the |
| paint event, and ensures that everything is drawn correctly. Letting |
| the painter handle transformations is often easier than performing |
| manual calculations just to draw the contents of a custom widget. |
| |
| \image analogclock-viewport.png |
| |
| We draw the hour hand first, using a formula that rotates the coordinate |
| system counterclockwise by a number of degrees determined by the current |
| hour and minute. This means that the hand will be shown rotated clockwise |
| by the required amount. |
| |
| \snippet widgets/analogclock/analogclock.cpp 15 |
| \snippet widgets/analogclock/analogclock.cpp 16 |
| |
| We set the pen to be Qt::NoPen because we don't want any outline, |
| and we use a solid brush with the color appropriate for |
| displaying hours. Brushes are used when filling in polygons and |
| other geometric shapes. |
| |
| \snippet widgets/analogclock/analogclock.cpp 17 |
| \snippet widgets/analogclock/analogclock.cpp 19 |
| |
| We save and restore the transformation matrix before and after the |
| rotation because we want to place the minute hand without having to |
| take into account any previous rotations. |
| |
| \snippet widgets/analogclock/analogclock.cpp 20 |
| \codeline |
| \snippet widgets/analogclock/analogclock.cpp 21 |
| |
| We draw markers around the edge of the clock for each hour. We |
| draw each marker then rotate the coordinate system so that the |
| painter is ready for the next one. |
| |
| \snippet widgets/analogclock/analogclock.cpp 22 |
| \snippet widgets/analogclock/analogclock.cpp 23 |
| |
| The minute hand is rotated in a similar way to the hour hand. |
| |
| \snippet widgets/analogclock/analogclock.cpp 25 |
| \codeline |
| \snippet widgets/analogclock/analogclock.cpp 26 |
| |
| Again, we draw markers around the edge of the clock, but this |
| time to indicate minutes. We skip multiples of 5 to avoid drawing |
| minute markers on top of hour markers. |
| */ |