// 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.

    \borderedimage shapedclock-example.png

    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 \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
*/