source: trunk/doc/src/examples/tooltips.qdoc

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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.