--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/shapedclock.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,145 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example widgets/shapedclock
+ \title Shaped Clock Example
+
+ The Shaped Clock example shows how to apply a widget mask to a top-level
+ widget to produce a shaped window.
+
+ \image shapedclock-example.png
+
+ Widget masks are used to customize the shapes of top-level widgets by restricting
+ the available area for painting. On some 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 \gui File menu or a close
+ button, we provide a context menu with an \gui 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}{Analog Clock} example. The whole class definition is
+ presented below:
+
+ \snippet examples/widgets/shapedclock/shapedclock.h 0
+
+ The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found
+ in the \c AnalogClock class. 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.
+
+ 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 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:
+
+ \snippet examples/widgets/shapedclock/shapedclock.cpp 0
+
+ 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 examples/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 examples/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 given for completeness. See the
+ \l{Analog Clock Example}{Analog Clock} example for a description of the process used
+ to render the clock.
+
+ \snippet examples/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:
+
+ \snippet examples/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 examples/widgets/shapedclock/shapedclock.cpp 5
+
+ \section1 Notes on Widget Masks
+
+ 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().
+*/