diff options
Diffstat (limited to 'examples/widgets/doc/src/shapedclock.qdoc')
| -rw-r--r-- | examples/widgets/doc/src/shapedclock.qdoc | 104 |
1 files changed, 23 insertions, 81 deletions
diff --git a/examples/widgets/doc/src/shapedclock.qdoc b/examples/widgets/doc/src/shapedclock.qdoc index 732820cdc8..4bcd04683c 100644 --- a/examples/widgets/doc/src/shapedclock.qdoc +++ b/examples/widgets/doc/src/shapedclock.qdoc @@ -1,43 +1,21 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example widgets/shapedclock - \title Shaped Clock Example + \title Translucent Background + \examplecategory {User Interface Components} \ingroup examples-widgets - \brief The Shaped Clock example shows how to apply a translucent background - and a widget mask to a top-level widget to produce a shaped window. + \brief The example shows how to make a round window with a translucent + background. \borderedimage shapedclock-example.png - Widget masks are used to customize the shapes of top-level widgets by - restricting the area available for painting and mouse input. Using a - translucent background facilitates partially transparent windows and smooth - edges. On most window systems, setting certain window flags will cause the + 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. @@ -49,17 +27,15 @@ \section1 ShapedClock Class Definition The \c ShapedClock class is based on the \c AnalogClock class defined in the - \l{Analog Clock Example}{Analog Clock} example. The whole class definition is + \l{Analog Clock} example. The whole class definition is presented below: \snippet widgets/shapedclock/shapedclock.h 0 - The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as - that found in the \c AnalogClock class, with one important exception: we - now must also draw background (the clock face) ourselves, since the widget - background is just transparent. We implement \l{QWidget::sizeHint()}{sizeHint()} - so that we don't have to resize the widget explicitly. We also provide an event - handler for resize events. This allows us to update the mask if the clock is resized. + 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 @@ -69,8 +45,9 @@ \section1 ShapedClock Class Implementation - The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock - constructor. We set up a timer and connect it to the widget's update() slot: + 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 @@ -101,49 +78,14 @@ 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}{Analog Clock} example. The one addition is that we - use QPainter::drawEllipse() to draw a round clock face with the current - palette's default background color. We make the clock face a bit smaller - than the widget mask, so that the anti-aliased, semi-transparent pixels on - the edge are not clipped away by the widget mask. This gives the shaped - window smooth edges on the screen. + \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 - In the \c resizeEvent() handler, we re-use some of the code from the \c - paintEvent() to determine the region of the widget that is visible to the - user. This tells the system the area where mouse clicks should go to us, - and not to whatever window is behind us: - - \snippet widgets/shapedclock/shapedclock.cpp 4 - - Since the clock face is a circle drawn in the center of the widget, this is the region - we use as the mask. - - Although the lack of a window frame may make it difficult for the user to resize the - widget on some platforms, it will not necessarily be impossible. The \c resizeEvent() - function ensures that the widget mask will always be updated if the widget's dimensions - change, and additionally ensures that it will be set up correctly when the widget is - first displayed. - 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 5 - - \section1 Notes on Widget Masks - - Widget masks are used to hint to the window system that the application - does not want mouse events for areas outside the mask. On most systems, - they also result in coarse visual clipping. To get smooth window edges, one - should use translucent background and anti-aliased painting, as shown in - this example. - - Since QRegion allows arbitrarily complex regions to be created, widget masks can be - made to suit the most unconventionally-shaped windows, and even allow widgets to be - displayed with holes in them. - - Widget masks can also be constructed by using the contents of pixmap to define the - opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be - obtained with QPixmap::mask(). + \snippet widgets/shapedclock/shapedclock.cpp 4 */ |