Редактирование: Qt:Документация 4.3.2/qtxml
Материал из Wiki.crossplatform.ru
Внимание: Вы не представились системе. Ваш IP-адрес будет записан в историю изменений этой страницы.
ПРЕДУПРЕЖДЕНИЕ: Длина этой страницы составляет 38 килобайт. Страницы, размер которых приближается к 32 КБ или превышает это значение, могут неверно отображаться в некоторых браузерах. Пожалуйста, рассмотрите вариант разбиения страницы на меньшие части.
Правка может быть отменена. Пожалуйста, просмотрите сравнение версий, чтобы убедиться, что это именно те изменения, которые вас интересуют, и нажмите «Записать страницу», чтобы изменения вступили в силу.
Текущая версия | Ваш текст | ||
Строка 1: | Строка 1: | ||
{{Qt4.3.2_header}} | {{Qt4.3.2_header}} | ||
- | [ | + | [Previous: [[Qt:Документация 4.3.2/qtsvg | QtSvg Module]]] [ [[Qt:Документация 4.3.2/modules | Qt's Modules]] ] [Next: [[Qt:Документация 4.3.2/qtdesigner | QtDesigner Module]]] |
=Модуль QtXml<br />= | =Модуль QtXml<br />= | ||
- | |||
Модуль QtXml обеспечивает работу с потоками чтения и записи XML документов и реализацию их в форме SAX и DOM. [[#details | Далее...]] | Модуль QtXml обеспечивает работу с потоками чтения и записи XML документов и реализацию их в форме SAX и DOM. [[#details | Далее...]] | ||
==Классы== | ==Классы== | ||
- | |||
{| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | {| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | ||
Строка 126: | Строка 124: | ||
|Запись XML с простым потоковым API | |Запись XML с простым потоковым API | ||
|} | |} | ||
- | + | ||
==Подробное описание== | ==Подробное описание== | ||
+ | SAX is an event-based standard interface for XML parsers. The Qt interface follows the design of the SAX2 Java implementation. Its naming scheme was adapted to fit the Qt naming conventions. Details on SAX2 can be found at [http://www.saxproject.org http://www.saxproject.org]. | ||
- | + | Support for SAX2 filters and the reader factory are under development. The Qt implementation does not include the SAX1 compatibility classes present in the Java interface. For an introduction to Qt's SAX2 classes, see [[#the-qt-sax2-classes | The Qt SAX2 Classes]]. | |
- | + | DOM Level 2 is a W3C Recommendation for XML interfaces that maps the constituents of an XML document to a tree structure. The specification of DOM Level 2 can be found at [http://www.w3.org/DOM/ http://www.w3.org/DOM/]. For more information about the DOM classes in Qt is provided, see [[#the-qt-dom-classes | The Qt DOM Classes]]. | |
- | + | Since version 4.3, Qt provides two new classes for reading and writing XML: [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] and [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]]. | |
- | + | In addition to core XML support, [[Qt:Документация 4.3.2/qsvgrenderer | QSvgRenderer]] can read a subset of SVG. Additional XML support is provided by the [http://www.trolltech.com/products/qt/addon/solutions/ Qt Solutions] group who provide, for example, classes that support SOAP and MML with the Qt XML classes. | |
- | + | To include the definitions of the module's classes, use the following directive: | |
- | + | ||
- | + | ||
<source lang="cpp-qt"> #include <QtXml></source> | <source lang="cpp-qt"> #include <QtXml></source> | ||
- | + | To link against the module, add this line to your [[Qt:Документация 4.3.2/qmake-manual#qmake | qmake]] <tt>.pro</tt> file: | |
<source lang="cpp-qt"> QT += xml</source> | <source lang="cpp-qt"> QT += xml</source> | ||
- | + | This module is part of the [[Qt:Документация 4.3.2/commercialeditions#qt-console-edition | Qt Console Edition]], the [[Qt:Документация 4.3.2/commercialeditions#qt-desktop-edition | Qt Desktop Edition]], and the [[Qt:Документация 4.3.2/opensourceedition | Qt Open Source Edition]]. | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ===Configuring the Build Process=== | |
- | == | + | Applications that use Qt's XML classes need to be configured to be built against the QtXml module. The following declaration in a <tt>qmake</tt> project file ensures that an application is compiled and linked appropriately: |
- | + | ||
<source lang="cpp-qt"> QT += xml</source> | <source lang="cpp-qt"> QT += xml</source> | ||
- | + | This line is necessary because only the [[Qt:Документация 4.3.2/qtcore | QtCore]] and [[Qt:Документация 4.3.2/qtgui | QtGui]] modules are used in the default build process. | |
- | + | ||
- | === | + | ===The QtXml Stream Classes=== |
- | [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] | + | The [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] and [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]] are two new classes provided in Qt 4.3 and later. A stream reader reports an XML document as a stream of tokens. This differs from SAX as SAX applications provide handlers to receive XML events from the parser whereas the [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] drives the loop, pulling tokens from the reader when they are needed. This pulling approach makes it possible to build recursive descent parsers, allowing XML parsing code to be split into different methods or classes. |
- | [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] | + | [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] is a well-formed XML 1.0 parser that excludes external parsed entities. Hence, data provided by the stream reader adheres to the W3C's criteria for well-formed XML, as long as no error occurs. Otherwise, functions such as [[Qt:Документация 4.3.2/qxmlstreamreader#atEnd | atEnd()]], [[Qt:Документация 4.3.2/qxmlstreamreader#error | error()]] and [[Qt:Документация 4.3.2/qxmlstreamreader#hasError | hasError()]] can be used to check and view the errors. |
- | + | An example of [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] implementation would be the <tt>XbelReader</tt> in [[Qt:Документация 4.3.2/xml-streambookmarks | QXmlStream Bookmarks Example]], which is a subclass of QXmlStreamReder. The constructor takes ''treeWidget'' as a parameter and the class has Xbel specific functions: | |
<source lang="cpp-qt"> XbelReader(QTreeWidget *treeWidget); | <source lang="cpp-qt"> XbelReader(QTreeWidget *treeWidget); | ||
... | ... | ||
Строка 185: | Строка 166: | ||
QTreeWidget *treeWidget; | QTreeWidget *treeWidget; | ||
...</source> | ...</source> | ||
- | + | The <tt>read()</tt> function accepts a [[Qt:Документация 4.3.2/qiodevice | QIODevice]] and sets it with [[Qt:Документация 4.3.2/qxmlstreamreader#setDevice | setDevice()]]. The [[Qt:Документация 4.3.2/qxmlstreamreader#raiseError | raiseError()]] function is used to display a custom error message, inidicating that the file's version is incorrect. | |
<source lang="cpp-qt"> bool XbelReader::read(QIODevice *device) | <source lang="cpp-qt"> bool XbelReader::read(QIODevice *device) | ||
{ | { | ||
Строка 197: | Строка 178: | ||
readXBEL(); | readXBEL(); | ||
else | else | ||
- | raiseError(QObject::tr(" | + | raiseError(QObject::tr("The file is not an XBEL version 1.0 file.")); |
} | } | ||
} | } | ||
Строка 203: | Строка 184: | ||
return !error(); | return !error(); | ||
}</source> | }</source> | ||
- | + | The pendent to [[Qt:Документация 4.3.2/qxmlstreamreader | QXmlStreamReader]] is [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]], which provides an XML writer with a simple streaming API. [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]] operates on a [[Qt:Документация 4.3.2/qiodevice | QIODevice]] and has specialised functions for all XML tokens or events you want to write, such as [[Qt:Документация 4.3.2/qxmlstreamwriter#writeDTD | writeDTD()]], [[Qt:Документация 4.3.2/qxmlstreamwriter#writeCharacters | writeCharacters()]], [[Qt:Документация 4.3.2/qxmlstreamwriter#writeComment | writeComment()]] and so on. | |
- | + | To write XML document with [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]], you start a document with the [[Qt:Документация 4.3.2/qxmlstreamwriter#writeStartDocument | writeStartDocument()]] function and end it with [[Qt:Документация 4.3.2/qxmlstreamwriter#writeEndDocument | writeEndDocument()]], which implicitly closes all remaining open tags. Element tags are opened with [[Qt:Документация 4.3.2/qxmlstreamwriter#writeStartDocument | writeStartDocument()]] and followed by [[Qt:Документация 4.3.2/qxmlstreamwriter#writeAttribute | writeAttribute()]] or [[Qt:Документация 4.3.2/qxmlstreamwriter#writeAttributes | writeAttributes()]], element content, and then [[Qt:Документация 4.3.2/qxmlstreamwriter#writeEndDocument | writeEndDocument()]]. Also, [[Qt:Документация 4.3.2/qxmlstreamwriter#writeEmptyElement | writeEmptyElement()]] can be used to write empty elements. | |
- | + | Element content comprises characters, entity references or nested elements. Content can be written with [[Qt:Документация 4.3.2/qxmlstreamwriter#writeCharacters | writeCharacters()]], a function that also takes care of escaping all forbidden characters and character sequences, [[Qt:Документация 4.3.2/qxmlstreamwriter#writeEntityReference | writeEntityReference()]], or subsequent calls to [[Qt:Документация 4.3.2/qxmlstreamwriter#writeStartElement | writeStartElement()]]. | |
- | + | The <tt>XbelWriter</tt> class from [[Qt:Документация 4.3.2/xml-streambookmarks | QXmlStream Bookmarks Example]] is a subclass of [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]]. Its <tt>writeFile()</tt> function illustrates the core functions of [[Qt:Документация 4.3.2/qxmlstreamwriter | QXmlStreamWriter]] mentioned above: | |
<source lang="cpp-qt"> bool XbelWriter::writeFile(QIODevice *device) | <source lang="cpp-qt"> bool XbelWriter::writeFile(QIODevice *device) | ||
{ | { | ||
Строка 223: | Строка 204: | ||
writeEndDocument(); | writeEndDocument(); | ||
return true; | return true; | ||
- | }</source> | + | }</source> |
- | + | ===The Qt 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: | |
<source lang="cpp-qt"> <quote>A quotation.</quote></source> | <source lang="cpp-qt"> <quote>A quotation.</quote></source> | ||
- | + | Whilst reading (a SAX2 parser is usually referred to as "reader") the above document three events would be triggered: | |
- | # | + | #A start tag occurs (<tt><quote></tt>). |
- | # | + | #Character data (i.e. text) is found, "A quotation.". |
- | # | + | #An end tag is parsed (<tt></quote></tt>). |
- | + | 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 | 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 Qt XML module provides an abstract class, [[Qt:Документация 4.3.2/qxmlreader | QXmlReader]], that defines the interface for potential SAX2 readers. Qt includes a reader implementation, [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]], that is easy to adapt through subclassing. | |
- | + | The reader reports parsing events through special handler classes: | |
{| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | {| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | ||
|- valign="top" class="qt-style" | | |- valign="top" class="qt-style" | | ||
- | ! | + | !Handler class |
- | ! | + | !Description |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|[[Qt:Документация 4.3.2/qxmlcontenthandler | QXmlContentHandler]] | |[[Qt:Документация 4.3.2/qxmlcontenthandler | QXmlContentHandler]] | ||
- | | | + | |Reports events related to the content of a document (e.g. the start tag or characters). |
|- valign="top" class="even" | | |- valign="top" class="even" | | ||
|[[Qt:Документация 4.3.2/qxmldtdhandler | QXmlDTDHandler]] | |[[Qt:Документация 4.3.2/qxmldtdhandler | QXmlDTDHandler]] | ||
- | | | + | |Reports events related to the DTD (e.g. notation declarations). |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|[[Qt:Документация 4.3.2/qxmlerrorhandler | QXmlErrorHandler]] | |[[Qt:Документация 4.3.2/qxmlerrorhandler | QXmlErrorHandler]] | ||
- | | | + | |Reports errors or warnings that occurred during parsing. |
|- valign="top" class="even" | | |- valign="top" class="even" | | ||
|[[Qt:Документация 4.3.2/qxmlentityresolver | QXmlEntityResolver]] | |[[Qt:Документация 4.3.2/qxmlentityresolver | QXmlEntityResolver]] | ||
- | | | + | |Reports external entities during parsing and allows users to resolve external entities themselves instead of leaving it to the reader. |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|[[Qt:Документация 4.3.2/qxmldeclhandler | QXmlDeclHandler]] | |[[Qt:Документация 4.3.2/qxmldeclhandler | QXmlDeclHandler]] | ||
- | | | + | |Reports further DTD related events (e.g. attribute declarations). |
|- valign="top" class="even" | | |- valign="top" class="even" | | ||
|[[Qt:Документация 4.3.2/qxmllexicalhandler | QXmlLexicalHandler]] | |[[Qt:Документация 4.3.2/qxmllexicalhandler | QXmlLexicalHandler]] | ||
- | | | + | |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 [[Qt:Документация 4.3.2/qxmldefaulthandler | QXmlDefaultHandler]] class provides a "do nothing" default implementation for all of them. Therefore users only need to overload the [[Qt:Документация 4.3.2/qxmldefaulthandler | QXmlDefaultHandler]] functions they are interested in. | |
- | + | To read input XML data a special class [[Qt:Документация 4.3.2/qxmlinputsource | QXmlInputSource]] is used. | |
+ | |||
+ | Apart from those already mentioned, the following SAX2 support classes provide additional useful functionality: | ||
- | |||
{| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | {| width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0" | ||
|- valign="top" class="qt-style" | | |- valign="top" class="qt-style" | | ||
- | ! | + | !Class |
- | ! | + | !Description |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|[[Qt:Документация 4.3.2/qxmlattributes | QXmlAttributes]] | |[[Qt:Документация 4.3.2/qxmlattributes | QXmlAttributes]] | ||
- | | | + | |Used to pass attributes in a start element event. |
|- valign="top" class="even" | | |- valign="top" class="even" | | ||
|[[Qt:Документация 4.3.2/qxmllocator | QXmlLocator]] | |[[Qt:Документация 4.3.2/qxmllocator | QXmlLocator]] | ||
- | | | + | |Used to obtain the actual parsing position of an event. |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|[[Qt:Документация 4.3.2/qxmlnamespacesupport | QXmlNamespaceSupport]] | |[[Qt:Документация 4.3.2/qxmlnamespacesupport | QXmlNamespaceSupport]] | ||
- | | | + | |Used to implement namespace support for a reader. Note that namespaces do not change the parsing behavior. They are only reported through the handler. |
|} | |} | ||
- | [[Qt:Документация 4.3.2/xml-saxbookmarks | | + | The [[Qt:Документация 4.3.2/xml-saxbookmarks | SAX Bookmarks example]] illustrates how to subclass [[Qt:Документация 4.3.2/qxmldefaulthandler | QXmlDefaultHandler]] to read an XML bookmark file (XBEL) and how to generate XML by hand. |
- | + | ||
- | + | ||
- | + | ||
- | + | ====SAX2 Features==== | |
+ | The behavior 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 Qt SAX2 implementation can report whether the reader has particular functionality using the [[Qt:Документация 4.3.2/qxmlreader#hasFeature | QXmlReader::hasFeature]]() function. Available features can be tested with [[Qt:Документация 4.3.2/qxmlreader#feature | QXmlReader::feature]](), and switched on or off using [[Qt:Документация 4.3.2/qxmlreader#setFeature | QXmlReader::setFeature]](). | |
- | + | Consider the example | |
<source lang="cpp-qt"> <document xmlns:book = 'http://trolltech.com/fnord/book/' | <source lang="cpp-qt"> <document xmlns:book = 'http://trolltech.com/fnord/book/' | ||
xmlns = 'http://trolltech.com/fnord/' ></source> | xmlns = 'http://trolltech.com/fnord/' ></source> | ||
- | + | 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 [[Qt:Документация 4.3.2/qxmlreader#feature | 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 required, support for ''http://xml.org/sax/features/namespace'' (and thus ''http://xml.org/sax/features/namespace-prefixes'') is mandantory. The [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] implementation of [[Qt:Документация 4.3.2/qxmlreader | QXmlReader]], supports them, and can do namespace processing. | |
- | [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] | + | [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] 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: | |
- | + | #Namespace prefixes and local parts of elements and attributes can be reported. | |
+ | #The qualified names of elements and attributes are reported. | ||
+ | #[[Qt:Документация 4.3.2/qxmlcontenthandler#startPrefixMapping | QXmlContentHandler::startPrefixMapping]]() and [[Qt:Документация 4.3.2/qxmlcontenthandler#endPrefixMapping | QXmlContentHandler::endPrefixMapping]]() are called by the reader. | ||
+ | #Attributes that declare namespaces (i.e. the attribute ''xmlns'' and attributes starting with ''xmlns:'') are reported. | ||
- | + | Consider the following element: | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
<source lang="cpp-qt"> <author xmlns:fnord = 'http://trolltech.com/fnord/' | <source lang="cpp-qt"> <author xmlns:fnord = 'http://trolltech.com/fnord/' | ||
title="Ms" | title="Ms" | ||
fnord:title="Goddess" | fnord:title="Goddess" | ||
name="Eris Kallisti"/></source> | name="Eris Kallisti"/></source> | ||
- | + | 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 Qt 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 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/ http://www.w3.org/2000/xmlns/] to associate ''xmlns'' with the namespace ''http://www.w3.org/2000/xmlns''. | |
- | + | As the SAX2 standard suggests, [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] 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 [[Qt:Документация 4.3.2/qxmlsimplereader#setFeature | QXmlSimpleReader::setFeature]]() note that the combination of both features set to false is illegal. | |
- | + | ||
- | + | ||
- | [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] | + | =====Summary===== |
+ | [[Qt:Документация 4.3.2/qxmlsimplereader | QXmlSimpleReader]] implements the following behavior: | ||
Строка 348: | Строка 322: | ||
|- valign="top" class="qt-style" | | |- valign="top" class="qt-style" | | ||
!(namespaces, namespace-prefixes) | !(namespaces, namespace-prefixes) | ||
- | ! | + | !Namespace prefix and local part |
- | ! | + | !Qualified names |
- | ! | + | !Prefix mapping |
- | ! | + | !xmlns attributes |
|- valign="top" class="odd" | | |- valign="top" class="odd" | | ||
|(true, false) | |(true, false) | ||
Строка 375: | Строка 349: | ||
|} | |} | ||
- | + | The behavior of the entries marked with an asterisk (*) is not specified by SAX. | |
- | + | ||
====Свойства==== | ====Свойства==== | ||
- | |||
Свойства are a more general concept. They have a unique name, represented as an URI, but their value is <tt>void*</tt>. 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. Свойства are useful if a reader supports special handler classes. | Свойства are a more general concept. They have a unique name, represented as an URI, but their value is <tt>void*</tt>. 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. Свойства are useful if a reader supports special handler classes. | ||
Строка 387: | Строка 359: | ||
To set or query properties the following functions are provided: [[Qt:Документация 4.3.2/qxmlreader#setProperty | QXmlReader::setProperty]](), [[Qt:Документация 4.3.2/qxmlreader#property | QXmlReader::property]]() and [[Qt:Документация 4.3.2/qxmlreader#hasProperty | QXmlReader::hasProperty]](). | To set or query properties the following functions are provided: [[Qt:Документация 4.3.2/qxmlreader#setProperty | QXmlReader::setProperty]](), [[Qt:Документация 4.3.2/qxmlreader#property | QXmlReader::property]]() and [[Qt:Документация 4.3.2/qxmlreader#hasProperty | QXmlReader::hasProperty]](). | ||
- | |||
- | === | + | ===The Qt 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. |
- | DOM | + | All DOM nodes in the document tree are subclasses of [[Qt:Документация 4.3.2/qdomnode | QDomNode]]. The document itself is represented as a [[Qt:Документация 4.3.2/qdomdocument | QDomDocument]] object. |
- | + | Here are the available node classes and their potential child classes: | |
- | + | *[[Qt:Документация 4.3.2/qdomdocument | QDomDocument]]: возможные дети | |
- | + | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] (at most one) | |
- | *[[Qt:Документация 4.3.2/qdomdocument | QDomDocument]]: | + | |
- | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] ( | + | |
**[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | **[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | ||
**[[Qt:Документация 4.3.2/qdomcomment | QDomComment]] | **[[Qt:Документация 4.3.2/qdomcomment | QDomComment]] | ||
**[[Qt:Документация 4.3.2/qdomdocumenttype | QDomDocumentType]] | **[[Qt:Документация 4.3.2/qdomdocumenttype | QDomDocumentType]] | ||
- | *[[Qt:Документация 4.3.2/qdomdocumentfragment | QDomDocumentFragment]]: | + | *[[Qt:Документация 4.3.2/qdomdocumentfragment | QDomDocumentFragment]]: возможные дети |
**[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | ||
**[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | **[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | ||
Строка 413: | Строка 382: | ||
**[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | **[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | ||
- | *[[Qt:Документация 4.3.2/qdomdocumenttype | QDomDocumentType]]: нет | + | *[[Qt:Документация 4.3.2/qdomdocumenttype | QDomDocumentType]]: детей нет |
- | *[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]]: | + | *[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]]: возможные дети |
**[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | ||
**[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | **[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | ||
Строка 422: | Строка 391: | ||
**[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | **[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | ||
- | *[[Qt:Документация 4.3.2/qdomelement | QDomElement]]: | + | *[[Qt:Документация 4.3.2/qdomelement | QDomElement]]: возможные дети |
**[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | ||
**[[Qt:Документация 4.3.2/qdomtext | QDomText]] | **[[Qt:Документация 4.3.2/qdomtext | QDomText]] | ||
Строка 430: | Строка 399: | ||
**[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | **[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | ||
- | *[[Qt:Документация 4.3.2/qdomattr | QDomAttr]]: | + | *[[Qt:Документация 4.3.2/qdomattr | QDomAttr]]: возможные дети |
**[[Qt:Документация 4.3.2/qdomtext | QDomText]] | **[[Qt:Документация 4.3.2/qdomtext | QDomText]] | ||
**[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | **[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | ||
- | *[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]]: нет | + | *[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]]: детей нет |
- | *[[Qt:Документация 4.3.2/qdomcomment | QDomComment]]: | + | *[[Qt:Документация 4.3.2/qdomcomment | QDomComment]]: детей нет |
- | *[[Qt:Документация 4.3.2/qdomtext | QDomText]]: нет | + | *[[Qt:Документация 4.3.2/qdomtext | QDomText]]: детей нет |
- | *[[Qt:Документация 4.3.2/qdomcdatasection | QDomCDATASection]]: нет | + | *[[Qt:Документация 4.3.2/qdomcdatasection | QDomCDATASection]]: детей нет |
- | *[[Qt:Документация 4.3.2/qdomentity | QDomEntity]]: | + | *[[Qt:Документация 4.3.2/qdomentity | QDomEntity]]: возможные дети |
**[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | **[[Qt:Документация 4.3.2/qdomelement | QDomElement]] | ||
**[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | **[[Qt:Документация 4.3.2/qdomprocessinginstruction | QDomProcessingInstruction]] | ||
Строка 446: | Строка 415: | ||
**[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | **[[Qt:Документация 4.3.2/qdomentityreference | QDomEntityReference]] | ||
- | *[[Qt:Документация 4.3.2/qdomnotation | QDomNotation]]: нет | + | *[[Qt:Документация 4.3.2/qdomnotation | QDomNotation]]: детей нет |
- | [[Qt:Документация 4.3.2/qdomnodelist | QDomNodeList]] | + | With [[Qt:Документация 4.3.2/qdomnodelist | QDomNodeList]] and [[Qt:Документация 4.3.2/qdomnamednodemap | QDomNamedNodeMap]] two collection classes are provided: [[Qt:Документация 4.3.2/qdomnodelist | QDomNodeList]] is a list of nodes, and [[Qt:Документация 4.3.2/qdomnamednodemap | QDomNamedNodeMap]] is used to handle unordered sets of nodes (often used for attributes). |
- | + | The [[Qt:Документация 4.3.2/qdomimplementation | QDomImplementation]] class allows the user to query features of the DOM implementation. | |
- | + | To get started please refer to the [[Qt:Документация 4.3.2/qdomdocument | QDomDocument]] documentation. You might also want to take a look at the [[Qt:Документация 4.3.2/xml-dombookmarks | DOM Bookmarks example]], which illustrates how to read and write an XML bookmark file (XBEL) using DOM. | |
- | + | ||
- | === | + | ===An Introduction to Namespaces=== |
+ | Parts of the Qt XML module documentation assume that you are familiar with XML namespaces. Here we present a brief introduction; skip to [[#namespacesconventions | Qt 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: | |
- | + | ||
- | + | ||
<source lang="cpp-qt"> <document> | <source lang="cpp-qt"> <document> | ||
<book> | <book> | ||
Строка 471: | Строка 438: | ||
</book> | </book> | ||
</document></source> | </document></source> | ||
- | + | 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.: | |
<source lang="cpp-qt"> <book:title>Practical XML</book:title></source> | <source lang="cpp-qt"> <book:title>Practical XML</book:title></source> | ||
- | + | ''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 | |
<source lang="cpp-qt"> xmlns="http://trolltech.com/fnord/"</source> | <source lang="cpp-qt"> xmlns="http://trolltech.com/fnord/"</source> | ||
- | + | To distinguish the ''http://trolltech.com/fnord/book/'' namespace from the default, we must supply it with a prefix: | |
<source lang="cpp-qt"> xmlns:book="http://trolltech.com/fnord/book/"</source> | <source lang="cpp-qt"> xmlns:book="http://trolltech.com/fnord/book/"</source> | ||
- | + | 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: | |
<source lang="cpp-qt"> <document xmlns:book = 'http://trolltech.com/fnord/book/' | <source lang="cpp-qt"> <document xmlns:book = 'http://trolltech.com/fnord/book/' | ||
xmlns = 'http://trolltech.com/fnord/' > | xmlns = 'http://trolltech.com/fnord/' > | ||
Строка 505: | Строка 472: | ||
</book> | </book> | ||
</document></source> | </document></source> | ||
- | + | 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 quite complex: | |
- | * | + | *attributes without a prefix don't belong to any XML namespace at all, not even to the default namespace; |
- | * | + | *additionally omitting the prefix would lead to a ''title-title'' clash; |
- | * | + | *writing it as ''xmlns:title'' would declare a new namespace with the prefix ''title'' instead of applying the default ''xmlns'' namespace. |
- | + | With the Qt 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/ http://www.w3.org/TR/REC-xml-names/]. | |
- | + | ||
- | + | ||
- | + | ====Conventions Used in the Qt XML Documentation==== | |
+ | The following terms are used to distinguish the parts of names within the context of namespaces: | ||
- | * | + | *The ''qualified name'' is the name as it appears in the document. (In the above example ''book:title'' is a qualified name.) |
- | * | + | *A ''namespace prefix'' in a qualified name is the part to the left of the ":". (''book'' is the namespace prefix in ''book:title''.) |
- | *'' | + | *The ''local part'' of a name (also refered to as the ''local name'') appears to the right of the ":". (Thus ''title'' is the local part of ''book:title''.) |
- | * | + | *The ''namespace URI'' ("Uniform Resource Identifier") is a unique identifier for a namespace. It looks like a URL (e.g. ''http://trolltech.com/fnord/'' ) but does not require data to be accessible by the given protocol at the named address. |
- | + | 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''). | |
- | + | See also [[Qt:Документация 4.3.2/xml-dombookmarks | DOM Bookmarks Example]] and [[Qt:Документация 4.3.2/xml-saxbookmarks | SAX Bookmarks Example]]. | |
- | [Previous: [[Qt:Документация 4.3.2/qtsvg | QtSvg Module]] ] | + | [Previous: [[Qt:Документация 4.3.2/qtsvg | QtSvg Module]]] [ [[Qt:Документация 4.3.2/modules | Qt's Modules]] ] [Next: [[Qt:Документация 4.3.2/qtdesigner | QtDesigner Module]]] |
{{Qt4.3.2_footer}} | {{Qt4.3.2_footer}} |