Home · All Classes · Overviews

QWebElement Class Reference
[QtWebKit module]

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

 #include <QWebElement>

This class was introduced in Qt 4.6.

Public Types

enum ResolveRule { IgnoreCascadingStyles, RespectCascadingStyles }
enum StylePriority { NormalStylePriority, DeclaredStylePriority, ImportantStylePriority }

Public Functions

QWebElement ()
QWebElement ( const QWebElement & other )
~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
QString attributeNS ( const QString & namespaceUri, const QString & name, const QString & defaultValue = QString() ) const
QVariant callFunction ( const QString & name, const QVariantList & arguments = QVariantList() )
QStringList classes () const
QWebElement clone () const
QString computedStyleProperty ( const QString & name ) const
QWebElement document () const
void encloseContentsWith ( const QWebElement & element )
void encloseContentsWith ( const QString & markup )
void encloseWith ( const QString & markup )
void encloseWith ( const QWebElement & element )
QVariant evaluateScript ( const QString & scriptSource )
QList<QWebElement> findAll ( const QString & selectorQuery ) const
QWebElement findFirst ( const QString & selectorQuery ) const
QWebElement firstChild () const
QStringList functions () 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 isNull () const
QWebElement lastChild () const
QString localName () const
QString namespaceUri () const
QWebElement nextSibling () 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 removeAttribute ( const QString & name )
void removeAttributeNS ( const QString & namespaceUri, const QString & name )
void removeChildren ()
void removeClass ( const QString & name )
void removeFromDocument ()
void replace ( const QString & markup )
void replace ( const QWebElement & element )
QStringList scriptableProperties () const
QVariant scriptableProperty ( const QString & name ) const
void setAttribute ( const QString & name, const QString & value )
void setAttributeNS ( const QString & namespaceUri, const QString & name, const QString & value )
void setInnerXml ( const QString & markup )
void setOuterXml ( const QString & markup )
void setPlainText ( const QString & text )
void setScriptableProperty ( const QString & name, const QVariant & value )
void setStyleProperty ( const QString & name, const QString & value, StylePriority priority = DeclaredStylePriority )
QString styleProperty ( const QString & name, ResolveRule rule = IgnoreCascadingStyles ) const
QString tagName () const
QWebElement & takeFromDocument ()
QString toInnerXml () const
QString toOuterXml () const
QString toPlainText () const
void toggleClass ( const QString & name )
QWebFrame * webFrame () const
bool operator!= ( const QWebElement & o ) const
QWebElement & operator= ( const QWebElement & other )
bool operator== ( const QWebElement & o ) const

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

     QWebElement document = frame->documentElement();
     /* 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>
     */

     QList<QWebElement> allSpans = document.findAll("span");
     QList<QWebElement> 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 doc = frame->documentElement();
     QWebElement body = doc.firstChild();
     QWebElement firstParagraph = body.firstChild();
     QWebElement secondParagraph = firstParagraph.nextSibling();

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 element's attributes can be read using attribute() and modified with setAttribute().

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

In the JavaScript DOM interfaces, elements can have additional functions depending on their type. For example, an HTML form element can be triggered to submit the entire form to the web server using the submit() function. A list of these special functions can be obtained in QWebElement using functions(); they can be invoked using callFunction().

Similarly, element specific properties can be obtained using scriptableProperties() and read or written using scriptableProperty() or setScriptableProperty().

Member Type Documentation

enum QWebElement::ResolveRule

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

ConstantValueDescription
QWebElement::IgnoreCascadingStyles0Return the property value as it is defined in the element, without respecting style inheritance and other CSS rules.
QWebElement::RespectCascadingStyles1The property's value is determined using the inheritance and importance rules defined in the document's stylesheet.

This enum was introduced in Qt 4.6.

enum QWebElement::StylePriority

This enum describes the priority newly set CSS properties should have when set using QWebElement::setStyleProperty().

ConstantValueDescription
QWebElement::NormalStylePriority0Define the property without important priority even if "!important" is explicitly set in value.
QWebElement::DeclaredStylePriority1Define the property respecting the priority specified in value.
QWebElement::ImportantStylePriority2Define the property to have an important priority. This is equal to appending "!important" to the value.

This enum was introduced in Qt 4.6.

Member Function 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.

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(), and 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(), and 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(), and 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(), and 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(), and attributeNS().

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(), and attribute().

QVariant QWebElement::callFunction ( const QString & name, const QVariantList & arguments = QVariantList() )

Calls the function with the given name and arguments.

The underlying DOM element that QWebElement wraps may have dedicated functions, depending on its type. For example, a form element can have the submit function, that would submit the form to the destination specified in the HTML.

See also functions().

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(), and appendOutside().

QString QWebElement::computedStyleProperty ( const QString & name ) const

Returns the computed value for style with the given name. If a style with name does not exist, an empty string is returned.

QWebElement QWebElement::document () const

Returns the document which this element belongs to.

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::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::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::evaluateScript ( const QString & scriptSource )

Executes scriptSource with this element as this object.

See also callFunction().

QList<QWebElement> 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(), and nextSibling().

QStringList QWebElement::functions () const

Returns a list of function names this element supports.

The function names returned are the same functions callable from the DOM element's JavaScript binding.

See also callFunction().

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

bool QWebElement::hasAttributes () const

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

See also attribute() and 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::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(), and 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(), and lastChild().

QWebElement QWebElement::parent () const

Returns the parent element of this elemen. 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(), and 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(), and 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(), and 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(), and appendOutside().

QWebElement QWebElement::previousSibling () const

Returns the element's previous sibling.

See also firstChild(), nextSibling(), and lastChild().

void QWebElement::removeAttribute ( const QString & name )

Removes the attribute with the given name from this element.

See also attribute(), setAttribute(), and 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(), and hasAttributeNS().

void QWebElement::removeChildren ()

Removes all children from this element.

See also removeFromDocument() and takeFromDocument().

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 removeChildren() and takeFromDocument().

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

QStringList QWebElement::scriptableProperties () const

Returns a list of property names this element supports.

The function names returned are the same properties that are accessible from the DOM element's JavaScript binding.

See also setScriptableProperty() and scriptableProperty().

QVariant QWebElement::scriptableProperty ( const QString & name ) const

Returns the value of the element's name property. If no such property exists, an invalid QVariant is returned.

The return value's property has the same value as the corresponding property in the element's JavaScript binding with the same name.

Information about all available properties is provided through scriptProperties().

See also setScriptableProperty() and scriptableProperties().

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(), and 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(), and setAttribute().

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(), and 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(), and 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::setScriptableProperty ( const QString & name, const QVariant & value )

Sets the value of the element's name property to value.

Information about all available properties is provided through scriptProperties().

Setting the property will affect the corresponding property in the element's JavaScript binding with the same name.

See also scriptableProperty() and scriptableProperties().

void QWebElement::setStyleProperty ( const QString & name, const QString & value, StylePriority priority = DeclaredStylePriority )

Sets the value of the 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 priority in external or embedded style declarations.

In order to ensure that the value will be applied, ImportantStylePriority should be used as priority.

Following the CSS syntax for property values, this is equal to appending "!important" to the value.

This syntax is supported when using DeclaredStylePriority as priority.

Using NormalStylePriority as priority, the property will have normal priority, and any "!important" declaration will be ignored. On the other hand, using ImportantStylePriority sets the important priority even when it is not explicitly passed in value.

By using DeclaredStylePriority as priority the property will respect the priority specified in value.

See also styleProperty().

QString QWebElement::styleProperty ( const QString & name, ResolveRule rule = IgnoreCascadingStyles ) const

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

If rule is IgnoreCascadingStyles, the value defined inside the element (inline in CSS terminology) is returned.

if rule is RespectCascadingStyles, the actual style applied to the element 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.

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 removeChildren() and removeFromDocument().

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.

See also setInnerXml(), setOuterXml(), and 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.

See also setOuterXml(), setInnerXml(), and 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().

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.

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.

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.

Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt 4.6.0-tp1