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

Перейти к: навигация, поиск

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

__NOTOC__

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

Содержание

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

[править] Описание класса 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 являются всего лишь ссылками на внутреннее дерево. Объекты внутреннего дерева существуют до тех пор, пока на них есть ссылки объектов классов 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(&amp;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();
 }
 
 // Здесь мы присоединяем элемент в конец дерева
 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(), and 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(), and 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 не знает какой из атрибутов является идентификатором, фукнция всегда возвращает null element. Данное поведение может быть изменено в будущих версиях.

[править]
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() возвращают пустые строки.

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

Ссылки на внутренние общие или символьные сущности, находящиеся в данном контексте, включаются. Результатом является узел QDomText с ссылками, соответствующими значению сущности.
Ссылки на параметры сущностей, определенные во внутреннем подмножестве, включаются. Результатом является узел QDomDocumentType, который содержит сущность и декларацию с ссылками, соответствующими значению сущности.
Любая общая анализируемая ссылка на сущность, которая не определена во внутреннем подмножестве, но которая встречается в содержании, представляется узлом QDomEntityReference.
Любая общая анализируемая ссылка на сущность, которая не определена во внутреннем подмножестве и встречается вне содержания, заменяется пустой строкой.
Любая непроанализированная ссылка заменяется пустой строкой.

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

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