Класс QDomNode

Класс QDomNode — базовый класс для всех узлов в дереве DOM. Подробнее...

• Список всех членов, включая наследуемые

Примечание: Все функции в этом классе являются повторно входящими.

Типы public

Public Функции

Protected Variables

Related Non-Members

Detailed Description

The QDomNode class is the base class for all the nodes in a DOM tree.

Many functions in the DOM return a QDomNode.

You can find out the type of a node using isAttr(), isCDATASection(), isDocumentFragment(), isDocument(), isDocumentType(), isElement(), isEntityReference(), isText(), isEntity(), isNotation(), isProcessingInstruction(), isCharacterData() and isComment().

A QDomNode can be converted into one of its subclasses using toAttr(), toCDATASection(), toDocumentFragment(), toDocument(), toDocumentType(), toElement(), toEntityReference(), toText(), toEntity(), toNotation(), toProcessingInstruction(), toCharacterData() or toComment(). You can convert a node to a null node with clear().

Copies of the QDomNode class share their data using explicit sharing. This means that modifying one node will change all copies. This is especially useful in combination with functions which return a QDomNode, e.g. firstChild(). You can make an independent (deep) copy of the node with cloneNode().

A QDomNode can be null, much like a null pointer. Creating a copy of a null node results in another null node. It is not possible to modify a null node, but it is possible to assign another, possibly non-null node to it. In this case, the copy of the null node will remain null. You can check if a QDomNode is null by calling isNull(). The empty constructor of a QDomNode (or any of the derived classes) creates a null node.

Nodes are inserted with insertBefore(), insertAfter() or appendChild(). You can replace one node with another using replaceChild() and remove a node with removeChild().

To traverse nodes use firstChild() to get a node's first child (if any), and nextSibling() to traverse. QDomNode also provides lastChild(), previousSibling() and parentNode(). To find the first child node with a particular node name use namedItem().

To find out if a node has children use hasChildNodes() and to get a list of all of a node's children use childNodes().

The node's name and value (the meaning of which varies depending on its type) is returned by nodeName() and nodeValue() respectively. The node's type is returned by nodeType(). The node's value can be set with setNodeValue().

The document to which the node belongs is returned by ownerDocument().

Adjacent QDomText nodes can be merged into a single node with normalize().

QDomElement nodes have attributes which can be retrieved with attributes().

QDomElement and QDomAttr nodes can have namespaces which can be retrieved with namespaceURI(). Their local name is retrieved with localName(), and their prefix with prefix(). The prefix can be set with setPrefix().

You can write the XML representation of the node to a text stream with save().

The following example looks for the first element in an XML document and prints the names of all the elements that are its direct children.

QDomDocument d;
d.setContent(someXML);
QDomNode n = d.firstChild();
while (!n.isNull()) {
    if (n.isElement()) {
        QDomElement e = n.toElement();
        cout << "Element name: " << e.tagName() << endl;
        break;
    }
    n = n.nextSibling();
}

For further information about the Document Object Model see Level 1 and Level 2 Core. For a more general introduction of the DOM implementation see the QDomDocument documentation.

Member Type Documentation

enum QDomNode::EncodingPolicy

This enum specifies how QDomNode::save() determines what encoding to use when serializing.

This enum was introduced or modified in Qt 4.3.

See also QDomNode::save().

enum QDomNode::NodeType

This enum defines the type of the node:

Member Function Documentation

QDomNode::QDomNode()

Создает пустой узел.

QDomNode::QDomNode(const QDomNode &n)

Создает копию n.

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

QDomNode::~QDomNode()

Удаляет объект и освобождает его ресурсы.

QDomNode QDomNode::appendChild(const QDomNode &newChild)

Добавляет newChild в качестве последнего дочернего узла.

Если newChild является дочерним узлом другого узла, он переродится в этот узел. Если newChild является дочерним узлом этого узла, его позиция в списке дочерних узлов изменится.

Если newChild является QDomDocumentFragment, то дочерние узлы фрагмента удаляются из фрагмента и добавляются.

Если newChild — это QDomElement, а этот узел — QDomDocument, который уже содержит элемент-потомок, то newChild не добавляется в качестве потомка, и возвращается узел со значением null.

Возвращает новую ссылку на newChild при успехе или узел со значением null при ошибке.

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

Спецификация DOM запрещает вставку узлов атрибутов, но по историческим причинам QDom всё же их принимает.

См. также insertBefore(), insertAfter(), replaceChild() и removeChild().

QDomNamedNodeMap QDomNode::attributes() const

Возвращает карту узлов имен всех атрибутов. Атрибуты предоставляются только для QDomElement.

Изменение атрибутов в карте также изменит атрибуты этого QDomNode.

QDomNodeList QDomNode::childNodes() const

Возвращает список всех непосредственных дочерних узлов.

Чаще всего эта функция вызывается для объекта QDomElement.

Например, если XML-документ выглядит так:

<body>
<h1>Heading</h1>
<p>Hello <b>you</b></p>
</body>

Тогда список дочерних узлов для элемента "body" будет содержать узел, созданный тегом <h1>, и узел, созданный тегом <p>.

Узлы в списке не копируются; поэтому изменение узлов в списке также изменит дочерние узлы этого узла.

См. также firstChild() и lastChild().

void QDomNode::clear()

Преобразует узел в узел со значением null; если он не был узлом со значением null ранее, его тип и содержимое удаляются.

См. также isNull().

QDomNode QDomNode::cloneNode(bool deep = true) const

Создаёт глубокую (а не поверхностную) копию QDomNode.

Если deep имеет значение true, клонирование выполняется рекурсивно, что означает, что все дочерние узлы также копируются глубоко. Если deep имеет значение false, копируется только сам узел, и у копии не будет дочерних узлов.

int QDomNode::columnNumber() const

Для узлов, созданных с помощью QDomDocument::setContent(), эта функция возвращает номер столбца в XML-документе, где узел был проанализирован. В противном случае возвращается -1.

Эта функция была добавлена в Qt 4.1.

См. также lineNumber() и QDomDocument::setContent().

QDomNode QDomNode::firstChild() const

Возвращает первого потомка узла. Если дочерних узлов нет, возвращается узел со значением null. Изменение возвращённого узла также изменит узел в дереве документа.

См. также lastChild() и childNodes().

QDomElement QDomNode::firstChildElement(const QString &tagName = QString()) const

Возвращает первый дочерний элемент с именем тега tagName, если tagName не пустое; в противном случае возвращает первый дочерний элемент. Возвращает пустой элемент, если такой дочерний элемент не существует.

См. также lastChildElement(), previousSiblingElement() и nextSiblingElement().

bool QDomNode::hasAttributes() const

Возвращает true если у узла есть атрибуты; в противном случае возвращает false.

См. также attributes().

bool QDomNode::hasChildNodes() const

Возвращает true если у узла есть один или несколько потомков; в противном случае возвращает false.

QDomNode QDomNode::insertAfter(const QDomNode &newChild, const QDomNode &refChild)

Вставляет узел newChild после дочернего узла refChild. refChild должен быть непосредственным потомком этого узла. Если refChild имеет значение null, то newChild добавляется в качестве последнего потомка этого узла.

Если newChild является потомком другого узла, он переназначается этому узлу. Если newChild является потомком этого узла, изменяется его позиция в списке потомков.

Если newChild является QDomDocumentFragment, потомки фрагмента удаляются из фрагмента и вставляются после refChild.

Возвращает новую ссылку на newChild при успехе или узел со значением null при ошибке.

Спецификация DOM запрещает вставку узлов атрибутов, но по историческим причинам QDom их принимает.

См. также insertBefore(), replaceChild(), removeChild() и appendChild().

QDomNode QDomNode::insertBefore(const QDomNode &newChild, const QDomNode &refChild)

Вставляет узел newChild перед дочерним узлом refChild. refChild должен быть непосредственным потомком этого узла. Если refChild имеет значение null, то newChild вставляется в качестве первого потомка узла.

Если newChild является потомком другого узла, он переназначается этому узлу. Если newChild является потомком этого узла, изменяется его позиция в списке потомков.

Если newChild является QDomDocumentFragment, потомки фрагмента удаляются из фрагмента и вставляются перед refChild.

Возвращает новую ссылку на newChild при успехе или узел со значением null при ошибке.

Спецификация DOM запрещает вставку узлов атрибутов, но по историческим причинам QDom их принимает.

См. также insertAfter(), replaceChild(), removeChild() и appendChild().

bool QDomNode::isAttr() const

Возвращает true если узел является атрибутом; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomAttribute; вы можете получить QDomAttribute с помощью toAttribute().

См. также toAttr().

bool QDomNode::isCDATASection() const

Возвращает true если узел является секцией CDATA; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomCDATASection; вы можете получить QDomCDATASection с помощью toCDATASection().

См. также toCDATASection().

bool QDomNode::isCharacterData() const

Возвращает true если узел является узлом данных символов; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomCharacterData; вы можете получить QDomCharacterData с помощью toCharacterData().

См. также toCharacterData().

bool QDomNode::isComment() const

Возвращает true если узел является комментарием; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomComment; вы можете получить QDomComment с помощью toComment().

См. также toComment().

bool QDomNode::isDocument() const

Возвращает true если узел является документом; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomDocument; вы можете получить QDomDocument с помощью toDocument().

См. также toDocument().

bool QDomNode::isDocumentFragment() const

Возвращает true если узел является фрагментом документа; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomDocumentFragment; вы можете получить QDomDocumentFragment с помощью toDocumentFragment().

См. также toDocumentFragment().

bool QDomNode::isDocumentType() const

Возвращает true если узел является типом документа; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomDocumentType; вы можете получить QDomDocumentType с помощью toDocumentType().

См. также toDocumentType().

bool QDomNode::isElement() const

Возвращает true , если узел является элементом; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomElement; вы можете получить QDomElement с помощью toElement().

См. также toElement().

bool QDomNode::isEntity() const

Возвращает true , если узел является сущностью; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomEntity; вы можете получить QDomEntity с помощью toEntity().

См. также toEntity().

bool QDomNode::isEntityReference() const

Возвращает true , если узел является ссылкой на сущность; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomEntityReference; вы можете получить QDomEntityReference с помощью toEntityReference().

См. также toEntityReference().

bool QDomNode::isNotation() const

Возвращает true , если узел является обозначением; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomNotation; вы можете получить QDomNotation с помощью toNotation().

См. также toNotation().

bool QDomNode::isNull() const

Возвращает true , если этот узел равен null (т. е. если у него нет типа или содержимого); в противном случае возвращает false.

bool QDomNode::isProcessingInstruction() const

Возвращает true , если узел является инструкцией обработки; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomProcessingInstruction; вы можете получить QProcessingInstruction с помощью toProcessingInstruction().

См. также toProcessingInstruction().

bool QDomNode::isSupported(const QString &feature, const QString &version) const

Возвращает true , если реализация DOM реализует функцию feature и эта функция поддерживается этим узлом в версии version; в противном случае возвращает false.

См. также QDomImplementation::hasFeature().

bool QDomNode::isText() const

Возвращает true , если узел является узлом текста; в противном случае возвращает false.

Если эта функция возвращает true, это не подразумевает, что этот объект является QDomText; вы можете получить QDomText с помощью toText().

См. также toText().

QDomNode QDomNode::lastChild() const

Возвращает последнего дочернего узла. Если дочерних узлов нет, возвращается узел null. Изменение возвращённого узла также изменит узел в дереве документа.

См. также firstChild() и childNodes().

QDomElement QDomNode::lastChildElement(const QString &tagName = QString()) const

Возвращает последний дочерний элемент с именем тега tagName, если tagName не пуста; в противном случае возвращает последний дочерний элемент. Возвращает элемент null, если такого элемента нет.

См. также firstChildElement(), previousSiblingElement() и nextSiblingElement().

int QDomNode::lineNumber() const

Для узлов, созданных с помощью QDomDocument::setContent(), эта функция возвращает номер строки в документе XML, где был проанализирован узел. В противном случае возвращается -1.

Эта функция была введена в Qt 4.1.

См. также columnNumber() и QDomDocument::setContent().

QString QDomNode::localName() const

Если узел использует пространства имён, эта функция возвращает локальное имя узла; в противном случае возвращает пустую строку.

Только узлы типа ElementNode или AttributeNode могут иметь пространства имён. Пространство имён должно быть указано при создании; его нельзя добавить позже.

См. также prefix(), namespaceURI(), QDomDocument::createElementNS() и QDomDocument::createAttributeNS().

QDomNode QDomNode::namedItem(const QString &name) const

Возвращает первый непосредственный дочерний узел, для которого nodeName() равно name.

Если такого непосредственного дочернего узла нет, возвращается узел null.

См. также nodeName().

QString QDomNode::namespaceURI() const

Возвращает URI пространства имён этого узла или пустую строку, если у узла нет URI пространства имён.

Только узлы типа ElementNode или AttributeNode могут иметь пространства имён. URI пространства имён должен быть указан при создании и не может быть изменён позднее.

См. также prefix(), localName(), QDomDocument::createElementNS() и QDomDocument::createAttributeNS().

QDomNode QDomNode::nextSibling() const

Возвращает следующего брата в дереве документа. Изменение возвращаемого узла также изменит узел в дереве документа.

Если у вас есть XML такого вида:

<h1>Heading</h1>
<p>The text...</p>
<h2>Next heading</h2>

и этот QDomNode представляет тег <p>, nextSibling() вернёт узел, представляющий тег <h2>.

См. также previousSibling().

QDomElement QDomNode::nextSiblingElement(const QString &tagName = QString()) const

Возвращает следующий элемент-брата с именем тега tagName, если tagName не пуста; в противном случае возвращает любой следующий элемент-брат. Возвращает null-элемент, если такого элемента нет.

См. также firstChildElement(), previousSiblingElement() и lastChildElement().

QString QDomNode::nodeName() const

Возвращает имя узла.

Значение имени зависит от подкласса:

Примечание: Эта функция не учитывает наличие пространств имён при обработке имён узлов элементов и атрибутов. В результате возвращаемое имя может содержать любой префикс пространства имён, который может быть присутствующим. Для получения имени узла элемента или атрибута используйте localName; для получения префикса пространства имён используйте namespaceURI().

См. также nodeValue().

QDomNode::NodeType QDomNode::nodeType() const

Возвращает тип узла.

См. также toAttr(), toCDATASection(), toDocumentFragment(), toDocument(), toDocumentType(), toElement(), toEntityReference(), toText(), toEntity(), toNotation(), toProcessingInstruction(), toCharacterData() и toComment().

QString QDomNode::nodeValue() const

Возвращает значение узла.

Значение зависит от подкласса:

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

См. также setNodeValue() и nodeName().

void QDomNode::normalize()

Вызов normalize() для элемента преобразует все его дочерние элементы в стандартную форму. Это означает, что смежные объекты QDomText будут объединены в один текстовый объект (QDomCDATASection узлы не объединяются).

QDomDocument QDomNode::ownerDocument() const

Возвращает документ, к которому принадлежит этот узел.

QDomNode QDomNode::parentNode() const

Возвращает родительский узел. Если у этого узла нет родителя, возвращается нулевой узел (т.е. узел, для которого isNull() возвращает true).

QString QDomNode::prefix() const

Возвращает префикс пространства имён узла или пустую строку, если у узла нет префикса пространства имён.

Пространства имён могут иметь только узлы типа ElementNode или AttributeNode. Префикс пространства имён должен быть указан во время создания. Если узел был создан с префиксом пространства имён, вы можете изменить его позже с помощью setPrefix().

Если вы создаёте элемент или атрибут с помощью QDomDocument::createElement() или QDomDocument::createAttribute(), префикс будет пустой строкой. Если вы используете QDomDocument::createElementNS() или QDomDocument::createAttributeNS() вместо этого, префикс не будет пустой строкой; но он может быть пустой строкой, если имя не имеет префикса.

См. также setPrefix(), localName(), namespaceURI(), QDomDocument::createElementNS() и QDomDocument::createAttributeNS().

QDomNode QDomNode::previousSibling() const

Возвращает предыдущего брата в дереве документа. Изменение возвращённого узла также изменит узел в дереве документа.

Например, если у вас есть XML, подобный этому:

<h1>Heading</h1>
<p>The text...</p>
<h2>Next heading</h2>

и этот QDomNode представляет тег &lt;p&gt;, previousSibling() вернёт узел, представляющий тег &lt;h1&gt;.

См. также nextSibling().

QDomElement QDomNode::previousSiblingElement(const QString &tagName = QString()) const

Возвращает предыдущий элемент-брата с именем тега tagName, если tagName не пустая; в противном случае возвращает любой предыдущий элемент-брата. Возвращает нулевой элемент, если такого элемента-брата не существует.

См. также firstChildElement(), nextSiblingElement() и lastChildElement().

QDomNode QDomNode::removeChild(const QDomNode &oldChild)

Удаляет oldChild из списка дочерних элементов. oldChild должен быть непосредственным потомком этого узла.

Возвращает новую ссылку на oldChild при успехе или нулевой узел при ошибке.

См. также insertBefore(), insertAfter(), replaceChild() и appendChild().

QDomNode QDomNode::replaceChild(const QDomNode &newChild, const QDomNode &oldChild)

Заменяет oldChild на newChild. oldChild должен быть непосредственным потомком этого узла.

Если newChild является потомком другого узла, он переназначается этому узлу. Если newChild является потомком этого узла, то его позиция в списке дочерних элементов изменяется.

Если newChild является QDomDocumentFragment, то oldChild заменяется всеми потомками фрагмента.

Возвращает новую ссылку на oldChild при успехе или нулевой узел при ошибке.

См. также insertBefore(), insertAfter(), removeChild() и appendChild().

void QDomNode::save(QTextStream &stream, int indent, QDomNode::EncodingPolicy encodingPolicy = QDomNode::EncodingFromDocument) const

Записывает XML-представление узла и всех его потомков в поток stream. Эта функция использует indent как отступ узла.

Если документ содержит недопустимые символы XML или символы, которые не могут быть закодированы в заданной кодировке, результат и поведение не определены.

Если encodingPolicy равен QDomNode::EncodingFromDocument, и этот узел является узлом документа, кодировка потока stream устанавливается, обрабатывая инструкцию обработки с именем "xml" как объявление XML, если оно существует, а в противном случае по умолчанию используется UTF-8. Объявления XML не являются инструкциями обработки, но это поведение существует по историческим причинам. Если этот узел не является узлом документа, используется кодировка потока.

Если encodingPolicy равен EncodingFromTextStream, и этот узел является узлом документа, эта функция работает так же, как save(QTextStream &str, int indent), за исключением того, что используется кодировка, указанная в текстовом потоке stream.

Если документ содержит недопустимые символы XML или символы, которые не могут быть закодированы в заданной кодировке, результат и поведение не определены.

Эта функция была представлена в Qt 4.2.

void QDomNode::setNodeValue(const QString &v)

Устанавливает значение узла в v.

См. также nodeValue().

void QDomNode::setPrefix(const QString &pre)

Если у узла есть префикс пространства имён, эта функция изменяет префикс пространства имён узла на pre. В противном случае эта функция ничего не делает.

Пространства имён могут иметь только узлы типа ElementNode или AttributeNode. Префикс пространства имён должен быть указан при создании; его нельзя добавить позже.

См. также prefix(), localName(), namespaceURI(), QDomDocument::createElementNS() и QDomDocument::createAttributeNS().

QDomAttr QDomNode::toAttr() const

Преобразует QDomNode в QDomAttr. Если узел не является атрибутом, возвращаемый объект будет нулевым.

См. также isAttr().

QDomCDATASection QDomNode::toCDATASection() const

Преобразует QDomNode в QDomCDATASection. Если узел не является разделом CDATA, возвращаемый объект будет нулевым.

См. также isCDATASection().

QDomCharacterData QDomNode::toCharacterData() const

Преобразует QDomNode в QDomCharacterData. Если узел не является узлом данных символов, возвращаемый объект будет нулевым.

См. также isCharacterData().

QDomComment QDomNode::toComment() const

Преобразует QDomNode в QDomComment. Если узел не является комментарием, возвращаемый объект будет нулевым.

См. также isComment().

QDomDocument QDomNode::toDocument() const

Преобразует QDomNode в QDomDocument. Если узел не является документом, возвращаемый объект будет null.

См. также isDocument().

QDomDocumentFragment QDomNode::toDocumentFragment() const

Преобразует QDomNode в QDomDocumentFragment. Если узел не является фрагментом документа, возвращаемый объект будет null.

См. также isDocumentFragment().

QDomDocumentType QDomNode::toDocumentType() const

Преобразует QDomNode в QDomDocumentType. Если узел не является типом документа, возвращаемый объект будет null.

См. также isDocumentType().

QDomElement QDomNode::toElement() const

Преобразует QDomNode в QDomElement. Если узел не является элементом, возвращаемый объект будет null.

См. также isElement().

QDomEntity QDomNode::toEntity() const

Преобразует QDomNode в QDomEntity. Если узел не является сущностью, возвращаемый объект будет null.

См. также isEntity().

QDomEntityReference QDomNode::toEntityReference() const

Преобразует QDomNode в QDomEntityReference. Если узел не является ссылкой на сущность, возвращаемый объект будет null.

См. также isEntityReference().

QDomNotation QDomNode::toNotation() const

Преобразует QDomNode в QDomNotation. Если узел не является обозначением, возвращаемый объект будет null.

См. также isNotation().

QDomProcessingInstruction QDomNode::toProcessingInstruction() const

Преобразует QDomNode в QDomProcessingInstruction. Если узел не является инструкцией обработки, возвращаемый объект будет null.

См. также isProcessingInstruction().

QDomText QDomNode::toText() const

Преобразует QDomNode в QDomText. Если узел не является текстом, возвращаемый объект будет null.

См. также isText().

bool QDomNode::operator!=(const QDomNode &n) const

Возвращает true если n и этот узел DOM не равны; в противном случае возвращает false.

QDomNode &QDomNode::operator=(const QDomNode &n)

Присваивает копию n этому узлу DOM.

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

bool QDomNode::operator==(const QDomNode &n) const

Возвращает true если n и этот узел DOM равны; в противном случае возвращает false.

Любой экземпляр QDomNode действует как ссылка на базовый структуру данных в QDomDocument. Проверка на равенство проверяет, указывают ли две ссылки на один и тот же базовый узел. Например:

QDomDocument document;
QDomElement element1 = document.documentElement();
QDomElement element2 = element1;

Оба узла (QDomElement — подкласс QDomNode) ссылаются на корневой элемент документа, и element1 == element2 вернёт true. С другой стороны:

QDomElement element3 = document.createElement("MyElement");
QDomElement element4 = document.createElement("MyElement");

Несмотря на то, что оба узла являются пустыми элементами с одинаковым именем, element3 == element4 вернёт false, потому что они ссылаются на два разных узла в базовой структуре данных.