com.trolltech.qt.webkit
Class QWebView

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      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.webkit.QWebView
All Implemented Interfaces:
QPaintDeviceInterface, QtJambiInterface

public class QWebView
extends QWidget

The QWebView class provides a widget that is used to view and edit web documents. QWebView is the main widget component of the QtWebKit web browsing module. It can be used in various applications to display web content live from the Internet.

The image below shows QWebView previewed in Qt Designer with the Trolltech website.


A web site can be loaded onto QWebView with the load() function. Like all Qt Widgets, the show() function must be invoked in order to display QWebView. The snippet below illustrates this:
        QWebView view = new QWebView(parent);
        view.load(new QUrl("http://www.trolltech.com/"));
        view.show();
Alternatively, setUrl() can also be used to load a web site. If you have the HTML content readily available, you can use setHtml() instead.

The loadStarted() signal is emitted when the view begins loading. The loadProgress() signal, on the other hand, is emitted whenever an element of the web view completes loading, such as an embedded image, a script, etc. Finally, the loadFinished() signal is emitted when the view has loaded completely. It's argument - either true or false - indicates load success or failure.

The page() function returns a pointer to the web page object. See Elements of QWebView for an explanation of how the web page is related to the view. To modify your web view's settings, you can access the QWebSettings object with the settings() function. With QWebSettings, you can change the default fonts, enable or disable features such as JavaScript and plugins.

The title of an HTML document can be accessed with the title() property. Additionally, a web site may also specify an icon, which can be accessed using the icon() property. If the title or the icon changes, the corresponding titleChanged() and iconChanged() signals will be emitted. The textSizeMultiplier() property can be used to change the overall size of the text displayed in the web view.

If you require a custom context menu, you can implement it by reimplementing contextMenuEvent() and populating your QMenu with the actions obtained from pageAction(). More functionality such as reloading the view, copying selected text to the clipboard, or pasting into the view, is also encapsulated within the QAction objects returned by pageAction(). These actions can be programmatically triggered using triggerPageAction(). Alternatively, the actions can be added to a toolbar or a menu directly. QWebView maintains the state of the returned actions but allows modification of action properties such as text or icon.

A QWebView can be printed onto a QPrinter using the print() function. This function is marked as a slot and can be conveniently connected to QPrintPreviewDialog's paintRequested() signal.

If you want to provide support for web sites that allow the user to open new windows, such as pop-up windows, you can subclass QWebView and reimplement the createWindow() function.

Elements of QWebView

QWebView consists of other objects such as QWebFrame and QWebPage. The flowchart below shows these elements are related.

Note: It is possible to use QWebPage and QWebFrame, without using QWebView, if you do not require QWidget attributes. Nevertheless, QtWebKit depends on QtGui, so you should use a QApplication instead of QCoreApplication.

See also:
Previewer Example, and Browser.


Nested Class Summary
 
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.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 QSignalEmitter.Signal0 iconChanged
          This signal is emitted whenever the icon of the page is loaded or changes.
 QSignalEmitter.Signal1 linkClicked
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 loadFinished
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 loadProgress
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal0 loadStarted
          This signal is emitted when a new load of the page is started.
 QSignalEmitter.Signal0 selectionChanged
          This signal is emitted whenever the selection changes.
 QSignalEmitter.Signal1 statusBarMessage
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 titleChanged
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 urlChanged
          This signal takes 1 generic argument(s).
 
Fields inherited from class com.trolltech.qt.gui.QWidget
customContextMenuRequested
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QWebView()
          Constructs an empty QWebView with parent parent.
QWebView(QWidget parent)
          Constructs an empty QWebView with parent parent.
 
Method Summary
 void back()
          Convenience slot that loads the previous document in the list of documents built by navigating links.
protected  QWebView createWindow(QWebPage.WebWindowType type)
          This function is called whenever WebKit wants to create a new window of the given type, for example as a result of a JavaScript request to open a document in a new window.
 boolean findText(java.lang.String subString)
          Finds the next occurrence of the string, subString, in the page, using the given options.
 boolean findText(java.lang.String subString, QWebPage.FindFlag[] options)
           
 boolean findText(java.lang.String subString, QWebPage.FindFlags options)
          Finds the next occurrence of the string, subString, in the page, using the given options.
 void forward()
          Convenience slot that loads the next document in the list of documents built by navigating links.
 QWebHistory history()
          Returns a pointer to the view's history of navigated web pages.
 QIcon icon()
          This property holds the icon associated with the web page currently viewed.
 boolean isModified()
          This property holds whether the document was modified by the user.
 void load(QNetworkRequest request)
          Loads a network request, request, using the method specified in operation.
 void load(QNetworkRequest request, QNetworkAccessManager.Operation operation)
          Loads a network request, request, using the method specified in operation.
 void load(QNetworkRequest request, QNetworkAccessManager.Operation operation, QByteArray body)
          Loads a network request, request, using the method specified in operation.
 void load(QUrl url)
          Loads the specified url and displays it.
 QWebPage page()
          Returns a pointer to the underlying web page.
 QAction pageAction(QWebPage.WebAction action)
          Returns a pointer to a QAction that encapsulates the specified web action action.
 void print(QPrinter printer)
          Prints the main frame to the given printer.
 void reload()
          Reloads the current document.
 java.lang.String selectedText()
          This property holds the text currently selected.
 void setContent(QByteArray data)
          Sets the content of the web view to the specified content data.
 void setContent(QByteArray data, java.lang.String mimeType)
          Sets the content of the web view to the specified content data.
 void setContent(QByteArray data, java.lang.String mimeType, QUrl baseUrl)
          Sets the content of the web view to the specified content data.
 void setHtml(java.lang.String html)
          Sets the content of the web view to the specified html.
 void setHtml(java.lang.String html, QUrl baseUrl)
          Sets the content of the web view to the specified html.
 void setPage(QWebPage page)
          Makes page the new web page of the web view.
 void setTextSizeMultiplier(double factor)
          Sets the value of the multiplier used to scale the text in a Web page to the factor specified.
 QWebSettings settings()
          Returns a pointer to the view/page specific settings object.
 void setUrl(QUrl url)
          This property holds the url of the web page currently viewed.
 void setZoomFactor(double factor)
          This property holds the zoom factor for the view.
 void stop()
          Convenience slot that stops loading the document.
 double textSizeMultiplier()
          Returns the value of the multiplier used to scale the text in a Web page.
 java.lang.String title()
          This property holds the title of the web page currently viewed.
 void triggerPageAction(QWebPage.WebAction action)
          Triggers the specified action.
 void triggerPageAction(QWebPage.WebAction action, boolean checked)
          Triggers the specified action.
 QUrl url()
          This property holds the url of the web page currently viewed.
 double zoomFactor()
          This property holds the zoom factor for the view.
 
Methods inherited from class com.trolltech.qt.gui.QWidget
acceptDrops, accessibleDescription, accessibleName, actionEvent, actions, activateWindow, addAction, addActions, adjustSize, autoFillBackground, backgroundRole, baseSize, changeEvent, childAt, childAt, childrenRect, childrenRegion, clearFocus, clearMask, close, closeEvent, contentsRect, contextMenuEvent, contextMenuPolicy, cursor, depth, destroy, destroy, destroy, dragEnterEvent, dragLeaveEvent, dragMoveEvent, dropEvent, effectiveWinId, ensurePolished, enterEvent, focusInEvent, focusNextChild, focusNextPrevChild, focusOutEvent, focusPolicy, focusPreviousChild, focusProxy, focusWidget, font, fontInfo, fontMetrics, foregroundRole, frameGeometry, frameSize, geometry, getContentsMargins, grabKeyboard, grabMouse, grabMouse, grabShortcut, grabShortcut, graphicsProxyWidget, hasFocus, hasMouseTracking, height, heightForWidth, heightMM, hide, hideEvent, inputContext, inputMethodEvent, inputMethodQuery, insertAction, insertActions, isActiveWindow, isAncestorOf, isEnabled, isEnabledTo, isFullScreen, isHidden, isMaximized, isMinimized, isModal, isVisible, isVisibleTo, isWindow, isWindowModified, keyboardGrabber, keyPressEvent, keyReleaseEvent, languageChange, layout, layoutDirection, leaveEvent, locale, logicalDpiX, logicalDpiY, lower, mapFrom, mapFromGlobal, mapFromParent, mapTo, mapToGlobal, mapToParent, mask, maximumHeight, maximumSize, maximumWidth, metric, minimumHeight, minimumSize, minimumSizeHint, minimumWidth, mouseDoubleClickEvent, mouseGrabber, mouseMoveEvent, mousePressEvent, mouseReleaseEvent, move, move, moveEvent, nativeParentWidget, nextInFocusChain, normalGeometry, numColors, overrideWindowFlags, overrideWindowFlags, overrideWindowState, paintEngine, paintEvent, paintingActive, palette, parentWidget, physicalDpiX, physicalDpiY, pos, raise, rect, releaseKeyboard, releaseMouse, releaseShortcut, removeAction, render, render, render, render, render, render, render, render, render, repaint, repaint, repaint, repaint, resetInputContext, resize, resize, resizeEvent, 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, setWindowFilePath, setWindowFlags, setWindowFlags, setWindowIcon, setWindowIconText, setWindowModality, setWindowModified, setWindowOpacity, setWindowRole, setWindowState, setWindowState, setWindowTitle, show, showEvent, showFullScreen, showMaximized, showMinimized, showNormal, size, sizeHint, sizeIncrement, sizePolicy, stackUnder, statusTip, style, styleSheet, tabletEvent, testAttribute, toolTip, underMouse, unsetCursor, unsetLayoutDirection, unsetLocale, update, update, update, update, updateGeometry, updateMicroFocus, updatesEnabled, visibleRegion, whatsThis, wheelEvent, width, widthMM, window, windowFilePath, windowFlags, windowIcon, windowIconText, windowModality, windowOpacity, windowRole, windowState, windowTitle, windowType, winId, x, y
 
Methods inherited from class com.trolltech.qt.core.QObject
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

iconChanged

public final QSignalEmitter.Signal0 iconChanged
This signal is emitted whenever the icon of the page is loaded or changes.

See also:
icon().


linkClicked

public final QSignalEmitter.Signal1 linkClicked

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QUrl(named: url)>:

This signal is emitted whenever the user clicks on a link and the page's linkDelegationPolicy property is set to delegate the link handling for the specified url.

See also:
QWebPage::linkDelegationPolicy().


loadFinished

public final QSignalEmitter.Signal1 loadFinished

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.Boolean(named: ok)>:

This signal is emitted when a load of the page is finished. ok will indicate whether the load was successful or any error occurred.

See also:
loadStarted() .


loadProgress

public final QSignalEmitter.Signal1 loadProgress

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.Integer(named: progress)>:

This signal is emitted every time an element in the web page completes loading and the overall loading progress advances.

This signal tracks the progress of all child frames.

The current value is provided by progress and scales from 0 to 100, which is the default range of QProgressBar.

See also:
loadStarted() , and loadFinished() .


loadStarted

public final QSignalEmitter.Signal0 loadStarted
This signal is emitted when a new load of the page is started.

See also:
loadProgress() , and loadFinished() .


selectionChanged

public final QSignalEmitter.Signal0 selectionChanged
This signal is emitted whenever the selection changes.

See also:
selectedText().


statusBarMessage

public final QSignalEmitter.Signal1 statusBarMessage

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.String(named: text)>:

This signal is emitted when the statusbar text is changed by the page.


titleChanged

public final QSignalEmitter.Signal1 titleChanged

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.String(named: title)>:

This signal is emitted whenever the title of the main frame changes.

See also:
title().


urlChanged

public final QSignalEmitter.Signal1 urlChanged

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QUrl(named: url)>:

This signal is emitted when the url of the view changes.

See also:
url(), and load().

Constructor Detail

QWebView

public QWebView()
Constructs an empty QWebView with parent parent.

See also:
load().


QWebView

public QWebView(QWidget parent)
Constructs an empty QWebView with parent parent.

See also:
load().

Method Detail

back

public final void back()
Convenience slot that loads the previous document in the list of documents built by navigating links. Does nothing if there is no previous document.

It is equivalent to

    view.page().triggerAction(QWebPage.WebAction.GoBack);

See also:
forward(), and pageAction().


findText

public final boolean findText(java.lang.String subString,
                              QWebPage.FindFlag[] options)

findText

public final boolean findText(java.lang.String subString)
Finds the next occurrence of the string, subString, in the page, using the given options. Returns true of subString was found and selects the match visually; otherwise returns false.

See also:
selectedText(), and selectionChanged() .


findText

public final boolean findText(java.lang.String subString,
                              QWebPage.FindFlags options)
Finds the next occurrence of the string, subString, in the page, using the given options. Returns true of subString was found and selects the match visually; otherwise returns false.

See also:
selectedText(), and selectionChanged() .


forward

public final void forward()
Convenience slot that loads the next document in the list of documents built by navigating links. Does nothing if there is no next document.

It is equivalent to

    view.page().triggerAction(QWebPage.WebAction.GoForward);

See also:
back(), and pageAction().


history

public final QWebHistory history()
Returns a pointer to the view's history of navigated web pages.

It is equivalent to

    view.page().history();


icon

public final QIcon icon()
This property holds the icon associated with the web page currently viewed. By default, this property contains a null icon.

See also:
iconChanged() , and QWebSettings::iconForUrl().


isModified

public final boolean isModified()
This property holds whether the document was modified by the user. Parts of HTML documents can be editable for example through the contenteditable attribute on HTML elements.

By default, this property is false.


load

public final void load(QNetworkRequest request,
                       QNetworkAccessManager.Operation operation)
Loads a network request, request, using the method specified in operation.

body is optional and is only used for POST operations.

Note: The view remains the same until enough data has arrived to display the new url.

See also:
url(), and urlChanged() .


load

public final void load(QNetworkRequest request)
Loads a network request, request, using the method specified in operation.

body is optional and is only used for POST operations.

Note: The view remains the same until enough data has arrived to display the new url.

See also:
url(), and urlChanged() .


load

public final void load(QNetworkRequest request,
                       QNetworkAccessManager.Operation operation,
                       QByteArray body)
Loads a network request, request, using the method specified in operation.

body is optional and is only used for POST operations.

Note: The view remains the same until enough data has arrived to display the new url.

See also:
url(), and urlChanged() .


load

public final void load(QUrl url)
Loads the specified url and displays it.

Note: The view remains the same until enough data has arrived to display the new url.

See also:
setUrl(), url(), and urlChanged() .


page

public final QWebPage page()
Returns a pointer to the underlying web page.

See also:
setPage().


pageAction

public final QAction pageAction(QWebPage.WebAction action)
Returns a pointer to a QAction that encapsulates the specified web action action.


print

public final void print(QPrinter printer)
Prints the main frame to the given printer.

See also:
QWebFrame::print(), and QPrintPreviewDialog.


reload

public final void reload()
Reloads the current document.

See also:
stop(), pageAction(), and loadStarted() .


selectedText

public final java.lang.String selectedText()
This property holds the text currently selected. By default, this property contains an empty string.

See also:
findText(), and selectionChanged() .


setContent

public final void setContent(QByteArray data,
                             java.lang.String mimeType)
Sets the content of the web view to the specified content data. If the mimeType argument is empty it is currently assumed that the content is HTML but in future versions we may introduce auto-detection.

External objects referenced in the content are located relative to baseUrl.

See also:
load(), setHtml(), and QWebFrame::toHtml().


setContent

public final void setContent(QByteArray data)
Sets the content of the web view to the specified content data. If the mimeType argument is empty it is currently assumed that the content is HTML but in future versions we may introduce auto-detection.

External objects referenced in the content are located relative to baseUrl.

See also:
load(), setHtml(), and QWebFrame::toHtml().


setContent

public final void setContent(QByteArray data,
                             java.lang.String mimeType,
                             QUrl baseUrl)
Sets the content of the web view to the specified content data. If the mimeType argument is empty it is currently assumed that the content is HTML but in future versions we may introduce auto-detection.

External objects referenced in the content are located relative to baseUrl.

See also:
load(), setHtml(), and QWebFrame::toHtml().


setHtml

public final void setHtml(java.lang.String html)
Sets the content of the web view to the specified html.

External objects such as stylesheets or images referenced in the HTML document are located relative to baseUrl.

When using this method, WebKit assumes that external resources such as JavaScript programs or style sheets are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external script can be specified through the charset attribute of the HTML script tag. Alternatively, the encoding can also be specified by the web server.

See also:
load(), setContent(), and QWebFrame::toHtml().


setHtml

public final void setHtml(java.lang.String html,
                          QUrl baseUrl)
Sets the content of the web view to the specified html.

External objects such as stylesheets or images referenced in the HTML document are located relative to baseUrl.

When using this method, WebKit assumes that external resources such as JavaScript programs or style sheets are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external script can be specified through the charset attribute of the HTML script tag. Alternatively, the encoding can also be specified by the web server.

See also:
load(), setContent(), and QWebFrame::toHtml().


setPage

public final void setPage(QWebPage page)
Makes page the new web page of the web view.

The parent QObject of the provided page remains the owner of the object. If the current document is a child of the web view, it will be deleted.

See also:
page().


setTextSizeMultiplier

public final void setTextSizeMultiplier(double factor)
Sets the value of the multiplier used to scale the text in a Web page to the factor specified.

See also:
textSizeMultiplier().


setUrl

public final void setUrl(QUrl url)
This property holds the url of the web page currently viewed. Setting this property clears the view and loads the URL.

By default, this property contains an empty, invalid URL.

See also:
load(), and urlChanged() .


setZoomFactor

public final void setZoomFactor(double factor)
This property holds the zoom factor for the view.


settings

public final QWebSettings settings()
Returns a pointer to the view/page specific settings object.

It is equivalent to

    view.page().settings();

See also:
QWebSettings::globalSettings().


stop

public final void stop()
Convenience slot that stops loading the document.

It is equivalent to

    view.page().triggerAction(QWebPage.WebAction.Stop);

See also:
reload(), pageAction(), and loadFinished() .


textSizeMultiplier

public final double textSizeMultiplier()
Returns the value of the multiplier used to scale the text in a Web page.

See also:
setTextSizeMultiplier().


title

public final java.lang.String title()
This property holds the title of the web page currently viewed. By default, this property contains an empty string.

See also:
titleChanged() .


triggerPageAction

public final void triggerPageAction(QWebPage.WebAction action)
Triggers the specified action. If it is a checkable action the specified checked state is assumed.

The following example triggers the copy action and therefore copies any selected text to the clipboard.

    view.triggerAction(QWebPage.WebAction.Copy);

See also:
pageAction().


triggerPageAction

public final void triggerPageAction(QWebPage.WebAction action,
                                    boolean checked)
Triggers the specified action. If it is a checkable action the specified checked state is assumed.

The following example triggers the copy action and therefore copies any selected text to the clipboard.

    view.triggerAction(QWebPage.WebAction.Copy);

See also:
pageAction().


url

public final QUrl url()
This property holds the url of the web page currently viewed. Setting this property clears the view and loads the URL.

By default, this property contains an empty, invalid URL.

See also:
load(), and urlChanged() .


zoomFactor

public final double zoomFactor()
This property holds the zoom factor for the view.


createWindow

protected QWebView createWindow(QWebPage.WebWindowType type)
This function is called whenever WebKit wants to create a new window of the given type, for example as a result of a JavaScript request to open a document in a new window.

See also:
QWebPage::createWindow().