Описание класса QDomDocument [модуль QtXml]
Класс QDomDocument служит для представления XML-документа. Далее...
#include <QDomDocument> Унаследован от QDomNode.
Замечание: все функции этого класса реентерабильны.
Открытые функции
- QDomDocument ()
- QDomDocument ( const QString & name )
- QDomDocument ( const QDomDocumentType & doctype )
- QDomDocument ( const QDomDocument & x )
- ~QDomDocument ()
- QDomAttr createAttribute ( const QString & name )
- QDomAttr createAttributeNS ( const QString & nsURI, const QString & qName )
- QDomCDATASection createCDATASection ( const QString & value )
- QDomComment createComment ( const QString & value )
- QDomDocumentFragment createDocumentFragment ()
- QDomElement createElement ( const QString & tagName )
- QDomElement createElementNS ( const QString & nsURI, const QString & qName )
- QDomEntityReference createEntityReference ( const QString & name )
- QDomProcessingInstruction createProcessingInstruction ( const QString & target, const QString & data )
- QDomText createTextNode ( const QString & value )
- QDomDocumentType doctype () const
- QDomElement documentElement () const
- QDomElement elementById ( const QString & elementId )
- QDomNodeList elementsByTagName ( const QString & tagname ) const
- QDomNodeList elementsByTagNameNS ( const QString & nsURI, const QString & localName )
- QDomImplementation implementation () const
- QDomNode importNode ( const QDomNode & importedNode, bool deep )
- QDomNode::NodeType nodeType () const
- bool setContent ( const QByteArray & data, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( const QString & text, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( QIODevice * dev, bool namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( const QString & text, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( const QByteArray & buffer, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( QIODevice * dev, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- bool setContent ( QXmlInputSource * source, QXmlReader * reader, QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
- QByteArray toByteArray ( int indent = 1 ) const
- QString toString ( int indent = 1 ) const
- QDomDocument & operator= ( const QDomDocument & x )
- 66 открытых функций, унаследованных от 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; узел действительно является элементом.
}
n = n.nextSibling();
}
Здесь мы присоединяем элемент в конец дереваt
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().
Создает новый фрагмент документа, который может быть использован для хранения части документа, когда производятся комплексные операции над деревом.
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().
Создает новую инструкцию обработки, которая может быть добавлена в документ, например, с помощью функции 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().
Возвращает тип текущего документа.
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 | Descendents of entity reference nodes are never imported: deep has no effect. |
QDomNotation | Узлы нотации XML могут быть импортированы, но на данный момент нет возможности их использования, поскольку в DOM level 2 тип документа доступен только для чтения. |
QDomProcessingInstruction | Цель и значение инструкции обработки копируются в новый узел. |
QDomText | Текст копируется в новый узел. |
QDomCDATASection | Текст копируется в новый узел. |
QDomComment | Текст копируется в новый узел. |
QDomNode::insertAfter() QDomNode::replaceChild() QDomNode::removeChild() QDomNode::appendChild()
Смотрите также QDomElement::setAttribute() и QDomNode::insertBefore().
Возвращает 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() возвращают пустые строки.
Ссылки на сущность анализируются следующим образом:
- Ссылки на внутренние общие или символьные сущности, находящиеся в данном контексте, включаются. Результатом является узел QDomText с ссылками, соответствующими значению сущности.
- Ссылки на параметры сущностей, определенные во внутреннем подмножестве, включаются. Результатом является узел QDomDocumentType, который содержит сущность и декларацию с ссылками, соответствующими значению сущности.
- Любая общая анализируемая ссылка на сущность, которая не определена во внутреннем подмножестве, но которая встречается в содержании, представляется узлом QDomEntityReference.
- Любая общая анализируемая ссылка на сущность, которая не определена во внутреннем подмножестве и встречается вне содержания, заменяется пустой строкой.
- Любая непроанализированная ссылка заменяется пустой строкой.
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().
|