The QXmlContentHandler class provides an interface to
report the logical content of XML data.
More...
Detailed Description
The QXmlContentHandler class provides an interface to
report the logical content of XML data.
If the application needs to be informed of basic parsing events,
it can implement this interface and activate it using
QXmlReader::setContentHandler(). The reader can then report basic
document-related events like the start and end of elements and
character data through this interface.
The order of events in this interface is very important, and
mirrors the order of information in the document itself. For
example, all of an element's content (character data, processing
instructions, and sub-elements) appears, in order, between the
startElement() event and the corresponding endElement() event.
The class QXmlDefaultHandler provides a default implementation for
this interface; subclassing from the QXmlDefaultHandler class is
very convenient if you only want to be informed of some parsing
events.
The startDocument() function is called at the start of the
document, and endDocument() is called at the end. Before parsing
begins setDocumentLocator() is called. For each element
startElement() is called, with endElement() being called at the
end of each element. The characters() function is called with
chunks of character data; ignorableWhitespace() is called with
chunks of whitespace and processingInstruction() is called with
processing instructions. If an entity is skipped skippedEntity()
is called. At the beginning of prefix-URI scopes
startPrefixMapping() is called.
See also the Introduction to SAX2.
See also QXmlDTDHandler, QXmlDeclHandler, QXmlEntityResolver, QXmlErrorHandler, QXmlLexicalHandler, and XML.
Member Function Documentation
bool QXmlContentHandler::characters ( const QString & ch ) [pure virtual]
The reader calls this function when it has parsed a chunk of
character data (either normal character data or character data
inside a CDATA section; if you need to distinguish between those
two types you must use QXmlLexicalHandler::startCDATA() and
QXmlLexicalHandler::endCDATA()). The character data is reported in
ch.
Some readers report whitespace in element content using the
ignorableWhitespace() function rather than using this one.
A reader may report the character data of an element in more than
one chunk; e.g. a reader might want to report "a<b" in three
characters() events ("a ", "<" and " b").
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
bool QXmlContentHandler::endDocument () [pure virtual]
The reader calls this function after it has finished parsing. It
is called just once, and is the last handler function called. It
is called after the reader has read all input or has abandoned
parsing because of a fatal error.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also startDocument().
bool QXmlContentHandler::endElement ( const QString & namespaceURI, const QString & localName, const QString & qName ) [pure virtual]
The reader calls this function when it has parsed an end element
tag with the qualified name qName, the local name localName
and the namespace URI namespaceURI.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also the namespace description.
See also startElement().
Examples: xml/tagreader-with-features/structureparser.cpp and xml/tagreader/structureparser.cpp.
bool QXmlContentHandler::endPrefixMapping ( const QString & prefix ) [pure virtual]
The reader calls this function to signal the end of a prefix
mapping for the prefix prefix.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also the namespace description.
See also startPrefixMapping().
QString QXmlContentHandler::errorString () [pure virtual]
The reader calls this function to get an error string, e.g. if any
of the handler functions returns FALSE.
bool QXmlContentHandler::ignorableWhitespace ( const QString & ch ) [pure virtual]
Some readers may use this function to report each chunk of
whitespace in element content. The whitespace is reported in ch.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
bool QXmlContentHandler::processingInstruction ( const QString & target, const QString & data ) [pure virtual]
The reader calls this function when it has parsed a processing
instruction.
target is the target name of the processing instruction and data is the data in the processing instruction.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
void QXmlContentHandler::setDocumentLocator ( QXmlLocator * locator ) [pure virtual]
The reader calls this function before it starts parsing the
document. The argument locator is a pointer to a QXmlLocator
which allows the application to get the parsing position within
the document.
Do not destroy the locator; it is destroyed when the reader is
destroyed. (Do not use the locator after the reader is
destroyed).
bool QXmlContentHandler::skippedEntity ( const QString & name ) [pure virtual]
Some readers may skip entities if they have not seen the
declarations (e.g. because they are in an external DTD). If they
do so they report that they skipped the entity called name by
calling this function.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
bool QXmlContentHandler::startDocument () [pure virtual]
The reader calls this function when it starts parsing the
document. The reader calls this function just once, after the call
to setDocumentLocator(), and before any other functions in this
class or in the QXmlDTDHandler class are called.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also endDocument().
Example: xml/tagreader/structureparser.cpp.
bool QXmlContentHandler::startElement ( const QString & namespaceURI, const QString & localName, const QString & qName, const QXmlAttributes & atts ) [pure virtual]
The reader calls this function when it has parsed a start element
tag.
There is a corresponding endElement() call when the corresponding
end element tag is read. The startElement() and endElement() calls
are always nested correctly. Empty element tags (e.g. <x/>)
cause a startElement() call to be immediately followed by an
endElement() call.
The attribute list provided only contains attributes with explicit
values. The attribute list contains attributes used for namespace
declaration (i.e. attributes starting with xmlns) only if the
namespace-prefix property of the reader is TRUE.
The argument namespaceURI is the namespace URI, or
QString::null if the element has no namespace URI or if no
namespace processing is done. localName is the local name
(without prefix), or QString::null if no namespace processing is
done, qName is the qualified name (with prefix) and atts are
the attributes attached to the element. If there are no
attributes, atts is an empty attributes object.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also the namespace description.
See also endElement().
Examples: xml/tagreader-with-features/structureparser.cpp and xml/tagreader/structureparser.cpp.
bool QXmlContentHandler::startPrefixMapping ( const QString & prefix, const QString & uri ) [pure virtual]
The reader calls this function to signal the begin of a prefix-URI
namespace mapping scope. This information is not necessary for
normal namespace processing since the reader automatically
replaces prefixes for element and attribute names.
Note that startPrefixMapping() and endPrefixMapping() calls are
not guaranteed to be properly nested relative to each other: all
startPrefixMapping() events occur before the corresponding
startElement() event, and all endPrefixMapping() events occur
after the corresponding endElement() event, but their order is not
otherwise guaranteed.
The argument prefix is the namespace prefix being declared and
the argument uri is the namespace URI the prefix is mapped to.
If this function returns FALSE the reader stops parsing and
reports an error. The reader uses the function errorString() to
get the error message.
See also the namespace description.
See also endPrefixMapping().
This file is part of the Qt toolkit.
Copyright © 1995-2003
Trolltech. All Rights Reserved.
