Contents

• Public Functions
• Detailed Description

Detailed Description

TheQXmlContentHandler 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 usingQXmlReader::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 thestartElement() event and the correspondingendElement() event.

The classQXmlDefaultHandler provides a default implementation for this interface; subclassing from theQXmlDefaultHandler class is very convenient if you only want to be informed of some parsing events.

ThestartDocument() function is called at the start of the document, andendDocument() is called at the end. Before parsing beginssetDocumentLocator() is called. For each elementstartElement() is called, withendElement() being called at the end of each element. Thecharacters() function is called with chunks of character data;ignorableWhitespace() is called with chunks of whitespace andprocessingInstruction() is called with processing instructions. If an entity is skippedskippedEntity() is called. At the beginning of prefix-URI scopesstartPrefixMapping() is called.

Member Function Documentation

[virtual]QXmlContentHandler::~QXmlContentHandler()

Destroys the content handler.

[pure virtual]bool QXmlContentHandler::characters(constQString & ch)

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 useQXmlLexicalHandler::startCDATA() andQXmlLexicalHandler::endCDATA()). The character data is reported inch.

Some readers report whitespace in element content using theignorableWhitespace() 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 functionerrorString() to get the error message.

[pure virtual]bool QXmlContentHandler::endDocument()

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 functionerrorString() to get the error message.

See alsostartDocument().

[pure virtual]bool QXmlContentHandler::endElement(constQString & namespaceURI, constQString & localName, constQString & qName)

The reader calls this function when it has parsed an end element tag with the qualified nameqName, the local namelocalName and the namespace URInamespaceURI.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

See alsostartElement() andNamespace Support via Features.

[pure virtual]bool QXmlContentHandler::endPrefixMapping(constQString & prefix)

The reader calls this function to signal the end of a prefix mapping for the prefixprefix.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

See alsostartPrefixMapping() andNamespace Support via Features.

[pure virtual]QString QXmlContentHandler::errorString() const

The reader calls this function to get an error string, e.g. if any of the handler functions returns false.

[pure virtual]bool QXmlContentHandler::ignorableWhitespace(constQString & ch)

Some readers may use this function to report each chunk of whitespace in element content. The whitespace is reported inch.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

[pure virtual]bool QXmlContentHandler::processingInstruction(constQString & target, constQString & data)

The reader calls this function when it has parsed a processing instruction.

target is the target name of the processing instruction anddata is the data in the processing instruction.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

[pure virtual]void QXmlContentHandler::setDocumentLocator(QXmlLocator * locator)

The reader calls this function before it starts parsing the document. The argumentlocator is a pointer to aQXmlLocator which allows the application to get the parsing position within the document.

Do not destroy thelocator; it is destroyed when the reader is destroyed. (Do not use thelocator after the reader is destroyed).

[pure virtual]bool QXmlContentHandler::skippedEntity(constQString & name)

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 calledname by calling this function.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

[pure virtual]bool QXmlContentHandler::startDocument()

The reader calls this function when it starts parsing the document. The reader calls this function just once, after the call tosetDocumentLocator(), and before any other functions in this class or in theQXmlDTDHandler class are called.

If this function returns false the reader stops parsing and reports an error. The reader uses the functionerrorString() to get the error message.

See alsoendDocument().

[pure virtual]bool QXmlContentHandler::startElement(constQString & namespaceURI, constQString & localName, constQString & qName, constQXmlAttributes & atts)

The reader calls this function when it has parsed a start element tag.

There is a correspondingendElement() call when the corresponding end element tag is read. The startElement() andendElement() calls are always nested correctly. Empty element tags (e.g.<x/>) cause a startElement() call to be immediately followed by anendElement() 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 argumentnamespaceURI is the namespace URI, or an empty string if the element has no namespace URI or if no namespace processing is done.localName is the local name (without prefix), or an empty string if no namespace processing is done,qName is the qualified name (with prefix) andatts 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 functionerrorString() to get the error message.

See alsoendElement() andNamespace Support via Features.

[pure virtual]bool QXmlContentHandler::startPrefixMapping(constQString & prefix, constQString & uri)

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() andendPrefixMapping() calls are not guaranteed to be properly nested relative to each other: all startPrefixMapping() events occur before the correspondingstartElement() event, and allendPrefixMapping() events occur after the correspondingendElement() event, but their order is not otherwise guaranteed.

The argumentprefix is the namespace prefix being declared and the argumenturi 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 functionerrorString() to get the error message.

See alsoendPrefixMapping() andNamespace Support via Features.