QWebFrame Class Reference

The QWebFrame class represents a frame in a web page. More...

#include <qwebframe.h>

Public Types
enum	RenderLayer { ContentsLayer = 0x10, ScrollBarLayer = 0x20, PanIconLayer = 0x40, AllLayers = 0xff }
Public Slots
QVariant	evaluateJavaScript (const QString &scriptSource)
void	print (QPrinter *printer) const
Signals
void	javaScriptWindowObjectCleared ()
void	provisionalLoad ()
void	titleChanged (const QString &title)
void	urlChanged (const QUrl &url)
void	initialLayoutCompleted ()
void	iconChanged ()
void	contentsSizeChanged (const QSize &size)
void	loadStarted ()
void	loadFinished (bool ok)
Public Member Functions
QWebPage *	page () const
void	load (const QUrl &url)
void	load (const QNetworkRequest &request, QNetworkAccessManager::Operation operation=QNetworkAccessManager::GetOperation, const QByteArray &body=QByteArray())
void	setHtml (const QString &html, const QUrl &baseUrl=QUrl())
void	setContent (const QByteArray &data, const QString &mimeType=QString(), const QUrl &baseUrl=QUrl())
void	addToJavaScriptWindowObject (const QString &name, QObject *object)
void	addToJavaScriptWindowObject (const QString &name, QObject *object, QScriptEngine::ValueOwnership ownership)
QString	toHtml () const
QString	toPlainText () const
QString	renderTreeDump () const
QString	title () const
void	setUrl (const QUrl &url)
QUrl	url () const
QUrl	requestedUrl () const
QUrl	baseUrl () const
QIcon	icon () const
QMultiMap< QString, QString >	metaData () const
	Returns the meta data in this frame as a QMultiMap.
QString	frameName () const
QWebFrame *	parentFrame () const
QList< QWebFrame * >	childFrames () const
Qt::ScrollBarPolicy	scrollBarPolicy (Qt::Orientation orientation) const
void	setScrollBarPolicy (Qt::Orientation orientation, Qt::ScrollBarPolicy policy)
void	setScrollBarValue (Qt::Orientation orientation, int value)
int	scrollBarValue (Qt::Orientation orientation) const
int	scrollBarMinimum (Qt::Orientation orientation) const
int	scrollBarMaximum (Qt::Orientation orientation) const
QRect	scrollBarGeometry (Qt::Orientation orientation) const
void	scroll (int, int)
bool	scrollRecursively (int, int)
QPoint	scrollPosition () const
void	setScrollPosition (const QPoint &pos)
void	render (QPainter *)
void	render (QPainter *, const QRegion &clip)
void	render (QPainter *, RenderLayer layer, const QRegion &clip=QRegion())
void	setTextSizeMultiplier (qreal factor)
qreal	textSizeMultiplier () const
qreal	zoomFactor () const
void	setZoomFactor (qreal factor)
bool	hasFocus () const
void	setFocus ()
QPoint	pos () const
QRect	geometry () const
QSize	contentsSize () const
QWebElement	documentElement () const
QWebElementCollection	findAllElements (const QString &selectorQuery) const
QWebElement	findFirstElement (const QString &selectorQuery) const
QWebHitTestResult	hitTestContent (const QPoint &pos) const
virtual bool	event (QEvent *)
QWebSecurityOrigin	securityOrigin () const
Properties
qreal	textSizeMultiplier
	the scaling factor for all text in the frame
qreal	zoomFactor
	the zoom factor for the frame
QString	title
	the title of the frame as defined by the HTML <title> element
QUrl	url
	the url of the frame currently viewed
QUrl	requestedUrl
QUrl	baseUrl
	the base URL of the frame, can be used to resolve relative URLs
QIcon	icon
	the icon associated with this frame
QSize	contentsSize
	the size of the contents in this frame
QPoint	scrollPosition
	the position the frame is currently scrolled to.
bool	focus
Private Member Functions
	QWebFrame (QWebPage parent, QWebFrameData frameData)
	QWebFrame (QWebFrame parent, QWebFrameData frameData)
	~QWebFrame ()
Private Attributes
QWebFramePrivate *	d
Friends
class	QWebPage
class	QWebPagePrivate
class	QWebFramePrivate
class	WebCore::WidgetPrivate
class	WebCore::FrameLoaderClientQt
class	WebCore::ChromeClientQt

Detailed Description

The QWebFrame class represents a frame in a web page.

Since:: 4.4 QtWebKit

QWebFrame represents a frame inside a web page. Each QWebPage object contains at least one frame, the main frame, obtained using QWebPage::mainFrame(). Additional frames will be created for HTML {<frame>} or {<iframe>} elements.

A frame can be loaded using load() or setUrl(). Alternatively, if you have the HTML content readily available, you can use setHtml() instead.

The page() function returns a pointer to the web page object. See {QWebView}{Elements of QWebView} for an explanation of how web frames are related to a web page and web view.

The QWebFrame class also offers methods to retrieve both the URL currently loaded by the frame (see url()) as well as the URL originally requested to be loaded (see requestedUrl()). These methods make possible the retrieval of the URL before and after a DNS resolution or a redirection occurs during the load process. The requestedUrl() also matches to the URL added to the frame history ({QWebHistory}) if load is successful.

The title of an HTML frame can be accessed with the title() property. Additionally, a frame 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 zoomFactor() property can be used to change the overall size of the content displayed in the frame.

QWebFrame objects are created and controlled by the web page. You can connect to the web page's {QWebPage::}{frameCreated()} signal to be notified when a new frame is created.

The hitTestContent() function can be used to programmatically examine the contents of a frame.

A QWebFrame 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 {QPrintPreviewDialog::}{paintRequested()} signal.

See also:: QWebPage

Definition at line 103 of file qwebframe.h.

Member Enumeration Documentation

enum QWebFrame::RenderLayer

This enum describes the layers available for rendering using {QWebFrame::}{render()}. The layers can be OR-ed together from the following list:

ContentsLayer The web content of the frame ScrollBarLayer The scrollbars of the frame PanIconLayer The icon used when panning the frame

AllLayers Includes all the above layers

Enumerator:

ContentsLayer
ScrollBarLayer
PanIconLayer
AllLayers

Definition at line 163 of file qwebframe.h.

Constructor & Destructor Documentation

QWebFrame::QWebFrame	(	QWebPage *	parent,
		QWebFrameData *	frameData
	)			`[private]`

Definition at line 480 of file qwebframe.cpp.

References d.

QWebFrame::QWebFrame	(	QWebFrame *	parent,
		QWebFrameData *	frameData
	)			`[private]`

Definition at line 493 of file qwebframe.cpp.

References d.

QWebFrame::~QWebFrame ( ) [private]

Definition at line 501 of file qwebframe.cpp.

References d.

Member Function Documentation

void QWebFrame::addToJavaScriptWindowObject	(	const QString &	name,
		QObject *	object,
		QScriptEngine::ValueOwnership	own
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Make object available under name from within the frame's JavaScript context. The object will be inserted as a child of the frame's window object.

Qt properties will be exposed as JavaScript properties and slots as JavaScript methods.

If you want to ensure that your QObjects remain accessible after loading a new URL, you should add them in a slot connected to the javaScriptWindowObjectCleared() signal.

If Javascript is not enabled for this page, then this method does nothing.

The ownership of object is specified using own.

Definition at line 549 of file qwebframe.cpp.

References d, and page().

Here is the call graph for this function:

void QWebFrame::addToJavaScriptWindowObject	(	const QString &	name,
		QObject *	object
	)

Make object available under name from within the frame's JavaScript context. The object will be inserted as a child of the frame's window object.

Qt properties will be exposed as JavaScript properties and slots as JavaScript methods.

If you want to ensure that your QObjects remain accessible after loading a new URL, you should add them in a slot connected to the javaScriptWindowObjectCleared() signal.

If Javascript is not enabled for this page, then this method does nothing.

The object will never be explicitly deleted by QtWebKit.

Definition at line 525 of file qwebframe.cpp.

QUrl QWebFrame::baseUrl ( ) const

QList< QWebFrame * > QWebFrame::childFrames ( ) const

Returns a list of all frames that are direct children of this frame.

See also:: parentFrame()

Definition at line 911 of file qwebframe.cpp.

References d.

QSize QWebFrame::contentsSize ( ) const

void QWebFrame::contentsSizeChanged ( const QSize & size ) [signal]

Since:: 4.6

This signal is emitted when the frame's contents size changes to size.

See also:: contentsSize()

QWebElement QWebFrame::documentElement ( ) const

Since:: 4.6

Returns the document element of this frame.

The document element provides access to the entire structured content of the frame.

Definition at line 1285 of file qwebframe.cpp.

References d.

QVariant QWebFrame::evaluateJavaScript ( const QString & scriptSource ) [slot]

Evaluates the JavaScript defined by scriptSource using this frame as context and returns the result of the last executed statement.

See also:: addToJavaScriptWindowObject(), javaScriptWindowObjectCleared()

Definition at line 1451 of file qwebframe.cpp.

References d.

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

Definition at line 1342 of file qwebframe.cpp.

QWebElementCollection QWebFrame::findAllElements ( const QString & selectorQuery ) const

Since:: 4.6 Returns a new list of elements matching the given CSS selector selectorQuery. If there are no matching elements, an empty list is returned.

{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is used for the query.

See also:: QWebElement::findAll()

Definition at line 1303 of file qwebframe.cpp.

References documentElement().

Here is the call graph for this function:

QWebElement QWebFrame::findFirstElement ( const QString & selectorQuery ) const

Since:: 4.6 Returns the first element in the frame's document that matches the given CSS selector selectorQuery. If there is no matching element, a null element is returned.

{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is used for the query.

See also:: QWebElement::findFirst()

Definition at line 1319 of file qwebframe.cpp.

References documentElement().

Here is the call graph for this function:

QString QWebFrame::frameName ( ) const

The name of this frame as defined by the parent frame.

Definition at line 759 of file qwebframe.cpp.

References d.

QRect QWebFrame::geometry ( ) const

Return the geometry of the frame relative to it's parent frame.

Definition at line 1256 of file qwebframe.cpp.

References d.

bool QWebFrame::hasFocus ( ) const

Definition at line 1226 of file qwebframe.cpp.

References d.

QWebHitTestResult QWebFrame::hitTestContent ( const QPoint & pos ) const

Performs a hit test on the frame contents at the given position pos and returns the hit test result.

Definition at line 1327 of file qwebframe.cpp.

References d, and WebCore::HitTestResult::scrollbar().

Here is the call graph for this function:

QIcon QWebFrame::icon ( ) const

void QWebFrame::iconChanged ( ) [signal]

This signal is emitted when the icon ("favicon") associated with the frame has been loaded.

See also:: icon()

void QWebFrame::initialLayoutCompleted ( ) [signal]

This signal is emitted when the frame is laid out the first time. This is the first time you will see contents displayed on the frame.

Note:: A frame can be laid out multiple times.

void QWebFrame::javaScriptWindowObjectCleared ( ) [signal]

This signal is emitted whenever the global window object of the JavaScript environment is cleared, e.g., before starting a new load.

If you intend to add QObjects to a QWebFrame using addToJavaScriptWindowObject(), you should add them in a slot connected to this signal. This ensures that your objects remain accessible when loading new URLs.

void QWebFrame::load	(	const QNetworkRequest &	req,
		QNetworkAccessManager::Operation	operation = `QNetworkAccessManager::GetOperation`,
		const QByteArray &	body = `QByteArray()`
	)

Loads a network request, req, into this frame, 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:: setUrl()

Definition at line 794 of file qwebframe.cpp.

References d, ensureAbsoluteUrl(), and url().

Here is the call graph for this function:

void QWebFrame::load ( const QUrl & url )

Loads url into this frame.

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

See also:: setUrl(), setHtml(), setContent()

Definition at line 779 of file qwebframe.cpp.

References ensureAbsoluteUrl().

Here is the call graph for this function:

void QWebFrame::loadFinished ( bool ok ) [signal]

Since:: 4.6

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

See also:: loadStarted()

void QWebFrame::loadStarted ( ) [signal]

Since:: 4.6

This signal is emitted when a new load of this frame is started.

See also:: loadFinished()

QMultiMap< QString, QString > QWebFrame::metaData ( ) const

Returns the meta data in this frame as a QMultiMap.

Since:: 4.5 The meta data consists of the name and content attributes of the of the {<meta>} tags in the HTML document.

For example:

    <html>
        <head>
            <meta name="description" content="This document is a tutorial about Qt development">
            <meta name="keywords" content="Qt, WebKit, Programming">
        </head>
        ...
    </html>

Given the above HTML code the metaData() function will return a map with two entries: Key Value "description" "This document is a tutorial about Qt development" "keywords" "Qt, WebKit, Programming"

This function returns a multi map to support multiple meta tags with the same attribute name.

Definition at line 657 of file qwebframe.cpp.

References d.

QWebPage * QWebFrame::page ( ) const

The web page that contains this frame.

Definition at line 767 of file qwebframe.cpp.

References d.

QWebFrame * QWebFrame::parentFrame ( ) const

Returns the parent frame of this frame, or 0 if the frame is the web pages main frame.

This is equivalent to qobject_cast<QWebFrame*>(frame->parent()).

See also:: childFrames()

Definition at line 901 of file qwebframe.cpp.

References d.

QPoint QWebFrame::pos ( ) const

Returns the position of the frame relative to it's parent frame.

Definition at line 1245 of file qwebframe.cpp.

References d.

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

Prints the frame to the given printer.

See also:: render()

Definition at line 1353 of file qwebframe.cpp.

References d, page(), and qt_defaultDpi().

Here is the call graph for this function:

void QWebFrame::provisionalLoad ( ) [signal]

void QWebFrame::render	(	QPainter *	painter,
		RenderLayer	layer,
		const QRegion &	clip = `QRegion()`
	)

Since:: 4.6 Render the layer of the frame using painter clipping to clip.

See also:: print()

Definition at line 1136 of file qwebframe.cpp.

References d.

void QWebFrame::render	(	QPainter *	painter,
		const QRegion &	clip
	)

Render the frame into painter clipping to clip.

Definition at line 1151 of file qwebframe.cpp.

References AllLayers, and d.

void QWebFrame::render ( QPainter * painter )

Render the frame into painter.

Definition at line 1163 of file qwebframe.cpp.

References AllLayers, and d.

QString QWebFrame::renderTreeDump ( ) const

Returns a dump of the rendering tree. This is mainly useful for debugging html.

Definition at line 604 of file qwebframe.cpp.

References d.

QUrl QWebFrame::requestedUrl ( ) const

void QWebFrame::scroll	(	int	dx,
		int	dy
	)

Since:: 4.5 Scrolls the frame dx pixels to the right and dy pixels downward. Both dx and dy may be negative.

See also:: QWebFrame::scrollPosition

Definition at line 1049 of file qwebframe.cpp.

References d.

QRect QWebFrame::scrollBarGeometry ( Qt::Orientation orientation ) const

Since:: 4.6 Returns the geometry for the scrollbar with orientation orientation.

If the scrollbar does not exist an empty rect is returned.

Definition at line 1032 of file qwebframe.cpp.

References d.

int QWebFrame::scrollBarMaximum ( Qt::Orientation orientation ) const

Returns the maximum value for the scrollbar with orientation orientation, or 0 if no scrollbar is found for orientation.

See also:: scrollBarMinimum()

Definition at line 1004 of file qwebframe.cpp.

References d.

int QWebFrame::scrollBarMinimum ( Qt::Orientation orientation ) const

Returns the minimum value for the scrollbar with orientation orientation.

The minimum value is always 0.

See also:: scrollBarMaximum()

Definition at line 1020 of file qwebframe.cpp.

Qt::ScrollBarPolicy QWebFrame::scrollBarPolicy ( Qt::Orientation orientation ) const

Returns the scrollbar policy for the scrollbar defined by orientation.

Definition at line 930 of file qwebframe.cpp.

References d.

int QWebFrame::scrollBarValue ( Qt::Orientation orientation ) const

Returns the current value for the scrollbar with orientation orientation, or 0 if no scrollbar is found for orientation.

See also:: scrollBarMinimum(), scrollBarMaximum()

Definition at line 989 of file qwebframe.cpp.

References d.

QPoint QWebFrame::scrollPosition ( ) const

bool QWebFrame::scrollRecursively	(	int	dx,
		int	dy
	)

Since:: 4.7 Scrolls nested frames starting at this frame, dx pixels to the right and dy pixels downward. Both dx and dy may be negative. First attempts to scroll elements with CSS overflow followed by this frame. If this frame doesn't scroll, attempts to scroll the parent

See also:: QWebFrame::scroll

Definition at line 1066 of file qwebframe.cpp.

References d.

QWebSecurityOrigin QWebFrame::securityOrigin ( ) const

Since:: 4.5

Returns the frame's security origin.

Definition at line 1468 of file qwebframe.cpp.

void QWebFrame::setContent	(	const QByteArray &	data,
		const QString &	mimeType = `QString()`,
		const QUrl &	baseUrl = `QUrl()`
	)

Sets the content of this frame 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.

The data is loaded immediately; external objects are loaded asynchronously.

Note:: This method will not affect session or global history for the frame.

See also:: toHtml(), setHtml()

Definition at line 881 of file qwebframe.cpp.

References d.

void QWebFrame::setFocus ( )

Since:: 4.6

Gives keyboard input focus to this frame.

Definition at line 1237 of file qwebframe.cpp.

void QWebFrame::setHtml	(	const QString &	html,
		const QUrl &	baseUrl = `QUrl()`
	)

Sets the content of this frame to html. baseUrl is optional and used to resolve relative URLs in the document, such as referenced images or stylesheets.

The html 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. It is also possible for the encoding to be specified by web server.

Note:: This method will not affect session or global history for the frame.

See also:: toHtml(), setContent()

Definition at line 858 of file qwebframe.cpp.

References d.

void QWebFrame::setScrollBarPolicy	(	Qt::Orientation	orientation,
		Qt::ScrollBarPolicy	policy
	)

Sets the scrollbar policy for the scrollbar defined by orientation to policy.

Definition at line 940 of file qwebframe.cpp.

References d.

void QWebFrame::setScrollBarValue	(	Qt::Orientation	orientation,
		int	value
	)

Sets the current value for the scrollbar with orientation orientation.

The scrollbar forces the value to be within the legal range: minimum <= value <= maximum.

Changing the value also updates the thumb position.

See also:: scrollBarMinimum(), scrollBarMaximum()

Definition at line 970 of file qwebframe.cpp.

References d, and scrollBarMaximum().

Here is the call graph for this function:

void QWebFrame::setScrollPosition ( const QPoint & pos )

Definition at line 1121 of file qwebframe.cpp.

References scroll(), and scrollPosition().

Here is the call graph for this function:

void QWebFrame::setTextSizeMultiplier ( qreal factor )

Sets the value of the multiplier used to scale the text in a Web frame to the factor specified.

Definition at line 1191 of file qwebframe.cpp.

References d.

void QWebFrame::setUrl ( const QUrl & url )

Definition at line 688 of file qwebframe.cpp.

References d, ensureAbsoluteUrl(), and load().

Here is the call graph for this function:

void QWebFrame::setZoomFactor ( qreal factor )

Definition at line 1210 of file qwebframe.cpp.

References d.

qreal QWebFrame::textSizeMultiplier ( ) const

QString QWebFrame::title ( ) const

void QWebFrame::titleChanged ( const QString & title ) [signal]

This signal is emitted whenever the title of the frame changes. The title string specifies the new title.

See also:: title()

QString QWebFrame::toHtml ( ) const

Returns the frame's content as HTML, enclosed in HTML and BODY tags.

See also:: setHtml(), toPlainText()

Definition at line 576 of file qwebframe.cpp.

References d.

QString QWebFrame::toPlainText ( ) const

Returns the content of this frame converted to plain text, completely stripped of all HTML formatting.

See also:: toHtml()

Definition at line 589 of file qwebframe.cpp.

References d, and documentElement().

Here is the call graph for this function:

QUrl QWebFrame::url ( ) const

void QWebFrame::urlChanged ( const QUrl & url ) [signal]

This signal is emitted with the URL of the frame when the frame's title is received. The new URL is specified by url.

See also:: url()

qreal QWebFrame::zoomFactor ( ) const

Friends And Related Function Documentation

friend class QWebFramePrivate [friend]

Definition at line 223 of file qwebframe.h.

friend class QWebPage [friend]

Definition at line 221 of file qwebframe.h.

friend class QWebPagePrivate [friend]

Definition at line 222 of file qwebframe.h.

friend class WebCore::ChromeClientQt [friend]

Definition at line 226 of file qwebframe.h.

friend class WebCore::FrameLoaderClientQt [friend]

Definition at line 225 of file qwebframe.h.

friend class WebCore::WidgetPrivate [friend]

Definition at line 224 of file qwebframe.h.

Member Data Documentation

QWebFramePrivate* QWebFrame::d [private]

Definition at line 227 of file qwebframe.h.

Property Documentation

QUrl QWebFrame::baseUrl [read]

the base URL of the frame, can be used to resolve relative URLs

Since:: 4.6; 4.6

Definition at line 110 of file qwebframe.h.

QSize QWebFrame::contentsSize [read]

the size of the contents in this frame

See also:: contentsSizeChanged()

Definition at line 112 of file qwebframe.h.

QWebFrame::focus [read]

Since:: 4.6

Returns true if this frame has keyboard input focus; otherwise, returns false.

Definition at line 114 of file qwebframe.h.

QIcon QWebFrame::icon [read]

the icon associated with this frame

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

Definition at line 111 of file qwebframe.h.

QUrl QWebFrame::requestedUrl [read]

Since:: 4.6

The URL requested to loaded by the frame currently viewed. The URL may differ from the one returned by url() if a DNS resolution or a redirection occurs.

See also:: url(), setUrl()

Definition at line 109 of file qwebframe.h.

QPoint QWebFrame::scrollPosition [read, write]

the position the frame is currently scrolled to.

Since:: 4.5

Definition at line 113 of file qwebframe.h.

qreal QWebFrame::textSizeMultiplier [read, write]

the scaling factor for all text in the frame

Use setZoomFactor instead, in combination with the ZoomTextOnly attribute in QWebSettings.

Note:: Setting this property also enables the ZoomTextOnly attribute in QWebSettings.

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

Definition at line 105 of file qwebframe.h.

QString QWebFrame::title [read]

the title of the frame as defined by the HTML <title> element

See also:: titleChanged()

Definition at line 107 of file qwebframe.h.

QUrl QWebFrame::url [read, write]

the url of the frame currently viewed

See also:: urlChanged()

Definition at line 108 of file qwebframe.h.

qreal QWebFrame::zoomFactor [read, write]

the zoom factor for the frame

Since:: 4.5

Definition at line 106 of file qwebframe.h.

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

QWebFrame Class Reference

Public Types

Public Slots

Signals

Public Member Functions

Properties

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

Property Documentation