--- 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<HbGraphicsScene *>( 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();
}