Главная · Все классы · Основные классы · Классы по группам · Модули · Функции

Описание класса QDomDocument
[модуль QtXml]

Класс QDomDocument служит для представления XML-документа. Далее...

 #include <QDomDocument>

Унаследован от QDomNode.

Замечание: Все функции в этом классе реентерабельны.

Открытые функции


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

Класс QDomDocument служит для представления XML-документа.

Класс QDomDocument представляет содержимое XML-документа. В принципе, это корень документа и отправная точка для анализа содержащихся в документе данных.

Поскольку элементы, текстовые узлы, комментарии, инструкции обработки и т.д. не могут существовать вне контекста документа, в этом классе также содержатся функции-фабрики, необходимые для создания таких объектов. Объекты узлов создаются с помощью функции ownerDocument(), которая связывает их с документом, учитывая контекст, в котором они были созданы. Наиболее часто используемыми DOM-классами являются QDomNode, QDomDocument, QDomElement и QDomText.

При разборе XML-документ представляется в виде дерева объектов, в качестве которых можно использовать классы QDom. Все объекты классов QDom являются всего лишь ссылками (reference) на внутреннее дерево. Объекты внутреннего дерева существуют до тех пор, пока на них есть ссылки объектов классов QDom и пока существует объект QDomDocument.

При создании элементов, текстовых узлов и т.д. используются различные функции-фабрики, реализованные в этом классе. Использование конструкторов по умолчанию классов QDom приведет к созданию пустых объектов, которыми невозможно будет манипулировать или вставлять в документ.

Класс QDomDocument имеет несколько функций для создания данных, например, createElement(), createTextNode(), createComment(), createCDATASection(), createProcessingInstruction(), createAttribute() и createEntityReference(). Некоторые из этих функций имеют реализации, поддерживающие пространства имен, например, createElementNS() и createAttributeNS(). Функция createDocumentFragment() используется для манипулирования частью документа; это может быть полезно при работе со сложными документами.

Содержимое документа устанавливается с помощью setContent(). Эта функция анализирует строку как XML-документ и создает по нему дерево DOM. Корневой элемент доступен через функцию documentElement(). Текстовое представление документа может быть получено с помощью функции toString().

Можно вставить узлы из одного документа в другой с помощью функции importNode().

Вы можете получить список всех элементов, которые имеют одно имя, посредством elementsByTagName() или elementsByTagNameNS().

Пример использования классов QDom приведен ниже:

 QDomDocument doc("mydocument");
 QFile file("mydocument.xml");
 if (!file.open(QIODevice::ReadOnly))
     return;
 if (!doc.setContent(&file)) {
     file.close();
     return;
 }
 file.close();

 // печатает имена всех непосредственных потомков
 // внешнего элемента.
 QDomElement docElem = doc.documentElement();

 QDomNode n = docElem.firstChild();
 while(!n.isNull()) {
     QDomElement e = n.toElement(); // пробуем преобразовать узел в элемент.
     if(!e.isNull()) {
         cout << e.tagName() << endl; // the node really is an element.
     }
     n = n.nextSibling();
 }

 // Здесь мы присоединяем элемент в конец документа
 QDomElement elem = doc.createElement("img");
 elem.setAttribute("src", "myimage.png");
 docElem.appendChild(elem);

После того, как doc и elem выйдут из области видимости, все внутреннее дерево, представляющее XML документ, будет уничтожено.

Пример создания документа, используя DOM, приведен ниже:

 QDomDocument doc("MyML");
 QDomElement root = doc.createElement("MyML");
 doc.appendChild(root);

 QDomElement tag = doc.createElement("Greeting");
 root.appendChild(tag);

 QDomText t = doc.createTextNode("Hello World");
 tag.appendChild(t);

 QString xml = doc.toString();

Для получения более подробной информации о Document Object Model смотрите спецификацию DOM Уровень 1 и Уровень 2 .

Смотрите также Пример DOM Bookmarks и Пример Simple DOM Model.


Описание функций-членов

QDomDocument::QDomDocument ()

Создает пустой документ.

QDomDocument::QDomDocument ( const QString & name )

Создает документ и устанавливает название типа документа как name.

QDomDocument::QDomDocument ( const QDomDocumentType & doctype )

Создает документ с типом doctype.

Смотрите также QDomImplementation::createDocumentType().

QDomDocument::QDomDocument ( const QDomDocument & x )

Создаёт копию x

Данные в копиях общие (поверхностное копирование): изменение одного узла повлечет за собой изменение другого. Если вы хотите использовать глубокое копирование, воспользуйтесь cloneNode().

QDomDocument::~QDomDocument ()

Уничтожает объекты и освобождает их ресурсы.

QDomAttr QDomDocument::createAttribute ( const QString & name )

Создает новый атрибут, который называется name и может быть вставлен в элемент (используя QDomElement::setAttributeNode()).

Если name не является правильным XML именем, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также createAttributeNS().

QDomAttr QDomDocument::createAttributeNS ( const QString & nsURI, const QString & qName )

Создает новый атрибут с поддержкой пространств имен, который может быть вставлен в элемент. Имя атрибута - qName, а ссылка пространства имен - nsURI. Эта функция также устанавливает QDomNode::prefix() и QDomNode::localName() в соответствующие значения (зависящие от qName).

Если qName не является правильным XML именем, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также createAttribute().

QDomCDATASection QDomDocument::createCDATASection ( const QString & value )

Создает новую область CDATA и помещает value в качестве ее содержимого. Может быть вставлено в документ с помощью QDomNode::appendChild().

Если value содержит символы, которые не могут быть сохранены в CDATA, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также QDomNode::appendChild(), QDomNode::insertBefore() и QDomNode::insertAfter().

QDomComment QDomDocument::createComment ( const QString & value )

Создает новый комментарий из строки value, который может быть вставлен в документ с помощью QDomNode::appendChild().

Если value содержит символы, которые не могут быть сохранены в комментарии XML, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также QDomNode::appendChild(), QDomNode::insertBefore() и QDomNode::insertAfter().

QDomDocumentFragment QDomDocument::createDocumentFragment ()

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

QDomElement QDomDocument::createElement ( const QString & tagName )

Создает новый элемент с именем tagName, который может быть вставлен в дерево DOM, используя QDomNode::appendChild().

Если tagName не является корректным XML именем, поведение этой функции определяется QDomImplementation::InvalidDataPolicy.

QDomNode::insertAfter()

Смотрите также createElementNS(), QDomNode::appendChild() и QDomNode::insertBefore().

QDomElement QDomDocument::createElementNS ( const QString & nsURI, const QString & qName )

Создает новый элемент с поддержкой пространств имен, который может быть вставлен в дерево DOM. Имя элемента определяется параметром qName, а URI пространства имен - nsURI. Эта функция также устанавливает QDomNode::prefix() и QDomNode::localName() в соответствующие значения (зависящие от qName).

Если qName является пустой строкой, возвращается нулевой элемент.

Смотрите также createElement().

QDomEntityReference QDomDocument::createEntityReference ( const QString & name )

Создает новую ссылку на сущность с именем name, которая может быть вставлена в документ с помощью функции QDomNode::appendChild().

Если name не является правильным XML именем, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также QDomNode::appendChild(), QDomNode::insertBefore() и QDomNode::insertAfter().

QDomProcessingInstruction QDomDocument::createProcessingInstruction ( const QString & target, const QString & data )

Создает новую инструкцию обработки, которая может быть добавлена в документ, например, с помощью функции QDomNode::appendChild(). Эта функция определяет целью инструкции target и данными data.

Если target не является корректным XML именем, или данные содержат символы, которые не могут быть использованы в инструкции обработки, поведение функции определяется QDomImplementation::InvalidDataPolicy.

Смотрите также QDomNode::appendChild(), QDomNode::insertBefore() и QDomNode::insertAfter().

QDomText QDomDocument::createTextNode ( const QString & value )

Создает текстовый узел из строки value, который может быть вставлен в дерево документа с помощью функции QDomNode::appendChild().

Если value содержит символы, которые не могут быть сохранены как данные в XML-документе (даже в форме символьных ссылок), поведение этих функций определяется QDomImplementation::InvalidDataPolicy.

Смотрите также QDomNode::appendChild(), QDomNode::insertBefore() и QDomNode::insertAfter().

QDomDocumentType QDomDocument::doctype () const

Возвращает тип текущего документа.

QDomElement QDomDocument::documentElement () const

Возвращает корневой элемент текущего документа.

QDomElement QDomDocument::elementById ( const QString & elementId )

Возвращает элемент, идентификатор (ID) которого равен elementId. Если такой элементы не найден, функция возвращает нулевой элемент.

Пока QDomClasses не знает какой из атрибутов является идентификатором, функция всегда возвращает нулевой элемент. Данное поведение может быть изменено в будущих версиях.

QDomNodeList QDomDocument::elementsByTagName ( const QString & tagname ) const

Возвращает QDomNodeList, который содержит все элементы документа с именем tagname. Порядок элементов в списке определяется тем, как они встречаются при обходе в ширину всего дерева.

Смотрите также elementsByTagNameNS() и QDomElement::elementsByTagName().

QDomNodeList QDomDocument::elementsByTagNameNS ( const QString & nsURI, const QString & localName )

Возвращает QDomNodeList, который содержит все элементы документа с локальным именем localName и URI пространства имен nsURI. Порядок элементов в списке определяется тем, как они встречаются при обходе в ширину всего дерева.

Смотрите также elementsByTagName() и QDomElement::elementsByTagNameNS().

QDomImplementation QDomDocument::implementation () const

Возвращает объект QDomImplementation.

QDomNode QDomDocument::importNode ( const QDomNode & importedNode, bool deep )

Импортирует узел importedNode из другого документа в текущий. importedNode остается в исходном документе; функция создает копию этого элемента, которая может быть использована независимо от исходного документа.

Функция возвращает импортированный узел, содержащийся в текущем документе. Возвращенный узел не имеет родителей. Его невозможно импортировать QDomDocument и узлы QDomDocumentType. В этом случае функция возвращает нулевой узел.

Если deep установлен в true, функция импортирует не только узел importedNode, но и целое поддерево; если установлен в false, импортируется только importedNode. Аргумент deep не влияет на узлы QDomAttr и QDomEntityReference, поскольку потомки узлов QDomAttr всегда импортируются, в то время как узлы QDomEntityReference не импортируются никогда.

Поведение этой функции несколько отличается в зависимости от вида узла:

Тип узлаПоведение
QDomAttrЭлемент-предок устанавливается в 0 и указанный флаг устанавливается в true в порождаемом атрибуте. Целые поддеревья importedNode всегда импортируются с узлами атрибутов: deep ни на что не влияет.
QDomDocumentДанные узлы не могут быть импортированы.
QDomDocumentFragmentЕсли deep установлен в true, функция импортирует целый фрагмент документа; если нет, то создается пустой фрагмент документа.
QDomDocumentTypeДанные узлы не могут быть импортированы.
QDomElementАтрибуты, у которых QDomAttr::specified() равно true, также импортируются, в отличие от остальных. Если deep равно true, функция также импортирует поддеревья importedNode; в остальных случаях импортируется только элемент (и некоторые атрибуты, смотрите выше).
QDomEntityУзлы сущностей могут быть импортированы, но на данный момент нет возможности их использования, поскольку в DOM level 2 документ доступен только для чтения.
QDomEntityReferenceПотомки узлов сущностей не могут быть импортированы: deep ни на что не влияет.
QDomNotationУзлы нотации XML могут быть импортированы, но на данный момент нет возможности их использования, поскольку в DOM level 2 тип документа доступен только для чтения.
QDomProcessingInstructionЦель и значение инструкции обработки копируются в новый узел.
QDomTextТекст копируется в новый узел.
QDomCDATASectionТекст копируется в новый узел.
QDomCommentТекст копируется в новый узел.

QDomNode::insertAfter() QDomNode::replaceChild() QDomNode::removeChild() QDomNode::appendChild()

Смотрите также QDomElement::setAttribute() и QDomNode::insertBefore().

QDomNode::NodeType QDomDocument::nodeType () const

Возвращает DocumentNode.

bool QDomDocument::setContent ( const QByteArray & data, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Эта функция анализирует XML-документ, представленный в виде массива байт data, устанавливая его как содержимое документа. Она пытается определить кодировку документа в соответствии со спецификацией XML.

Если namespaceProcessing равно true, синтаксический анализатор учитывает пространства имен в XML-файле и устанавливает префиксы имен, локальные имена и URI пространств имен в соответствующие значения. Если namespaceProcessing равно false, анализатор не учитывает пространства имен при чтении XML-файла.

Если при анализе произошли ошибки, функция возвращает false и сообщение об ошибке помещается в *errorMsg, номер строки в *errorLine и номер столбца в *errorColumn (если ошибка не произошла, указатели устанавливаются в 0); при успешном выполнении функция возвращает true. Различные сообщения об ошибках описаны в документации о классе QXmlParseException. Помните, если вы хотите показать сообщения об ошибке пользователю, они будут отображены по английски, если не будут непосредственно переведены.

Если namespaceProcessing равно true, функция QDomNode::prefix() возвращает соответствующую строку для всех элементов и атрибутов. Если элемент или атрибут не имеют префикса, возвращается пустая строка.

Текстовые узлы, состоящие только из пробелов, являются разделителями и не будут отображаться в QDomDocument. Если данное поведение является нежелательным, то можно использовать перегрузку setContent(), что позволяет поставляемый QXmlReader.

Если namespaceProcessing равно false, функции QDomNode::prefix(), QDomNode::localName() и QDomNode::namespaceURI() возвращают пустые строки.

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

QDomNode::prefix() QString::isNull() QString::isEmpty()

Смотрите также QDomNode::namespaceURI() и QDomNode::localName().

bool QDomDocument::setContent ( const QString & text, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Функция читает XML-документ из строки text, возвращая true, если данные были успешно проанализированы; в противном случае возвращает false. Поскольку text уже является Unicode строкой, определения кодировки не производится.

bool QDomDocument::setContent ( QIODevice * dev, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Эта функция читает XML-документ с устройства ввода-вывода dev, возвращая true, если данные были успешно проанализированы; в противном случае возвращает false.

bool QDomDocument::setContent ( const QString & text, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Функция читает XML-документ из строки text, возвращая true, если данные были успешно проанализированы; в противном случае возвращает false. Поскольку text уже является Unicode строкой, определения кодировки не производится.

Обработка пространств имен не производится.

bool QDomDocument::setContent ( const QByteArray & buffer, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Эта функция читает XML документ из массива байт buffer, возвращая true, если данные были успешно проанализированы; в противном случае возвращает false.

Обработка пространств имен не производится.

bool QDomDocument::setContent ( QIODevice * dev, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Эта функция читает XML-документ с устройства ввода-вывода dev, возвращая true, если данные были успешно проанализированы; в противном случае возвращает false.

Обработка пространств имен не производится.

bool QDomDocument::setContent ( QXmlInputSource * source, QXmlReader * reader, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )

Это перегруженная функция, предоставленная для удобства.

Функция читает XML-документ из QXmlInputSource source и анализирует его, используя QXmlReader reader, возвращает true, если анализ был успешно завершен; в противном случае возвращает false.

Эта функция не изменяет особенностей reader. Вы можете использовать эту функцию, если хотите определить какие-либо особенности процесса анализа документа в соответствии с вашими потребностями.

Смотрите также QXmlSimpleReader.

QByteArray QDomDocument::toByteArray ( int indent = 1 ) const

Переводит анализируемый документ обратно в его текстовое представление и возвращает QByteArray, содержащий данные в кодировке UTF-8.

Эта функция использует indent для определения величины отступа для подэлементов.

Смотрите также toString().

QString QDomDocument::toString ( int indent = 1 ) const

Переводит анализируемый документ обратно в его текстовое представление.

Эта функция использует indent для определения величины отступа для подэлементов.

QDomDocument & QDomDocument::operator= ( const QDomDocument & x )

Ассоциирует x с текущим документом DOM.

Данные в копиях общие (поверхностное копирование): изменение одного узла повлечет за собой изменение другого. Если вы хотите использовать глубокое копирование, воспользуйтесь cloneNode().


Copyright © 2008 Trolltech Торговые марки
Qt 4.3.5