summaryrefslogtreecommitdiffstats
path: root/doc/html/ntqwhatsthis.html
blob: 5986243e69b17d46bfa1a539a5eef9620b856f97 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
<!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/qwhatsthis.cpp:61 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>TQWhatsThis 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&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;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>TQWhatsThis Class Reference</h1>

<p>The TQWhatsThis class provides a simple description of any
widget, i.e. answering the question "What's this?".
<a href="#details">More...</a>
<p><tt>#include &lt;<a href="qwhatsthis-h.html">ntqwhatsthis.h</a>&gt;</tt>
<p>Inherits <a href="ntqt.html">TQt</a>.
<p><a href="qwhatsthis-members.html">List of all member functions.</a>
<h2>Public Members</h2>
<ul>
<li class=fn><a href="#TQWhatsThis"><b>TQWhatsThis</b></a> ( TQWidget&nbsp;*&nbsp;widget )</li>
<li class=fn>virtual <a href="#~TQWhatsThis"><b>~TQWhatsThis</b></a> ()</li>
<li class=fn>virtual TQString <a href="#text"><b>text</b></a> ( const TQPoint &amp; )</li>
<li class=fn>virtual bool <a href="#clicked"><b>clicked</b></a> ( const&nbsp;TQString&nbsp;&amp;&nbsp;href )</li>
</ul>
<h2>Static Public Members</h2>
<ul>
<li class=fn>void <a href="#setFont"><b>setFont</b></a> ( const&nbsp;TQFont&nbsp;&amp;&nbsp;font )</li>
<li class=fn>void <a href="#add"><b>add</b></a> ( TQWidget&nbsp;*&nbsp;widget, const&nbsp;TQString&nbsp;&amp;&nbsp;text )</li>
<li class=fn>void <a href="#remove"><b>remove</b></a> ( TQWidget&nbsp;*&nbsp;widget )</li>
<li class=fn>TQString <a href="#textFor"><b>textFor</b></a> ( TQWidget&nbsp;*&nbsp;w, const&nbsp;TQPoint&nbsp;&amp;&nbsp;pos = TQPoint ( ), bool&nbsp;includeParents = FALSE )</li>
<li class=fn>TQToolButton * <a href="#whatsThisButton"><b>whatsThisButton</b></a> ( TQWidget&nbsp;*&nbsp;parent )</li>
<li class=fn>void <a href="#enterWhatsThisMode"><b>enterWhatsThisMode</b></a> ()</li>
<li class=fn>bool <a href="#inWhatsThisMode"><b>inWhatsThisMode</b></a> ()</li>
<li class=fn>void <a href="#leaveWhatsThisMode"><b>leaveWhatsThisMode</b></a> ( const&nbsp;TQString&nbsp;&amp;&nbsp;text = TQString::null, const&nbsp;TQPoint&nbsp;&amp;&nbsp;pos = TQCursor::pos ( ), TQWidget&nbsp;*&nbsp;w = 0 )</li>
<li class=fn>void <a href="#display"><b>display</b></a> ( const&nbsp;TQString&nbsp;&amp;&nbsp;text, const&nbsp;TQPoint&nbsp;&amp;&nbsp;pos = TQCursor::pos ( ), TQWidget&nbsp;*&nbsp;w = 0 )</li>
</ul>
<hr><a name="details"></a><h2>Detailed Description</h2>


The TQWhatsThis class provides a simple description of any
widget, i.e. answering the question "What's this?".
<p> 

<p> "What's this?" help is part of an application's online <a href="helpsystem.html#help-system">help system</a>
that provides users with information about functionality, usage,
background etc., in various levels of detail from short tool tips
to full text browsing help windows.
<p> TQWhatsThis provides a single window with an explanatory text that
pops up when the user asks "What's this?". The default way to do
this is to focus the relevant widget and press Shift+F1. The help
text appears immediately; it goes away as soon as the user does
something else.
<p> (Note that if there is an accelerator for Shift+F1, this mechanism
will not work.)
<p> To add "What's this?" text to a widget you simply call
<a href="#add">TQWhatsThis::add</a>() for the widget. For example, to assign text to a
menu item, call <a href="tqmenudata.html#setWhatsThis">TQMenuData::setWhatsThis</a>(); for a global
accelerator key, call <a href="ntqaccel.html#setWhatsThis">TQAccel::setWhatsThis</a>() and If you're using
actions, use <a href="tqaction.html#setWhatsThis">TQAction::setWhatsThis</a>().
<p> The text can be either rich text or plain text. If you specify a
rich text formatted string, it will be rendered using the default
stylesheet. This makes it possible to embed images. See
<a href="tqstylesheet.html#defaultSheet">TQStyleSheet::defaultSheet</a>() for details.
<p> 

<pre>        const char * fileOpenText = "&lt;p&gt;&lt;img source=\"fileopen\"&gt; "
                         "Click this button to open a &lt;em&gt;new file&lt;/em&gt;. &lt;br&gt;"
                         "You can also select the &lt;b&gt;Open&lt;/b&gt; command "
                         "from the &lt;b&gt;File&lt;/b&gt; menu.&lt;/p&gt;";
    <a name="x2104"></a>    TQMimeSourceFactory::<a href="tqmimesourcefactory.html#defaultFactory">defaultFactory</a>()-&gt;setPixmap( "document-open",
    <a name="x2102"></a>                          fileOpenAction-&gt;<a href="tqaction.html#iconSet">iconSet</a>().pixmap() );
    <a name="x2103"></a>    fileOpenAction-&gt;<a href="tqaction.html#setWhatsThis">setWhatsThis</a>( fileOpenText );
</pre>
<p> An alternative way to enter "What's this?" mode is to use the
ready-made tool bar tool button from
<a href="#whatsThisButton">TQWhatsThis::whatsThisButton</a>(). By invoking this context help
button (in the picture below the first one from the right) the
user switches into "What's this?" mode. If they now click on a
widget the appropriate help text is shown. The mode is left when
help is given or when the user presses Esc.
<p> <center><img src="whatsthis.png"></center> 
<p> If you are using <a href="tqmainwindow.html">TQMainWindow</a> you can also use the
<a href="tqmainwindow.html#whatsThis">TQMainWindow::whatsThis</a>() slot to invoke the mode from a menu item.
<p> For more control you can create a dedicated TQWhatsThis object for
a special widget. By subclassing and reimplementing
<a href="#text">TQWhatsThis::text</a>() it is possible to have different help texts,
depending on the position of the mouse click. By reimplementing
<a href="#clicked">TQWhatsThis::clicked</a>() it is possible to have hyperlinks inside the
help texts.
<p> If you wish to control the "What's this?" behavior of a widget
manually see <a href="tqwidget.html#customWhatsThis">TQWidget::customWhatsThis</a>().
<p> The What's This object can be removed using <a href="#remove">TQWhatsThis::remove</a>(),
although this is rarely necessary because it is automatically
removed when the widget is destroyed.
<p> <p>See also <a href="tqtooltip.html">TQToolTip</a> and <a href="helpsystem.html">Help System</a>.

<hr><h2>Member Function Documentation</h2>
<h3 class=fn><a name="TQWhatsThis"></a>TQWhatsThis::TQWhatsThis ( <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;widget )
</h3>
Constructs a dynamic "What's this?" object for <em>widget</em>. The
object is deleted when the <em>widget</em> is destroyed.
<p> When the widget is queried by the user the <a href="#text">text</a>() function of this
TQWhatsThis will be called to provide the appropriate text, rather
than using the text assigned by <a href="#add">add</a>().

<h3 class=fn><a name="~TQWhatsThis"></a>TQWhatsThis::~TQWhatsThis ()<tt> [virtual]</tt>
</h3>
Destroys the object and frees any allocated resources.

<h3 class=fn>void <a name="add"></a>TQWhatsThis::add ( <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;widget, const&nbsp;<a href="tqstring.html">TQString</a>&nbsp;&amp;&nbsp;text )<tt> [static]</tt>
</h3>
Adds <em>text</em> as "What's this" help for <em>widget</em>. If the text is
rich text formatted (i.e. it contains markup) it will be rendered
with the default stylesheet <a href="tqstylesheet.html#defaultSheet">TQStyleSheet::defaultSheet</a>().
<p> The text is destroyed if the widget is later destroyed, so it need
not be explicitly removed.
<p> <p>See also <a href="#remove">remove</a>().

<p>Examples: <a href="simple-application-example.html#x1591">application/application.cpp</a>, <a href="helpsystem-example.html#x2698">helpsystem/mainwindow.cpp</a>, and <a href="mdi-example.html#x2075">mdi/application.cpp</a>.
<h3 class=fn>bool <a name="clicked"></a>TQWhatsThis::clicked ( const&nbsp;<a href="tqstring.html">TQString</a>&nbsp;&amp;&nbsp;href )<tt> [virtual]</tt>
</h3>

<p> This virtual function is called when the user clicks inside the
"What's this?" window. <em>href</em> is the link the user clicked on, or
<a href="tqstring.html#TQString-null">TQString::null</a> if there was no link.
<p> If the function returns TRUE (the default), the "What's this?"
window is closed, otherwise it remains visible.
<p> The default implementation ignores <em>href</em> and returns TRUE.

<h3 class=fn>void <a name="display"></a>TQWhatsThis::display ( const&nbsp;<a href="tqstring.html">TQString</a>&nbsp;&amp;&nbsp;text, const&nbsp;<a href="ntqpoint.html">TQPoint</a>&nbsp;&amp;&nbsp;pos = TQCursor::pos ( ), <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;w = 0 )<tt> [static]</tt>
</h3>
Display <em>text</em> in a help window at the global screen position <em>pos</em>.
<p> If widget <em>w</em> is not 0 and has its own dedicated TQWhatsThis
object, this object will receive <a href="#clicked">clicked</a>() messages when the user
clicks on hyperlinks inside the help text.
<p> <p>See also <a href="#clicked">TQWhatsThis::clicked</a>().

<h3 class=fn>void <a name="enterWhatsThisMode"></a>TQWhatsThis::enterWhatsThisMode ()<tt> [static]</tt>
</h3>
Enters "What's this?" mode and returns immediately.
<p> TQt will install a special cursor and take over mouse input until
the user clicks somewhere. It then shows any help available and
ends "What's this?" mode. Finally, TQt removes the special cursor
and help window and then restores ordinary event processing, at
which point the left mouse button is no longer pressed.
<p> The user can also use the Esc key to leave "What's this?" mode.
<p> <p>See also <a href="#inWhatsThisMode">inWhatsThisMode</a>() and <a href="#leaveWhatsThisMode">leaveWhatsThisMode</a>().

<h3 class=fn>bool <a name="inWhatsThisMode"></a>TQWhatsThis::inWhatsThisMode ()<tt> [static]</tt>
</h3>
Returns TRUE if the application is in "What's this?" mode;
otherwise returns FALSE.
<p> <p>See also <a href="#enterWhatsThisMode">enterWhatsThisMode</a>() and <a href="#leaveWhatsThisMode">leaveWhatsThisMode</a>().

<h3 class=fn>void <a name="leaveWhatsThisMode"></a>TQWhatsThis::leaveWhatsThisMode ( const&nbsp;<a href="tqstring.html">TQString</a>&nbsp;&amp;&nbsp;text = TQString::null, const&nbsp;<a href="ntqpoint.html">TQPoint</a>&nbsp;&amp;&nbsp;pos = TQCursor::pos ( ), <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;w = 0 )<tt> [static]</tt>
</h3>
Leaves "What's this?" question mode.
<p> This function is used internally by widgets that support
<a href="tqwidget.html#customWhatsThis">TQWidget::customWhatsThis</a>(); applications do not usually call it.
An example of such a widget is TQPopupMenu: menus still work
normally in "What's this?" mode but also provide help texts for
individual menu items.
<p> If <em>text</em> is not <a href="tqstring.html#TQString-null">TQString::null</a>, a "What's this?" help window is
displayed at the global screen position <em>pos</em>. If widget <em>w</em> is
not 0 and has its own dedicated TQWhatsThis object, this object
will receive <a href="#clicked">clicked</a>() messages when the user clicks on hyperlinks
inside the help text.
<p> <p>See also <a href="#inWhatsThisMode">inWhatsThisMode</a>(), <a href="#enterWhatsThisMode">enterWhatsThisMode</a>(), and <a href="#clicked">TQWhatsThis::clicked</a>().

<h3 class=fn>void <a name="remove"></a>TQWhatsThis::remove ( <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;widget )<tt> [static]</tt>
</h3>
Removes the "What's this?" help associated with the <em>widget</em>.
This happens automatically if the widget is destroyed.
<p> <p>See also <a href="#add">add</a>().

<h3 class=fn>void <a name="setFont"></a>TQWhatsThis::setFont ( const&nbsp;<a href="ntqfont.html">TQFont</a>&nbsp;&amp;&nbsp;font )<tt> [static]</tt>
</h3>
Sets the font for all "What's this?" helps to <em>font</em>.

<h3 class=fn><a href="tqstring.html">TQString</a> <a name="text"></a>TQWhatsThis::text ( const&nbsp;<a href="ntqpoint.html">TQPoint</a>&nbsp;&amp; )<tt> [virtual]</tt>
</h3>
This virtual function returns the text for position <em>p</em> in the
widget that this "What's this?" object documents. If there is no
"What's this?" text for the position, <a href="tqstring.html#TQString-null">TQString::null</a> is returned.
<p> The default implementation returns TQString::null.

<h3 class=fn><a href="tqstring.html">TQString</a> <a name="textFor"></a>TQWhatsThis::textFor ( <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;w, const&nbsp;<a href="ntqpoint.html">TQPoint</a>&nbsp;&amp;&nbsp;pos = TQPoint ( ), bool&nbsp;includeParents = FALSE )<tt> [static]</tt>
</h3>
Returns the what's this text for widget <em>w</em> or <a href="tqstring.html#TQString-null">TQString::null</a> if
there is no "What's this?" help for the widget. <em>pos</em> contains
the mouse position; this is useful, for example, if you've
subclassed to make the text that is displayed position dependent.
<p> If <em>includeParents</em> is TRUE, parent widgets are taken into
consideration as well when looking for what's this help text.
<p> <p>See also <a href="#add">add</a>().

<h3 class=fn><a href="tqtoolbutton.html">TQToolButton</a>&nbsp;* <a name="whatsThisButton"></a>TQWhatsThis::whatsThisButton ( <a href="tqwidget.html">TQWidget</a>&nbsp;*&nbsp;parent )<tt> [static]</tt>
</h3>
Creates a <a href="tqtoolbutton.html">TQToolButton</a> preconfigured to enter "What's this?" mode
when clicked. You will often use this with a tool bar as <em>parent</em>:
<pre>
        (void) TQWhatsThis::whatsThisButton( my_help_tool_bar );
    </pre>
 

<p>Example: <a href="helpsystem-example.html#x2699">helpsystem/mainwindow.cpp</a>.
<!-- eof -->
<hr><p>
This file is part of the <a href="index.html">TQt toolkit</a>.
Copyright &copy; 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 &copy; 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>