34 /*! |
34 /*! |
35 @stable |
35 @stable |
36 @hbcore |
36 @hbcore |
37 \class HbToolTip |
37 \class HbToolTip |
38 |
38 |
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. |
40 |
63 |
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. |
42 |
67 |
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. |
|
45 |
69 |
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. |
|
64 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,25} |
73 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,25} |
65 |
74 |
66 \sa QGraphicsItem::toolTip, QAction::toolTip |
75 \sa QGraphicsItem, QAction |
67 */ |
76 */ |
68 |
77 |
69 /*! |
78 /*! |
|
79 This is analogous to calling |
|
80 HbToolTip::showText(const QString&,QGraphicsItem*,const QRectF&,Qt::Alignment) |
|
81 with the \a rect argument set to the widget's bounding rectangle |
|
82 (QGraphicsItem::boundingRect()). |
|
83 |
70 \overload |
84 \overload |
71 |
|
72 This is analogous to calling HbToolTip::showText(\a text, \a item, |
|
73 item->boundingRect(), \a preferredAlignment) |
|
74 */ |
85 */ |
75 void HbToolTip::showText( const QString &text, QGraphicsItem *item, |
86 void HbToolTip::showText( const QString &text, QGraphicsItem *item, |
76 Qt::Alignment preferredAlignment ) |
87 Qt::Alignment preferredAlignment ) |
77 { |
88 { |
78 showText( text, item, item ? item->boundingRect() : QRectF(), preferredAlignment ); |
89 showText( text, item, item ? item->boundingRect() : QRectF(), preferredAlignment ); |
79 } |
90 } |
80 |
91 |
81 /*! |
92 /*! |
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. |
84 |
111 |
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(). |
87 |
115 |
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 |
|
112 */ |
134 */ |
113 void HbToolTip::showText( const QString &text, QGraphicsItem *item, const QRectF &rect, |
135 void HbToolTip::showText( const QString &text, QGraphicsItem *item, const QRectF &rect, |
114 Qt::Alignment preferredAlignment ) |
136 Qt::Alignment preferredAlignment ) |
115 { |
137 { |
116 if (!item) { |
138 if (!item) { |
117 return; |
139 return; |
118 } |
140 } |
119 HbGraphicsScene *scene = qobject_cast<HbGraphicsScene *>( item->scene() ); |
141 HbGraphicsScene *scene = qobject_cast<HbGraphicsScene *>( item->scene() ); |
120 if ( scene && text.isEmpty() ) { // empty text means hide current tip |
142 if ( scene ) { |
121 scene->d_ptr->mToolTip->hide(); |
143 HbToolTipLabel *toolTip = scene->d_ptr->toolTip(); |
122 } else if (scene && scene->d_ptr->mToolTip) { |
144 if ( text.isEmpty() ) { // empty text means hide current tip |
123 |
145 toolTip->hide(); |
124 scene->d_ptr->mToolTip->setText(text); |
146 } else { |
125 scene->d_ptr->mToolTip->setRect( item->mapRectToScene(rect) ); |
147 toolTip->setText(text); |
126 scene->d_ptr->mToolTip->showText( item, preferredAlignment ); |
148 toolTip->setRect( item->mapRectToScene(rect) ); |
|
149 toolTip->showText( item, preferredAlignment ); |
|
150 } |
127 } |
151 } |
128 } |
152 } |
129 |
153 |
130 /*! |
154 /*! |
131 \fn void HbToolTip::hideText() |
155 Hides the visible tooltip in \a scene. This is equivalent to calling showText() |
132 |
156 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. |
|
135 |
157 |
136 \sa showText() |
158 \sa showText() |
137 */ |
159 */ |
138 void HbToolTip::hideText( HbGraphicsScene *scene ) |
160 void HbToolTip::hideText( HbGraphicsScene *scene ) |
139 { |
161 { |
140 if ( scene && scene->d_ptr->mToolTip) { |
162 if ( scene ) { |
141 if (scene->d_ptr->mToolTip->isVisible()) { |
163 HbToolTipLabel *toolTip = scene->d_ptr->toolTip(); |
142 scene->d_ptr->mToolTip->hide(); |
164 if (toolTip->isVisible()) { |
|
165 toolTip->hide(); |
143 } else { |
166 } else { |
144 //reset tooltip timers |
167 //reset tooltip timers |
145 scene->d_ptr->mToolTip->hideTextImmediately(); |
168 toolTip->hideTextImmediately(); |
146 } |
169 } |
147 } |
170 } |
148 } |
171 } |
149 |
172 |
150 /*! |
173 /*! |
151 Returns true if this tooltip is currently shown. |
174 Returns true if this tooltip is currently visible. |
152 |
175 |
153 \sa showText() |
176 \sa showText() |
154 */ |
177 */ |
155 bool HbToolTip::isVisible( const HbGraphicsScene *scene ) |
178 bool HbToolTip::isVisible( const HbGraphicsScene *scene ) |
156 { |
179 { |
157 if ( scene && scene->d_ptr->mToolTip ) { |
180 if ( scene ) { |
158 return scene->d_ptr->mToolTip->isVisible(); |
181 return scene->d_ptr->toolTip()->isVisible(); |
159 } else { |
182 } else { |
160 return false; |
183 return false; |
161 } |
184 } |
162 } |
185 } |
163 |
186 |
164 /*! |
187 /*! |
165 Returns the tooltip text, if a tooltip is visible, or an |
188 If the tooltip is visible, this returns the tooltip text; otherwise this function |
166 empty string if a tooltip is not visible. |
189 returns an empty string. |
167 */ |
190 */ |
168 QString HbToolTip::text( const HbGraphicsScene *scene ) |
191 QString HbToolTip::text( const HbGraphicsScene *scene ) |
169 { |
192 { |
170 if ( HbToolTip::isVisible(scene) ) { |
193 if ( scene ) { |
171 return scene->d_ptr->mToolTip->text(); |
194 return scene->d_ptr->toolTip()->text(); |
172 } |
195 } |
173 return QString(); |
196 return QString(); |
174 } |
197 } |