Merge branch 'master' of git@scm.dev.nokia.troll.no:qt/qt-s60-public

1 files changed, 99 insertions, 8 deletions

diff --git a/src/corelib/xml/qxmlstream.cpp b/src/corelib/xml/qxmlstream.cpp
index 004e823..4eadc75 100644
--- a/src/corelib/xml/qxmlstream.cpp
+++ b/src/corelib/xml/qxmlstream.cpp
@@ -129,6 +129,21 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \enum QXmlStreamReader::ReadElementTextBehaviour
+
+    This enum specifies the different behaviours of readElementText().
+
+    \value ErrorOnUnexpectedElement Raise an UnexpectedElementError and return
+    what was read so far when a child element is encountered.
+
+    \value IncludeChildElements Recursively include the text from child elements.
+
+    \value SkipChildElements Skip child elements.
+
+    \since 4.6
+*/
+
+/*!
     \enum QXmlStreamReader::Error
 
     This enum specifies different error cases
@@ -621,6 +636,56 @@ QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const
     return d->type;
 }
 
+/*!
+  Reads until the next start element within the current element. Returns true
+  when a start element was reached. When the end element was reached, or when
+  an error occurred, false is returned.
+
+  The current element is the element matching the most recently parsed start
+  element of which a matching end element has not yet been reached. When the
+  parser has reached the end element, the current element becomes the parent
+  element.
+
+  This is a convenience function for when you're only concerned with parsing
+  XML elements. The \l{QXmlStream Bookmarks Example} makes extensive use of
+  this function.
+
+  \since 4.6
+  \sa readNext()
+ */
+bool QXmlStreamReader::readNextStartElement()
+{
+    while (readNext() != Invalid) {
+        if (isEndElement())
+            return false;
+        else if (isStartElement())
+            return true;
+    }
+    return false;
+}
+
+/*!
+  Reads until the end of the current element, skipping any child nodes.
+  This function is useful for skipping unknown elements.
+
+  The current element is the element matching the most recently parsed start
+  element of which a matching end element has not yet been reached. When the
+  parser has reached the end element, the current element becomes the parent
+  element.
+
+  \since 4.6
+ */
+void QXmlStreamReader::skipCurrentElement()
+{
+    int depth = 1;
+    while (depth && readNext() != Invalid) {
+        if (isEndElement())
+            --depth;
+        else if (isStartElement())
+            ++depth;
+    }
+}
+
 /*
  * Use the following Perl script to generate the error string index list:
 ===== PERL SCRIPT ====
@@ -2022,12 +2087,17 @@ void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDe
 
   The function concatenates text() when it reads either \l Characters
   or EntityReference tokens, but skips ProcessingInstruction and \l
-  Comment. In case anything else is read before reaching EndElement,
-  the function returns what it read so far and raises an
-  UnexpectedElementError. If the current token is not StartElement, an
-  empty string is returned.
+  Comment. If the current token is not StartElement, an empty string is
+  returned.
+
+  The \a behaviour defines what happens in case anything else is
+  read before reaching EndElement. The function can include the text from
+  child elements (useful for example for HTML), ignore child elements, or
+  raise an UnexpectedElementError and return what was read so far.
+
+  \since 4.6
  */
-QString QXmlStreamReader::readElementText()
+QString QXmlStreamReader::readElementText(ReadElementTextBehaviour behaviour)
 {
     Q_D(QXmlStreamReader);
     if (isStartElement()) {
@@ -2043,16 +2113,37 @@ QString QXmlStreamReader::readElementText()
             case ProcessingInstruction:
             case Comment:
                 break;
+            case StartElement:
+                if (behaviour == SkipChildElements) {
+                    skipCurrentElement();
+                    break;
+                } else if (behaviour == IncludeChildElements) {
+                    result += readElementText(behaviour);
+                    break;
+                }
+                // Fall through (for ErrorOnUnexpectedElement)
             default:
-                if (!d->error)
-                    d->raiseError(UnexpectedElementError, QXmlStream::tr("Expected character data."));
-                return result;
+                if (d->error || behaviour == ErrorOnUnexpectedElement) {
+                    if (!d->error)
+                        d->raiseError(UnexpectedElementError, QXmlStream::tr("Expected character data."));
+                    return result;
+                }
             }
         }
     }
     return QString();
 }
 
+/*!
+  \overload readElementText()
+
+  Calling this function is equivalent to calling readElementText(ErrorOnUnexpectedElement).
+ */
+QString QXmlStreamReader::readElementText()
+{
+    return readElementText(ErrorOnUnexpectedElement);
+}
+
 /*!  Raises a custom error with an optional error \a message.
 
   \sa error(), errorString()