source: trunk/doc/html/qtextbrowser.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 15.3 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/widgets/qtextbrowser.cpp:59 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QTextBrowser Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QTextBrowser Class Reference</h1>
33
34<p>The QTextBrowser class provides a rich text browser with hypertext navigation.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qtextbrowser-h.html">qtextbrowser.h</a>&gt;</tt>
37<p>Inherits <a href="qtextedit.html">QTextEdit</a>.
38<p><a href="qtextbrowser-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QTextBrowser"><b>QTextBrowser</b></a> ( QWidget&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
42<li class=fn>QString <a href="#source"><b>source</b></a> () const</li>
43</ul>
44<h2>Public Slots</h2>
45<ul>
46<li class=fn>virtual void <a href="#setSource"><b>setSource</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
47<li class=fn>virtual void <a href="#backward"><b>backward</b></a> ()</li>
48<li class=fn>virtual void <a href="#forward"><b>forward</b></a> ()</li>
49<li class=fn>virtual void <a href="#home"><b>home</b></a> ()</li>
50<li class=fn>virtual void <a href="#reload"><b>reload</b></a> ()</li>
51</ul>
52<h2>Signals</h2>
53<ul>
54<li class=fn>void <a href="#backwardAvailable"><b>backwardAvailable</b></a> ( bool&nbsp;available )</li>
55<li class=fn>void <a href="#forwardAvailable"><b>forwardAvailable</b></a> ( bool&nbsp;available )</li>
56<li class=fn>void <a href="#sourceChanged"><b>sourceChanged</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;src )</li>
57<li class=fn>void <a href="#highlighted"><b>highlighted</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;link )</li>
58<li class=fn>void <a href="#linkClicked"><b>linkClicked</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;link )</li>
59<li class=fn>void <a href="#anchorClicked"><b>anchorClicked</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, const&nbsp;QString&nbsp;&amp;&nbsp;link )</li>
60</ul>
61<h2>Properties</h2>
62<ul>
63<li class=fn>bool <a href="#modified-prop"><b>modified</b></a>&nbsp;- whether the contents have been modified &nbsp;<em>(read only)</em></li>
64<li class=fn>bool <a href="#overwriteMode-prop"><b>overwriteMode</b></a>&nbsp;- this text browser's overwrite mode &nbsp;<em>(read only)</em></li>
65<li class=fn>bool <a href="#readOnly-prop"><b>readOnly</b></a>&nbsp;- whether the contents are read only &nbsp;<em>(read only)</em></li>
66<li class=fn>QString <a href="#source-prop"><b>source</b></a>&nbsp;- the name of the displayed document</li>
67<li class=fn>int <a href="#undoDepth-prop"><b>undoDepth</b></a>&nbsp;- this text browser's undo depth &nbsp;<em>(read only)</em></li>
68<li class=fn>bool <a href="#undoRedoEnabled-prop"><b>undoRedoEnabled</b></a>&nbsp;- whether undo and redo are enabled &nbsp;<em>(read only)</em></li>
69</ul>
70<h2>Protected Members</h2>
71<ul>
72<li class=fn>virtual void <a href="#keyPressEvent"><b>keyPressEvent</b></a> ( QKeyEvent&nbsp;*&nbsp;e )</li>
73</ul>
74<hr><a name="details"></a><h2>Detailed Description</h2>
75
76
77The QTextBrowser class provides a rich text browser with hypertext navigation.
78<p>
79
80
81
82<p> This class extends <a href="qtextedit.html">QTextEdit</a> (in read-only mode), adding some
83navigation functionality so that users can follow links in
84hypertext documents. The contents of QTextEdit is set with
85<a href="qtextedit.html#setText">setText</a>(), but QTextBrowser has an additional function,
86<a href="#setSource">setSource</a>(), which makes it possible to set the text to a named
87document. The name is looked up in the text view's mime source
88factory. If a document name ends with an anchor (for example, "<tt>#anchor"</tt>), the text browser automatically scrolls to that position
89(using <a href="qtextedit.html#scrollToAnchor">scrollToAnchor</a>()). When the user clicks on a hyperlink, the
90browser will call setSource() itself, with the link's <tt>href</tt>
91value as argument. You can track the current source by connetion
92to the <a href="#sourceChanged">sourceChanged</a>() signal.
93<p> QTextBrowser provides <a href="#backward">backward</a>() and <a href="#forward">forward</a>() slots which you can
94use to implement Back and Forward buttons. The <a href="#home">home</a>() slot sets
95the text to the very first document displayed. The <a href="#linkClicked">linkClicked</a>()
96signal is emitted when the user clicks a link.
97<p> By using <a href="qtextedit.html#setMimeSourceFactory">QTextEdit::setMimeSourceFactory</a>() you can provide your
98own subclass of <a href="qmimesourcefactory.html">QMimeSourceFactory</a>. This makes it possible to
99access data from anywhere, for example from a network or from a
100database. See <a href="qmimesourcefactory.html#data">QMimeSourceFactory::data</a>() for details.
101<p> If you intend using the mime factory to read the data directly
102from the file system, you may have to specify the encoding for the
103file extension you are using. For example:
104<pre>
105 <a href="qtextedit.html#mimeSourceFactory">mimeSourceFactory</a>()-&gt;setExtensionType("qml", "text/utf8");
106 </pre>
107
108This is to ensure that the factory is able to resolve the document
109names.
110<p> QTextBrowser interprets the tags it processes in accordance with
111the default style sheet. Change the style sheet with
112<a href="qtextedit.html#setStyleSheet">setStyleSheet</a>(); see <a href="qstylesheet.html">QStyleSheet</a> for details.
113<p> If you want to provide your users with editable rich text use
114<a href="qtextedit.html">QTextEdit</a>. If you want a text browser without hypertext navigation
115use QTextEdit, and use <a href="qtextedit.html#setReadOnly">QTextEdit::setReadOnly</a>() to disable
116editing. If you just need to display a small piece of rich text
117use <a href="qsimplerichtext.html">QSimpleRichText</a> or <a href="qlabel.html">QLabel</a>.
118<p> <img src=qtextbrowser-m.png> <img src=qtextbrowser-w.png>
119<p>See also <a href="advanced.html">Advanced Widgets</a>, <a href="helpsystem.html">Help System</a>, and <a href="text.html">Text Related Classes</a>.
120
121<hr><h2>Member Function Documentation</h2>
122<h3 class=fn><a name="QTextBrowser"></a>QTextBrowser::QTextBrowser ( <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
123</h3>
124Constructs an empty QTextBrowser called <em>name</em>, with parent <em>parent</em>.
125
126<h3 class=fn>void <a name="anchorClicked"></a>QTextBrowser::anchorClicked ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;link )<tt> [signal]</tt>
127</h3>
128
129<p> This signal is emitted when the user clicks an anchor. The <em>link</em> is
130the value of the <tt>href</tt> i.e. the name of the target document. The <em>name</em>
131is the name of the anchor.
132<p> <p>See also <a href="#linkClicked">linkClicked</a>().
133
134<h3 class=fn>void <a name="backward"></a>QTextBrowser::backward ()<tt> [virtual slot]</tt>
135</h3>
136Changes the document displayed to the previous document in the
137list of documents built by navigating links. Does nothing if there
138is no previous document.
139<p> <p>See also <a href="#forward">forward</a>() and <a href="#backwardAvailable">backwardAvailable</a>().
140
141<p>Example: <a href="helpviewer-example.html#x1019">helpviewer/helpwindow.cpp</a>.
142<h3 class=fn>void <a name="backwardAvailable"></a>QTextBrowser::backwardAvailable ( bool&nbsp;available )<tt> [signal]</tt>
143</h3>
144
145<p> This signal is emitted when the availability of <a href="#backward">backward</a>()
146changes. <em>available</em> is FALSE when the user is at <a href="#home">home</a>();
147otherwise it is TRUE.
148
149<p>Example: <a href="helpviewer-example.html#x1020">helpviewer/helpwindow.cpp</a>.
150<h3 class=fn>void <a name="forward"></a>QTextBrowser::forward ()<tt> [virtual slot]</tt>
151</h3>
152Changes the document displayed to the next document in the list of
153documents built by navigating links. Does nothing if there is no
154next document.
155<p> <p>See also <a href="#backward">backward</a>() and <a href="#forwardAvailable">forwardAvailable</a>().
156
157<p>Example: <a href="helpviewer-example.html#x1021">helpviewer/helpwindow.cpp</a>.
158<h3 class=fn>void <a name="forwardAvailable"></a>QTextBrowser::forwardAvailable ( bool&nbsp;available )<tt> [signal]</tt>
159</h3>
160
161<p> This signal is emitted when the availability of <a href="#forward">forward</a>() changes.
162<em>available</em> is TRUE after the user navigates <a href="#backward">backward</a>() and FALSE
163when the user navigates or goes forward().
164
165<p>Example: <a href="helpviewer-example.html#x1022">helpviewer/helpwindow.cpp</a>.
166<h3 class=fn>void <a name="highlighted"></a>QTextBrowser::highlighted ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;link )<tt> [signal]</tt>
167</h3>
168<p> This signal is emitted when the user has selected but not
169activated a link in the document. <em>link</em> is the value of the <tt>href</tt> i.e. the name of the target document.
170
171<p>Example: <a href="helpviewer-example.html#x1023">helpviewer/helpwindow.cpp</a>.
172<h3 class=fn>void <a name="home"></a>QTextBrowser::home ()<tt> [virtual slot]</tt>
173</h3>
174Changes the document displayed to be the first document the
175browser displayed.
176
177<p>Example: <a href="helpviewer-example.html#x1024">helpviewer/helpwindow.cpp</a>.
178<h3 class=fn>void <a name="keyPressEvent"></a>QTextBrowser::keyPressEvent ( <a href="qkeyevent.html">QKeyEvent</a>&nbsp;*&nbsp;e )<tt> [virtual protected]</tt>
179</h3>
180The event <em>e</em> is used to provide the following keyboard shortcuts:
181<center><table cellpadding="4" cellspacing="2" border="0">
182<tr bgcolor="#a2c511"> <th valign="top">Keypress <th valign="top">Action
183<tr bgcolor="#f0f0f0"> <td valign="top">Alt+Left Arrow <td valign="top"><a href="#backward">backward</a>()
184<tr bgcolor="#d0d0d0"> <td valign="top">Alt+Right Arrow <td valign="top"><a href="#forward">forward</a>()
185<tr bgcolor="#f0f0f0"> <td valign="top">Alt+Up Arrow <td valign="top"><a href="#home">home</a>()
186</table></center>
187
188<p>Reimplemented from <a href="qtextedit.html#keyPressEvent">QTextEdit</a>.
189<h3 class=fn>void <a name="linkClicked"></a>QTextBrowser::linkClicked ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;link )<tt> [signal]</tt>
190</h3>
191
192<p> This signal is emitted when the user clicks a link. The <em>link</em> is
193the value of the <tt>href</tt> i.e. the name of the target document.
194<p> The <em>link</em> will be the absolute location of the document, based
195on the value of the anchor's href tag and the current context of
196the document.
197<p> <p>See also <a href="#anchorClicked">anchorClicked</a>() and <a href="qtextedit.html#context">context</a>().
198
199<h3 class=fn>void <a name="reload"></a>QTextBrowser::reload ()<tt> [virtual slot]</tt>
200</h3>
201Reloads the current set source.
202
203<h3 class=fn>void <a name="setSource"></a>QTextBrowser::setSource ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [virtual slot]</tt>
204</h3><p>Sets the name of the displayed document to <em>name</em>.
205See the <a href="qtextbrowser.html#source-prop">"source"</a> property for details.
206<h3 class=fn><a href="qstring.html">QString</a> <a name="source"></a>QTextBrowser::source () const
207</h3><p>Returns the name of the displayed document.
208See the <a href="qtextbrowser.html#source-prop">"source"</a> property for details.
209<h3 class=fn>void <a name="sourceChanged"></a>QTextBrowser::sourceChanged ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;src )<tt> [signal]</tt>
210</h3>
211
212<p> This signal is emitted when the mime source has changed, <em>src</em>
213being the new source.
214<p> Source changes happen both programmatically when calling
215<a href="#setSource">setSource</a>(), <a href="#forward">forward</a>(), backword() or <a href="#home">home</a>() or when the user
216clicks on links or presses the equivalent key sequences.
217
218<p>Example: <a href="helpviewer-example.html#x1027">helpviewer/helpwindow.cpp</a>.
219<hr><h2>Property Documentation</h2>
220<h3 class=fn>bool <a name="modified-prop"></a>modified</h3>
221<p>This property holds whether the contents have been modified.
222<p>
223<p><h3 class=fn>bool <a name="overwriteMode-prop"></a>overwriteMode</h3>
224<p>This property holds this text browser's overwrite mode.
225<p>
226<p><h3 class=fn>bool <a name="readOnly-prop"></a>readOnly</h3>
227<p>This property holds whether the contents are read only.
228<p>
229<p><h3 class=fn><a href="qstring.html">QString</a> <a name="source-prop"></a>source</h3>
230<p>This property holds the name of the displayed document.
231<p>This is a <a href="qstring.html#QString-null">QString::null</a> if no document is displayed or if the
232source is unknown.
233<p> Setting this property uses the <a href="qtextedit.html#mimeSourceFactory">mimeSourceFactory</a>() to lookup the
234named document. It also checks for optional anchors and scrolls
235the document accordingly.
236<p> If the first tag in the document is <tt>&lt;qt type=detail&gt;</tt>, the
237document is displayed as a popup rather than as new document in
238the browser window itself. Otherwise, the document is displayed
239normally in the text browser with the text set to the contents of
240the named document with <a href="qtextedit.html#setText">setText</a>().
241<p> If you are using the filesystem access capabilities of the mime
242source factory, you must ensure that the factory knows about the
243encoding of specified files; otherwise no data will be available.
244The default factory handles a couple of common file extensions
245such as <tt>*.html</tt> and <tt>*.txt</tt> with reasonable defaults. See
246<a href="qmimesourcefactory.html#data">QMimeSourceFactory::data</a>() for details.
247
248<p>Set this property's value with <a href="#setSource">setSource</a>() and get this property's value with <a href="#source">source</a>().
249<h3 class=fn>int <a name="undoDepth-prop"></a>undoDepth</h3>
250<p>This property holds this text browser's undo depth.
251<p>
252<p><h3 class=fn>bool <a name="undoRedoEnabled-prop"></a>undoRedoEnabled</h3>
253<p>This property holds whether undo and redo are enabled.
254<p>
255<p><!-- eof -->
256<hr><p>
257This file is part of the <a href="index.html">Qt toolkit</a>.
258Copyright &copy; 1995-2007
259<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
260<table width=100% cellspacing=0 border=0><tr>
261<td>Copyright &copy; 2007
262<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
263<td align=right><div align=right>Qt 3.3.8</div>
264</table></div></address></body>
265</html>
Note: See TracBrowser for help on using the repository browser.