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

Текущая версия на 17:35, 18 января 2009

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

__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

Поведение модуля чтения (reader) XML зависит от того, как он поддерживает ряд необязательных опций. Например, модуль чтения может иметь возможность "выдача атрибутов, используемых для объявления префикса пространства имен и связывания префикса с локальным именем тега". Подобно другим, данная возможность имеет уникальное имя, представленное URI: http://xml.org/sax/features/namespace-prefixes.

Реализация SAX2 в Qt позволяет определить, может ли модуль чтения иметь не стандартную функциональность . Для этого используется функция QXmlReader::hasFeature(). Доступные особенности могут определяться с помощью QXmlReader::feature(). Их можно включать и отключать используя QXmlReader::setFeature().

Возьмем следующий пример

 <document xmlns:book = 'http://trolltech.com/fnord/book/'
           xmlns      = 'http://trolltech.com/fnord/' >

Модуль чтения, который не поддерживает опцию http://xml.org/sax/features/namespace-prefixes будет выдавать имя элемента document, но без его атрибутов xmlns:book и xmlns и их значений. Модуль чтения с поддержкой опции http://xml.org/sax/features/namespace-prefixes выдаст атрибуты пространства имен, если feature включен.

Другие особенности включают http://xml.org/sax/features/namespace (обработка пространства имен, полагая http://xml.org/sax/features/namespace-prefixes) и http://xml.org/sax/features/validation (способность выдавать ошибки проверки на соответствие схеме).

В том случае, если SAX2 предоставляет возможность пользователю задавать и выполнять требуемые особенности, поддержка http://xml.org/sax/features/namespace (а также http://xml.org/sax/features/namespace-prefixes) обязательна. Функциональность QXmlSimpleReader из QXmlReader, поддерживает их, и позволяя обрабатывать пространства имен.

QXmlSimpleReader не проверяет на соответствие схеме, поскольку он не поддерживает http://xml.org/sax/features/validation.

[править] Поддержка пространства имен посредством опций

Как показано в предыдущем разделе, мы можем конфигурировать правила работы модуля чтения, когда он получает управление для обработки пространства имен. Это выполняется посредством задания и отключения опций http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes.

Они влияют на алгоритм поведения в следующих случаях:

1. При отображении префиксов пространств имен и локальных частей элементов и атрибутов.
2. При отображении квалификационных имен элементов и атрибутов.
3. При вызове модулем чтения QXmlContentHandler::startPrefixMapping() и QXmlContentHandler::endPrefixMapping().
4. При отображении атрибутов, которые объявляют пространства имен (т.е. атрибута xmlns и атрибутов, начинающиеся с xmlns:).

Возьмем следующий элемент:

 <author xmlns:fnord = 'http://trolltech.com/fnord/'
              title="Ms"
              fnord:title="Goddess"
              name="Eris Kallisti"/>

Если установить http://xml.org/sax/features/namespace-prefixes в true, то модуль чтения будет отображать четыре атирибута; но установив опцию namespace-prefixes в false только три. Атрибут xmlns:fnord, определяющий пространство имен "невидим" для модуля чтения.

Опция http://xml.org/sax/features/namespaces отвечает за видимость локальных имен, префиксов пространства имен и URI. В случае установки http://xml.org/sax/features/namespaces в true, парсер отобразит title как локальное имя атрибута fnord:title, fnord как префикс пространства имен и http://trolltech.com/fnord/ как URI пространства имен. Когда http://xml.org/sax/features/namespaces установлен в false они не будут отображаться.

В текущей версии классов Qt XML определено, что префикс xmlns самостоятельно не сопоставляется ни с каким пространством имен (см. http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using). Следовательно, даже если и http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes установлены в true, модуль чтения не сможет вернуть ни локальное именя, ни префикс пространства имен, ни URI пространства имен для xmlns:fnord.

Возможно это изменится в будущем, когда W3C даст указание http://www.w3.org/2000/xmlns/ связывать xmlns с пространством имен http://www.w3.org/2000/xmlns.

Стандарт SAX2 предлагает, значение по умолчанию для QXmlSimpleReader http://xml.org/sax/features/namespaces установлено в true, а для http://xml.org/sax/features/namespace-prefixes в false. Отметим, что комбинация QXmlSimpleReader::setFeature(), связанная с установлением обеих опций в false является незаконной.

[править] Заключение

QXmlSimpleReader поддерживает следующие правила:

Поведение записей, отмеченных звездочкой (*) не определено в 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 ]