Qt Jambi Home

com.trolltech.qt.xml
Class QXmlContentHandler

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.xml.QXmlContentHandler
All Implemented Interfaces:
QtJambiInterface, QXmlContentHandlerInterface

public abstract class QXmlContentHandler
extends QtJambiObject
implements QXmlContentHandlerInterface

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:
QXmlDTDHandler, QXmlDeclHandler, QXmlEntityResolver, QXmlErrorHandler, QXmlLexicalHandler, to SAX2

Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Constructor Summary
QXmlContentHandler()
          Creates a new QXmlContentHandler.
 
Method Summary
abstract  boolean characters(java.lang.String 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 use QXmlLexicalHandler::startCDATA() and QXmlLexicalHandler::endCDATA()).
abstract  boolean endDocument()
          The reader calls this function after it has finished parsing.
abstract  boolean endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
          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.
abstract  boolean endPrefixMapping(java.lang.String prefix)
          The reader calls this function to signal the end of a prefix mapping for the prefix prefix.
abstract  java.lang.String errorString()
          The reader calls this function to get an error string, e.g. if any of the handler functions returns false.
static QXmlContentHandler fromNativePointer(QNativePointer nativePointer)
          This function returns the QXmlContentHandler instance pointed to by nativePointer
abstract  boolean ignorableWhitespace(java.lang.String ch)
          Some readers may use this function to report each chunk of whitespace in element content.
abstract  boolean processingInstruction(java.lang.String target, java.lang.String data)
          The reader calls this function when it has parsed a processing instruction.
abstract  void setDocumentLocator(QXmlLocator locator)
          The reader calls this function before it starts parsing the document.
abstract  boolean skippedEntity(java.lang.String name)
          Some readers may skip entities if they have not seen the declarations (e.g. because they are in an external DTD).
abstract  boolean startDocument()
          The reader calls this function when it starts parsing the document.
abstract  boolean startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, QXmlAttributes atts)
          The reader calls this function when it has parsed a start element tag.
abstract  boolean startPrefixMapping(java.lang.String prefix, java.lang.String uri)
          The reader calls this function to signal the begin of a prefix-URI namespace mapping scope.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QXmlContentHandler

public QXmlContentHandler()
Creates a new QXmlContentHandler.

Method Detail

characters

public abstract boolean characters(java.lang.String 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 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.

Specified by:
characters in interface QXmlContentHandlerInterface

endDocument

public abstract boolean 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 function errorString to get the error message.

Specified by:
endDocument in interface QXmlContentHandlerInterface
See Also:
startDocument

endElement

public abstract boolean endElement(java.lang.String namespaceURI,
                                   java.lang.String localName,
                                   java.lang.String qName)

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.

Specified by:
endElement in interface QXmlContentHandlerInterface
See Also:
startElement, Support via Features

endPrefixMapping

public abstract boolean endPrefixMapping(java.lang.String prefix)

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.

Specified by:
endPrefixMapping in interface QXmlContentHandlerInterface
See Also:
startPrefixMapping, Support via Features

errorString

public abstract java.lang.String errorString()

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

Specified by:
errorString in interface QXmlContentHandlerInterface

ignorableWhitespace

public abstract boolean ignorableWhitespace(java.lang.String ch)

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.

Specified by:
ignorableWhitespace in interface QXmlContentHandlerInterface

processingInstruction

public abstract boolean processingInstruction(java.lang.String target,
                                              java.lang.String data)

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.

Specified by:
processingInstruction in interface QXmlContentHandlerInterface

setDocumentLocator

public abstract void setDocumentLocator(QXmlLocator locator)

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

Specified by:
setDocumentLocator in interface QXmlContentHandlerInterface

skippedEntity

public abstract boolean skippedEntity(java.lang.String 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 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.

Specified by:
skippedEntity in interface QXmlContentHandlerInterface

startDocument

public abstract boolean startDocument()

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.

Specified by:
startDocument in interface QXmlContentHandlerInterface
See Also:
endDocument

startElement

public abstract boolean startElement(java.lang.String namespaceURI,
                                     java.lang.String localName,
                                     java.lang.String qName,
                                     QXmlAttributes atts)

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

Specified by:
startElement in interface QXmlContentHandlerInterface
See Also:
endElement, Support via Features

startPrefixMapping

public abstract boolean startPrefixMapping(java.lang.String prefix,
                                           java.lang.String 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 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.

Specified by:
startPrefixMapping in interface QXmlContentHandlerInterface
See Also:
endPrefixMapping, Support via Features

fromNativePointer

public static QXmlContentHandler fromNativePointer(QNativePointer nativePointer)
This function returns the QXmlContentHandler instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

Qt Jambi Home