QWebElement Class Reference

#include <mw/QtWebKit/qwebelement.h>

class QWebElement

The QWebElement class provides convenient access to DOM elements in a QWebFrame. QtWebKit.

Public Member Enumerations
enum	StyleResolveStrategy { InlineStyle, CascadedStyle, ComputedStyle }

Public Member Functions
	QWebElement()
	QWebElement(const QWebElement &)
	~QWebElement()
void	addClass(const QString &)
void	appendInside(const QString &)
void	appendInside(const QWebElement &)
void	appendOutside(const QString &)
void	appendOutside(const QWebElement &)
QString	attribute(const QString &, const QString &)
QString	attributeNS(const QString &, const QString &, const QString &)
QStringList	attributeNames(const QString &)
QStringList	classes()
QWebElement	clone()
QWebElement	document()
void	encloseContentsWith(const QWebElement &)
void	encloseContentsWith(const QString &)
void	encloseWith(const QString &)
void	encloseWith(const QWebElement &)
QVariant	evaluateJavaScript(const QString &)
QWebElementCollection	findAll(const QString &)
QWebElement	findFirst(const QString &)
QWebElement	firstChild()
QRect	geometry()
bool	hasAttribute(const QString &)
bool	hasAttributeNS(const QString &, const QString &)
bool	hasAttributes()
bool	hasClass(const QString &)
bool	hasFocus()
bool	isNull()
QWebElement	lastChild()
QString	localName()
QString	namespaceUri()
QWebElement	nextSibling()
bool	operator!=(const QWebElement &)
QWebElement &	operator=(const QWebElement &)
bool	operator==(const QWebElement &)
QWebElement	parent()
QString	prefix()
void	prependInside(const QString &)
void	prependInside(const QWebElement &)
void	prependOutside(const QString &)
void	prependOutside(const QWebElement &)
QWebElement	previousSibling()
void	removeAllChildren()
void	removeAttribute(const QString &)
void	removeAttributeNS(const QString &, const QString &)
void	removeClass(const QString &)
void	removeFromDocument()
void	render(QPainter *)
void	replace(const QString &)
void	replace(const QWebElement &)
void	setAttribute(const QString &, const QString &)
void	setAttributeNS(const QString &, const QString &, const QString &)
void	setFocus()
void	setInnerXml(const QString &)
void	setOuterXml(const QString &)
void	setPlainText(const QString &)
void	setStyleProperty(const QString &, const QString &)
QString	styleProperty(const QString &, StyleResolveStrategy)
QString	tagName()
QWebElement &	takeFromDocument()
QString	toInnerXml()
QString	toOuterXml()
QString	toPlainText()
void	toggleClass(const QString &)
QWebFrame *	webFrame()

Detailed Description

Since: 4.6 A QWebElement object allows easy access to the document model, represented by a tree-like structure of DOM elements. The root of the tree is called the document element and can be accessed using QWebFrame::documentElement().

Specific elements can be accessed using findAll() and findFirst(). These elements are identified using CSS selectors. The code snippet below demonstrates the use of findAll().

The first list contains all span elements in the document. The second list contains span elements that are children of p, classified with intro.

Using findFirst() is more efficient than calling findAll(), and extracting the first element only in the list returned.

Alternatively you can traverse the document manually using firstChild() and nextSibling():

Individual elements can be inspected or changed using methods such as attribute() or setAttribute(). For examle, to capture the user's input in a text field for later use (auto-completion), a browser could do something like this:

When the same page is later revisited, the browser can fill in the text field automatically by modifying the value attribute of the input element:

Another use case is to emulate a click event on an element. The following code snippet demonstrates how to call the JavaScript DOM method click() of a submit button:

The underlying content of QWebElement is explicitly shared. Creating a copy of a QWebElement does not create a copy of the content. Instead, both instances point to the same element.

The contents of child elements can be converted to plain text with toPlainText(); to XHTML using toInnerXml(). To include the element's tag in the output, use toOuterXml().

It is possible to replace the contents of child elements using setPlainText() and setInnerXml(). To replace the element itself and its contents, use setOuterXml().

Member Enumeration Documentation

Enum StyleResolveStrategy

This enum describes how QWebElement's styleProperty resolves the given property name.

InlineStyle Return the property value as it is defined in the element, without respecting style inheritance and other CSS rules. CascadedStyle The property's value is determined using the inheritance and importance rules defined in the document's stylesheet. ComputedStyle The property's value is the absolute value of the style property resolved from the environment.

Enumerator	Value	Description
InlineStyle
CascadedStyle
ComputedStyle

Constructor & Destructor Documentation

QWebElement ( )

QWebElement

(

)

Constructs a null web element.

QWebElement ( const QWebElement & )

QWebElement

(

const QWebElement &

)

Constructs a copy of other.

~QWebElement ( )

~QWebElement

(

)

Destroys the element. However, the underlying DOM element is not destroyed.

Member Function Documentation

addClass ( const QString & )

void

addClass

(

const QString &

name

)

Adds the specified class with the given name to the element.

appendInside ( const QString & )

void

appendInside

(

const QString &

markup

)

Appends the result of parsing markup as the element's last child.

Calling this function on a null element does nothing.

appendInside ( const QWebElement & )

void

appendInside

(

const QWebElement &

element

)

Appends the given element as the element's last child.

If element is the child of another element, it is re-parented to this element. If element is a child of this element, then its position in the list of children is changed.

Calling this function on a null element does nothing.

appendOutside ( const QString & )

void

appendOutside

(

const QString &

markup

)

Inserts the result of parsing markup after this element.

Calling this function on a null element does nothing.

appendOutside ( const QWebElement & )

void

appendOutside

(

const QWebElement &

element

)

Inserts the given element after this element.

If element is the child of another element, it is re-parented to the parent of this element.

Calling this function on a null element does nothing.

attribute ( const QString &, const QString & )

QString	attribute	(	const QString &	name,
			const QString &	defaultValue = QString()
		)	const

Returns the attribute with the given name. If the attribute does not exist, defaultValue is returned.

attributeNS ( const QString &, const QString &, const QString & )

QString	attributeNS	(	const QString &	namespaceUri,
			const QString &	name,
			const QString &	defaultValue = QString()
		)	const

Returns the attribute with the given name in namespaceUri. If the attribute does not exist, defaultValue is returned.

attributeNames ( const QString & )

QStringList

attributeNames

(

const QString &

namespaceUri = QString()

)

const

Return the list of attributes for the namespace given as namespaceUri.

classes ( )

QStringList

classes

(

)

const

Returns the list of classes of this element.

clone ( )

QWebElement

clone

(

)

const

Returns a clone of this element.

The clone may be inserted at any point in the document.

document ( )

QWebElement

document

(

)

const

Returns the document which this element belongs to.

encloseContentsWith ( const QWebElement & )

void

encloseContentsWith

(

const QWebElement &

element

)

Encloses the contents of this element with element. This element becomes the child of the deepest descendant within element.

### illustration

See also: encloseWith()

encloseContentsWith ( const QString & )

void

encloseContentsWith

(

const QString &

markup

)

Encloses the contents of this element with the result of parsing markup. This element becomes the child of the deepest descendant within markup.

See also: encloseWith()

encloseWith ( const QString & )

void

encloseWith

(

const QString &

markup

)

Encloses this element with the result of parsing markup. This element becomes the child of the deepest descendant within markup.

encloseWith ( const QWebElement & )

void

encloseWith

(

const QWebElement &

element

)

Encloses this element with element. This element becomes the child of the deepest descendant within element.

evaluateJavaScript ( const QString & )

QVariant

evaluateJavaScript

(

const QString &

scriptSource

)

Executes scriptSource with this element as this object.

findAll ( const QString & )

QWebElementCollection

findAll

(

const QString &

selectorQuery

)

const

Returns a new list of child 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.

Note:

This search is performed recursively.

findFirst ( const QString & )

QWebElement

findFirst

(

const QString &

selectorQuery

)

const

Returns the first child element that matches the given CSS selector selectorQuery.

{Standard CSS2 selector} syntax is used for the query.

Note:

This search is performed recursively.

firstChild ( )

QWebElement

firstChild

(

)

const

Returns the element's first child.

geometry ( )

QRect

geometry

(

)

const

Returns the geometry of this element, relative to its containing frame.

hasAttribute ( const QString & )

bool

hasAttribute

(

const QString &

name

)

const

Returns true if this element has an attribute with the given name; otherwise returns false.

hasAttributeNS ( const QString &, const QString & )

bool	hasAttributeNS	(	const QString &	namespaceUri,
			const QString &	name
		)	const

Returns true if this element has an attribute with the given name, in namespaceUri; otherwise returns false.

hasAttributes ( )

bool

hasAttributes

(

)

const

Returns true if the element has any attributes defined; otherwise returns false;

hasClass ( const QString & )

bool

hasClass

(

const QString &

name

)

const

Returns true if this element has a class with the given name; otherwise returns false.

hasFocus ( )

bool

hasFocus

(

)

const

Returns true if the element has keyboard input focus; otherwise, returns false

isNull ( )

bool

isNull

(

)

const

Returns true if the element is a null element; otherwise returns false.

lastChild ( )

QWebElement

lastChild

(

)

const

Returns the element's last child.

localName ( )

QString

localName

(

)

const

Returns the local name of the element. If the element does not use namespaces, an empty string is returned.

namespaceUri ( )

QString

namespaceUri

(

)

const

Returns the namespace URI of this element. If the element has no namespace URI, an empty string is returned.

nextSibling ( )

QWebElement

nextSibling

(

)

const

Returns the element's next sibling.

operator!= ( const QWebElement & )

bool

operator!=

(

const QWebElement &

)

const [inline]

Returns true if this element points to a different underlying DOM object than o; otherwise returns false.

operator= ( const QWebElement & )

QWebElement &

operator=

(

const QWebElement &

)

Assigns other to this element and returns a reference to this element.

operator== ( const QWebElement & )

bool

operator==

(

const QWebElement &

)

const [inline]

Returns true if this element points to the same underlying DOM object as o; otherwise returns false.

parent ( )

QWebElement

parent

(

)

const

Returns the parent element of this elemen. If this element is the root document element, a null element is returned.

prefix ( )

QString

prefix

(

)

const

Returns the namespace prefix of the element. If the element has no\ namespace prefix, empty string is returned.

prependInside ( const QString & )

void

prependInside

(

const QString &

markup

)

Prepends the result of parsing markup as the element's first child.

Calling this function on a null element does nothing.

prependInside ( const QWebElement & )

void

prependInside

(

const QWebElement &

element

)

Prepends element as the element's first child.

If element is the child of another element, it is re-parented to this element. If element is a child of this element, then its position in the list of children is changed.

Calling this function on a null element does nothing.

prependOutside ( const QString & )

void

prependOutside

(

const QString &

markup

)

Inserts the result of parsing markup before this element.

Calling this function on a null element does nothing.

prependOutside ( const QWebElement & )

void

prependOutside

(

const QWebElement &

element

)

Inserts the given element before this element.

If element is the child of another element, it is re-parented to the parent of this element.

Calling this function on a null element does nothing.

previousSibling ( )

QWebElement

previousSibling

(

)

const

Returns the element's previous sibling.

removeAllChildren ( )

void

removeAllChildren

(

)

Removes all children from this element.

removeAttribute ( const QString & )

void

removeAttribute

(

const QString &

name

)

Removes the attribute with the given name from this element.

removeAttributeNS ( const QString &, const QString & )

void	removeAttributeNS	(	const QString &	namespaceUri,
			const QString &	name
		)

Removes the attribute with the given name, in namespaceUri, from this element.

removeClass ( const QString & )

void

removeClass

(

const QString &

name

)

Removes the specified class with the given name from the element.

removeFromDocument ( )

void

removeFromDocument

(

)

Removes this element from the document and makes it a null element.

render ( QPainter * )

void

render

(

QPainter *

painter

)

Render the element into painter .

replace ( const QString & )

void

replace

(

const QString &

markup

)

Replaces this element with the result of parsing markup.

This method will not replace the <html>, <head> or <body> elements.

See also: encloseWith()

replace ( const QWebElement & )

void

replace

(

const QWebElement &

element

)

Replaces this element with element.

This method will not replace the <html>, <head> or <body> elements.

See also: encloseWith()

setAttribute ( const QString &, const QString & )

void	setAttribute	(	const QString &	name,
			const QString &	value
		)

Adds an attribute with the given name and value. If an attribute with the same name exists, its value is replaced by value.

setAttributeNS ( const QString &, const QString &, const QString & )

void	setAttributeNS	(	const QString &	namespaceUri,
			const QString &	name,
			const QString &	value
		)

Adds an attribute with the given name in namespaceUri with value. If an attribute with the same name exists, its value is replaced by value.

setFocus ( )

void

setFocus

(

)

Gives keyboard input focus to this element

setInnerXml ( const QString & )

void

setInnerXml

(

const QString &

markup

)

Replaces the contents of this element with markup. The string may contain HTML or XML tags, which is parsed and formatted before insertion into the document.

Note:

This is currently implemented for (X)HTML elements only.

setOuterXml ( const QString & )

void

setOuterXml

(

const QString &

markup

)

Replaces the contents of this element as well as its own tag with markup. The string may contain HTML or XML tags, which is parsed and formatted before insertion into the document.

Note:

This is currently only implemented for (X)HTML elements.

setPlainText ( const QString & )

void

setPlainText

(

const QString &

text

)

Replaces the existing content of this element with text.

This is equivalent to setting the HTML innerText property.

setStyleProperty ( const QString &, const QString & )

void	setStyleProperty	(	const QString &	name,
			const QString &	value
		)

Sets the value of the inline style with the given name to value.

Setting a value, does not necessarily mean that it will become the applied value, due to the fact that the style property's value might have been set earlier with a higher priority in external or embedded style declarations.

In order to ensure that the value will be applied, you may have to append "!important" to the value.

styleProperty ( const QString &, StyleResolveStrategy )

QString	styleProperty	(	const QString &	name,
			StyleResolveStrategy	strategy
		)	const

Returns the value of the style with the given name using the specified strategy. If a style with name does not exist, an empty string is returned.

In CSS, the cascading part depends on which CSS rule has priority and is thus applied. Generally, the last defined rule has priority. Thus, an inline style rule has priority over an embedded block style rule, which in return has priority over an external style rule.

If the "!important" declaration is set on one of those, the declaration receives highest priority, unless other declarations also use the "!important" declaration. Then, the last "!important" declaration takes predecence.

tagName ( )

QString

tagName

(

)

const

Returns the tag name of this element.

takeFromDocument ( )

QWebElement &

takeFromDocument

(

)

Removes this element from the document and returns a reference to it.

The element is still valid after removal, and can be inserted into other parts of the document.

toInnerXml ( )

QString

toInnerXml

(

)

const

Returns the XML content between the element's start and end tags.

Note:

This is currently implemented for (X)HTML elements only.

toOuterXml ( )

QString

toOuterXml

(

)

const

Returns this element converted to XML, including the start and the end tags as well as its attributes.

Note:

This is currently implemented for (X)HTML elements only.

toPlainText ( )

QString

toPlainText

(

)

const

Returns the text between the start and the end tag of this element.

This is equivalent to reading the HTML innerText property.

toggleClass ( const QString & )

void

toggleClass

(

const QString &

name

)

Adds the specified class with the given name if it is not present. If the class is already present, it will be removed.

webFrame ( )

QWebFrame *

webFrame

(

)

const

Returns the web frame which this element is a part of. If the element is a null element, null is returned.