Commit 7fd25f4a authored by hausmann@webkit.org's avatar hausmann@webkit.org

2009-05-05 Simon Hausmann <simon.hausmann@nokia.com>

        Reviewed by Tor Arne Vestbø.

        Various improvements to the class documentation, including a simple snippet for QWebElement.

git-svn-id: http://svn.webkit.org/repository/webkit/trunk@43236 268f45cc-cd09-0410-ab3c-d52691b4dbfc
parent 1d5cb99b
......@@ -52,9 +52,25 @@ public:
\brief The QWebElement class provides convenience access to DOM elements in a QWebFrame.
\preliminary
QWebElement is the main class to provide easy access to the tree structure of DOM elements.
The underlying data is explicitly shared. Creating a copy of a QWebElement object does not
create a copy of the underlying element, both instances point to the same element.
QWebElement is the main class to provide easy access to the document model.
The document model is 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().
You can reach specific elements by using the findAll() and findFirst() functions, which
allow the use of CSS selectors to identify elements.
\snippet webkitsnippets/webelement/main.cpp FindAll
The first list contains all span elements in the document. The second list contains
only the span elements that are children of the paragraph that is classified
as "intro" paragraph.
Alternatively you can manually traverse the document using firstChild() and nextSibling():
\snippet webkitsnippets/webelement/main.cpp Traversing with QWebElement
The underlying content of QWebElement is explicitly shared. Creating a copy of a QWebElement
does not create a copy of the content, both instances point to the same underlying element.
The element's attributes can be read using attribute() and changed using setAttribute().
......@@ -143,6 +159,8 @@ bool QWebElement::isNull() const
/*!
Returns a new collection of elements that are children of this element
and that match the given CSS selector \a selectorQuery.
The query is specified using \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{standard CSS2 selectors}.
*/
QList<QWebElement> QWebElement::findAll(const QString &selectorQuery) const
{
......@@ -425,7 +443,8 @@ QString QWebElement::namespaceUri() const
}
/*!
Returns the parent element of this element.
Returns the parent element of this element or a null element if this element
is the root document element.
*/
QWebElement QWebElement::parent() const
{
......@@ -1216,6 +1235,10 @@ void QWebElement::removeChildren()
m_element->removeAllChildren();
}
/*!
Makes the children of this element children of \a element,
and then makes \a element the only child of this element.
*/
void QWebElement::encloseContentsWith(const QWebElement &element)
{
if (!m_element || element.isNull())
......@@ -1231,6 +1254,11 @@ void QWebElement::encloseContentsWith(const QWebElement &element)
appendInside(other);
}
/*!
Parses the \a markup and makes the children of this element
children of the parsed markup. Afterwards the element parsed
from the markup becomes the only child of this element.
*/
void QWebElement::encloseContentsWith(const QString &markup)
{
if (!m_element)
......
......@@ -986,6 +986,8 @@ QWebElement QWebFrame::documentElement() const
\since 4.6
Returns a new collection of elements that are children of the frame's
document element and that match the given CSS selector \a selectorQuery.
\sa QWebElement::findAll()
*/
QList<QWebElement> QWebFrame::findAllElements(const QString &selectorQuery) const
{
......@@ -997,6 +999,8 @@ QList<QWebElement> QWebFrame::findAllElements(const QString &selectorQuery) cons
Returns the first element in the frame's document that matches the
given CSS selector \a selectorQuery. Returns a null element if there is no
match.
\sa QWebElement::findFirst()
*/
QWebElement QWebFrame::findFirstElement(const QString &selectorQuery) const
{
......
2009-05-05 Simon Hausmann <simon.hausmann@nokia.com>
Reviewed by Tor Arne Vestbø.
Various improvements to the class documentation, including a simple snippet for QWebElement.
* Api/qwebelement.cpp:
* Api/qwebframe.cpp:
* docs/webkitsnippets/webelement/main.cpp: Added.
* docs/webkitsnippets/webelement/webelement.pro: Added.
2009-05-05 Simon Hausmann <simon.hausmann@nokia.com>
Reviewed by Ariya Hidayat.
......
/*
Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies)
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#include <QApplication>
#include <QUrl>
#include <qwebview.h>
#include <qwebframe.h>
#include <qwebelement.h>
#include <qdebug.h>
static QWebFrame *frame;
static void traverse()
{
//! [Traversing with QWebElement]
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();
//! [Traversing with QWebElement]
}
static void findAll()
{
//! [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");
//! [FindAll]
}
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWebView *view = new QWebView(0);
frame = view->page()->mainFrame();
traverse();
findAll();
return 0;
}
TEMPLATE = app
CONFIG -= app_bundle
SOURCES = main.cpp
include(../../../../../WebKit.pri)
QMAKE_RPATHDIR = $$OUTPUT_DIR/lib $$QMAKE_RPATHDIR
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment