QTextBrowser Class Reference

#include <qtextbrowser.h>

Inheritance diagram for QTextBrowser:

[legend]Collaboration diagram for QTextBrowser:

[legend]List of all members.

---

Detailed Description

The QTextBrowser class provides a rich text browser with hypertext navigation.

This class extends QTextEdit (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, use QTextEdit. If you want a text browser without hypertext navigation use QTextEdit, and use QTextEdit::setReadOnly() to disable editing. If you just need to display a small piece of rich text use QLabel.

The contents of QTextEdit are set with setHtml() or setPlainText(), but QTextBrowser also implements the setSource() 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, "\c #anchor"), the text browser automatically scrolls to that position (using scrollToAnchor()). When the user clicks on a hyperlink, the browser will call setSource() itself with the link's \c href value as argument. You can track the current source by connecting to the sourceChanged() signal. @section Navigation QTextBrowser provides backward() and forward() slots which you can use to implement Back and Forward buttons. The home() slot sets the text to the very first document displayed. The anchorClicked() signal is emitted when the user clicks an anchor. To override the default navigation behavior of the browser, call the setSource() 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 use \c{qrc} as the scheme in the URL to load. For example, for the document resource path \c{:/docs/index.html} use \c{qrc:/docs/index.html} as the URL with setSource(). \sa QTextEdit, QTextDocument Definition at line 38 of file qtextbrowser.h.

Public Slots
virtual void	setSource (const QUrl &name)
virtual void	backward ()
virtual void	forward ()
virtual void	home ()
virtual void	reload ()
Signals
void	backwardAvailable (bool)
void	forwardAvailable (bool)
void	sourceChanged (const QUrl &)
void	highlighted (const QUrl &)
void	highlighted (const QString &)
void	anchorClicked (const QUrl &)
Public Member Functions
	QTextBrowser (QWidget *parent=0)
virtual	~QTextBrowser ()
QUrl	source () const
QStringList	searchPaths () const
void	setSearchPaths (const QStringList &paths)
virtual QVariant	loadResource (int type, const QUrl &name)
bool	isBackwardAvailable () const
bool	isForwardAvailable () const
void	clearHistory ()
bool	openExternalLinks () const
void	setOpenExternalLinks (bool open)
Protected Member Functions
bool	event (QEvent *e)
virtual void	keyPressEvent (QKeyEvent *ev)
virtual void	mouseMoveEvent (QMouseEvent *ev)
virtual void	mousePressEvent (QMouseEvent *ev)
virtual void	mouseReleaseEvent (QMouseEvent *ev)
virtual void	focusOutEvent (QFocusEvent *ev)
virtual bool	focusNextPrevChild (bool next)
virtual void	paintEvent (QPaintEvent *e)
Private Member Functions
	Q_PRIVATE_SLOT (d_func(), void _q_documentModified()) Q_PRIVATE_SLOT(d_func()
void	_q_activateAnchor (const QString &)) Q_PRIVATE_SLOT(d_func()

---

Constructor & Destructor Documentation

QTextBrowser::QTextBrowser

(

QWidget *

parent = 0

)

[explicit]

Constructs an empty QTextBrowser with parent parent.

Definition at line 445 of file qtextbrowser.cpp.

References d.

    : QTextEdit(*new QTextBrowserPrivate, parent)
{
    Q_D(QTextBrowser);
    d->init();
}

QTextBrowser::~QTextBrowser

(

)

[virtual]

Definition at line 469 of file qtextbrowser.cpp.

{
}

---

Member Function Documentation

QUrl QTextBrowser::source

(

)

const

Definition at line 492 of file qtextbrowser.cpp.

References d.

Referenced by HelpDialog::addBookmark(), getPixmap(), HelpWindow::hasAnchorAt(), MainWindow::on_actionSaveAs_triggered(), MainWindow::saveSettings(), MainWindow::showLinks(), and MainWindow::showSearchLink().

{
    Q_D(const QTextBrowser);
    if (d->stack.isEmpty())
        return QUrl();
    else
        return d->stack.top().url;
}

QStringList QTextBrowser::searchPaths

(

)

const

Definition at line 509 of file qtextbrowser.cpp.

References d.

Referenced by FeatureTextBrowser::FeatureTextBrowser().

{
    Q_D(const QTextBrowser);
    return d->searchPaths;
}

void QTextBrowser::setSearchPaths

(

const QStringList &

paths

)

Definition at line 515 of file qtextbrowser.cpp.

References d.

Referenced by TabbedBrowser::createHelpWindow(), and FeatureTextBrowser::FeatureTextBrowser().

{
    Q_D(QTextBrowser);
    d->searchPaths = paths;
}

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

This function is called when the document is loaded. The type indicates the type of resource to be loaded. For each image in the document, this function is called once.

The default implementation ignores type and tries to locate the resources by interpreting name as a file name. If it is not an absolute path it tries to find the file in the paths of the searchPaths property and in the same directory as the current source. On success, the result is a QVariant that stores a QByteArray with the contents of the file.

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

ResourceType QVariant::Type QTextDocument::HtmlResource QString or QByteArray QTextDocument::ImageResource QImage, QPixmap or QByteArray QTextDocument::StyleSheetResource QString or QByteArray

Reimplemented from QTextEdit.

Definition at line 829 of file qtextbrowser.cpp.

References QFile::close(), d, data, name, QFile::open(), qWarning(), QIODevice::readAll(), and QIODevice::ReadOnly.

{
    Q_D(QTextBrowser);

    QByteArray data;
    QString fileName = d->findFile(d->resolveUrl(name));
    QFile f(fileName);
    if (f.open(QFile::ReadOnly)) {
        data = f.readAll();
        f.close();
    } else {
        qWarning("QTextBrowser: Cannot open '%s' for reading", name.toString().toLocal8Bit().data());
        return QVariant();
    }

    return data;
}

Here is the call graph for this function:

bool QTextBrowser::isBackwardAvailable

(

)

const

Since:

4.2

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

See also:

backwardAvailable(), backward()

Definition at line 855 of file qtextbrowser.cpp.

References d.

Referenced by MainWindow::browserTabChanged().

{
    Q_D(const QTextBrowser);
    return d->stack.count() > 1;
}

bool QTextBrowser::isForwardAvailable

(

)

const

Since:

4.2

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

See also:

forwardAvailable(), forward()

Definition at line 869 of file qtextbrowser.cpp.

References d.

Referenced by MainWindow::browserTabChanged().

{
    Q_D(const QTextBrowser);
    return !d->forwardStack.isEmpty();
}

void QTextBrowser::clearHistory

(

)

Since:

4.2

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

See also:

backward(), forward()

Definition at line 883 of file qtextbrowser.cpp.

References backwardAvailable(), d, emit, and forwardAvailable().

{
    Q_D(QTextBrowser);
    d->forwardStack.clear();
    if (!d->stack.isEmpty())
        d->stack.resize(1);
    emit forwardAvailable(false);
    emit backwardAvailable(false);
}

bool QTextBrowser::openExternalLinks

(

)

const

Definition at line 904 of file qtextbrowser.cpp.

References d.

{
    Q_D(const QTextBrowser);
    return d->openExternalLinks;
}

void QTextBrowser::setOpenExternalLinks

(

bool

open

)

Definition at line 910 of file qtextbrowser.cpp.

References d.

{
    Q_D(QTextBrowser);
    d->openExternalLinks = open;
}

void QTextBrowser::setSource

(

const QUrl &

name

)

[virtual, slot]

Definition at line 532 of file qtextbrowser.cpp.

References backwardAvailable(), d, emit, forwardAvailable(), QTextBrowserPrivate::HistoryEntry::hpos, QUrl::isValid(), QTextBrowserPrivate::HistoryEntry::url, and QTextBrowserPrivate::HistoryEntry::vpos.

Referenced by forward(), home(), reload(), FeatureTextBrowser::setSource(), and HelpWindow::setSource().

{
    Q_D(QTextBrowser);

    int hpos = d->hbar->value();
    int vpos = d->vbar->value();

    d->setSource(url);

    if (!url.isValid())
        return;

    if (!d->stack.isEmpty() && d->stack.top().url == url) {
        // the same url you are already watching
    } else {
        if (!d->stack.isEmpty()) {
            d->stack.top().hpos = hpos;
            d->stack.top().vpos = vpos;
        }
        QTextBrowserPrivate::HistoryEntry entry;
        entry.url = url;
        entry.hpos = 0;
        entry.vpos = 0;
        d->stack.push(entry);

        emit backwardAvailable(d->stack.count() > 1);

        if (!d->forwardStack.isEmpty() && d->forwardStack.top().url == url) {
            d->forwardStack.pop();
            emit forwardAvailable(d->forwardStack.count() > 0);
        } else {
            d->forwardStack.clear();
            emit forwardAvailable(false);
        }
    }
}

void QTextBrowser::backward

(

)

[virtual, slot]

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 also:

forward(), backwardAvailable()

Definition at line 631 of file qtextbrowser.cpp.

References backwardAvailable(), d, emit, and forwardAvailable().

Referenced by TabbedBrowser::backward(), and keyPressEvent().

{
    Q_D(QTextBrowser);
    if (d->stack.count() <= 1)
        return;
    d->forwardStack.push(d->stack.pop());
    d->forwardStack.top().hpos = d->hbar->value();
    d->forwardStack.top().vpos = d->vbar->value();
    d->setSource(d->stack.top().url);
    d->hbar->setValue(d->stack.top().hpos);
    d->vbar->setValue(d->stack.top().vpos);
    emit backwardAvailable(d->stack.count() > 1);
    emit forwardAvailable(true);
}

void QTextBrowser::forward

(

)

[virtual, slot]

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 also:

backward(), forwardAvailable()

Definition at line 653 of file qtextbrowser.cpp.

References backwardAvailable(), d, emit, forwardAvailable(), and setSource().

Referenced by TabbedBrowser::forward(), and keyPressEvent().

{
    Q_D(QTextBrowser);
    if (d->forwardStack.isEmpty())
        return;
    if (!d->stack.isEmpty()) {
        d->stack.top().hpos = d->hbar->value();
        d->stack.top().vpos = d->vbar->value();
    }
    d->stack.push(d->forwardStack.pop());
    setSource(d->stack.top().url);
    d->hbar->setValue(d->stack.top().hpos);
    d->vbar->setValue(d->stack.top().vpos);
    emit backwardAvailable(true);
    emit forwardAvailable(!d->forwardStack.isEmpty());
}

void QTextBrowser::home

(

)

[virtual, slot]

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

Definition at line 674 of file qtextbrowser.cpp.

References d, and setSource().

Referenced by TabbedBrowser::home(), and keyPressEvent().

{
    Q_D(QTextBrowser);
    if (d->home.isValid())
        setSource(d->home);
}

void QTextBrowser::reload

(

)

[virtual, slot]

Reloads the current set source.

Definition at line 524 of file qtextbrowser.cpp.

References d, s, and setSource().

Referenced by TabbedBrowser::reload(), and MainWindow::showSearchLink().

{
    Q_D(QTextBrowser);
    QUrl s = d->currentURL;
    d->currentURL = QUrl();
    setSource(s);
}

void QTextBrowser::backwardAvailable

(

bool

available

)

[signal]

This signal is emitted when the availability of backward() changes. available is false when the user is at home(); otherwise it is true.

Referenced by backward(), clearHistory(), forward(), and setSource().

void QTextBrowser::forwardAvailable

(

bool

available

)

[signal]

This signal is emitted when the availability of forward() changes. available is true after the user navigates backward() and false when the user navigates or goes forward().

Referenced by backward(), clearHistory(), forward(), and setSource().

void QTextBrowser::sourceChanged

(

const QUrl &

src

)

[signal]

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

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

void QTextBrowser::highlighted

(

const QUrl &

link

)

[signal]

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 in link.

void QTextBrowser::highlighted

(

const QString &

link

)

[signal]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Convenience signal that allows connecting to a slot that takes just a QString, like for example QStatusBar's message().

void QTextBrowser::anchorClicked

(

const QUrl &

link

)

[signal]

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

Note that the browser will automatically handle navigation to the location specified by link unless you call setSource() in a slot connected. This mechanism is used to override the default navigation features of the browser.

bool QTextBrowser::event

(

QEvent *

e

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 917 of file qtextbrowser.cpp.

References QTextEdit::event().

{
    return QTextEdit::event(e);
}

Here is the call graph for this function:

void QTextBrowser::keyPressEvent

(

QKeyEvent *

ev

)

[protected, virtual]

The event ev is used to provide the following keyboard shortcuts: Keypress Action Alt+Left Arrow backward() Alt+Right Arrow forward() Alt+Up Arrow home()

Reimplemented from QTextEdit.

Definition at line 690 of file qtextbrowser.cpp.

References QEvent::accept(), Qt::AltModifier, backward(), d, forward(), home(), QEvent::ignore(), QKeyEvent::key(), Qt::Key_Back, Qt::Key_Down, Qt::Key_Left, Qt::Key_Right, Qt::Key_Select, Qt::Key_Up, QTextEdit::keyPressEvent(), and QKeyEvent::modifiers().

Referenced by HelpWindow::keyPressEvent().

{
#ifdef QT_KEYPAD_NAVIGATION
    switch (ev->key()) {
    case Qt::Key_Select:
        if (QApplication::keypadNavigationEnabled() && !hasEditFocus()) {
            setEditFocus(true);
            return;
        }
        break;
    case Qt::Key_Back:
        if (QApplication::keypadNavigationEnabled()) {
            if (hasEditFocus()) {
                setEditFocus(false);
                ev->accept();
                return;
            }
        }
        QTextEdit::keyPressEvent(ev);
        return;
    default:
        if (QApplication::keypadNavigationEnabled() && !hasEditFocus()) {
            ev->ignore();
            return;
        }
    }
#endif

    if (ev->modifiers() & Qt::AltModifier) {
        switch (ev->key()) {
        case Qt::Key_Right:
            forward();
            ev->accept();
            return;
        case Qt::Key_Left:
            backward();
            ev->accept();
            return;
        case Qt::Key_Up:
            home();
            ev->accept();
            return;
        }
    }
#ifdef QT_KEYPAD_NAVIGATION
    else {
        Q_D(QTextBrowser);
        if (ev->key() == Qt::Key_Up) {
            d->keypadMove(false);
            return;
        } else if (ev->key() == Qt::Key_Down) {
            d->keypadMove(true);
            return;
        }
    }
#endif
    QTextEdit::keyPressEvent(ev);
}

Here is the call graph for this function:

void QTextBrowser::mouseMoveEvent

(

QMouseEvent *

e

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 752 of file qtextbrowser.cpp.

References QTextEdit::mouseMoveEvent().

{
    QTextEdit::mouseMoveEvent(e);
}

Here is the call graph for this function:

void QTextBrowser::mousePressEvent

(

QMouseEvent *

e

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 760 of file qtextbrowser.cpp.

References QTextEdit::mousePressEvent().

Referenced by HelpWindow::mousePressEvent().

{
    QTextEdit::mousePressEvent(e);
}

Here is the call graph for this function:

void QTextBrowser::mouseReleaseEvent

(

QMouseEvent *

e

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 768 of file qtextbrowser.cpp.

References QTextEdit::mouseReleaseEvent().

Referenced by HelpWindow::mouseReleaseEvent().

{
    QTextEdit::mouseReleaseEvent(e);
}

Here is the call graph for this function:

void QTextBrowser::focusOutEvent

(

QFocusEvent *

ev

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 776 of file qtextbrowser.cpp.

References d, QTextEdit::focusOutEvent(), Qt::IBeamCursor, and Qt::TextEditable.

{
    Q_D(QTextBrowser);
#ifndef QT_NO_CURSOR
    d->viewport->setCursor((!(d->control->textInteractionFlags() & Qt::TextEditable)) ? d->oldCursor : Qt::IBeamCursor);
#endif
    QTextEdit::focusOutEvent(ev);
}

Here is the call graph for this function:

bool QTextBrowser::focusNextPrevChild

(

bool

next

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 788 of file qtextbrowser.cpp.

References d, and QTextEdit::focusNextPrevChild().

{
    Q_D(QTextBrowser);
    if (d->control->setFocusToNextOrPreviousAnchor(next))
        return true;
    return QTextEdit::focusNextPrevChild(next);
}

Here is the call graph for this function:

void QTextBrowser::paintEvent

(

QPaintEvent *

e

)

[protected, virtual]

Reimplemented from QTextEdit.

Definition at line 799 of file qtextbrowser.cpp.

References d, and p.

{
    Q_D(QTextBrowser);
    QPainter p(d->viewport);
    d->paint(&p, e);
}

QTextBrowser::Q_PRIVATE_SLOT	(	d_func()	,
		void	_q_documentModified()
	)			[private]

Reimplemented from QWidget.

void QTextBrowser::_q_activateAnchor

(

const QString &

)

[private]

---

The documentation for this class was generated from the following files:

• src/gui/widgets/qtextbrowser.h
• src/gui/widgets/qtextbrowser.cpp

---