diff -r 7516d6d86cf5 -r ed14f46c0e55 src/hbcore/gui/hbtooltip.cpp --- a/src/hbcore/gui/hbtooltip.cpp Mon Oct 04 17:49:30 2010 +0300 +++ b/src/hbcore/gui/hbtooltip.cpp Mon Oct 18 18:23:13 2010 +0300 @@ -36,41 +36,52 @@ @hbcore \class HbToolTip - \brief The HbToolTip class provides tool tips (balloon help) for any graphics item. - - \mainclass - - The tip is a short piece of text reminding the user of the - graphics item's function. - - The simplest and most common way to set a graphics item's tool tip is by - calling its QGraphicsItem::setToolTip() function. + \brief The HbToolTip class provides a set of static functions that augment the + standard features provided by the tooltip framework. + + A tooltip is a short piece of text that opens in a balloon, usually in response to + the user tapping and holding on a widget or action button. The text provides a brief + explanation of the purpose of the item. + + The easiest way to set a tooltip on a widget or action is to call the \c setToolTip() + function provided by QGraphicsItem and QAction, respectively. Both QGraphicsItem and + QAction also provide a \c toolTip() getter function. After setting the tooltip, you + can generally simply let the tooltip framework handle showing the tooltip when the + user taps and holds on the item and hiding the tooltip afterwards. The framework + shows the tooltip with the \c Qt::AlignTop alignment flag, which means that the tooltip + appears above the top edge of the widget. + + When the tooltip framework detects a tap and hold event, it sends a + QGraphicsSceneHelpEvent to the QGraphicsItem that is topmost in the scene under the + press point and has a non-empty tooltip text. If the QGraphicsItem accepts + the event, the framework does not show the tooltip. This means that when necessary + classes that are derived from QGraphicsItem can implement their own logic to show + the tooltip; for example, if you want the tooltip to appear to the right of the widget + rather than in the default position above it. To do this, the implementation calls + one of the HbToolTip::showText() static function overloads to display the + tooltip. - When a tooltip is currently on - display, isVisible() returns true and text() the currently visible - text. + The %HbToolTip class has other static functions that provide additional features. + For example, you can call HbToolTip::isVisible() to find out whether a tooltip is + currently displayed and HbToolTip::text() to get the text that is currently visible. - By default the tool tip framework is responsible for showing and hiding the tool tips - on the scene. When the framework detects a long mouse press event it checks what is the - top most QGraphicsItem on the scene having non empty tooltip text under the press point and - sends an QGraphicsSceneHelpEvent to it. This makes it possible that QGraphicsItem derived - objects can implement their own tool tip showing logic. If the sent QGraphicsSceneHelpEvent - event is accepted by the QGraphicsItem object then framework does nothing. Otherwise it shows - the tool tip text with Qt::AlignTop alignment. + \section _usecases_hbtooltip Using the HbToolTip class - In rare cases QGraphicsItem derived classes can handle QGraphicsSceneHelpEvent to provide - custom tool tip showing logic. An example on how to get custom tooltip alignment - on a QGraphicsItem derived class. + This example shows how a custom widget class that is derived fromQGraphicsItem can + handle the QGraphicsSceneHelpEvent event to provide custom logic for showing a tooltip. + \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,25} - \sa QGraphicsItem::toolTip, QAction::toolTip + \sa QGraphicsItem, QAction */ /*! - \overload + This is analogous to calling + HbToolTip::showText(const QString&,QGraphicsItem*,const QRectF&,Qt::Alignment) + with the \a rect argument set to the widget's bounding rectangle + (QGraphicsItem::boundingRect()). - This is analogous to calling HbToolTip::showText(\a text, \a item, - item->boundingRect(), \a preferredAlignment) + \overload */ void HbToolTip::showText( const QString &text, QGraphicsItem *item, Qt::Alignment preferredAlignment ) @@ -79,36 +90,47 @@ } /*! - Shows \a text as a tool tip, with the prefererred alignment \a preferredAlignment in relation - to \a item. - - If you specify a non-empty rect the tip will be hidden as soon - as you move your cursor out of this area. - - The \a rect is in the coordinates of the graphics item you specify with - \a item. - - If \a text is empty or the item 0 the tool tip is hidden. + Shows a given text as a tooltip for a widget using a prefererred alignment. There + is an additional option to specify a region within the widget that accepts the + events that trigger the appearance of the tooltip. If this argument is specified, + the tooltip disappears when the user's finger moves out of the defined region. + + Specify the preferred alignment of the tooltip relative to the side of the widget + using one of the following flags or flag combinations: + + - \c Qt::AlignTop + - \c Qt::AlignRight + - \c Qt::AlignLeft + - \c Qt::AlignTop | \c Qt::AlignRight + - \c Qt::AlignTop | \c Qt::AlignLeft + + For example, \c Qt::AlignTop aligns the lower edge of the tool tip with the top edge + of the widget; \c Qt::AlignTop | \c Qt::AlignLeft aligns the lower-right corner of the + tooltip with the top-left corner of the widget; and \c Qt::AlignTop | \c Qt::AlignRight + aligns the lower-left corner of the tooltip with the top-right corner of the widget. - The supported alignment flags are Qt::AlignTop, Qt::AlignRight, Qt::AlignLeft, - Qt::AlignTop|Qt::AlignRight, Qt::AlignTop|Qt::AlignLeft. Any other alignment flags are ignored. - Alignment flags are referring to the side of \a item i.e. when \a preferredAlignment - equals Qt::AlignTop the tool tip is aligned to the top of \a item and so on. - When Qt::AlignTop|Qt::AlignLeft combination is used the bottom-right corner of the tool tip is - aligned to the top-left corner of \a item. When Qt::AlignTop|Qt::AlignRight combination is used - the bottom-left corner of the tool tip is aligned to the top-right corner of \a item. + If the layout is right-to-left, the horizontal alignments are effectively reversed + (for example, \c Qt::AlignRight becomes \c Qt::AlignLeft), using the rules described + in \c QStyle::visualAlignment(). - HbToolTip uses QStyle::visualAlignment() to transforms \a preferredAlignment according to the - current layout direction. Qt::AlignAbsolute is supported the way is described - in QStyle::visualAlignment(). - - If the tool tip could not be aligned properly i.e. without intersecting \a item's bounding - rectangle by using the provided \a preferredAlignment then it will be aligned by another - supported alignment option. - - If none of the supported alignment options results proper alignment then Qt::AlignTop will - be used. - + If the tooltip cannot be aligned properly using the specified alignment without the + tooltip intersecting the widget's bounding rectangle, this function uses another of the + supported alignment options. + + You can use this function to hide a tooltip by setting \a text to empty or the \a item + parameter to 0. + + \overload + + \param text The text to be displayed. If this is empty, the function hides the + tooltip. + \param item The widget the tooltip applies to. If this is 0, the function + hides the tooltip. + \param rect The region within the widget that the user can tap to display the tooltip. + This is expressed in the coordinates of \a item. + \param preferredAlignment The alignment of the tooltip relative to the side of \a item. + This must be one of the supported alignment flags or flag combinations + specified above. Any other alignment flags are ignored. */ void HbToolTip::showText( const QString &text, QGraphicsItem *item, const QRectF &rect, Qt::Alignment preferredAlignment ) @@ -117,58 +139,59 @@ return; } HbGraphicsScene *scene = qobject_cast( item->scene() ); - if ( scene && text.isEmpty() ) { // empty text means hide current tip - scene->d_ptr->mToolTip->hide(); - } else if (scene && scene->d_ptr->mToolTip) { - - scene->d_ptr->mToolTip->setText(text); - scene->d_ptr->mToolTip->setRect( item->mapRectToScene(rect) ); - scene->d_ptr->mToolTip->showText( item, preferredAlignment ); + if ( scene ) { + HbToolTipLabel *toolTip = scene->d_ptr->toolTip(); + if ( text.isEmpty() ) { // empty text means hide current tip + toolTip->hide(); + } else { + toolTip->setText(text); + toolTip->setRect( item->mapRectToScene(rect) ); + toolTip->showText( item, preferredAlignment ); + } } } /*! - \fn void HbToolTip::hideText() - - Hides the visible tooltip in the \a scene. This is the same as calling showText() with an - empty string or item parameter as 0. + Hides the visible tooltip in \a scene. This is equivalent to calling showText() + with an empty string or with the \a item parameter set to 0. \sa showText() */ void HbToolTip::hideText( HbGraphicsScene *scene ) { - if ( scene && scene->d_ptr->mToolTip) { - if (scene->d_ptr->mToolTip->isVisible()) { - scene->d_ptr->mToolTip->hide(); + if ( scene ) { + HbToolTipLabel *toolTip = scene->d_ptr->toolTip(); + if (toolTip->isVisible()) { + toolTip->hide(); } else { //reset tooltip timers - scene->d_ptr->mToolTip->hideTextImmediately(); + toolTip->hideTextImmediately(); } } } /*! - Returns true if this tooltip is currently shown. + Returns true if this tooltip is currently visible. - \sa showText() + \sa showText() */ bool HbToolTip::isVisible( const HbGraphicsScene *scene ) { - if ( scene && scene->d_ptr->mToolTip ) { - return scene->d_ptr->mToolTip->isVisible(); + if ( scene ) { + return scene->d_ptr->toolTip()->isVisible(); } else { return false; } } /*! - Returns the tooltip text, if a tooltip is visible, or an - empty string if a tooltip is not visible. + If the tooltip is visible, this returns the tooltip text; otherwise this function + returns an empty string. */ QString HbToolTip::text( const HbGraphicsScene *scene ) { - if ( HbToolTip::isVisible(scene) ) { - return scene->d_ptr->mToolTip->text(); + if ( scene ) { + return scene->d_ptr->toolTip()->text(); } return QString(); }