--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/tooltips.qdoc	Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,408 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 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/tooltips
+    \title Tool Tips Example
+
+    The Tool Tips example shows how to provide static and dynamic tool
+    tips for an application's widgets.
+
+    The simplest and most common way to set a widget's tool tip is by
+    calling its QWidget::setToolTip() function (static tool
+    tips). Then the tool tip is shown whenever the cursor points at
+    the widget. We show how to do this with our application's tool
+    buttons. But it is also possible to show different tool tips
+    depending on the cursor's position (dynamic tooltips). This
+    approach uses mouse tracking and event handling to determine what
+    widgets are located under the cursor at any point in time, and
+    displays their tool tips. The tool tips for the shape items in our
+    application are implemented using the latter approach.
+
+    \image tooltips-example.png
+
+    With the \c Tooltips application the user can create new shape
+    items with the provided tool buttons, and move the items around
+    using the mouse. Tooltips are provided whenever the cursor is
+    pointing to a shape item or one of the buttons.
+
+    The Tooltips example consists of two classes:
+
+    \list
+    \o \c ShapeItem is a custom widget representing one single shape item.
+    \o \c SortingBox inherits from QWidget and is the application's main
+        widget.
+    \endlist
+
+    First we will review the \c SortingBox class, then we will take a
+    look at the \c ShapeItem class.
+
+    \section1  SortingBox Class Definition
+
+    \snippet examples/widgets/tooltips/sortingbox.h 0
+
+    The \c SortingBox class inherits QWidget, and it is the Tooltips
+    application's main widget. We reimplement several of the event
+    handlers.
+
+    The \c event() function provides tooltips, the \c resize()
+    function makes sure the application appears consistently when the
+    user resizes the main widget, and the \c paintEvent() function
+    displays the shape items within the \c SortingBox widget. The
+    mouse event handlers are reimplemented to make the user able to
+    move the items around.
+
+    In addition we need three private slots to make the user able to
+    create new shape items.
+
+    \snippet examples/widgets/tooltips/sortingbox.h 1
+
+    We also create several private functions: We use the \c
+    initialItemPosition(), \c initialItemColor() and \c
+    createToolButton() functions when we are constructing the widget,
+    and we use the \c updateButtonGeometry() function whenever the
+    user is resizing the application's main widget.
+
+    The \c itemAt() function determines if there is a shape item at a
+    particular position, and the \c moveItemTo() function moves an
+    item to a new position. We use the \c createShapeItem(), \c
+    randomItemPosition() and \c randomItemColor() functions to create
+    new shape items.
+
+    \snippet examples/widgets/tooltips/sortingbox.h 2
+
+    We keep all the shape items in a QList, and we keep three
+    QPainterPath objects holding the shapes of a circle, a square and
+    a triangle. We also need to have a pointer to an item when it is
+    moving, and we need to know its previous position.
+
+    \section1 SortingBox Class Implementation
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 0
+
+    In the constructor, we first set the Qt::WA_StaticContents
+    attribute on the widget. This attribute indicates that the widget
+    contents are north-west aligned and static. On resize, such a
+    widget will receive paint events only for the newly visible part
+    of itself.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 1
+
+    To be able to show the appropiate tooltips while the user is
+    moving the cursor around, we need to enable mouse tracking for the
+    widget.
+
+    If mouse tracking is disabled (the default), the widget only
+    receives mouse move events when at least one mouse button is
+    pressed while the mouse is being moved. If mouse tracking is
+    enabled, the widget receives mouse move events even if no buttons
+    are pressed.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 2
+
+    A widget's background role defines the brush from the widget's
+    palette that is used to render the background, and QPalette::Base
+    is typically white.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 3
+
+    After creating the application's tool buttons using the private \c
+    createToolButton() function, we construct the shapes of a circle,
+    a square and a triangle using QPainterPath.
+
+    The QPainterPath class provides a container for painting
+    operations, enabling graphical shapes to be constructed and
+    reused. The main advantage of painter paths over normal drawing
+    operations is that complex shapes only need to be created once,
+    but they can be drawn many times using only calls to
+    QPainter::drawPath().
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 4
+
+    Then we set the window title, resize the widget to a suitable
+    size, and finally create three initial shape items using the
+    private \c createShapeItem(), \c initialItemPosition() and \c
+    initialItemColor() functions.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 5
+
+    QWidget::event() is the main event handler and receives all the
+    widget's events. Normally, we recommend reimplementing one of the
+    specialized event handlers instead of this function. But here we
+    want to catch the QEvent::ToolTip events, and since these are
+    rather rare, there exists no specific event handler. For that
+    reason we reimplement the main event handler, and the first thing
+    we need to do is to determine the event's type:
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 6
+
+    If the type is QEvent::ToolTip, we cast the event to a QHelpEvent,
+    otherwise we propagate the event using the QWidget::event()
+    function.
+
+    The QHelpEvent class provides an event that is used to request
+    helpful information about a particular point in a widget.
+
+    For example, the QHelpEvent::pos() function returns the event's
+    position relative to the widget to which the event is dispatched.
+    Here we use this information to determine if the position of the
+    event is contained within the area of any of the shape items. If
+    it is, we display the shape item's tooltip at the position of the
+    event. If not, we hide the tooltip and explicitly ignore the event.
+    This makes sure that the calling code does not start any tooltip
+    specific modes as a result of the event. Note that the
+    QToolTip::showText() function needs the event's position in global
+    coordinates provided by QHelpEvent::globalPos().
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 7
+
+    The \c resizeEvent() function is reimplemented to receive the
+    resize events dispatched to the widget. It makes sure that the
+    tool buttons keep their position relative to the main widget when
+    the widget is resized. We want the buttons to always be vertically
+    aligned in the application's bottom right corner, so each time the
+    main widget is resized we update the buttons geometry.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 8
+
+    The \c paintEvent() function is reimplemented to receive paint
+    events for the widget. We create a QPainter for the \c SortingBox
+    widget, and run through the list of created shape items, drawing
+    each item at its defined position.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 9
+
+    The painter will by default draw all the shape items at position
+    (0,0) in the \c SortingBox widget. The QPainter::translate()
+    function translates the coordinate system by the given offset,
+    making each shape item appear at its defined position. But
+    remember to translate the coordinate system back when the item is
+    drawn, otherwise the next shape item will appear at a position
+    relative to the item we drawed last.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 10
+
+    The QPainter::setBrush() function sets the current brush used by
+    the painter. When the provided argument is a QColor, the function
+    calls the appropiate QBrush constructor which creates a brush with
+    the specified color and Qt::SolidPattern style. The
+    QPainter::drawPath() function draws the given path using the
+    current pen for outline and the current brush for filling.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 11
+
+    The \c mousePressEvent() function is reimplemented to receive the
+    mouse press events dispatched to the widget. It determines if an
+    event's position is contained within the area of any of the shape
+    items, using the private \c itemAt() function.
+
+    If an item covers the position, we store a pointer to that item
+    and the event's position. If several of the shape items cover the
+    position, we store the pointer to the uppermost item. Finally, we
+    move the shape item to the end of the list, and make a call to the
+    QWidget::update() function to make the item appear on top.
+
+    The QWidget::update() function does not cause an immediate
+    repaint; instead it schedules a paint event for processing when Qt
+    returns to the main event loop.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 12
+
+    The \c mouseMoveEvent() function is reimplemented to receive mouse
+    move events for the widget. If the left mouse button is pressed
+    and there exists a shape item in motion, we use the private \c
+    moveItemTo() function to move the item with an offset
+    corresponding to the offset between the positions of the current
+    mouse event and the previous one.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 13
+
+    The \c mouseReleaseEvent() function is reimplemented to receive
+    the mouse release events dispatched to the widget. If the left
+    mouse button is pressed and there exists a shape item in motion,
+    we use the private \c moveItemTo() function to move the item like
+    we did in \c mouseMoveEvent(). But then we remove the pointer to
+    the item in motion, making the shape item's position final for
+    now. To move the item further, the user will need to press the
+    left mouse button again.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 14
+    \codeline
+    \snippet examples/widgets/tooltips/sortingbox.cpp 15
+    \codeline
+    \snippet examples/widgets/tooltips/sortingbox.cpp 16
+
+    The \c createNewCircle(), \c createNewSquare() and \c
+    createNewTriangle() slots simply create new shape items, using the
+    private \c createShapeItem(), \c randomItemPosition() and \c
+    randomItemColor() functions.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 17
+
+    In the \c itemAt() function, we run through the list of created
+    shape items to check if the given position is contained within the
+    area of any of the shape items.
+
+    For each shape item we use the QPainterPath::contains() function
+    to find out if the item's painter path contains the position. If
+    it does we return the index of the item, otherwise we return
+    -1. We run through the list backwards to get the index of the
+    uppermost shape item in case several items cover the position.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 18
+
+    The \c moveItemTo() function moves the shape item in motion, and
+    the parameter \c pos is the position of a mouse event. First we
+    calculate the offset between the parameter \c pos and the previous
+    mouse event position. Then we add the offset to the current
+    position of the item in motion.
+
+    It is tempting to simply set the position of the item to be the
+    parameter \c pos. But an item's position defines the top left
+    corner of the item's bounding rectangle, and the parameter \c pos
+    can be any point; The suggested shortcut would cause the item to
+    jump to a position where the cursor is pointing to the bounding
+    rectangle's top left corner, regardless of the item's previous
+    position.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 19
+
+    Finally, we update the previous mouse event position, and make a
+    call to the QWidget::update() function to make the item appear at
+    its new position.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 20
+
+    In the \c updateButtonGeometry() function we set the geometry for
+    the given button. The parameter coordinates define the bottom
+    right corner of the button. We use these coordinates and the
+    button's size hint to determine the position of the upper left
+    corner. This position, and the button's width and height, are the
+    arguments required by the QWidget::setGeometry() function.
+
+    In the end, we calculate and return the y-coordinate of the bottom
+    right corner of the next button. We use the QWidget::style()
+    function to retrieve the widget's GUI style, and then
+    QStyle::pixelMetric() to determine the widget's preferred default
+    spacing between its child widgets.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 21
+
+    The \c createShapeItem() function creates a single shape item. It
+    sets the path, tooltip, position and color, using the item's own
+    functions. In the end, the function appends the new item to the
+    list of shape items, and calls the QWidget::update() function to
+    make it appear with the other items within the \c SortingBox
+    widget.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 22
+
+    The \c createToolButton() function is called from the \c
+    SortingBox constructor. We create a tool button with the given
+    tooltip and icon. The button's parent is the \c SortingBox widget,
+    and its size is 32 x 32 pixels. Before we return the button, we
+    connect it to the given slot.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 23
+
+    The \c initialItemPosition() function is also called from the
+    constructor. We want the three first items to initially be
+    centered in the middle of the \c SortingBox widget, and we use
+    this function to calculate their positions.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 24
+
+    Whenever the user creates a new shape item, we want the new item
+    to appear at a random position, and we use the \c
+    randomItemPosition() function to calculate such a position. We
+    make sure that the item appears within the visible area of the
+    \c SortingBox widget, using the widget's current width and heigth
+    when calculating the random coordinates.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 25
+
+    As with \c initialItemPosition(), the \c initialItemColor()
+    function is called from the constructor. The purposes of both
+    functions are purely cosmetic: We want to control the inital
+    position and color of the three first items.
+
+    \snippet examples/widgets/tooltips/sortingbox.cpp 26
+
+    Finally the \c randomItemColor() function is implemented to give
+    the shape items the user creates, a random color.
+
+    \section1 ShapeItem Class Definition
+
+    \snippet examples/widgets/tooltips/shapeitem.h 0
+
+    The \c ShapeItem class is a custom widget representing one single
+    shape item. The widget has a path, a position, a color and a
+    tooltip. We need functions to set or modify these objects, as well
+    as functions that return them. We make the latter functions \c
+    const to prohibit any modifications of the objects,
+    i.e. prohibiting unauthorized manipulation of the shape items
+    appearance.
+
+    \section1 ShapeItem Class Implementation
+
+    \snippet examples/widgets/tooltips/shapeitem.cpp 0
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 1
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 2
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 3
+
+    This first group of functions simply return the objects that are
+    requested. The objects are returned as constants, i.e. they cannot
+    be modified.
+
+    \snippet examples/widgets/tooltips/shapeitem.cpp 4
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 5
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 6
+    \codeline
+    \snippet examples/widgets/tooltips/shapeitem.cpp 7
+
+    The last group of functions set or modify the shape item's path,
+    position, color and tooltip, respectively.
+*/