Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Reimplemented Protected Functions
• Detailed Description
• Document Source and Contents
• Navigation

Detailed Description

TheQTextBrowser class provides a rich text browser with hypertext navigation.

This class extendsQTextEdit (in read-only mode), adding some navigation functionality so that users can follow links in hypertext documents.

If you want to provide your users with an editable rich text editor, useQTextEdit. If you want a text browser without hypertext navigation useQTextEdit, and useQTextEdit::setReadOnly() to disable editing. If you just need to display a small piece of rich text useQLabel.

Document Source and Contents

The contents ofQTextEdit are set withsetHtml() orsetPlainText(), butQTextBrowser also implements thesetSource() function, making it possible to use a named document as the source text. The name is looked up in a list of search paths and in the directory of the current document factory.

If a document name ends with an anchor (for example, "#anchor"), the text browser automatically scrolls to that position (usingscrollToAnchor()). When the user clicks on a hyperlink, the browser will callsetSource() itself with the link'shref value as argument. You can track the current source by connecting to thesourceChanged() signal.

Navigation

QTextBrowser providesbackward() andforward() slots which you can use to implement Back and Forward buttons. Thehome() slot sets the text to the very first document displayed. TheanchorClicked() signal is emitted when the user clicks an anchor. To override the default navigation behavior of the browser, call thesetSource() function to supply new document text in a slot connected to this signal.

If you want to load documents stored in the Qt resource system useqrc as the scheme in the URL to load. For example, for the document resource path:/docs/index.html useqrc:/docs/index.html as the URL withsetSource(). To access local files, usefile as the scheme in the URL.

Property Documentation

modified : constbool

This property holds whether the contents of the text browser have been modified.

openExternalLinks :bool

Specifies whetherQTextBrowser should automatically open links to external sources usingQDesktopServices::openUrl() instead of emitting theanchorClicked signal. Links are considered external if their scheme is neither file or qrc.

The default value is false.

This property was introduced in Qt 4.2.

Access functions:

openLinks :bool

This property specifies whetherQTextBrowser should automatically open links the user tries to activate by mouse or keyboard.

Regardless of the value of this property theanchorClicked signal is always emitted.

The default value is true.

This property was introduced in Qt 4.3.

Access functions:

readOnly :bool

This property holds whether the text browser is read-only.

By default, this property is true.

Access functions:

searchPaths :QStringList

This property holds the search paths used by the text browser to find supporting content.

QTextBrowser uses this list to locate images and documents.

By default, this property contains an empty string list.

Access functions:

source :QUrl

This property holds the name of the displayed document.

This is a an invalid url if no document is displayed or if the source is unknown.

When setting this propertyQTextBrowser tries to find a document with the specified name in the paths of thesearchPaths property and directory of the current source, unless the value is an absolute file path. It also checks for optional anchors and scrolls the document accordingly

If the first tag in the document is<qt type=detail>, the document is displayed as a popup rather than as new document in the browser window itself. Otherwise, the document is displayed normally in the text browser with the text set to the contents of the named document withsetHtml().

By default, this property contains an empty URL.

Access functions:

undoRedoEnabled :bool

This property holds whether the text browser supports undo/redo operations.

By default, this property is false.

Access functions:

Member Function Documentation

QTextBrowser::QTextBrowser(QWidget * parent = 0)

Constructs an emptyQTextBrowser with parentparent.

[signal]void QTextBrowser::anchorClicked(constQUrl & link)

This signal is emitted when the user clicks an anchor. The URL referred to by the anchor is passed inlink.

Note that the browser will automatically handle navigation to the location specified bylink unless theopenLinks property is set to false or you callsetSource() in a slot connected. This mechanism is used to override the default navigation features of the browser.

[virtual slot]void QTextBrowser::backward()

Changes the document displayed to the previous document in the list of documents built by navigating links. Does nothing if there is no previous document.

See alsoforward() andbackwardAvailable().

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

This signal is emitted when the availability ofbackward() changes.available is false when the user is athome(); otherwise it is true.

int QTextBrowser::backwardHistoryCount() const

Returns the number of locations backward in the history.

This function was introduced in Qt 4.4.

void QTextBrowser::clearHistory()

Clears the history of visited documents and disables the forward and backward navigation.

This function was introduced in Qt 4.2.

See alsobackward() andforward().

[virtual protected]bool QTextBrowser::event(QEvent * e)

Reimplemented fromQObject::event().

[virtual protected]bool QTextBrowser::focusNextPrevChild(bool next)

Reimplemented fromQWidget::focusNextPrevChild().

[virtual protected]void QTextBrowser::focusOutEvent(QFocusEvent * ev)

Reimplemented fromQWidget::focusOutEvent().

[virtual slot]void QTextBrowser::forward()

Changes the document displayed to the next document in the list of documents built by navigating links. Does nothing if there is no next document.

See alsobackward() andforwardAvailable().

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

This signal is emitted when the availability offorward() changes.available is true after the user navigatesbackward() and false when the user navigates or goesforward().

int QTextBrowser::forwardHistoryCount() const

Returns the number of locations forward in the history.

This function was introduced in Qt 4.4.

[signal]void QTextBrowser::highlighted(constQUrl & link)

This signal is emitted when the user has selected but not activated an anchor in the document. The URL referred to by the anchor is passed inlink.

Note:Signalhighlighted is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(textBrowser,static_cast<void(QTextBrowser::*)(constQUrl&)>(&QTextBrowser::highlighted),[=](constQUrl&link){/* ... */ });

[signal]void QTextBrowser::highlighted(constQString & link)

This is an overloaded function.

Convenience signal that allows connecting to a slot that takes just aQString, like for exampleQStatusBar's message().

Note:Signalhighlighted is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(textBrowser,static_cast<void(QTextBrowser::*)(constQString&)>(&QTextBrowser::highlighted),[=](constQString&link){/* ... */ });

[signal]void QTextBrowser::historyChanged()

This signal is emitted when the history changes.

This function was introduced in Qt 4.4.

See alsohistoryTitle() andhistoryUrl().

QString QTextBrowser::historyTitle(int i) const

Returns thedocumentTitle() of the HistoryItem.

backaction.setToolTip(browser.historyTitle(-1));forwardaction.setToolTip(browser.historyTitle(+1));

This function was introduced in Qt 4.4.

QUrl QTextBrowser::historyUrl(int i) const

Returns the url of the HistoryItem.

This function was introduced in Qt 4.4.

[virtual slot]void QTextBrowser::home()

Changes the document displayed to be the first document from the history.

bool QTextBrowser::isBackwardAvailable() const

Returns true if the text browser can go backward in the document history usingbackward().

This function was introduced in Qt 4.2.

See alsobackwardAvailable() andbackward().

bool QTextBrowser::isForwardAvailable() const

Returns true if the text browser can go forward in the document history usingforward().

This function was introduced in Qt 4.2.

See alsoforwardAvailable() andforward().

[virtual protected]void QTextBrowser::keyPressEvent(QKeyEvent * ev)

Reimplemented fromQWidget::keyPressEvent().

The eventev is used to provide the following keyboard shortcuts:

[virtual]QVariant QTextBrowser::loadResource(int type, constQUrl & name)

Reimplemented fromQTextEdit::loadResource().

This function is called when the document is loaded and for each image in the document. Thetype indicates the type of resource to be loaded. An invalidQVariant is returned if the resource cannot be loaded.

The default implementation ignorestype and tries to locate the resources by interpretingname as a file name. If it is not an absolute path it tries to find the file in the paths of thesearchPaths property and in the same directory as the current source. On success, the result is aQVariant that stores aQByteArray with the contents of the file.

If you reimplement this function, you can return otherQVariant types. The table below shows which variant types are supported depending on the resource type:

[virtual protected]void QTextBrowser::mouseMoveEvent(QMouseEvent * e)

Reimplemented fromQWidget::mouseMoveEvent().

[virtual protected]void QTextBrowser::mousePressEvent(QMouseEvent * e)

Reimplemented fromQWidget::mousePressEvent().

[virtual protected]void QTextBrowser::mouseReleaseEvent(QMouseEvent * e)

Reimplemented fromQWidget::mouseReleaseEvent().

[virtual protected]void QTextBrowser::paintEvent(QPaintEvent * e)

Reimplemented fromQWidget::paintEvent().

[virtual slot]void QTextBrowser::reload()

Reloads the current set source.

[signal]void QTextBrowser::sourceChanged(constQUrl & src)

This signal is emitted when the source has changed,src being the new source.

Source changes happen both programmatically when callingsetSource(),forward(), backword() orhome() or when the user clicks on links or presses the equivalent key sequences.