Qt Jambi Home

com.trolltech.qt.gui
Class QTextBrowser

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.core.QObject
              extended by com.trolltech.qt.gui.QWidget
                  extended by com.trolltech.qt.gui.QFrame
                      extended by com.trolltech.qt.gui.QAbstractScrollArea
                          extended by com.trolltech.qt.gui.QTextEdit
                              extended by com.trolltech.qt.gui.QTextBrowser
All Implemented Interfaces:
QPaintDeviceInterface, QtJambiInterface

public class QTextBrowser
extends QTextEdit

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.

Document Source and Contents

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, "#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 href value as argument. You can track the current source by connecting to the sourceChanged signal.

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 qrc as the scheme in the URL to load. For example, for the document resource path :/docs/index.html use qrc:/docs/index.html as the URL with setSource.

See Also:
QTextEdit, QTextDocument

Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QTextEdit
QTextEdit.AutoFormatting, QTextEdit.AutoFormattingFlag, QTextEdit.LineWrapMode
 
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QFrame
QFrame.Shadow, QFrame.Shape, QFrame.StyleMask
 
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QWidget
QWidget.RenderFlag, QWidget.RenderFlags
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Field Summary
 QSignalEmitter.Signal1<QUrl> anchorClicked
          This signal is emitted when the user clicks an anchor.
 QSignalEmitter.Signal1<java.lang.Boolean> backwardAvailable
          This signal is emitted when the availability of backward changes.
 QSignalEmitter.Signal1<java.lang.Boolean> forwardAvailable
          This signal is emitted when the availability of forward changes.
 QSignalEmitter.Signal1<QUrl> highlighted
          This signal is emitted when the user has selected but not activated an anchor in the document.
 QSignalEmitter.Signal1<java.lang.String> highlightedString
          Convenience signal that allows connecting to a slot that takes just a QString, like for example QStatusBar's message().
 QSignalEmitter.Signal1<QUrl> sourceChanged
          This signal is emitted when the source has changed, arg__1 being the new source.
 
Fields inherited from class com.trolltech.qt.gui.QTextEdit
copyAvailable, currentCharFormatChanged, cursorPositionChanged, redoAvailable, selectionChanged, textChanged, undoAvailable
 
Fields inherited from class com.trolltech.qt.gui.QWidget
customContextMenuRequested
 
Constructor Summary
QTextBrowser()
          Equivalent to QTextBrowser(0).
QTextBrowser(QWidget parent)
          Constructs an empty QTextBrowser with parent parent.
 
Method Summary
 void backward()
          Changes the document displayed to the previous document in the list of documents built by navigating links.
 void clearHistory()
          Clears the history of visited documents and disables the forward and backward navigation.
 boolean event(QEvent e)
          This function is reimplemented for internal reasons.
protected  boolean focusNextPrevChild(boolean next)
          This function is reimplemented for internal reasons.
protected  void focusOutEvent(QFocusEvent ev)
          This function is reimplemented for internal reasons.
 void forward()
          Changes the document displayed to the next document in the list of documents built by navigating links.
static QTextBrowser fromNativePointer(QNativePointer nativePointer)
          This function returns the QTextBrowser instance pointed to by nativePointer
 void home()
          Changes the document displayed to be the first document the browser displayed.
 boolean isBackwardAvailable()
          Returns true if the text browser can go backward in the document history using backward.
 boolean isForwardAvailable()
          Returns true if the text browser can go forward in the document history using forward.
protected  void keyPressEvent(QKeyEvent ev)
          The event ev is used to provide the following keyboard shortcuts:
 java.lang.Object loadResource(int type, QUrl name)
          This function is called when the document is loaded.
protected  void mouseMoveEvent(QMouseEvent ev)
          This function is reimplemented for internal reasons.
protected  void mousePressEvent(QMouseEvent ev)
          This function is reimplemented for internal reasons.
protected  void mouseReleaseEvent(QMouseEvent ev)
          This function is reimplemented for internal reasons.
 boolean openExternalLinks()
          Specifies whether QTextBrowser should automatically open links to external sources using QDesktopServices::openUrl() instead of emitting the anchorClicked signal.
 boolean openLinks()
          This property specifies whether QTextBrowser should automatically open links the user tries to activate by mouse or keyboard.
protected  void paintEvent(QPaintEvent e)
          This function is reimplemented for internal reasons.
 void reload()
          Reloads the current set source.
 java.util.List<java.lang.String> searchPaths()
          Returns the search paths used by the text browser to find supporting content.
 void setOpenExternalLinks(boolean open)
          Specifies whether QTextBrowser should automatically open links to external sources using QDesktopServices::openUrl() instead of emitting the anchorClicked signal.
 void setOpenLinks(boolean open)
          This property specifies whether QTextBrowser should automatically open links the user tries to activate by mouse or keyboard.
 void setSearchPaths(java.util.List<java.lang.String> paths)
          Sets the search paths used by the text browser to find supporting content to paths.
 void setSource(QUrl name)
          Sets the name of the displayed document.
 QUrl source()
          Returns the name of the displayed document..
 
Methods inherited from class com.trolltech.qt.gui.QTextEdit
acceptRichText, alignment, anchorAt, append, autoFormatting, canInsertFromMimeData, canPaste, changeEvent, clear, contextMenuEvent, copy, createMimeDataFromSelection, createStandardContextMenu, currentCharFormat, currentFont, cursorForPosition, cursorRect, cursorRect, cursorWidth, cut, document, documentTitle, dragEnterEvent, dragLeaveEvent, dragMoveEvent, dropEvent, ensureCursorVisible, extraSelections, find, find, find, focusInEvent, fontFamily, fontItalic, fontPointSize, fontUnderline, fontWeight, inputMethodEvent, inputMethodQuery, insertFromMimeData, insertHtml, insertPlainText, isReadOnly, isUndoRedoEnabled, keyReleaseEvent, lineWrapColumnOrWidth, lineWrapMode, mergeCurrentCharFormat, mouseDoubleClickEvent, moveCursor, moveCursor, overwriteMode, paste, print, redo, resizeEvent, scrollContentsBy, scrollToAnchor, selectAll, setAcceptRichText, setAlignment, setAlignment, setAutoFormatting, setAutoFormatting, setCurrentCharFormat, setCurrentFont, setCursorWidth, setDocument, setDocumentTitle, setExtraSelections, setFontFamily, setFontItalic, setFontPointSize, setFontUnderline, setFontWeight, setHtml, setLineWrapColumnOrWidth, setLineWrapMode, setOverwriteMode, setPlainText, setReadOnly, setTabChangesFocus, setTabStopWidth, setText, setTextColor, setTextCursor, setTextInteractionFlags, setTextInteractionFlags, setUndoRedoEnabled, setWordWrapMode, showEvent, tabChangesFocus, tabStopWidth, textColor, textCursor, textInteractionFlags, timerEvent, toHtml, toPlainText, undo, wheelEvent, wordWrapMode, zoomIn, zoomIn, zoomOut, zoomOut
 
Methods inherited from class com.trolltech.qt.gui.QAbstractScrollArea
addScrollBarWidget, addScrollBarWidget, cornerWidget, horizontalScrollBar, horizontalScrollBarPolicy, maximumViewportSize, minimumSizeHint, paintEngine, scrollBarWidgets, scrollBarWidgets, setCornerWidget, setHorizontalScrollBar, setHorizontalScrollBarPolicy, setupViewport, setVerticalScrollBar, setVerticalScrollBarPolicy, setViewport, setViewportMargins, sizeHint, verticalScrollBar, verticalScrollBarPolicy, viewport, viewportEvent
 
Methods inherited from class com.trolltech.qt.gui.QFrame
drawFrame, frameRect, frameShadow, frameShape, frameStyle, frameWidth, lineWidth, midLineWidth, setFrameRect, setFrameShadow, setFrameShape, setFrameStyle, setLineWidth, setMidLineWidth
 
Methods inherited from class com.trolltech.qt.gui.QWidget
acceptDrops, accessibleDescription, accessibleName, actionEvent, actions, activateWindow, addAction, addActions, adjustSize, autoFillBackground, backgroundRole, baseSize, childAt, childAt, childrenRect, childrenRegion, clearFocus, clearMask, close, closeEvent, contentsRect, contextMenuPolicy, createWinId, cursor, depth, destroy, destroy, destroy, devType, ensurePolished, enterEvent, focusNextChild, focusPolicy, focusPreviousChild, focusProxy, focusWidget, font, fontInfo, fontMetrics, foregroundRole, frameGeometry, frameSize, geometry, getContentsMargins, grabKeyboard, grabMouse, grabMouse, grabShortcut, grabShortcut, hasFocus, hasMouseTracking, height, heightForWidth, heightMM, hide, hideEvent, inputContext, insertAction, insertActions, isActiveWindow, isAncestorOf, isEnabled, isEnabledTo, isFullScreen, isHidden, isLeftToRight, isMaximized, isMinimized, isModal, isRightToLeft, isVisible, isVisibleTo, isWindow, isWindowModified, keyboardGrabber, layout, layoutDirection, leaveEvent, locale, logicalDpiX, logicalDpiY, lower, mapFrom, mapFromGlobal, mapFromParent, mapTo, mapToGlobal, mapToParent, mask, maximumHeight, maximumSize, maximumWidth, metric, minimumHeight, minimumSize, minimumWidth, mouseGrabber, move, move, moveEvent, nextInFocusChain, normalGeometry, numColors, overrideWindowFlags, overrideWindowFlags, overrideWindowState, overrideWindowState, paintingActive, palette, parentWidget, physicalDpiX, physicalDpiY, pos, raise, rect, releaseKeyboard, releaseMouse, releaseShortcut, removeAction, render, render, render, render, render, repaint, repaint, repaint, repaint, resetInputContext, resize, resize, restoreGeometry, saveGeometry, scroll, scroll, setAcceptDrops, setAccessibleDescription, setAccessibleName, setAttribute, setAttribute, setAutoFillBackground, setBackgroundRole, setBaseSize, setBaseSize, setContentsMargins, setContentsMargins, setContextMenuPolicy, setCursor, setDisabled, setEnabled, setFixedHeight, setFixedSize, setFixedSize, setFixedWidth, setFocus, setFocus, setFocusPolicy, setFocusProxy, setFont, setForegroundRole, setGeometry, setGeometry, setHidden, setInputContext, setLayout, setLayoutDirection, setLocale, setMask, setMask, setMaximumHeight, setMaximumSize, setMaximumSize, setMaximumWidth, setMinimumHeight, setMinimumSize, setMinimumSize, setMinimumWidth, setMouseTracking, setPalette, setParent, setParent, setParent, setShortcutAutoRepeat, setShortcutAutoRepeat, setShortcutEnabled, setShortcutEnabled, setSizeIncrement, setSizeIncrement, setSizePolicy, setSizePolicy, setStatusTip, setStyle, setStyleSheet, setTabOrder, setToolTip, setUpdatesEnabled, setVisible, setWhatsThis, setWindowFlags, setWindowFlags, setWindowIcon, setWindowIconText, setWindowModality, setWindowModified, setWindowOpacity, setWindowRole, setWindowState, setWindowState, setWindowTitle, show, showFullScreen, showMaximized, showMinimized, showNormal, size, sizeIncrement, sizePolicy, stackUnder, statusTip, style, styleSheet, tabletEvent, testAttribute, toolTip, underMouse, unsetCursor, unsetLayoutDirection, unsetLocale, update, update, update, update, updateGeometry, updateMicroFocus, updatesEnabled, visibleRegion, whatsThis, width, widthMM, window, windowFlags, windowIcon, windowIconText, windowModality, windowOpacity, windowRole, windowState, windowTitle, windowType, winId, x, y
 
Methods inherited from class com.trolltech.qt.core.QObject
blockSignals, childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, property, removeEventFilter, setObjectName, setParent, setProperty, signalsBlocked, startTimer, thread
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
disconnect, disconnect, signalSender
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

anchorClicked

public final QSignalEmitter.Signal1<QUrl> anchorClicked

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

Note that the browser will automatically handle navigation to the location specified by arg__1 unless the openLinks property is set to false or you call setSource in a slot connected. This mechanism is used to override the default navigation features of the browser.

Compatible Slot Signatures:
void mySlot(com.trolltech.qt.core.QUrl arg__1)
void mySlot()


backwardAvailable

public final QSignalEmitter.Signal1<java.lang.Boolean> backwardAvailable

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

Compatible Slot Signatures:
void mySlot(boolean arg__1)
void mySlot()


forwardAvailable

public final QSignalEmitter.Signal1<java.lang.Boolean> forwardAvailable

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

Compatible Slot Signatures:
void mySlot(boolean arg__1)
void mySlot()


highlightedString

public final QSignalEmitter.Signal1<java.lang.String> highlightedString

Convenience signal that allows connecting to a slot that takes just a QString, like for example QStatusBar's message().

Compatible Slot Signatures:
void mySlot(java.lang.String arg__1)
void mySlot()


highlighted

public final QSignalEmitter.Signal1<QUrl> highlighted

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 arg__1.

Compatible Slot Signatures:
void mySlot(com.trolltech.qt.core.QUrl arg__1)
void mySlot()


sourceChanged

public final QSignalEmitter.Signal1<QUrl> sourceChanged

This signal is emitted when the source has changed, arg__1 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.

Compatible Slot Signatures:
void mySlot(com.trolltech.qt.core.QUrl arg__1)
void mySlot()

Constructor Detail

QTextBrowser

public QTextBrowser()

Equivalent to QTextBrowser(0).


QTextBrowser

public QTextBrowser(QWidget parent)

Constructs an empty QTextBrowser with parent parent.

Method Detail

clearHistory

public final void clearHistory()

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

See Also:
backward, forward

isBackwardAvailable

public final boolean isBackwardAvailable()

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

See Also:
backwardAvailable, backward

isForwardAvailable

public final boolean isForwardAvailable()

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

See Also:
forwardAvailable, forward

openExternalLinks

public final boolean openExternalLinks()

Specifies whether QTextBrowser should automatically open links to external sources using QDesktopServices::openUrl() instead of emitting the anchorClicked signal. Links are considered external if their scheme is neither file or qrc.

The default value is false.

See Also:
setOpenExternalLinks

openLinks

public final boolean openLinks()

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

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

The default value is true.

See Also:
setOpenLinks

searchPaths

public final java.util.List<java.lang.String> searchPaths()

Returns the search paths used by the text browser to find supporting content.

QTextBrowser uses this list to locate images and documents.

See Also:
setSearchPaths

setOpenExternalLinks

public final void setOpenExternalLinks(boolean open)

Specifies whether QTextBrowser should automatically open links to external sources using QDesktopServices::openUrl() instead of emitting the anchorClicked signal. Links are considered external if their scheme is neither file or qrc.

The default value is false.

See Also:
openExternalLinks

setOpenLinks

public final void setOpenLinks(boolean open)

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

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

The default value is true.

See Also:
openLinks

setSearchPaths

public final void setSearchPaths(java.util.List<java.lang.String> paths)

Sets the search paths used by the text browser to find supporting content to paths.

QTextBrowser uses this list to locate images and documents.

See Also:
searchPaths

source

public final QUrl source()

Returns 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 property QTextBrowser tries to find a document with the specified name in the paths of the searchPaths 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 with setHtml.

See Also:
setSource

backward

public void 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 Also:
forward, backwardAvailable

event

public boolean event(QEvent e)

This function is reimplemented for internal reasons.

Overrides:
event in class QTextEdit
See Also:
QEvent::type

focusNextPrevChild

protected boolean focusNextPrevChild(boolean next)

This function is reimplemented for internal reasons.

Overrides:
focusNextPrevChild in class QTextEdit
See Also:
focusNextChild, focusPreviousChild

focusOutEvent

protected void focusOutEvent(QFocusEvent ev)

This function is reimplemented for internal reasons.

Overrides:
focusOutEvent in class QTextEdit
See Also:
focusInEvent, setFocusPolicy, keyPressEvent, keyReleaseEvent, event, QFocusEvent

forward

public void 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 Also:
backward, forwardAvailable

home

public void home()

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


keyPressEvent

protected void keyPressEvent(QKeyEvent ev)

The event ev is used to provide the following keyboard shortcuts:

KeypressAction
Alt+Left Arrowbackward
Alt+Right Arrowforward
Alt+Up Arrowhome

Overrides:
keyPressEvent in class QTextEdit
See Also:
keyReleaseEvent, QKeyEvent::ignore, setFocusPolicy, focusInEvent, focusOutEvent, event, QKeyEvent, Tetrix Example

loadResource

public java.lang.Object loadResource(int type,
                                     QUrl name)

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:

ResourceTypeQVariant::Type
QTextDocument::HtmlResourceQString or QByteArray
QTextDocument::ImageResourceQImage, QPixmap or QByteArray
QTextDocument::StyleSheetResourceQString or QByteArray

Overrides:
loadResource in class QTextEdit
See Also:
QTextDocument::loadResource

mouseMoveEvent

protected void mouseMoveEvent(QMouseEvent ev)

This function is reimplemented for internal reasons.

Overrides:
mouseMoveEvent in class QTextEdit
See Also:
QWidget::mouseMoveEvent

mousePressEvent

protected void mousePressEvent(QMouseEvent ev)

This function is reimplemented for internal reasons.

Overrides:
mousePressEvent in class QTextEdit
See Also:
QWidget::mousePressEvent

mouseReleaseEvent

protected void mouseReleaseEvent(QMouseEvent ev)

This function is reimplemented for internal reasons.

Overrides:
mouseReleaseEvent in class QTextEdit
See Also:
QWidget::mouseReleaseEvent

paintEvent

protected void paintEvent(QPaintEvent e)

This function is reimplemented for internal reasons.

Overrides:
paintEvent in class QTextEdit
See Also:
QWidget::paintEvent

reload

public void reload()

Reloads the current set source.


setSource

public void setSource(QUrl name)

Sets the name of the displayed document. to name.

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

When setting this property QTextBrowser tries to find a document with the specified name in the paths of the searchPaths 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 with setHtml.

See Also:
source

fromNativePointer

public static QTextBrowser fromNativePointer(QNativePointer nativePointer)
This function returns the QTextBrowser instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

Qt Jambi Home