Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example widgets/analogclock
++ \examplecategory {Graphics}
++ \meta tags {widgets}
++
++ \title Analog Clock
++ \ingroup examples-widgets
++ \brief The Analog Clock example shows how to draw the contents of a
++ custom widget.
++
++ \image analogclock-example.png
++ {Analog clock with hour, minute, and seconds hands}
++ \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, minute and
++ second hands that is automatically updated every second.
++ 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
++
++ 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 1
++
++ 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 per second.
++
++ Before we set up the painter and draw the clock, we first define
++ three lists of \l {QPoint}s and three \l{QColor}s that will be used
++ for the hour, minute and second hands. We use the
++ \l{QWidget::palette()}{palette()} function to get appropriate colors
++ that fit into the rest of the window, both in light and dark mode.
++ The hour and minute hands are drawn in the foreground color, the
++ second hand is drawn in the accent color.
++
++ 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 8
++ \snippet widgets/analogclock/analogclock.cpp 10
++
++ 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.
++
++ \snippet widgets/analogclock/analogclock.cpp 11
++ \snippet widgets/analogclock/analogclock.cpp 14
++
++ We call QPainter::setRenderHint() with QPainter::Antialiasing to
++ turn on antialiasing. This makes drawing of diagonal lines much
++ smoother.
++
++ \snippet widgets/analogclock/analogclock.cpp 12
++
++ 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.
++
++ \snippet widgets/analogclock/analogclock.cpp 13
++
++ 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
++ {Shows widget coordinate system and origin on clock face}
++
++ 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 15
++ \snippet widgets/analogclock/analogclock.cpp 16
++
++ 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.
++ We save and restore the transformation matrix before and after the rotation
++ by instantiating a QPainterStateGuard because we want to place the minute
++ hand without having to take into account any previous rotations.
++
++ \snippet widgets/analogclock/analogclock.cpp 19
++
++ We draw markers around the edge of the clock for each hour in the same
++ color as the hour hand. We draw each marker then rotate the coordinate
++ system so that the painter is ready for the next one.
++
++ \snippet widgets/analogclock/analogclock.cpp 20
++
++ The minute hand is rotated and painted in a similar way to the hour hand.
++
++ \snippet widgets/analogclock/analogclock.cpp 21
++
++ For the seconds hand we do the same and add two circles as a visual highlight.
++
++ \snippet widgets/analogclock/analogclock.cpp 23
++ \codeline
++ \snippet widgets/analogclock/analogclock.cpp 24
++
++ Finally, we draw markers around the edge of the clock, indicating
++ minutes and seconds. This time we draw them as lines and therefore
++ set the pen to the respective color.
++
++ \snippet widgets/analogclock/analogclock.cpp 25
++ \codeline
++ \snippet widgets/analogclock/analogclock.cpp 27
++
++ */