Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example widgets/shapedclock
++ \title Translucent Background
++ \examplecategory {User Interface Components}
++ \ingroup examples-widgets
++ \brief The example shows how to make a round window with a translucent
++ background.
++
++ \image shapedclock-example.png
++ {Translucent clock overlaid on text}
++
++ Widgets that set their background to be translucent will be transparent for all
++ unpainted pixels, and the background will shine through pixels painted with an
++ opacity of less than 100%. Pixels that are not painted at all will also not
++ receive any mouse input. This can be used to customize the shapes of top-level
++ widgets. On most window systems, setting certain window flags will cause the
++ window decoration (title bar, window frame, buttons) to be disabled,
++ allowing specially-shaped windows to be created. In this example, we use
++ this feature to create a circular window containing an analog clock.
++
++ Since this example's window does not provide a \uicontrol File menu or a close
++ button, we provide a context menu with an \uicontrol Exit entry so that the example
++ can be closed. Click the right mouse button over the window to open this menu.
++
++ \section1 ShapedClock Class Definition
++
++ The \c ShapedClock class is based on the \c AnalogClock class defined in the
++ \l{Analog Clock} example. The whole class definition is
++ presented below:
++
++ \snippet widgets/shapedclock/shapedclock.h 0
++
++ The \l{QWidget::paintEvent()}{paintEvent()} implementation draws an analog clock
++ on a semi-transparent background (the clock face). In addition, we implement
++ \l{QWidget::sizeHint()}{sizeHint()} so that we don't have to resize the widget
++ explicitly.
++
++ Since the window containing the clock widget will have no title bar, we provide
++ implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and
++ \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged
++ around the screen. The \c dragPosition variable lets us keep track of where the user
++ last clicked on the widget.
++
++ \section1 ShapedClock Class Implementation
++
++ The \c ShapedClock constructor sets up a timer and connect it to the widget's
++ update() slot. In addition, we add an action to the widget, which will automatically
++ become available through a context menu when right-clicking on the widget.
++
++ \snippet widgets/shapedclock/shapedclock.cpp 0
++
++ We request a transparent window by setting the Qt::WA_TranslucentBackground
++ widget attribute. We inform the window manager that the widget is not to be
++ decorated with a window frame by setting the Qt::FramelessWindowHint flag
++ on the widget. As a result, we need to provide a way for the user to move
++ the clock around the screen.
++
++ Mouse button events are delivered to the \c mousePressEvent() handler:
++
++ \snippet widgets/shapedclock/shapedclock.cpp 1
++
++ If the left mouse button is pressed over the widget, we record the displacement in
++ global (screen) coordinates between the top-left position of the widget's frame (even
++ when hidden) and the point where the mouse click occurred. This displacement will be
++ used if the user moves the mouse while holding down the left button. Since we acted
++ on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function.
++
++ \image shapedclock-dragging.png
++ {The drag position relative to the clock face}
++
++ The \c mouseMoveEvent() handler is called if the mouse is moved over the widget.
++
++ \snippet widgets/shapedclock/shapedclock.cpp 2
++
++ If the left button is held down while the mouse is moved, the top-left corner of the
++ widget is moved to the point given by subtracting the \c dragPosition from the current
++ cursor position in global coordinates. If we drag the widget, we also accept the event.
++
++ The \c paintEvent() function is mainly the same as described in the
++ \l{Analog Clock} example. The one addition is that we use QPainter::drawEllipse() to
++ draw a round clock face. We reduce the painter's opacity to 90%, and use the palette's
++ default background color.
++
++ \snippet widgets/shapedclock/shapedclock.cpp 3
++
++ Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable
++ default size when it is first shown:
++
++ \snippet widgets/shapedclock/shapedclock.cpp 4
++ */