CopperSpice API  1.7.2
QWebFrame Class Reference

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

Inheritance diagram for QWebFrame:
QObject

Public Types

enum  RenderLayer
 

Public Signals

void contentsSizeChanged (const QSize &size)
 
void iconChanged ()
 
void initialLayoutCompleted ()
 
void javaScriptWindowObjectCleared ()
 
void loadFinished (bool ok)
 
void loadStarted ()
 
void pageChanged ()
 
void titleChanged (const QString &title)
 
void urlChanged (const QUrl &url)
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

QVariant evaluateJavaScript (const QString &scriptSource)
 
- Public Slots inherited from QObject
void deleteLater ()
 

Public Methods

void addToJavaScriptWindowObject (const QString &name, QObject *object)
 
void addToJavaScriptWindowObject (const QString &name, QObject *object, QScriptEngine::ValueOwnership ownership)
 
QList< QWebFrame * > childFrames () const
 
QWebElement documentElement () const
 
bool event (QEvent *) override
 
QWebElementCollection findAllElements (const QString &selectorQuery) const
 
QWebElement findFirstElement (const QString &selectorQuery) const
 
QString frameName () const
 
QRect geometry () const
 
QWebHitTestResult hitTestContent (const QPoint &pos) const
 
void load (const QNetworkRequest &request, QNetworkAccessManager::Operation operation=QNetworkAccessManager::GetOperation, const QByteArray &body=QByteArray ())
 
void load (const QUrl &url)
 
QMultiMap< QString, QStringmetaData () const
 
QWebPagepage () const
 
QWebFrame * parentFrame () const
 
QPoint pos () const
 
void render (QPainter *)
 
void render (QPainter *, const QRegion &clip)
 
void render (QPainter *, RenderLayer layer, const QRegion &clip=QRegion ())
 
QString renderTreeDump () const
 
void scroll (int, int)
 
QRect scrollBarGeometry (Qt::Orientation orientation) const
 
int scrollBarMaximum (Qt::Orientation orientation) const
 
int scrollBarMinimum (Qt::Orientation orientation) const
 
Qt::ScrollBarPolicy scrollBarPolicy (Qt::Orientation orientation) const
 
int scrollBarValue (Qt::Orientation orientation) const
 
void scrollToAnchor (const QString &anchor)
 
QWebSecurityOrigin securityOrigin () const
 
void setContent (const QByteArray &data, const QString &mimeType=QString (), const QUrl &baseUrl=QUrl ())
 
void setFocus ()
 
void setHtml (const QString &html, const QUrl &baseUrl=QUrl ())
 
void setScrollBarPolicy (Qt::Orientation orientation, Qt::ScrollBarPolicy policy)
 
void setScrollBarValue (Qt::Orientation orientation, int value)
 
void setTextSizeMultiplier (qreal factor)
 
qreal textSizeMultiplier () const
 
QString toHtml () const
 
QString toPlainText () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Properties

 baseUrl
 
 contentsSize
 
 focus
 
 icon
 
 requestedUrl
 
 scrollPosition
 
 textSizeMultiplier
 
 title
 
 url
 
 zoomFactor
 
- Properties inherited from QObject
 objectName
 

Friends

class QGraphicsWebView
 
class QWebPage
 

Additional Inherited Members

- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

The QWebFrame class represents a frame in a web page.

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 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 frameCreated() signal to be notified when a new frame is created.

There are multiple ways to programmatically examine the contents of a frame. The hitTestContent() function can be used to find elements by coordinate. For access to the underlying DOM tree, there is documentElement(), findAllElements() and findFirstElement().

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 paintRequested() signal.

See also
QWebPage

Member Enumeration Documentation

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

ConstantValueDescription
QWebFrame::ContentsLayer0x10The web content of the frame
QWebFrame::ScrollBarLayer0x20The scrollbars of the frame
QWebFrame::PanIconLayer0x40The icon used when panning the frame
QWebFrame::AllLayers0xffIncludes all the above layers

Method Documentation

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.

CopperSpice properties will be exposed as JavaScript properties and slots as JavaScript methods. The interaction between C++ and JavaScript is explained in the documentation of the CsWebKit Bridge.

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

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

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.

CopperSpice properties will be exposed as JavaScript properties and slots as JavaScript methods. The interaction between C++ and JavaScript is explained in the documentation of the CsWebKit Bridge.

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.

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

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

See also
parentFrame()
void QWebFrame::contentsSizeChanged ( const QSize size)
signal

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

See also
contentsSize()
QWebElement QWebFrame::documentElement ( ) const

Returns the document element of this frame.

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

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()
bool QWebFrame::event ( QEvent event)
overridevirtual

Reimplemented from QObject::event().

Reimplemented from QObject.

QWebElementCollection QWebFrame::findAllElements ( const QString selectorQuery) const

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

Standard CSS2 selector syntax is used for the query.

See also
QWebElement::findAll()
QWebElement QWebFrame::findFirstElement ( const QString selectorQuery) const

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.

Standard CSS2 selector syntax is used for the query.

See also
QWebElement::findFirst()
QString QWebFrame::frameName ( ) const

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

QRect QWebFrame::geometry ( ) const

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

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.

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 content.
See also
setUrl()
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()
void QWebFrame::loadFinished ( bool  ok)
signal

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

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

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 CopperSpice development">
<meta name="keywords" content="CopperSpice, WebKit, Programming">
</head>
...
</html>

Given the above HTML code the metaData() function will return a map with two entries:

KeyValue
"description""This document is a tutorial about CopperSpice development"
"keywords""CopperSpice, WebKit, Programming"

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

QWebPage * QWebFrame::page ( ) const

The web page that contains this frame.

See also
pageChanged()
void QWebFrame::pageChanged ( )
signal

This signal is emitted when this frame has been moved to a different QWebPage.

See also
page()
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()
QPoint QWebFrame::pos ( ) const

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

void QWebFrame::render ( QPainter painter)

Render the frame into painter.

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

Render the frame into painter clipping to clip.

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

Render the layer of the frame using painter clipping to clip.

See also
print()
QString QWebFrame::renderTreeDump ( ) const

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

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

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

See also
QWebFrame::scrollPosition
QRect QWebFrame::scrollBarGeometry ( Qt::Orientation  orientation) const

Returns the geometry for the scrollbar with orientation orientation.

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

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()
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()
Qt::ScrollBarPolicy QWebFrame::scrollBarPolicy ( Qt::Orientation  orientation) const

Returns the scrollbar policy for the scrollbar defined by orientation.

See also
setScrollBarPolicy()
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
setScrollBarValue(), scrollBarMinimum(), scrollBarMaximum()
void QWebFrame::scrollToAnchor ( const QString anchor)

Scrolls the frame to the given anchor name.

QWebSecurityOrigin QWebFrame::securityOrigin ( ) const

Returns the frame's security origin.

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 assumed the content is HTML.

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()
void QWebFrame::setFocus ( )

Gives keyboard input focus to this frame.

See also
hasFocus()
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.

If a script in the html runs longer than the default script timeout (currently 10 seconds), for example due to being blocked by a modal JavaScript alert dialog, this method will return as soon as possible after the timeout and any subsequent html will be 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.

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

Note
This method will not affect session or global history for the frame.
Warning
This function works only for HTML, for other mime types (i.e. XHTML, SVG) setContent() should be used instead.
See also
toHtml(), setContent(), load()
void QWebFrame::setScrollBarPolicy ( Qt::Orientation  orientation,
Qt::ScrollBarPolicy  policy 
)

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

See also
scrollBarPolicy()
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
scrollBarValue(), scrollBarMinimum(), scrollBarMaximum()
void QWebFrame::setTextSizeMultiplier ( qreal  factor)

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

See also
textSizeMultiplier()
qreal QWebFrame::textSizeMultiplier ( ) const

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

See also
setTextSizeMultiplier()
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()
QString QWebFrame::toPlainText ( ) const

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

See also
toHtml()
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()

Property Documentation

QWebFrame::baseUrl

This property holds the base URL of the frame, can be used to resolve relative URLs.

PropertiesClass Methods
read baseUrl
QWebFrame::contentsSize

This property holds the size of the contents in this frame.

See also
contentsSizeChanged()
PropertiesClass Methods
read contentsSize
QWebFrame::focus

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

PropertiesClass Methods
read hasFocus
QWebFrame::icon

This property holds the icon associated with this frame.

See also
iconChanged(), QWebSettings::iconForUrl()
PropertiesClass Methods
read icon
QWebFrame::requestedUrl

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()
PropertiesClass Methods
read requestedUrl
QWebFrame::scrollPosition

This property holds the position the frame is currently scrolled to.

PropertiesClass Methods
read scrollPosition
write setScrollPosition
QWebFrame::textSizeMultiplier
deprecated
Deprecated:
This property holds 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.
PropertiesClass Methods
read textSizeMultiplier
write setTextSizeMultiplier
designable true
QWebFrame::title

This property holds the title of the frame as defined by the HTML <title> element.

See also
titleChanged()
PropertiesClass Methods
read title
QWebFrame::url

This property holds the url of the frame currently viewed.

Setting this property clears the view and loads the URL.

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

See also
urlChanged()
PropertiesClass Methods
read url
write setUrl
QWebFrame::zoomFactor

This property holds the zoom factor for the frame.

PropertiesClass Methods
read zoomFactor
write setZoomFactor