39     \brief The HbToolTip class provides tool tips (balloon help) for any graphics item.

    39     \brief The HbToolTip class provides a set of static functions that augment the

    40     standard features provided by the tooltip framework. 

    41     

    42     A tooltip is a short piece of text that opens in a balloon, usually in response to

    43     the user tapping and holding on a widget or action button. The text provides a brief 

    44     explanation of the purpose of the item. 

    45     

    46     The easiest way to set a tooltip on a widget or action is to call the \c setToolTip() 

    47     function provided by QGraphicsItem and QAction, respectively. Both QGraphicsItem and 

    48     QAction also provide a \c toolTip() getter function. After setting the tooltip, you 

    49     can generally simply let the tooltip framework handle showing the tooltip when the 

    50     user taps and holds on the item and hiding the tooltip afterwards. The framework 

    51     shows the tooltip with the \c Qt::AlignTop alignment flag, which means that the tooltip

    52     appears above the top edge of the widget. 

    53     

    54     When the tooltip framework detects a tap and hold event, it sends a 

    55     QGraphicsSceneHelpEvent to the QGraphicsItem that is topmost in the scene under the 

    56     press point and has a non-empty tooltip text. If the QGraphicsItem accepts 

    57     the event, the framework does not show the tooltip. This means that when necessary 

    58     classes that are derived from QGraphicsItem can implement their own logic to show 

    59     the tooltip; for example, if you want the tooltip to appear to the right of the widget 

    60     rather than in the default position above it. To do this, the implementation calls

    61     one of the HbToolTip::showText() static function overloads to display the 

    62     tooltip.

    41     \mainclass

    64     The %HbToolTip class has other static functions that provide additional features.

    65     For example, you can call HbToolTip::isVisible() to find out whether a tooltip is 

    66     currently displayed and HbToolTip::text() to get the text that is currently visible.

    43     The tip is a short piece of text reminding the user of the

    68     \section _usecases_hbtooltip Using the HbToolTip class

    44     graphics item's function.

    46     The simplest and most common way to set a graphics item's tool tip is by

    70     This example shows how a custom widget class that is derived fromQGraphicsItem can 

    47     calling its QGraphicsItem::setToolTip() function.

    71     handle the QGraphicsSceneHelpEvent event to provide custom logic for showing a tooltip. 

    48 

    72     

    49     When a tooltip is currently on

    50     display, isVisible() returns true and text() the currently visible

    51     text.

    52 

    53     By default the tool tip framework is responsible for showing and hiding the tool tips

    54     on the scene. When the framework detects a long mouse press event it checks what is the

    55     top most QGraphicsItem on the scene having non empty tooltip text under the press point and

    56     sends an QGraphicsSceneHelpEvent to it. This makes it possible that QGraphicsItem derived

    57     objects can implement their own tool tip showing logic. If the sent QGraphicsSceneHelpEvent

    58     event is accepted by the QGraphicsItem object then framework does nothing. Otherwise it shows

    59     the tool tip text with Qt::AlignTop alignment.

    60 

    61     In rare cases QGraphicsItem derived classes can handle QGraphicsSceneHelpEvent to provide

    62     custom tool tip showing logic. An example on how to get custom tooltip alignment

    63     on a QGraphicsItem derived class.

    66     \sa QGraphicsItem::toolTip, QAction::toolTip

    75     \sa QGraphicsItem, QAction

    82     Shows \a text as a tool tip, with the prefererred alignment \a preferredAlignment in relation

    93     Shows a given text as a tooltip for a widget using a prefererred alignment. There

    83     to \a item.

    94     is an additional option to specify a region within the widget that accepts the 

    95     events that trigger the appearance of the tooltip. If this argument is specified,

    96     the tooltip disappears when the user's finger moves out of the defined region.

    97     

    98     Specify the preferred alignment of the tooltip relative to the side of the widget 

    99     using one of the following flags or flag combinations:

   100     

   101     - \c Qt::AlignTop

   102     - \c Qt::AlignRight

   103     - \c Qt::AlignLeft

   104     - \c Qt::AlignTop | \c Qt::AlignRight

   105     - \c Qt::AlignTop | \c Qt::AlignLeft

   106     

   107     For example, \c Qt::AlignTop aligns the lower edge of the tool tip with the top edge

   108     of the widget; \c Qt::AlignTop | \c Qt::AlignLeft aligns the lower-right corner of the 

   109     tooltip with the top-left corner of the widget; and \c Qt::AlignTop | \c Qt::AlignRight

   110     aligns the lower-left corner of the tooltip with the top-right corner of the widget.

    85     If you specify a non-empty rect the tip will be hidden as soon

   112     If the layout is right-to-left, the horizontal alignments are effectively reversed 

    86     as you move your cursor out of this area.

   113     (for example, \c Qt::AlignRight becomes \c Qt::AlignLeft), using the rules described 

   114     in \c QStyle::visualAlignment().

    88     The \a rect is in the coordinates of the graphics item you specify with

   116     If the tooltip cannot be aligned properly using the specified alignment without the

    89     \a item.

   117     tooltip intersecting the widget's bounding rectangle, this function uses another of the 

    90 

   118     supported alignment options.

    91     If \a text is empty or the item 0 the tool tip is hidden.

   119     

    92 

   120     You can use this function to hide a tooltip by setting \a text to empty or the \a item

    93     The supported alignment flags are Qt::AlignTop, Qt::AlignRight, Qt::AlignLeft,

   121     parameter to 0.

    94     Qt::AlignTop|Qt::AlignRight, Qt::AlignTop|Qt::AlignLeft. Any other alignment flags are ignored.

   122     

    95     Alignment flags are referring to the side of \a item i.e. when \a preferredAlignment

   123     \overload

    96     equals Qt::AlignTop the tool tip is aligned to the top of \a item and so on.

   124         

    97     When Qt::AlignTop|Qt::AlignLeft combination is used the bottom-right corner of the tool tip is

   125     \param text The text to be displayed. If this is empty, the function hides the 

    98     aligned to the top-left corner of \a item. When Qt::AlignTop|Qt::AlignRight combination is used

   126                 tooltip.

    99     the bottom-left corner of the tool tip is aligned to the top-right corner of \a item.

   127     \param item The widget the tooltip applies to. If this is 0, the function 

   100 

   128                 hides the tooltip.

   101     HbToolTip uses QStyle::visualAlignment() to transforms \a preferredAlignment according to the

   129     \param rect The region within the widget that the user can tap to display the tooltip.

   102     current layout direction. Qt::AlignAbsolute is supported the way is described

   130                 This is expressed in the coordinates of \a item.

   103     in QStyle::visualAlignment().

   131     \param preferredAlignment The alignment of the tooltip relative to the side of \a item. 

   104 

   132                 This must be one of the supported alignment flags or flag combinations 

   105     If the tool tip could not be aligned properly i.e. without intersecting \a item's bounding

   133                 specified above. Any other alignment flags are ignored.

   106     rectangle by using the provided \a preferredAlignment then it will be aligned by another

   107     supported alignment option.

   108 

   109     If none of the supported alignment options results proper alignment then Qt::AlignTop will

   110     be used.

   111 

   131     \fn void HbToolTip::hideText()

   153     Hides the visible tooltip in \a scene. This is equivalent to calling showText() 

   132 

   154     with an empty string or with the \a item parameter set to 0.

   133     Hides the visible tooltip in the \a scene. This is the same as calling showText() with an

   134     empty string or item parameter as 0.

   151   Returns true if this tooltip is currently shown.

   171     Returns true if this tooltip is currently visible.

   153   \sa showText()

   173     \sa showText()

   165   Returns the tooltip text, if a tooltip is visible, or an

   185    If the tooltip is visible, this returns the tooltip text; otherwise this function

   166   empty string if a tooltip is not visible.

   186    returns an empty string.