From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/xml.html | 573 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 573 insertions(+) create mode 100644 doc/html/xml.html (limited to 'doc/html/xml.html') diff --git a/doc/html/xml.html b/doc/html/xml.html new file mode 100644 index 000000000..2167b7852 --- /dev/null +++ b/doc/html/xml.html @@ -0,0 +1,573 @@ + + + + + +XML Module + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

XML Module

+ + +

+

+

+ + +

+

Overview of the XML architecture in TQt +

+

The XML module provides a well-formed XML parser using the SAX2 +(Simple API for XML) interface plus an implementation of the DOM Level +2 (Document Object Model). +

SAX is an event-based standard interface for XML parsers. +The TQt interface follows the design of the SAX2 Java implementation. +Its naming scheme was adapted to fit the TQt naming conventions. +Details on SAX2 can be found at +http://www.saxproject.org. +

Support for SAX2 filters and the reader factory are under +development. The TQt implementation does not include the SAX1 +compatibility classes present in the Java interface. +

For an introduction to TQt's SAX2 classes see +"The TQt SAX2 classes". +

DOM Level 2 is a W3C Recommendation for XML interfaces that maps the +constituents of an XML document to a tree structure. Details and the +specification of DOM Level 2 can be found at +http://www.w3.org/DOM/. +More information about the DOM classes in TQt is provided in the +TQt DOM classes. +

TQt provides the following XML related classes: +

+
Class Short description +
TQDomAttr +Represents one attribute of a TQDomElement +
TQDomCDATASection +Represents an XML CDATA section +
TQDomCharacterData +Represents a generic string in the DOM +
TQDomComment +Represents an XML comment +
TQDomDocument +The representation of an XML document +
TQDomDocumentFragment +Tree of TQDomNodes which is usually not a complete TQDomDocument +
TQDomDocumentType +The representation of the DTD in the document tree +
TQDomElement +Represents one element in the DOM tree +
TQDomEntity +Represents an XML entity +
TQDomEntityReference +Represents an XML entity reference +
TQDomImplementation +Information about the features of the DOM implementation +
TQDomNamedNodeMap +Collection of nodes that can be accessed by name +
TQDomNode +The base class for all nodes of the DOM tree +
TQDomNodeList +List of TQDomNode objects +
TQDomNotation +Represents an XML notation +
TQDomProcessingInstruction +Represents an XML processing instruction +
TQDomText +Represents textual data in the parsed XML document +
TQXmlAttributes +XML attributes +
TQXmlContentHandler +Interface to report logical content of XML data +
TQXmlDeclHandler +Interface to report declaration content of XML data +
TQXmlDefaultHandler +Default implementation of all XML handler classes +
TQXmlDTDHandler +Interface to report DTD content of XML data +
TQXmlEntityResolver +Interface to resolve extern entities contained in XML data +
TQXmlErrorHandler +Interface to report errors in XML data +
TQXmlInputSource +The input data for the TQXmlReader subclasses +
TQXmlLexicalHandler +Interface to report lexical content of XML data +
TQXmlLocator +The XML handler classes with information about the actual parsing position +
TQXmlNamespaceSupport +Helper class for XML readers which want to include namespace support +
TQXmlParseException +Used to report errors with the TQXmlErrorHandler interface +
TQXmlReader +Interface for XML readers (i.e. for SAX2 parsers) +
TQXmlSimpleReader +Implementation of a simple XML reader (a SAX2 parser) +
+

+

The TQt SAX2 classes +

+

+

Introduction to SAX2 +

+

The SAX2 interface is an event-driven mechanism to provide the user with +document information. An "event" in this context means something +reported by the parser, for example, it has encountered a start tag, +or an end tag, etc. +

To make it less abstract consider the following example: +

 
+<quote>A quotation.</quote>
+
+ +

Whilst reading (a SAX2 parser is usually referred to as "reader") +the above document three events would be triggered: +

    +
  1. A start tag occurs (<quote>). +
  2. Character data (i.e. text) is found, "A quotation.". +
  3. An end tag is parsed (</quote>). +
+

Each time such an event occurs the parser reports it; you can set up +event handlers to respond to these events. +

Whilst this is a fast and simple approach to read XML documents, +manipulation is difficult because data is not stored, simply handled +and discarded serially. The DOM interface reads in and stores the whole document in a tree structure; +this takes more memory, but makes it easier to manipulate the +document's structure.. +

The TQt XML module provides an abstract class, TQXmlReader, that +defines the interface for potential SAX2 readers. TQt includes a reader +implementation, TQXmlSimpleReader, that is easy to adapt through +subclassing. +

The reader reports parsing events through special handler classes: +

+
Handler class Description +
TQXmlContentHandler +Reports events related to the content of a document (e.g. the start tag +or characters). +
TQXmlDTDHandler +Reports events related to the DTD (e.g. notation declarations). +
TQXmlErrorHandler +Reports errors or warnings that occurred during parsing. +
TQXmlEntityResolver +Reports external entities during parsing and allows users to resolve +external entities themselves instead of leaving it to the reader. +
TQXmlDeclHandler +Reports further DTD related events (e.g. attribute declarations). +
TQXmlLexicalHandler +Reports events related to the lexical structure of the +document (the beginning of the DTD, comments etc.). +
+

These classes are abstract classes describing the interface. The TQXmlDefaultHandler class provides a "do nothing" default +implementation for all of them. Therefore users only need to overload +the TQXmlDefaultHandler functions they are interested in. +

To read input XML data a special class TQXmlInputSource is used. +

Apart from those already mentioned, the following SAX2 support classes +provide additional useful functionality: +

+
Class Description +
TQXmlAttributes +Used to pass attributes in a start element event. +
TQXmlLocator +Used to obtain the actual parsing position of an event. +
TQXmlNamespaceSupport +Used to implement namespace +support for a reader. Note that namespaces do not change the +parsing behavior. They are only reported through the handler. +
+

+

Features +

+

The behaviour of an XML reader depends on its support for certain +optional features. For example, a reader may have the feature "report +attributes used for namespace +declarations and prefixes along with the local name of a tag". Like +every other feature this has a unique name represented by a URI: it is +called http://xml.org/sax/features/namespace-prefixes. +

The TQt SAX2 implementation can report whether the reader has +particular functionality using the TQXmlReader::hasFeature() +function. Available features can be tested with TQXmlReader::feature(), +and switched on or off using TQXmlReader::setFeature(). +

Consider the example +

 
+<document xmlns:book = 'http://trolltech.com/fnord/book/'
+          xmlns      = 'http://trolltech.com/fnord/' >
+
+ +A reader that does not support the http://xml.org/sax/features/namespace-prefixes feature would report +the element name document but not its attributes xmlns:book and +xmlns with their values. A reader with the feature http://xml.org/sax/features/namespace-prefixes reports the namespace +attributes if the feature is +switched on. +

Other features include http://xml.org/sax/features/namespace +(namespace processing, implies http://xml.org/sax/features/namespace-prefixes) and http://xml.org/sax/features/validation (the ability to report +validation errors). +

Whilst SAX2 leaves it to the user to define and implement whatever +features are retquired, support for http://xml.org/sax/features/namespace (and thus http://xml.org/sax/features/namespace-prefixes) is mandantory. +The TQXmlSimpleReader implementation of TQXmlReader, +supports them, and can do namespace processing. +

TQXmlSimpleReader is not validating, so it +does not support http://xml.org/sax/features/validation. +

+

Namespace support via features +

+

As we have seen in the previous section +we can configure the behavior of the reader when it comes to namespace +processing. This is done by setting and unsetting the +http://xml.org/sax/features/namespaces and +http://xml.org/sax/features/namespace-prefixes features. +

They influence the reporting behavior in the following way: +

    +
  1. Namespace prefixes and local parts of elements and attributes can +be reported. +
  2. The qualified names of elements and attributes are reported. +
  3. TQXmlContentHandler::startPrefixMapping() and TQXmlContentHandler::endPrefixMapping() are called by the reader. +
  4. Attributes that declare namespaces (i.e. the attribute xmlns and +attributes starting with xmlns:) are reported. +
+

Consider the following element: +

+<author xmlns:fnord = 'http://trolltech.com/fnord/'
+             title="Ms" 
+             fnord:title="Goddess" 
+             name="Eris Kallisti"/>
+
+ +With http://xml.org/sax/features/namespace-prefixes set to TRUE +the reader will report four attributes; but with the namespace-prefixes feature set to FALSE only three, with the xmlns:fnord attribute defining a namespace being "invisible" to the +reader. +

The http://xml.org/sax/features/namespaces feature is responsible +for reporting local names, namespace prefixes and URIs. With http://xml.org/sax/features/namespaces set to TRUE the parser will +report title as the local name of the fnord:title attribute, fnord being the namespace prefix and http://trolltech.com/fnord/ as +the namespace URI. When http://xml.org/sax/features/namespaces is +FALSE none of them are reported. +

In the current implementation the TQt XML classes follow the definition +that the prefix xmlns itself isn't associated with any namespace at all +(see http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using). +Therefore even with http://xml.org/sax/features/namespaces and +http://xml.org/sax/features/namespace-prefixes both set to TRUE +the reader won't return either a local name, a namespace prefix or +a namespace URI for xmlns:fnord. +

This might be changed in the future following the W3C suggestion +http://www.w3.org/2000/xmlns/ +to associate xmlns with the namespace http://www.w3.org/2000/xmlns. +

As the SAX2 standard suggests, TQXmlSimpleReader defaults to having +http://xml.org/sax/features/namespaces set to TRUE and +http://xml.org/sax/features/namespace-prefixes set to FALSE. +When changing this behavior using TQXmlSimpleReader::setFeature() +note that the combination of both features set to +FALSE is illegal. +

For a practical demonstration of how the two features affect the +output of the reader run the tagreader with features example. +

+

Summary +

+

TQXmlSimpleReader implements the following behavior: +

+
(namespaces, namespace-prefixes) +Namespace prefix and local part +Qualified names +Prefix mapping +xmlns attributes +
(TRUE, FALSE) Yes Yes* Yes No +
(TRUE, TRUE) Yes Yes Yes Yes +
(FALSE, TRUE) No* Yes No* Yes +
(FALSE, FALSE) Illegal +
+

* The behavior of these entries is not specified by SAX. +

+

Properties +

+

Properties are a more general concept. They have a unique name, +represented as an URI, but their value is void*. Thus nearly +anything can be used as a property value. This concept involves some +danger, though: there is no means of ensuring type-safety; the user +must take care that they pass the right type. Properties are +useful if a reader supports special handler classes. +

The URIs used for features and properties often look like URLs, e.g. +http://xml.org/sax/features/namespace. This does not mean that the +data retquired is at this address. It is simply a way of defining +unique names. +

Anyone can define and use new SAX2 properties for their readers. +Property support is not mandatory. +

To set or query properties the following functions are provided: TQXmlReader::setProperty(), TQXmlReader::property() and TQXmlReader::hasProperty(). +

+

Further reading +

+

More information about XML (e.g. namespaces) +can be found in the introduction to the TQt XML module. +

+

The TQt DOM classes +

+

+

Introduction to DOM +

+

DOM provides an interface to access and change the content and +structure of an XML file. It makes a hierarchical view of the document +(a tree view). Thus -- in contrast to the SAX2 interface -- an object +model of the document is resident in memory after parsing which makes +manipulation easy. +

All DOM nodes in the document tree are subclasses of TQDomNode. The +document itself is represented as a TQDomDocument object. +

Here are the available node classes and their potential child classes: +

+

With TQDomNodeList and TQDomNamedNodeMap two collection classes +are provided: TQDomNodeList is a list of nodes, +and TQDomNamedNodeMap is used to handle unordered sets of nodes +(often used for attributes). +

The TQDomImplementation class allows the user to query features of the +DOM implementation. +

Further reading +

+

To get started please refer to the TQDomDocument documentation. +

+

An introduction to namespaces +

+

Parts of the TQt XML module documentation assume that you are familiar +with XML namespaces. Here we present a brief introduction; skip to +TQt XML documentation conventions +if you already know this material. +

Namespaces are a concept introduced into XML to allow a more modular +design. With their help data processing software can easily resolve +naming conflicts in XML documents. +

Consider the following example: +

+<document>
+<book>
+  <title>Practical XML</title>
+  <author title="Ms" name="Eris Kallisti"/>
+  <chapter>
+    <title>A Namespace Called fnord</title>
+  </chapter>
+</book>
+</document>
+
+ +

Here we find three different uses of the name title. If you wish to +process this document you will encounter problems because each of the +titles should be displayed in a different manner -- even though +they have the same name. +

The solution would be to have some means of identifying the first +occurrence of title as the title of a book, i.e. to use the title element of a book namespace to distinguish it from, for example, +the chapter title, e.g.: +

+<book:title>Practical XML</book:title>
+
+ +

book in this case is a prefix denoting the namespace. +

Before we can apply a namespace to element or attribute names we must +declare it. +

Namespaces are URIs like http://trolltech.com/fnord/book/. This +does not mean that data must be available at this address; the URI is +simply used to provide a unique name. +

We declare namespaces in the same way as attributes; strictly speaking +they are attributes. To make for example http://trolltech.com/fnord/ the document's default XML namespace xmlns we write +

+xmlns="http://trolltech.com/fnord/"
+
+ +

To distinguish the http://trolltech.com/fnord/book/ namespace from +the default, we must supply it with a prefix: +

+xmlns:book="http://trolltech.com/fnord/book/"
+
+ +

A namespace that is declared like this can be applied to element and +attribute names by prepending the appropriate prefix and a ":" +delimiter. We have already seen this with the book:title element. +

Element names without a prefix belong to the default namespace. This +rule does not apply to attributes: an attribute without a prefix does +not belong to any of the declared XML namespaces at all. Attributes +always belong to the "traditional" namespace of the element in which +they appear. A "traditional" namespace is not an XML namespace, it +simply means that all attribute names belonging to one element must be +different. Later we will see how to assign an XML namespace to an +attribute. +

Due to the fact that attributes without prefixes are not in any XML +namespace there is no collision between the attribute title (that +belongs to the author element) and for example the title element +within a chapter. +

Let's clarify this with an example: +

+<document xmlns:book = 'http://trolltech.com/fnord/book/'
+          xmlns      = 'http://trolltech.com/fnord/' >
+<book>
+  <book:title>Practical XML</book:title>
+  <book:author xmlns:fnord = 'http://trolltech.com/fnord/'
+               title="Ms"
+               fnord:title="Goddess"
+               name="Eris Kallisti"/>
+  <chapter>
+    <title>A Namespace Called fnord</title>
+  </chapter>
+</book>
+</document>
+
+ +

Within the document element we have two namespaces declared. The +default namespace http://trolltech.com/fnord/ applies to the book element, the chapter element, the appropriate title element +and of course to document itself. +

The book:author and book:title elements belong to the namespace +with the URI http://trolltech.com/fnord/book/. +

The two book:author attributes title and name have no XML +namespace assigned. They are only members of the "traditional" +namespace of the element book:author, meaning that for example two +title attributes in book:author are forbidden. +

In the above example we circumvent the last rule by adding a title +attribute from the http://trolltech.com/fnord/ namespace to book:author: the fnord:title comes from the namespace with the +prefix fnord that is declared in the book:author element. +

Clearly the fnord namespace has the same namespace URI as the +default namespace. So why didn't we simply use the default namespace +we'd already declared? The answer is tquite complex: +

+

With the TQt XML classes elements and attributes can be accessed in two +ways: either by refering to their qualified names consisting of the +namespace prefix and the "real" name (or local name) or by the +combination of local name and namespace URI. +

More information on XML namespaces can be found at +http://www.w3.org/TR/REC-xml-names/. +

+

Conventions used in TQt XML documentation +

+

The following terms are used to distinguish the parts of names within +the context of namespaces: +

+

Elements without a ":" (like chapter in the example) do not have a +namespace prefix. In this case the local part and the qualified name +are identical (i.e. chapter). + + +

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.3