xmldom::DomElement Class Reference

#include <DomElement.h>

Inherits xmldom::DomNode.

Inheritance diagram for xmldom::DomElement:

[legend]List of all members.

---

Detailed Description

By far the vast majority of objects (apart from text) that authors encounter when traversing a document are DomElement nodes.

Assume the following XML document:<elementExample id="demo"> <subelement1/> <subelement2><subsubelement/></subelement2> </elementExample>

On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

See also:

More Informations About the DOM 3 standard.

Public Member Functions
	DomElement ()
	ctor
	DomElement (const DomElement &copy)
	copy ctor
virtual	~DomElement ()
	dtor
const DomElement &	operator= (const DomElement &assign)
	assign
DOM Level 1
DomString	getTagName () const
	The name of the element.
DomString	getAttribute (const DomString &name) const
	Retrieves an attribute value by name.
DomAttribute	getAttributeNode (const DomString &name) const
	Retrieves an DomAttribute node by name.
DomNodeList	getElementsByTagName (const DomString &name) const
	Returns a DomNodeList of all descendant elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the DomElement tree.
void	setAttribute (const DomString &name, const DomString &value)
	Adds a new attribute.
DomAttribute	setAttributeNode (const DomAttribute &newAttribute)
	Adds a new attribute.
DomAttribute	removeAttributeNode (const DomAttribute &oldAttribute)
	Removes the specified attribute node.
void	removeAttribute (const DomString &name)
	Removes an attribute by name.
DOM Level 2
DomString	getAttributeNS (const DomString &namespaceURI, const DomString &localName) const
	Retrieves an attribute value by local name and namespace URI.
void	setAttributeNS (const DomString &namespaceURI, const DomString &qualifiedName, const DomString &value)
	Adds a new attribute.
void	removeAttributeNS (const DomString &namespaceURI, const DomString &localName)
	Removes an attribute by local name and namespace URI.
DomAttribute	getAttributeNodeNS (const DomString &namespaceURI, const DomString &localName) const
	Retrieves an DomAttribute node by local name and namespace URI.
DomAttribute	setAttributeNodeNS (const DomAttribute &newAttribute)
	Adds a new attribute.
DomNodeList	getElementsByTagNameNS (const DomString &namespaceURI, const DomString &localName) const
	Get a list of elements with a given name in a given namespace.
bool	hasAttribute (const DomString &name) const
	Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.
bool	hasAttributeNS (const DomString &namespaceURI, const DomString &localName) const
	Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
DOM Level 3
void	setIdAttribute (const DomString &name, bool isId)
	If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.
void	setIdAttributeNS (const DomString &namespaceURI, const DomString &localName, bool isId)
	If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.
void	setIdAttributeNode (const DomAttribute &idAttribute, bool isId)
	If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.
Extensions to the standard
DomElement	getFirstChildElement (const DomString &name=DomString()) const
	Get the first child element.
DomElement	getNextSiblingElement (const DomString &name=DomString()) const
	Get the next sibling element.

---

Constructor & Destructor Documentation

xmldom::DomElement::DomElement

(

)

ctor

xmldom::DomElement::DomElement

(

const DomElement &

copy

)

copy ctor

xmldom::DomElement::~DomElement

(

)

[virtual]

dtor

---

Member Function Documentation

const DomElement & xmldom::DomElement::operator=

(

const DomElement &

assign

)

assign

DomString xmldom::DomElement::getTagName

(

)

const

The name of the element.

DomString xmldom::DomElement::getAttribute

(

const DomString &

name

)

const

Retrieves an attribute value by name.

Parameters:

name

The name of the attribute to retrieve.

Returns:

The DomAttribute value as a string, or the empty string if that attribute does not have a specified or default value.

DomAttribute xmldom::DomElement::getAttributeNode

(

const DomString &

name

)

const

Retrieves an DomAttribute node by name.

Parameters:

name

The name (nodeName) of the attribute to retrieve.

Returns:

The DomAttribute node with the specified name (nodeName) or null if there is no such attribute.

DomNodeList xmldom::DomElement::getElementsByTagName

(

const DomString &

name

)

const

Returns a DomNodeList of all descendant elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the DomElement tree.

Parameters:

name

The name of the tag to match on. The special value "*" matches all tags.

Returns:

A list of matching DomElement nodes.

void xmldom::DomElement::setAttribute	(	const DomString &	name,
		const DomString &	value
	)

Adds a new attribute.

If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string, it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an DomAttribute node plus any DomText and DomEntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute.

Parameters:

	name	The name of the attribute to create or alter.
	value	Value to set in string form.

DomAttribute xmldom::DomElement::setAttributeNode

(

const DomAttribute &

newAttribute

)

Adds a new attribute.

If an attribute with that name (nodeName) is already present in the element, it is replaced by the new one.

Parameters:

newAttribute

The DomAttribute node to add to the attribute list.

Returns:

If the newAttr attribute replaces an existing attribute, the replaced DomAttribute node is returned, otherwise null is returned.

DomAttribute xmldom::DomElement::removeAttributeNode

(

const DomAttribute &

oldAttribute

)

Removes the specified attribute node.

If the removed DomAttribute has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix, when applicable.

Parameters:

oldAttribute

The DomAttribute node to remove from the attribute list.

Returns:

The DomAttribute node that was removed.

void xmldom::DomElement::removeAttribute

(

const DomString &

name

)

Removes an attribute by name.

If the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.

Parameters:

name

The name of the attribute to remove.

DomString xmldom::DomElement::getAttributeNS	(	const DomString &	namespaceURI,
		const DomString &	localName
	)			const

Retrieves an attribute value by local name and namespace URI.

Parameters:

	namespaceURI	The namespace URI of the attribute to retrieve.
	localName	The local name of the attribute to retrieve.

void xmldom::DomElement::setAttributeNS	(	const DomString &	namespaceURI,
		const DomString &	qualifiedName,
		const DomString &	value
	)

Adds a new attribute.

Parameters:

	namespaceURI	The namespace URI of the attribute to create or alter.
	qualifiedName	The qualified name of the attribute to create or alter.
	value	The value to set in string form.

void xmldom::DomElement::removeAttributeNS	(	const DomString &	namespaceURI,
		const DomString &	localName
	)

Removes an attribute by local name and namespace URI.

If the removed attribute has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix.

Parameters:

	namespaceURI	The namespace URI of the attribute to remove.
	localName	The local name of the attribute to remove.

DomAttribute xmldom::DomElement::getAttributeNodeNS	(	const DomString &	namespaceURI,
		const DomString &	localName
	)			const

Retrieves an DomAttribute node by local name and namespace URI.

Parameters:

	namespaceURI	The namespace URI of the attribute to retrieve.
	localName	The local name of the attribute to retrieve.

Returns:

The DomAttribute node with the specified attribute local name and namespace URI or null if there is no such attribute.

DomAttribute xmldom::DomElement::setAttributeNodeNS

(

const DomAttribute &

newAttribute

)

Adds a new attribute.

If an attribute with that local name and namespace URI is already present in the element, it is replaced by the new one.

Parameters:

newAttribute

The DomAttribute node to add to the attribute list.

DomNodeList xmldom::DomElement::getElementsByTagNameNS	(	const DomString &	namespaceURI,
		const DomString &	localName
	)			const

Get a list of elements with a given name in a given namespace.

Parameters:

	namespaceURI	The namespace URI of the elements to match on. The special value "*" matches all namespaces.
	localName	The local name of the elements to match on. The special value "*" matches all local names.

bool xmldom::DomElement::hasAttribute

(

const DomString &

name

)

const

Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.

Parameters:

name

The name of the attribute to look for.

Returns:

true if an attribute with the given name is specified on this element or has a default value, false otherwise.

bool xmldom::DomElement::hasAttributeNS	(	const DomString &	namespaceURI,
		const DomString &	localName
	)			const

Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.

HTML-only DOM implementations do not need to implement this method.

Parameters:

	namespaceURI	The namespace URI of the attribute to look for.
	localName	The local name of the attribute to look for.

void xmldom::DomElement::setIdAttribute	(	const DomString &	name,
		bool	isId
	)

If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.

This affects the value of DomAttribute.isId() and the behavior of DomDocument.getElementById(), but does not change any schema that may be in use, in particular this does not affect the DomAttribute.getSchemaTypeInfo() of the specified DomAttribute node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.

To specify an attribute by local name and namespace URI, use the setIdAttributeNS() method.

Parameters:

	name	The name of the attribute.
	isId	Whether the attribute is a of type ID.

Note:

brn_te, 2007-04-16, The param isId is currently ignored, and always assumed to be true.

void xmldom::DomElement::setIdAttributeNS	(	const DomString &	namespaceURI,
		const DomString &	localName,
		bool	isId
	)

If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.

This affects the value of DomAttribute.isId() and the behavior of DomDocument.getElementById(), but does not change any schema that may be in use, in particular this does not affect the DomAttribute.getSchemaTypeInfo() of the specified DomAttribute node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.

Parameters:

	namespaceURI	The namespace URI of the attribute.
	localName	The local name of the attribute.
	isId	Whether the attribute is a of type ID.

Note:

brn_te, 2007-04-16, The param isId is currently ignored, and always assumed to be true.

void xmldom::DomElement::setIdAttributeNode	(	const DomAttribute &	idAttribute,
		bool	isId
	)

If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute.

This affects the value of DomAttribute.isId() and the behavior of DomDocument.getElementById(), but does not change any schema that may be in use, in particular this does not affect the DomAttribute.getSchemaTypeInfo() of the specified DomAttribute node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.

Parameters:

	idAttribute	The DomAttribute node.
	isId	Whether the attribute is a of type ID.

Note:

brn_te, 2007-04-16, The param isId is currently ignored, and always assumed to be true.

DomElement xmldom::DomElement::getFirstChildElement

(

const DomString &

name = DomString()

)

const

Get the first child element.

Parameters:

name

If name is not a "null" string, the first child element with the given name is returned.

Returns:

The fisrt child element or "null" if there is no matching element.

DomElement xmldom::DomElement::getNextSiblingElement

(

const DomString &

name = DomString()

)

const

Get the next sibling element.

Parameters:

name

If name is not a "null" string, the next sibling element with the given name is returned.

Returns:

The next sibling element or "null" if there is no matching element.

---

The documentation for this class was generated from the following files:

• D:/Development/Sapphire_08_V1/InternalLibrary/Src/XMLDOM/V0/Src/XMLDOM/DomElement.h
• D:/Development/Sapphire_08_V1/InternalLibrary/Src/XMLDOM/V0/Src/XMLDOM/DomElement.cpp

---