Материал из Wiki.crossplatform.ru

Внимание: Актуальная версия перевода документации находится здесь

__NOTOC__

[Предыдущая: Модуль QtScript ] [ Модули Qt ] [Следующая: Модуль QtDesigner ]

Модуль QtXml

Модуль QtXml обеспечивает работу с потоками чтения и записи XML документов и реализацию их в форме SAX и DOM. Далее...

Классы

Подробное описание

SAX это стандартный, основанный на событиях интерфейс для XML парсеров. Qt интерфейс соответствует возможностям SAX2 Java. Его схема именования была адаптирована согласно соглашений именования, принятых в Qt. Подробное описание SAX2 может быть найдено на http://www.saxproject.org.

Поддержка для фильтров SAX2 и reader factory находятся в стадии разработки. Данная версия Qt не обеспечивает совместимости с классами SAX1, представленными в Java интерфейсе. Введение в классы Qt SAX2 смотрите на Классы Qt SAX2.

DOM Level 2 это W3C Recommendation для XML интерфейсов, которые отображают содержание XML документа в виде дерева. Спецификация DOM Level 2 может быть найдена на http://www.w3.org/DOM/. Дополнительную информацию о классах DOM в Qt представлена в Классы Qt DOM.

Начиная с версии 4.3, Qt ввела два новых класса для чтения и записи XML: QXmlStreamReader и QXmlStreamWriter.

Дополнительно возможности XML обеспечивают QSvgRenderer чтение поднабора SVG. Также развитие XML осуществляется группой Qt Solutions, которая разрабатывает, например, классы для поддержки SOAP и MML на основе классов Qt XML.

Для подключения модуля с классами нужно использовать следующую директиву:

 #include <QtXml>

Чтобы соединиться с модулем добавьте данную строку в ваш qmake .pro файл:

 QT += xml

Данный модуль это часть Qt Console Edition, Qt Desktop Edition и Qt Open Source Edition.

Разделы:

• Конфигурирование процесса сборки
• Классы потока QtXml
• Классы Qt SAX2
  • Введение в SAX2
  • Особенности SAX2
  • Поддержка пространства имен
    • Итоги
  • Свойства
• Классы Qt DOM
  • Введение в DOM
• Введение в пространство имен
  • Соглашения, используемые в документации Qt XML

Конфигурирование процесса сборки

Приложения, использующие классы Qt XML, должны быть собраны вместе с модулем QtXml. Следующее объявление в qmake файла проекта гарантирует, что приложение скомпилируется и отредактируется (linked) соответствующим образом:

 QT += xml

Данная строка необходима, поскольку только модули QtCore и QtGui используются по умолчанию в процессе сборки.

Классы потока QtXml

QXmlStreamReader и QXmlStreamWriter это два новых класса, появившихся начиная с версии Qt 4.3. Потоковый модуль чтения представляет XML документ как поток токенов (tokens). Это отличие от SAX, т.к. SAX приложения обеспечивают обработку поступающих событий XML от парсера, тогда как QXmlStreamReader передача осуществляется циклически, втягивая токены из модуля чтения, когда они требуются. Данный подход, основанный на втягивании, предоставляет возможность строить парсеры с рекурсивной обработкой, позволяя разделить код, выполняющий синтаксический анализ XML, на различные методы и классы.

QXmlStreamReader это парсеры, обеспечивающие обработку правильных (well-formed) XML документов, за исключением внешних сущностей. Следовательно, данные обрабатываемые потоковым модулем чтения удовлетворяют критерию W3C для правильных (well-formed) XML, что позволит избежать ошибок. С другой стороны, такие функции как atEnd(), error() и hasError() могут быть использованы для проверки и отображения ошибок.

Примером использования QXmlStreamReader может быть XbelReader в QXmlStream Bookmarks Example, который является подклассом QXmlStreamReder. Конструктор принимает treeWidget в качестве параметра и класс получает доступ к специфическим функциям Xbel:

     XbelReader(QTreeWidget *treeWidget);
     ...
     void readUnknownElement();
     void readXBEL();
     void readTitle(QTreeWidgetItem *item);
     void readSeparator(QTreeWidgetItem *item);
     void readFolder(QTreeWidgetItem *item);
     void readBookmark(QTreeWidgetItem *item);
 
     QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);
 
     QTreeWidget *treeWidget;
     ...

Функция read() принимает QIODevice и пердает его в setDevice(). Функция raiseError() используется для отображения пользовательских сообщений об ошибках, показывая, что версия файла некорректна.

 bool XbelReader::read(QIODevice *device)
 {
     setDevice(device);
 
     while (!atEnd()) {
         readNext();
 
         if (isStartElement()) {
             if (name() == "xbel" && attributes().value("version") == "1.0")
                 readXBEL();
             else
                 raiseError(QObject::tr("Файл не является файлом XBEL версии 1.0."));
         }
     }
 
     return !error();
 }

Дополнением к QXmlStreamReader является QXmlStreamWriter. Он представляет собой модуль записи XML с простым потоковым API. QXmlStreamWriter функционирует на основе QIODevice. Он включает специальные функции для токенов или событий XML, которые вы хотите записать. Это writeDTD(), writeCharacters(), writeComment() и т.д.

Для того, чтобы записать XML документ с помощью QXmlStreamWriter, документ должен начинаться с функции writeStartDocument() и заканчиваться функцией writeEndDocument(), которая закроет все оставшиеся открытые теги. Теги элементов открываются writeStartDocument(), далее следуют writeAttribute() или writeAttributes(), содержание элемента и в конце writeEndDocument(). Для записи пустого элемента может быть использован writeEmptyElement().

Содержание элемента представляет собой набор символов, ссылки на сущности или вложенные элементы. Содержание может быть записано посредством writeCharacters(), которая также удаляет запрещённые символы и символьные последовательности, writeEntityReference() , или последующими вызовами к writeStartElement().

Класс XbelWriter из QXmlStream Bookmarks Example является подклассом QXmlStreamWriter. Его функция writeFile() представляет базовые функции QXmlStreamWriter, которые упоминались выше:

 bool XbelWriter::writeFile(QIODevice *device)
 {
     setDevice(device);
 
     writeStartDocument();
     writeDTD("<!DOCTYPE xbel>");
     writeStartElement("xbel");
     writeAttribute("version", "1.0");
     for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
         writeItem(treeWidget->topLevelItem(i));
 
     writeEndDocument();
     return true;
 }

Классы Qt SAX2

Введение в SAX2

Интерфейс SAX2 - это механизм основанный на событиях для представления пользователю информации документа. В данном контексте "событие" ("event") это реакция парсера, например, на его встречу с начальным или конечным тегом.

Для большей конкретики давайте рассмотрим следующий пример:

 <quote>A quotation.</quote>

В процессе чтения (парсер SAX2 обычно называют читающий парсер ("reader")) представленного выше документа произойдет три события:

1. Встретится начальный тег (<quote>).
2. Обнаружены символьные данные (т.е. текст), "A quotation.".
3. Обработан конечный тег (</quote>).

Каждый раз, когда произойдет одно из событий парсер отреагирует на него. Вы можете установить обработчик событий для их перехвата.

Представленный подход обеспечивает быстрое чтение XML документа, однако его обработка достаточно трудоемка, поскольку данные не сохраняются в памяти. Они последовательно обрабатываются и отбрасываются. Интерфейс DOM читает и сохраняет весь документ, представляя его в виде дерева. Этот подход требует больше памяти, но позволяет более легко обрабатывать документ.

Модуль Qt XML включает абстрактный класс, QXmlReader. Он определяет интерфейс для потенциальной программы чтения согласно SAX2. Qt включает и собственный модуль чтения QXmlSimpleReader, который легко адаптируется посредством подклассов.

Модуль чтения во время синтаксического анализа реагирует на события через специальные классы обработки:

Данные классы это абстрактные классы описываемого интерфейса. Класс QXmlDefaultHandler обеспечивает по умолчанию для всех остальных классов "пустые действия" ("do nothing"). Следовательно пользователям необходимо только перегрузить функции QXmlDefaultHandler в зависимости от своих интересов.

Для чтения входных XML данных используется специальный класс QXmlInputSource.

Следующие классы поддержки SAX2 обеспечивают дополнительную полезную функциональность. Некоторые из них уже упоминались.

Пример SAX Bookmarks показывает как в подклассе QXmlDefaultHandler выполняется чтение XML bookmark файла (XBEL) и как генерировать XML вручную.

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 QXmlReader::hasFeature() function. Available features can be tested with QXmlReader::feature(), and switched on or off using QXmlReader::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 required, support for http://xml.org/sax/features/namespace (and thus http://xml.org/sax/features/namespace-prefixes) is mandantory. The QXmlSimpleReader implementation of QXmlReader, supports them, and can do namespace processing.

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:

1. Namespace prefixes and local parts of elements and attributes can be reported.
2. The qualified names of elements and attributes are reported.
3. QXmlContentHandler::startPrefixMapping() and QXmlContentHandler::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 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). 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, 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 QXmlSimpleReader::setFeature() note that the combination of both features set to false is illegal.

Summary

QXmlSimpleReader implements the following behavior:

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 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. Свойства 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 required 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: QXmlReader::setProperty(), QXmlReader::property() and QXmlReader::hasProperty().

Классы Qt DOM

Введение в DOM

DOM представляет интерфейс для доступа или изменения содержания и структуры XML файла. Он формирует иерархическое представление документа (представление в виде дерева). В противоположность интерфейсу SAX2 , объектная модель документа после синтаксического анализа располагается в памяти, что позволяет легко ей манипулировать.

Все узлы DOM в дереве документа являются подклассами QDomNode. Сам документ представляется как объект QDomDocument.

Ниже представлены доступные классы узлов и указано - есть ли у них дочерние классы:

• QDomDocument: возможны дочерние классы
  • QDomElement (максимум один)
  • QDomProcessingInstruction
  • QDomComment
  • QDomDocumentType

• QDomDocumentFragment: возможны дочерние классы
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference

• QDomDocumentType: нет дочерних классов
• QDomEntityReference: возможны дочерние классы
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference

• QDomElement: возможны дочерние классы
  • QDomElement
  • QDomText
  • QDomComment
  • QDomProcessingInstruction
  • QDomCDATASection
  • QDomEntityReference

• QDomAttr: возможны дочерние классы
  • QDomText
  • QDomEntityReference

• QDomProcessingInstruction: нет дочерних классов
• QDomComment: возможны дочерние классы
• QDomText: нет дочерних классов
• QDomCDATASection: нет дочерних классов
• QDomEntity: возможны дочерние классы
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference

• QDomNotation: нет дочерних классов

QDomNodeList и QDomNamedNodeMap - две коллекции классов, которые обеспечивают: QDomNodeList - список узлов, а QDomNamedNodeMap обработку неупорядоченного набора узлов (часто используется для атрибутов).

Класс QDomImplementation позволяет пользователю запрашивать особенности обработки DOM.

Прежде чем начать работать пожалуйста посмотрите документацию QDomDocument. Вы также можете захотеть посмотреть пример DOM Bookmarks, который иллюстрирует применение DOM для чтения и записи закладок XML файла (XBEL).

Введение в пространство имен (NameSpace)

Часть разделов документации Qt XML module предполагает, что вы знакомы с пространством имен XML. Здесь мы даем краткое введение. Если вы знакомы с Qt XML documentation conventions, то можете пропустить данный материал.

Пространство имен - это концепция, введенная в XML, чтобы позволить осуществлять более модульное проектирование. С его помощью во время программной обработки данных можно легко разрешить конфликты именования имен в XML документах.

Рассмотрим следующий пример:

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

Здесь можно увидеть три различных использования имени title. Если вы захотите обработать данный документ, то у вас появятся проблемы, поскольку каждый из titles должен представляться в разной манере, несмотря на то, что используется одно и тоже имя.

Решение должно основываться на неком способе, позволяющем идентифицировать первый title как название книги, т.е. использовать элемент title в пространстве имен книги для отличия его, например, от названия раздела:

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

В данном случае book является префиксом, указывающим на пространство имен.

До того, как применять пространство имен для элементов и атрибутов, необходимо его объявить.

Пространство имен подобно URI: http://trolltech.com/fnord/book/. Данное URI не указывает, что по этому адресу должны быть доступны данные. URI просто используется для задания уникального имени.

Мы указываем пространства имен точно также как и атрибуты. Строго говоря они и есть атрибуты. Для того, чтобы объявить пространство имен документа http://trolltech.com/fnord/ как пространство имен по умолчанию, мы должны написать

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

Чтобы отличить пространство имен http://trolltech.com/fnord/book/ от пространства имен по умолчанию, мы должны использовать префикс:

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

Пространство имен, объявленное таким образом, может быть добавлено к именам элементов и атрибутов посредством префикса и разделителя ":". Мы уже видели это у элемента book:title.

Имена элементов без префикса принадлежат пространству имен по умолчанию. Данное правило не распространяется на атрибуты. Атрибут без префикса вообще не принадлежит никакому объявленному пространству имен XML. Атрибуты всегда принадлежат к "традиционному" пространству имен элемента, с которым они применяются. "Традиционное" пространства имен это не пространства имен XML. Просто предполагается, что все имена атрибутов, принадлежащие одному элементу, должны быть разными. Далее мы увидим как назначается пространство имен XML для атрибута.

Фактически атрибуты без префикса не принадлежат никакому пространству имен XML, при этом нет коллизии между атрибутом title (который принадлежит элементу author) и, например, элементом title в контейнере chapter.

Давайте проясним это на примере:

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

В элементе document мы имеем два объявления пространства имен. Пространство имен по умолчанию http://trolltech.com/fnord/ применяется к элементу book, элементу chapter, соответствующему элементу title и, конечно, к самому элементу document.

Элементы book:author и book:title принадлежат пространству имен, идентифицируемому URI http://trolltech.com/fnord/book/.

Двум атрибутам title и name элемента book:author не назначено пространство имен XML. Они являются членами "традиционного" пространства имен элемента book:author. Это означает, что, например, два атрибута title в book:author недопустимо.

Выше в примере мы обошли данное правило. Мы объявили пространство имен http://trolltech.com/fnord/ с префиксом fnord в элементе book:author и добавили этот префикс к атрибуту title элемента book:author.

Очевидно, пространство имен fnord имеет точно такое же URI, что и пространство имен по умолчанию. Почему же мы просто не использовали ранее объявленное пространство имен по умолчанию? Ответ не совсем простой:

• атрибуты без префикса вообще не принадлежат никакому пространству имен, даже пространству имен по умолчанию;
• пренебрежение префиксом будет приводить к конфликту типа title-title;
• запись префикса как xmlns:title позволит объявить новое пространство имен с префиксом title вместо используемого пространства имен по умолчанию xmlns.

Используя классы Qt XML доступ к элементам и атрибутам может осуществляться двумя способами: либо ссылаясь на их квалифицированные имена, включающие префикс пространства имен и "реальное" имя (или "локальное" имя), либо используя комбинацию локального имени и URI пространства имен.

Дополнительную информацию о пространстве имен XML можно найти на http://www.w3.org/TR/REC-xml-names/.

Conventions Used in the Qt XML Documentation

Следующие термины используются для различия частей имен в контексте пространства имен:

• квалифицированное имя (qualified name) - это имя как оно представляется в документе. (В примерах, представленных выше, book:title это квалифицированное имя.)
• префикс пространства имен (namespace prefix) - часть квалифицированного имени слева от ":". (book - это префикс пространства имен в book:title.)
• локальная часть (local part) - часть квалифицированного имени справа от ":" (иногда ее называют локальное имя (local name)). (title - локальная часть часть book:title.)
• пространство имен URI (namespace URI ("Uniform Resource Identifier")) - это уникальный идентификатор пространства имен. Внешне он выглядит подобно URL (например, http://trolltech.com/fnord/ ), но не требует, чтобы по этому адресу были доступны какие-либо данные.

Элементы без ":" (в примере подобно chapter) не имеют префикса пространства имен. В этом случае локальная часть и квалифицированное имя идентичны (например, chapter).

Также смотрите DOM Bookmarks Example и SAX Bookmarks Example.

[Previous: QtSvg Module ] [ Qt's Modules ] [Next: QtDesigner Module ]