Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description
• Elements of QWebView

Detailed Description

TheQWebView class provides a widget that is used to view and edit web documents.

QWebView is the main widget component of theQtWebKit web browsing module. It can be used in various applications to display web content live from the Internet.

A web site can be loaded ontoQWebView with theload() function. Like all Qt widgets, theshow() function must be invoked in order to displayQWebView. The snippet below illustrates this:

QWebView*view=newQWebView(parent);    view->load(QUrl("http://qt-project.org"));    view->show();

Alternatively,setUrl() can also be used to load a web site. If you have the HTML content readily available, you can usesetHtml() instead.

TheloadStarted() signal is emitted when the view begins loading. TheloadProgress() 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, theloadFinished() signal is emitted when the view has loaded completely. It's argument - eithertrue orfalse - indicates load success or failure.

Thepage() function returns a pointer to the web page object. SeeElements 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 theQWebSettings object with thesettings() function. WithQWebSettings, 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 thetitle() property. Additionally, a web site may also specify an icon, which can be accessed using theicon() property. If the title or the icon changes, the correspondingtitleChanged() andiconChanged() signals will be emitted. ThetextSizeMultiplier() 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 reimplementingcontextMenuEvent() and populating yourQMenu with the actions obtained frompageAction(). More functionality such as reloading the view, copying selected text to the clipboard, or pasting into the view, is also encapsulated within theQAction objects returned bypageAction(). These actions can be programmatically triggered usingtriggerPageAction(). 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 astext oricon.

AQWebView can be printed onto aQPrinter using theprint() function. This function is marked as a slot and can be conveniently connected toQPrintPreviewDialog'spaintRequested() 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 subclassQWebView and reimplement thecreateWindow() function.

Elements of QWebView

QWebView consists of other objects such asQWebFrame andQWebPage. The flowchart below shows these elements are related.

Note:It is possible to useQWebPage andQWebFrame, without usingQWebView, if you do not requireQWidget attributes. Nevertheless,QtWebKit depends onQtGui, so you should use aQApplication instead ofQCoreApplication.

Property Documentation

hasSelection : constbool

This property holds whether this page contains selected content or not.

By default, this property is false.

Access functions:

See alsoselectionChanged().

icon : constQIcon

This property holds the icon associated with the web page currently viewed.

By default, this property contains a null icon.

Access functions:

See alsoiconChanged() andQWebSettings::iconForUrl().

modified : constbool

This property holds whether the document was modified by the user.

Parts of HTML documents can be editable for example through thecontenteditable attribute on HTML elements.

By default, this property is false.

Access functions:

renderHints :QPainter::RenderHints

This property holds the default render hints for the view.

These hints are used to initializeQPainter before painting the Web page.

QPainter::TextAntialiasing andQPainter::SmoothPixmapTransform are enabled by default.

Note:This property is not available on Symbian. However, the getter and setter functions can still be used directly.

This property was introduced in Qt 4.6.

Access functions:

See alsoQPainter::renderHints().

selectedHtml : constQString

This property holds the HTML currently selected.

By default, this property contains an empty string.

This property was introduced in Qt 4.8.

Access functions:

See alsofindText(),selectionChanged(), andselectedText().

selectedText : constQString

This property holds the text currently selected.

By default, this property contains an empty string.

Access functions:

See alsofindText(),selectionChanged(), andselectedHtml().

title : constQString

This property holds the title of the web page currently viewed.

By default, this property contains an empty string.

Access functions:

See alsotitleChanged().

url :QUrl

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.

Access functions:

See alsoload() andurlChanged().

zoomFactor :qreal

This property holds the zoom factor for the view.

This property was introduced in Qt 4.5.

Access functions:

Member Function Documentation

QWebView::QWebView(QWidget * parent = 0)

Constructs an emptyQWebView with parentparent.

See alsoload().

[virtual]QWebView::~QWebView()

Destroys the web view.

[slot]void QWebView::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()->triggerPageAction(QWebPage::GoBack);

See alsoforward() andpageAction().

[virtual protected]void QWebView::changeEvent(QEvent * e)

Reimplemented fromQWidget::changeEvent().

[virtual protected]void QWebView::contextMenuEvent(QContextMenuEvent * ev)

Reimplemented fromQWidget::contextMenuEvent().

[virtual protected]QWebView * QWebView::createWindow(QWebPage::WebWindowType type)

This function is called from the createWindow() method of the associatedQWebPage, each time the page wants to create a new window of the giventype. This might be the result, for example, of a JavaScript request to open a document in a new window.

Note:If the createWindow() method of the associated page is reimplemented, this method is not called, unless explicitly done so in the reimplementation.

Note:In the cases when the window creation is being triggered by JavaScript, apart from reimplementing this method application must also set the JavaScriptCanOpenWindows attribute ofQWebSettings to true in order for it to get called.

See alsoQWebPage::createWindow() andQWebPage::acceptNavigationRequest().

[virtual protected]void QWebView::dragEnterEvent(QDragEnterEvent * ev)

Reimplemented fromQWidget::dragEnterEvent().

[virtual protected]void QWebView::dragLeaveEvent(QDragLeaveEvent * ev)

Reimplemented fromQWidget::dragLeaveEvent().

[virtual protected]void QWebView::dragMoveEvent(QDragMoveEvent * ev)

Reimplemented fromQWidget::dragMoveEvent().

[virtual protected]void QWebView::dropEvent(QDropEvent * ev)

Reimplemented fromQWidget::dropEvent().

[virtual]bool QWebView::event(QEvent * e)

Reimplemented fromQObject::event().

bool QWebView::findText(constQString & subString,QWebPage::FindFlags options = 0)

Finds the specified string,subString, in the page, using the givenoptions.

If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences that exist in the page. All subsequent calls will extend the highlight, rather than replace it, with occurrences of the new string.

If the HighlightAllOccurrences flag is not passed, the function will select an occurrence and all subsequent calls will replace the current occurrence with the next one.

To clear the selection, just pass an empty string.

Returns true ifsubString was found; otherwise returns false.

See alsoselectedText() andselectionChanged().

[virtual protected]void QWebView::focusInEvent(QFocusEvent * ev)

Reimplemented fromQWidget::focusInEvent().

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

Reimplemented fromQWidget::focusNextPrevChild().

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

Reimplemented fromQWidget::focusOutEvent().

[slot]void QWebView::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()->triggerPageAction(QWebPage::GoForward);

See alsoback() andpageAction().

QWebHistory * QWebView::history() const

Returns a pointer to the view's history of navigated web pages.

It is equivalent to

    view->page()->history();

[signal]void QWebView::iconChanged()

This signal is emitted whenever the icon of the page is loaded or changes.

In order for icons to be loaded, you will need to set an icon database path usingQWebSettings::setIconDatabasePath().

See alsoicon() andQWebSettings::setIconDatabasePath().

[virtual protected]void QWebView::inputMethodEvent(QInputMethodEvent * e)

Reimplemented fromQWidget::inputMethodEvent().

[virtual]QVariant QWebView::inputMethodQuery(Qt::InputMethodQuery property) const

Reimplemented fromQWidget::inputMethodQuery().

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

Reimplemented fromQWidget::keyPressEvent().

[virtual protected]void QWebView::keyReleaseEvent(QKeyEvent * ev)

Reimplemented fromQWidget::keyReleaseEvent().

[signal]void QWebView::linkClicked(constQUrl & 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 specifiedurl.

See alsoQWebPage::linkDelegationPolicy().

void QWebView::load(constQUrl & url)

Loads the specifiedurl and displays it.

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

See alsosetUrl(),url(),urlChanged(), andQUrl::fromUserInput().

void QWebView::load(constQNetworkRequest & request,QNetworkAccessManager::Operation operation = QNetworkAccessManager::GetOperation, constQByteArray & body = QByteArray())

Loads a network request,request, using the method specified inoperation.

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 alsourl() andurlChanged().

[signal]void QWebView::loadFinished(bool 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 alsoloadStarted().

[signal]void QWebView::loadProgress(int 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 byprogress and scales from 0 to 100, which is the default range ofQProgressBar.

See alsoloadStarted() andloadFinished().

[signal]void QWebView::loadStarted()

This signal is emitted when a new load of the page is started.

See alsoloadProgress() andloadFinished().

[virtual protected]void QWebView::mouseDoubleClickEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mouseDoubleClickEvent().

[virtual protected]void QWebView::mouseMoveEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mouseMoveEvent().

[virtual protected]void QWebView::mousePressEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mousePressEvent().

[virtual protected]void QWebView::mouseReleaseEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mouseReleaseEvent().

QWebPage * QWebView::page() const

Returns a pointer to the underlying web page.

See alsosetPage().

QAction * QWebView::pageAction(QWebPage::WebAction action) const

Returns a pointer to aQAction that encapsulates the specified web actionaction.

[virtual protected]void QWebView::paintEvent(QPaintEvent * ev)

Reimplemented fromQWidget::paintEvent().

[slot]void QWebView::print(QPrinter * printer) const

Prints the main frame to the givenprinter.

See alsoQWebFrame::print() andQPrintPreviewDialog.

[slot]void QWebView::reload()

Reloads the current document.

See alsostop(),pageAction(), andloadStarted().

[virtual protected]void QWebView::resizeEvent(QResizeEvent * e)

Reimplemented fromQWidget::resizeEvent().

[signal]void QWebView::selectionChanged()

This signal is emitted whenever the selection changes.

See alsoselectedText().

void QWebView::setContent(constQByteArray & data, constQString & mimeType = QString(), constQUrl & baseUrl = QUrl())

Sets the content of the web view to the specified contentdata. If themimeType 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 tobaseUrl.

Thedata is loaded immediately; external objects are loaded asynchronously.

See alsoload(),setHtml(), andQWebFrame::toHtml().

void QWebView::setHtml(constQString & html, constQUrl & baseUrl = QUrl())

Sets the content of the web view to the specifiedhtml.

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

Thehtml is loaded immediately; external objects are loaded asynchronously.

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.

This is a convenience function equivalent tosetContent(html, "text/html", baseUrl).

Warning: This function works only for HTML, for other mime types (i.e. XHTML, SVG)setContent() should be used instead.

See alsoload(),setContent(),QWebFrame::toHtml(), andQWebFrame::setContent().

void QWebView::setPage(QWebPage * page)

Makespage the new web page of the web view.

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

See alsopage().

void QWebView::setRenderHint(QPainter::RenderHint hint,bool enabled = true)

Ifenabled is true, enables the specified renderhint; otherwise disables it.

This function was introduced in Qt 4.6.

See alsorenderHints andQPainter::renderHints().

void QWebView::setTextSizeMultiplier(qreal factor)

Sets the value of the multiplier used to scale the text in a Web page to thefactor specified.

See alsotextSizeMultiplier().

QWebSettings * QWebView::settings() const

Returns a pointer to the view/page specific settings object.

It is equivalent to

    view->page()->settings();

See alsoQWebSettings::globalSettings().

[virtual]QSize QWebView::sizeHint() const

Reimplemented fromQWidget::sizeHint().

[signal]void QWebView::statusBarMessage(constQString & text)

This signal is emitted when the status bartext is changed by the page.

[slot]void QWebView::stop()

Convenience slot that stops loading the document.

It is equivalent to

    view->page()->triggerPageAction(QWebPage::Stop);

See alsoreload(),pageAction(), andloadFinished().

qreal QWebView::textSizeMultiplier() const

Returns the value of the multiplier used to scale the text in a Web page.

See alsosetTextSizeMultiplier().

[signal]void QWebView::titleChanged(constQString & title)

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

See alsotitle().

void QWebView::triggerPageAction(QWebPage::WebAction action,bool checked = false)

Triggers the specifiedaction. If it is a checkable action the specifiedchecked state is assumed.

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

    view->triggerAction(QWebPage::Copy);

See alsopageAction().

[signal]void QWebView::urlChanged(constQUrl & url)

This signal is emitted when theurl of the view changes.

See alsourl() andload().

[virtual protected]void QWebView::wheelEvent(QWheelEvent * ev)

Reimplemented fromQWidget::wheelEvent().