CopperSpice API  1.7.2
QWebElement Class Reference

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

Public Types

enum  StyleResolveStrategy
 

Public Methods

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

Friends

class QWebElementCollection
 
class QWebFrame
 
class QWebHitTestResult
 
class QWebPage
 

Detailed Description

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

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

/* Assume the document has the following structure:
<p class=intro>
<span>Intro</span>
<span>Snippets</span>
</p>
<p>
<span>Content</span>
<span>Here</span>
</p>
*/
QWebElementCollection introSpans = document.findAll("p.intro span");

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():

frame->setHtml("<html><body><p>First Paragraph</p><p>Second Paragraph</p></body></html>");
QWebElement body = doc.firstChild();
QWebElement firstParagraph = body.firstChild();
QWebElement secondParagraph = firstParagraph.nextSibling();

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

QWebElement firstTextInput = document.findFirst("input[type=text]");
QString storedText = firstTextInput.attribute("value");

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:

QWebElement firstTextInput = document.findFirst("input[type=text]");
textInput.setAttribute("value", storedText);

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:

/* Assume that the document has the following structure:
<form name="myform" action="submit_form.asp" method="get">
<input type="text" name="myfield">
<input type="submit" value="Submit">
</form>
*/
QWebElement button = document.findFirst("input[type=submit]");
button.evaluateJavaScript("this.click()");

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

See also
prependInside(), prependOutside(), appendOutside()

Member Enumeration Documentation

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

ConstantValueDescription
QWebElement::InlineStyle0Return the property value as it is defined in the element, without respecting style inheritance and other CSS rules.
QWebElement::CascadedStyle1The property's value is determined using the inheritance and importance rules defined in the document's stylesheet.
QWebElement::ComputedStyle2The property's value is the absolute value of the style property resolved from the environment.

Constructor & Destructor Documentation

QWebElement::QWebElement ( )

Constructs a null web element.

QWebElement::QWebElement ( const QWebElement &  other)

Constructs a copy of other.

QWebElement::~QWebElement ( )

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

Method Documentation

void QWebElement::addClass ( const QString name)

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

void QWebElement::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.

See also
prependInside(), prependOutside(), appendOutside()
void QWebElement::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.

See also
prependInside(), prependOutside(), appendOutside()
void QWebElement::appendOutside ( const QString markup)

Inserts the result of parsing markup after this element.

Calling this function on a null element does nothing.

See also
appendInside(), prependInside(), prependOutside()
void QWebElement::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.

See also
appendInside(), prependInside(), prependOutside()
QString QWebElement::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.

See also
setAttribute(), setAttributeNS(), attributeNS()
QStringList QWebElement::attributeNames ( const QString namespaceUri = QString()) const

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

See also
attribute(), setAttribute()
QString QWebElement::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.

See also
setAttributeNS(), setAttribute(), attribute()
QStringList QWebElement::classes ( ) const

Returns the list of classes of this element.

QWebElement QWebElement::clone ( ) const

Returns a clone of this element.

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

See also
appendInside(), prependInside(), prependOutside(), appendOutside()
QWebElement QWebElement::document ( ) const

Returns the document which this element belongs to.

void QWebElement::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()
void QWebElement::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()
void QWebElement::encloseWith ( const QString markup)

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

See also
replace()
void QWebElement::encloseWith ( const QWebElement &  element)

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

See also
replace()
QVariant QWebElement::evaluateJavaScript ( const QString scriptSource)

Executes scriptSource with this element as this object.

QWebElementCollection QWebElement::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.
See also
findFirst()
QWebElement 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.
See also
findAll()
QWebElement QWebElement::firstChild ( ) const

Returns the element's first child.

See also
lastChild(), previousSibling(), nextSibling()
QRect QWebElement::geometry ( ) const

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

See also
tagName()
bool QWebElement::hasAttribute ( const QString name) const

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

See also
attribute(), setAttribute()
bool QWebElement::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.

See also
attributeNS(), setAttributeNS()
bool QWebElement::hasAttributes ( ) const

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

See also
attribute(), setAttribute()
bool QWebElement::hasClass ( const QString name) const

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

bool QWebElement::hasFocus ( ) const

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

See also
setFocus()
bool QWebElement::isNull ( ) const

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

QWebElement QWebElement::lastChild ( ) const

Returns the element's last child.

See also
firstChild(), previousSibling(), nextSibling()
QString QWebElement::localName ( ) const

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

QString QWebElement::namespaceUri ( ) const

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

QWebElement QWebElement::nextSibling ( ) const

Returns the element's next sibling.

See also
firstChild(), previousSibling(), lastChild()
bool QWebElement::operator!= ( const QWebElement &  o) const

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

QWebElement & QWebElement::operator= ( const QWebElement &  other)

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

bool QWebElement::operator== ( const QWebElement &  o) const

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

QWebElement QWebElement::parent ( ) const

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

QString QWebElement::prefix ( ) const

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

void QWebElement::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.

See also
appendInside(), prependOutside(), appendOutside()
void QWebElement::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.

See also
appendInside(), prependOutside(), appendOutside()
void QWebElement::prependOutside ( const QString markup)

Inserts the result of parsing markup before this element. Calling this function on a null element does nothing.

See also
appendInside(), prependInside(), appendOutside()
void QWebElement::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.

See also
appendInside(), prependInside(), appendOutside()
QWebElement QWebElement::previousSibling ( ) const

Returns the element's previous sibling.

See also
firstChild(), nextSibling(), lastChild()
void QWebElement::removeAllChildren ( )

Removes all children from this element.

See also
removeFromDocument(), takeFromDocument()
void QWebElement::removeAttribute ( const QString name)

Removes the attribute with the given name from this element.

See also
attribute(), setAttribute(), hasAttribute()
void QWebElement::removeAttributeNS ( const QString namespaceUri,
const QString name 
)

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

See also
attributeNS(), setAttributeNS(), hasAttributeNS()
void QWebElement::removeClass ( const QString name)

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

void QWebElement::removeFromDocument ( )

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

See also
removeAllChildren(), takeFromDocument()
void QWebElement::render ( QPainter painter)

Render the element into painter .

void QWebElement::render ( QPainter painter,
const QRect clip 
)

Render the element into painter clipping to clip.

void QWebElement::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()
void QWebElement::replace ( const QWebElement &  element)

Replaces this element with element.

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

See also
encloseWith()
void QWebElement::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.

See also
attribute(), attributeNS(), setAttributeNS()
void QWebElement::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.

See also
attributeNS(), attribute(), setAttribute()
void QWebElement::setFocus ( )

Gives keyboard input focus to this element

See also
hasFocus()
void QWebElement::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.
See also
toInnerXml(), toOuterXml(), setOuterXml()
void QWebElement::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.
See also
toOuterXml(), toInnerXml(), setInnerXml()
void QWebElement::setPlainText ( const QString text)

Replaces the existing content of this element with text.

This is equivalent to setting the HTML innerText property.

See also
toPlainText()
void QWebElement::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.

See also
styleProperty()
QString QWebElement::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 precedence.

See also
setStyleProperty()
QString QWebElement::tagName ( ) const

Returns the tag name of this element.

See also
geometry()
QWebElement & 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.

See also
removeAllChildren(), removeFromDocument()
void QWebElement::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.

QString QWebElement::toInnerXml ( ) const

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

Note
This is currently implemented for (X)HTML elements only.
The format of the markup returned will obey the namespace of the document containing the element. This means the return value will obey XML formatting rules, such as self-closing tags, only if the document is 'text/xhtml+xml'.
See also
setInnerXml(), setOuterXml(), toOuterXml()
QString QWebElement::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.
The format of the markup returned will obey the namespace of the document containing the element. This means the return value will obey XML formatting rules, such as self-closing tags, only if the document is 'text/xhtml+xml'.
See also
setOuterXml(), setInnerXml(), toInnerXml()
QString QWebElement::toPlainText ( ) const

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

This is equivalent to reading the HTML innerText property.

See also
setPlainText()
QWebFrame * QWebElement::webFrame ( ) const

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