diff options
Diffstat (limited to 'doc/html/qtooltip.html')
| -rw-r--r-- | doc/html/qtooltip.html | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/doc/html/qtooltip.html b/doc/html/qtooltip.html new file mode 100644 index 000000000..7f501c2ab --- /dev/null +++ b/doc/html/qtooltip.html @@ -0,0 +1,376 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/widgets/qtooltip.cpp:643 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>TQToolTip Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>TQToolTip Class Reference</h1> + +<p>The TQToolTip class provides tool tips (balloon help) for +any widget or rectangular part of a widget. +<a href="#details">More...</a> +<p><tt>#include <<a href="qtooltip-h.html">qtooltip.h</a>></tt> +<p>Inherits <a href="qt.html">TQt</a>. +<p><a href="qtooltip-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#TQToolTip"><b>TQToolTip</b></a> ( TQWidget * widget, TQToolTipGroup * group = 0 )</li> +<li class=fn>TQWidget * <a href="#parentWidget"><b>parentWidget</b></a> () const</li> +<li class=fn>TQToolTipGroup * <a href="#group"><b>group</b></a> () const</li> +</ul> +<h2>Static Public Members</h2> +<ul> +<li class=fn>void <a href="#add"><b>add</b></a> ( TQWidget * widget, const TQString & text )</li> +<li class=fn>void <a href="#add-2"><b>add</b></a> ( TQWidget * widget, const TQString & text, TQToolTipGroup * group, const TQString & longText )</li> +<li class=fn>void <a href="#remove"><b>remove</b></a> ( TQWidget * widget )</li> +<li class=fn>void <a href="#add-3"><b>add</b></a> ( TQWidget * widget, const TQRect & rect, const TQString & text )</li> +<li class=fn>void <a href="#add-4"><b>add</b></a> ( TQWidget * widget, const TQRect & rect, const TQString & text, TQToolTipGroup * group, const TQString & groupText )</li> +<li class=fn>void <a href="#remove-2"><b>remove</b></a> ( TQWidget * widget, const TQRect & rect )</li> +<li class=fn>TQString <a href="#textFor"><b>textFor</b></a> ( TQWidget * widget, const TQPoint & pos = TQPoint ( ) )</li> +<li class=fn>void <a href="#hide"><b>hide</b></a> ()</li> +<li class=fn>TQFont <a href="#font"><b>font</b></a> ()</li> +<li class=fn>void <a href="#setFont"><b>setFont</b></a> ( const TQFont & font )</li> +<li class=fn>TQPalette <a href="#palette"><b>palette</b></a> ()</li> +<li class=fn>void <a href="#setPalette"><b>setPalette</b></a> ( const TQPalette & palette )</li> +<li class=fn>void setEnabled ( bool enable ) <em>(obsolete)</em></li> +<li class=fn>bool enabled () <em>(obsolete)</em></li> +<li class=fn>void <a href="#setGloballyEnabled"><b>setGloballyEnabled</b></a> ( bool enable )</li> +<li class=fn>bool <a href="#isGloballyEnabled"><b>isGloballyEnabled</b></a> ()</li> +<li class=fn>void <a href="#setWakeUpDelay"><b>setWakeUpDelay</b></a> ( int i )</li> +</ul> +<h2>Protected Members</h2> +<ul> +<li class=fn>virtual void <a href="#maybeTip"><b>maybeTip</b></a> ( const TQPoint & p ) = 0</li> +<li class=fn>void <a href="#tip"><b>tip</b></a> ( const TQRect & rect, const TQString & text )</li> +<li class=fn>void <a href="#tip-2"><b>tip</b></a> ( const TQRect & rect, const TQString & text, const TQString & groupText )</li> +<li class=fn>void <a href="#tip-3"><b>tip</b></a> ( const TQRect & rect, const TQString & text, const TQRect & geometry )</li> +<li class=fn>void <a href="#tip-4"><b>tip</b></a> ( const TQRect & rect, const TQString & text, const TQString & groupText, const TQRect & geometry )</li> +<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + +The TQToolTip class provides tool tips (balloon help) for +any widget or rectangular part of a widget. +<p> + +<p> The tip is a short, single line of text reminding the user of the +widget's or rectangle's function. It is drawn immediately below +the region in a distinctive black-on-yellow combination. +<p> The tip can be any Rich-Text formatted string. +<p> <a href="qtooltipgroup.html">TQToolTipGroup</a> provides a way for tool tips to display another text +elsewhere (most often in a <a href="qstatusbar.html">status bar</a>). +<p> At any point in time, TQToolTip is either dormant or active. In +dormant mode the tips are not shown and in active mode they are. +The mode is global, not particular to any one widget. +<p> TQToolTip switches from dormant to active mode when the user hovers +the mouse on a tip-etquipped region for a second or so and remains +active until the user either clicks a mouse button, presses a key, +lets the mouse hover for five seconds or moves the mouse outside +<em>all</em> tip-etquipped regions for at least a second. +<p> The TQToolTip class can be used in three different ways: +<ol type=1> +<li> Adding a tip to an entire widget. +<li> Adding a tip to a fixed rectangle within a widget. +<li> Adding a tip to a dynamic rectangle within a widget. +</ol> +<p> To add a tip to a widget, call the <em>static</em> function +<a href="#add">TQToolTip::add</a>() with the widget and tip as arguments: +<p> <pre> + TQToolTip::<a href="#add">add</a>( tquitButton, "Leave the application" ); + </pre> + +<p> This is the simplest and most common use of TQToolTip. The tip +will be deleted automatically when <em>tquitButton</em> is deleted, but +you can remove it yourself, too: +<p> <pre> + TQToolTip::<a href="#remove">remove</a>( tquitButton ); + </pre> + +<p> You can also display another text (typically in a <a href="qstatusbar.html">status bar),</a> courtesy of <a href="qtooltipgroup.html">TQToolTipGroup</a>. This example +assumes that <em>grp</em> is a <tt>TQToolTipGroup *</tt> and is already +connected to the appropriate status bar: +<p> <pre> + TQToolTip::<a href="#add">add</a>( tquitButton, "Leave the application", grp, + "Leave the application, prompting to save if necessary" ); + TQToolTip::<a href="#add">add</a>( closeButton, "Close this window", grp, + "Close this window, prompting to save if necessary" ); + </pre> + +<p> To add a tip to a fixed rectangle within a widget, call the static +function <a href="#add">TQToolTip::add</a>() with the widget, rectangle and tip as +arguments. (See the <a href="tooltip-example.html">tooltip/tooltip.cpp</a> example.) Again, you +can supply a <tt>TQToolTipGroup *</tt> and another text if you want. +<p> Both of these are one-liners and cover the majority of cases. The +third and most general way to use TQToolTip retquires you to +reimplement a pure virtual function to decide whether to pop up a +tool tip. The <a href="tooltip-example.html">tooltip/tooltip.cpp</a> example demonstrates this +too. This mode can be used to implement tips for text that can +move as the user scrolls, for example. +<p> To use TQToolTip like this, you must subclass TQToolTip and +reimplement <a href="#maybeTip">maybeTip</a>(). TQToolTip calls maybeTip() when a tip +should pop up, and maybeTip() decides whether to show a tip. +<p> Tool tips can be globally disabled using +<a href="#setGloballyEnabled">TQToolTip::setGloballyEnabled</a>() or disabled in groups with +<a href="qtooltipgroup.html#setEnabled">TQToolTipGroup::setEnabled</a>(). +<p> You can retrieve the text of a tooltip for a given position within +a widget using <a href="#textFor">textFor</a>(). +<p> The global tooltip font and palette can be set with the static +<a href="#setFont">setFont</a>() and <a href="#setPalette">setPalette</a>() functions respectively. +<p> <p>See also <a href="qstatusbar.html">TQStatusBar</a>, <a href="qwhatsthis.html">TQWhatsThis</a>, <a href="qtooltipgroup.html">TQToolTipGroup</a>, <a href="guibooks.html#fowler">GUI Design Handbook: Tool Tip</a>, and <a href="helpsystem.html">Help System</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="TQToolTip"></a>TQToolTip::TQToolTip ( <a href="qwidget.html">TQWidget</a> * widget, <a href="qtooltipgroup.html">TQToolTipGroup</a> * group = 0 ) +</h3> +Constructs a tool tip object. This is only necessary if you need +tool tips on regions that can move within the widget (most often +because the widget's contents can scroll). +<p> <em>widget</em> is the widget you want to add dynamic tool tips to and +<em>group</em> (optional) is the tool tip group they should belong to. +<p> <b>Warning:</b> TQToolTip is not a subclass of <a href="qobject.html">TQObject</a>, so the instance of +TQToolTip is not deleted when <em>widget</em> is deleted. +<p> <b>Warning:</b> If you delete the tool tip before you have deleted +<em>widget</em> then you need to make sure you call <a href="#remove">remove</a>() yourself from +<em>widget</em> in your reimplemented TQToolTip destructor. +<p> <pre> + MyToolTip::~MyToolTip() + { + <a href="#remove">remove</a>( widget ); + } + </pre> + +<p> <p>See also <a href="#maybeTip">maybeTip</a>(). + +<h3 class=fn>void <a name="add"></a>TQToolTip::add ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qstring.html">TQString</a> & text )<tt> [static]</tt> +</h3> +Adds a tool tip to <em>widget</em>. <em>text</em> is the text to be shown in +the tool tip. +<p> This is the most common entry point to the TQToolTip class; it is +suitable for adding tool tips to buttons, checkboxes, comboboxes +and so on. + +<p>Examples: <a href="helpsystem-example.html#x2695">helpsystem/mainwindow.cpp</a>, <a href="qdir-example.html#x1848">qdir/qdir.cpp</a>, <a href="scribble-example.html#x945">scribble/scribble.cpp</a>, and <a href="tooltip-example.html#x450">tooltip/tooltip.cpp</a>. +<h3 class=fn>void <a name="add-2"></a>TQToolTip::add ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qstring.html">TQString</a> & text, <a href="qtooltipgroup.html">TQToolTipGroup</a> * group, const <a href="qstring.html">TQString</a> & longText )<tt> [static]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Adds a tool tip to <em>widget</em> and to tool tip group <em>group</em>. +<p> <em>text</em> is the text shown in the tool tip and <em>longText</em> is the +text emitted from <em>group</em>. +<p> Normally, <em>longText</em> is shown in a <a href="qstatusbar.html">status + bar</a> or similar. + +<h3 class=fn>void <a name="add-3"></a>TQToolTip::add ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text )<tt> [static]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Adds a tool tip to a fixed rectangle, <em>rect</em>, within <em>widget</em>. +<em>text</em> is the text shown in the tool tip. + +<h3 class=fn>void <a name="add-4"></a>TQToolTip::add ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text, <a href="qtooltipgroup.html">TQToolTipGroup</a> * group, const <a href="qstring.html">TQString</a> & groupText )<tt> [static]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Adds a tool tip to an entire <em>widget</em> and to tool tip group <em>group</em>. The tooltip will disappear when the mouse leaves the <em>rect</em>. +<p> <em>text</em> is the text shown in the tool tip and <em>groupText</em> is the +text emitted from <em>group</em>. +<p> Normally, <em>groupText</em> is shown in a <a href="qstatusbar.html">status + bar</a> or similar. + +<h3 class=fn>void <a name="clear"></a>TQToolTip::clear ()<tt> [protected]</tt> +</h3> +Immediately removes all tool tips for this tooltip's parent +widget. + +<h3 class=fn>bool <a name="enabled"></a>TQToolTip::enabled ()<tt> [static]</tt> +</h3> + +<p> <b>This function is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code. +<p> +<h3 class=fn><a href="qfont.html">TQFont</a> <a name="font"></a>TQToolTip::font ()<tt> [static]</tt> +</h3> +Returns the font common to all tool tips. +<p> <p>See also <a href="#setFont">setFont</a>(). + +<h3 class=fn><a href="qtooltipgroup.html">TQToolTipGroup</a> * <a name="group"></a>TQToolTip::group () const +</h3> + +<p> Returns the tool tip group this TQToolTip is a member of or 0 if it +isn't a member of any group. +<p> The tool tip group is the object responsible for maintaining +contact between tool tips and a <a href="qstatusbar.html">status + bar</a> or something else which can show the longer help text. +<p> <p>See also <a href="#parentWidget">parentWidget</a>() and <a href="qtooltipgroup.html">TQToolTipGroup</a>. + +<h3 class=fn>void <a name="hide"></a>TQToolTip::hide ()<tt> [static]</tt> +</h3> +Hides any tip that is currently being shown. +<p> Normally, there is no need to call this function; TQToolTip takes +care of showing and hiding the tips as the user moves the mouse. + +<h3 class=fn>bool <a name="isGloballyEnabled"></a>TQToolTip::isGloballyEnabled ()<tt> [static]</tt> +</h3> +Returns whether tool tips are enabled globally. +<p> <p>See also <a href="#setGloballyEnabled">setGloballyEnabled</a>(). + +<h3 class=fn>void <a name="maybeTip"></a>TQToolTip::maybeTip ( const <a href="qpoint.html">TQPoint</a> & p )<tt> [pure virtual protected]</tt> +</h3> + +<p> This pure virtual function is half of the most versatile interface +TQToolTip offers. +<p> It is called when there is a possibility that a tool tip should be +shown and must decide whether there is a tool tip for the point <em>p</em> in the widget that this TQToolTip object relates to. If so, +<a href="#maybeTip">maybeTip</a>() must call <a href="#tip">tip</a>() with the rectangle the tip applies to, +the tip's text and optionally the <a href="qtooltipgroup.html">TQToolTipGroup</a> details and the +geometry in screen coordinates. +<p> <em>p</em> is given in that widget's local coordinates. Most maybeTip() +implementations will be of the form: +<p> <pre> + if ( <something> ) { + <a href="#tip">tip</a>( <something>, <something> ); + } + </pre> + +<p> The first argument to tip() (a rectangle) must encompass <em>p</em>, +i.e. the tip must apply to the current mouse position; otherwise +TQToolTip's operation is undefined. +<p> Note that the tip will disappear once the mouse moves outside the +rectangle you give to tip(), and will not reappear if the mouse +moves back in: maybeTip() is called again instead. +<p> <p>See also <a href="#tip">tip</a>(). + +<p>Examples: <a href="helpsystem-example.html#x2684">helpsystem/tooltip.cpp</a> and <a href="tooltip-example.html#x451">tooltip/tooltip.cpp</a>. +<h3 class=fn><a href="qpalette.html">TQPalette</a> <a name="palette"></a>TQToolTip::palette ()<tt> [static]</tt> +</h3> +Returns the palette common to all tool tips. +<p> <p>See also <a href="#setPalette">setPalette</a>(). + +<h3 class=fn><a href="qwidget.html">TQWidget</a> * <a name="parentWidget"></a>TQToolTip::parentWidget () const +</h3> + +<p> Returns the widget this TQToolTip applies to. +<p> The tool tip is destroyed automatically when the parent widget is +destroyed. +<p> <p>See also <a href="#group">group</a>(). + +<h3 class=fn>void <a name="remove"></a>TQToolTip::remove ( <a href="qwidget.html">TQWidget</a> * widget )<tt> [static]</tt> +</h3> +Removes the tool tip from <em>widget</em>. +<p> If there is more than one tool tip on <em>widget</em>, only the one +covering the entire widget is removed. + +<h3 class=fn>void <a name="remove-2"></a>TQToolTip::remove ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qrect.html">TQRect</a> & rect )<tt> [static]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Removes any tool tip for <em>rect</em> from <em>widget</em>. +<p> If there is more than one tool tip on <em>widget</em>, only the one +covering rectangle <em>rect</em> is removed. + +<h3 class=fn>void <a name="setEnabled"></a>TQToolTip::setEnabled ( bool enable )<tt> [static]</tt> +</h3> + +<p> <b>This function is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code. +<p> +<h3 class=fn>void <a name="setFont"></a>TQToolTip::setFont ( const <a href="qfont.html">TQFont</a> & font )<tt> [static]</tt> +</h3> +Sets the font for all tool tips to <em>font</em>. +<p> <p>See also <a href="#font">font</a>(). + +<h3 class=fn>void <a name="setGloballyEnabled"></a>TQToolTip::setGloballyEnabled ( bool enable )<tt> [static]</tt> +</h3> +If <em>enable</em> is TRUE sets all tool tips to be enabled (shown when +needed); if <em>enable</em> is FALSE sets all tool tips to be disabled +(never shown). +<p> By default, tool tips are enabled. Note that this function affects +all tool tips in the entire application. +<p> <p>See also <a href="qtooltipgroup.html#enabled-prop">TQToolTipGroup::enabled</a>. + +<h3 class=fn>void <a name="setPalette"></a>TQToolTip::setPalette ( const <a href="qpalette.html">TQPalette</a> & palette )<tt> [static]</tt> +</h3> +Sets the palette for all tool tips to <em>palette</em>. +<p> <p>See also <a href="#palette">palette</a>(). + +<h3 class=fn>void <a name="setWakeUpDelay"></a>TQToolTip::setWakeUpDelay ( int i )<tt> [static]</tt> +</h3> +Sets the wakeup delay for all tooltips to <em>i</em> +milliseconds. + +<h3 class=fn><a href="qstring.html">TQString</a> <a name="textFor"></a>TQToolTip::textFor ( <a href="qwidget.html">TQWidget</a> * widget, const <a href="qpoint.html">TQPoint</a> & pos = TQPoint ( ) )<tt> [static]</tt> +</h3> +Returns the tool tip text for <em>widget</em> at position <em>pos</em>, or +<a href="qstring.html#TQString-null">TQString::null</a> if there is no tool tip for the given widget and +position. + +<h3 class=fn>void <a name="tip"></a>TQToolTip::tip ( const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text )<tt> [protected]</tt> +</h3> +Immediately pops up a tip saying <em>text</em> and removes the tip once +the cursor moves out of rectangle <em>rect</em> (which is given in the +coordinate system of the widget this TQToolTip relates to). +<p> The tip will not reappear if the cursor moves back; your +<a href="#maybeTip">maybeTip</a>() must reinstate it each time. + +<h3 class=fn>void <a name="tip-2"></a>TQToolTip::tip ( const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text, const <a href="qstring.html">TQString</a> & groupText )<tt> [protected]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Immediately pops up a tip saying <em>text</em> and removes that tip once +the cursor moves out of rectangle <em>rect</em> (which is given in the +coordinate system of the widget this TQToolTip relates to). <em>groupText</em> is the text emitted from the group. +<p> The tip will not reappear if the cursor moves back; your +<a href="#maybeTip">maybeTip</a>() must reinstate it each time. + +<h3 class=fn>void <a name="tip-3"></a>TQToolTip::tip ( const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text, const <a href="qrect.html">TQRect</a> & geometry )<tt> [protected]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Immediately pops up a tip within the rectangle <em>geometry</em>, saying +<em>text</em> and removes the tip once the cursor moves out of rectangle +<em>rect</em>. Both rectangles are given in the coordinate system of the +widget this TQToolTip relates to. +<p> The tip will not reappear if the cursor moves back; your +<a href="#maybeTip">maybeTip</a>() must reinstate it each time. +<p> If the tip does not fit inside <em>geometry</em>, the tip expands. + +<h3 class=fn>void <a name="tip-4"></a>TQToolTip::tip ( const <a href="qrect.html">TQRect</a> & rect, const <a href="qstring.html">TQString</a> & text, const <a href="qstring.html">TQString</a> & groupText, const <a href="qrect.html">TQRect</a> & geometry )<tt> [protected]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Immediately pops up a tip within the rectangle <em>geometry</em>, saying +<em>text</em> and removes the tip once the cursor moves out of rectangle +<em>rect</em>. <em>groupText</em> is the text emitted from the group. Both +rectangles are given in the coordinate system of the widget this +TQToolTip relates to. +<p> The tip will not reappear if the cursor moves back; your +<a href="#maybeTip">maybeTip</a>() must reinstate it each time. +<p> If the tip does not fit inside <em>geometry</em>, the tip expands. + +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">TQt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>TQt 3.3.8</div> +</table></div></address></body> +</html> |