| Classes - Annotated - Tree - Functions - Home - Structure

# QTextBrowser Class Reference

A rich text browser with simple navigation. More...

`#include <qtextbrowser.h>`

Inherits QTextView.

List of all member functions.

## Public Members

- QTextBrowser ( QWidget * parent=0, const char * name=0 )
- ~QTextBrowser ()
- virtual void setSource ( const QString & name )
- QString source () const
- virtual void setText ( const QString & contents, const QString & context=QString::null )
- void scrollToAnchor ( const QString & name )

## Public Slots

- virtual void backward ()
- virtual void forward ()
- virtual void home ()

## Signals

- void backwardAvailable ( bool )
- void forwardAvailable ( bool )
- void highlighted ( const QString & )
- void textChanged ()

## Protected Members

- virtual void viewportMousePressEvent ( QMouseEvent * )
- virtual void viewportMouseReleaseEvent ( QMouseEvent * )
- virtual void viewportMouseMoveEvent ( QMouseEvent * )
- virtual void keyPressEvent ( QKeyEvent * e )

## Properties

Type | Name | READ | WRITE | Options
--- | --- | --- | --- | ---
QString | source | source | setSource |

## Detailed Description

A rich text browser with simple navigation.

This class is the same as the QTextView it inherits, with the addition that it provides basic navigation features to follow links in hypertext documents that link to other rich text documents. While QTextView only allows to set its contents with setText(), QTextBrowser has an additional function setSource(), that makes it possible to set documents by name. These names are looked up in the text view's mime source factory. If a document name ends with an anchor, for example "`#anchor",` the text browser will automatically scroll accordingly ( using scrollToAnchor() ). When the user clicks on a hyperlink, the browser will call setSource() itself, with the link's `href` value as argument.

QTextBrowser doesn't provide actual Back and Forward buttons, but it has backward() and forward() slots that implement the functionality. The home() slots brings it back to its very first document displayed.

By using QTextView::setMimeSourceFactory(), you can provide your own subclass of QMimeSourceFactory. This makes it possible to access data from anywhere you need to, may it be the network or a database. See QMimeSourceFactory::data() for details.

If you intend to use the mime factory to read the data directly from the file system, you may have to specify the encoding for the file extension you are using. For example

      mimeSourceFactory()->setExtensionType("qml", "text/utf8");

Otherwise, the factory will not be able to resolve the document names.

For simpler richt text use, see QLabel, QTextView or QSimpleRichText.

## Member Function Documentation

### QTextBrowser::QTextBrowser ( QWidget * parent=0, const char * name=0 )

Constructs an empty QTextBrowser.

### QTextBrowser::~QTextBrowser ()

Destructs the browser.

### void QTextBrowser::backward () `[virtual slot]`

Changes the document displayed to be the previous document in the list of documents build by navigating links.

See also forward() and backwardAvailable().

### void QTextBrowser::backwardAvailable ( bool available ) `[signal]`

This signal is emitted when the availability of the backward() changes. It becomes available when the user navigates forward, and unavailable when the user is at the home().

### void QTextBrowser::forward () `[virtual slot]`

Changes the document displayed to be the next document in the list of documents build by navigating links.

See also backward() and forwardAvailable().

### void QTextBrowser::forwardAvailable ( bool available ) `[signal]`

This signal is emitted when the availability of the forward() changes. It becomes available after backward() is activated, and unavailable when the user navigates or goes forward() to the last navigated document.

### void QTextBrowser::highlighted ( const QString & href ) `[signal]`

This signal is emitted when the user has selected but not activated a link in the document. href is the value of the href tag in the link.

### void QTextBrowser::home () `[virtual slot]`

Changes the document displayed to be the first document the browser displayed.

### void QTextBrowser::keyPressEvent ( QKeyEvent * e ) `[virtual protected]`

Add Backward and Forward on ALT-Left and ALT-Right respectively.

Reimplemented from QWidget.

### void QTextBrowser::scrollToAnchor ( const QString & name )

Scrolls the browser so that the part of the document named name is at the top of the view (or as close to the top as the size of the document allows).

### void QTextBrowser::setSource ( const QString & name ) `[virtual]`

Sets the text document with the given name to be displayed. The name is looked up in the mimeSourceFactory() of the browser.

In addition to the factory lookup, this functions also checks for optional anchors and scrolls the document accordingly.

If the first tag in the document is `<qt type=detail>,` it is displayed as a popup rather than as new document in the browser window itself. Otherwise, the document is set normally via setText(), with name as new context.

If you are using the filesystem access capabilities of the mime source factory, you have to ensure that the factory knows about the encoding of specified text files, otherwise no data will be available. The default factory handles a couple of common file extensions such as `*.html` and `*.txt` with reasonable defaults. See QMimeSourceFactory::data() for details.

### void QTextBrowser::setText ( const QString & text, const QString & context=QString::null ) `[virtual]`

Sets the contents of the browser to text, and emits the textChanged() signal.

Reimplemented from QTextView.

### void QTextBrowser::showEvent ( QShowEvent * e ) `[virtual protected]`

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

### QString QTextBrowser::source () const

Returns the source of the currently display document. If no document is displayed or the source is unknown, a null string is returned.

See also setSource().

### void QTextBrowser::textChanged () `[signal]`

This signal is emitted whenever the setText() changes the contents (eg. because the user clicked on a link).

### void QTextBrowser::viewportMouseMoveEvent ( QMouseEvent * e ) `[virtual protected]`

Activate to emit highlighted().

Reimplemented from QScrollView.

### void QTextBrowser::viewportMousePressEvent ( QMouseEvent * e ) `[virtual protected]`

override to press anchors.

Reimplemented from QScrollView.

### void QTextBrowser::viewportMouseReleaseEvent ( QMouseEvent * e ) `[virtual protected]`

override to activate anchors.

Reimplemented from QScrollView.

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.