All Frameworks Class Hierarchy This Framework Indexes Previous Next

XMLParserItf Interface CATIDOMElement

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.

interface CATIDOMElement

Interface representing by far the vast majority of objects nodes (apart from text) that authors encounter when traversing a document.
Assume the following XML document:

<elementExample id="demo">
<subelement1/>
<subelement2><subsubelement/></subelement2>
</elementExample>

When represented using DOM, the top node is a CATIDOMElement node for "elementExample", which contains two child CATIDOMElement nodes, one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes.

Elements may have attributes associated with them; since the CATIDOMElement interface inherits from , the generic interface method may be used to retrieve the set of all attributes for an element.
There are methods on the CATIDOMElement interface to retrieve either a object by name or an attribute value by name. In XML, where an attribute value may contain entity references, a object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. 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.

Method Index

o GetAttribute(CATUnicodeString&,CATUnicodeString&): Retrieves an attribute value by name.
o GetAttributeNS(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&): Retrieves an attribute value by local name and namespace URI.
o GetAttributeNode(CATUnicodeString&,CATIDOMAttr_var&): Retrieves a CATIDOMAttr node by name.
o GetAttributeNodeNS(CATUnicodeString&,CATUnicodeString&,CATIDOMAttr_var&): Retrieves a CATIDOMAttr node by local name and namespace URI.
o GetElementsByTagName(CATUnicodeString&,CATIDOMNodeList_var&): Returns a CATIDOMNodeList of all descendant elements with a given tag name.
o GetElementsByTagNameNS(CATUnicodeString&,CATUnicodeString&,CATIDOMNodeList_var&): Returns a CATIDOMNodeList of all the CATIDOMElements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the CATIDOMDocument tree, starting from this node.
o GetTagName(CATUnicodeString&): Retrieves the name of the element.
o HasAttribute(CATUnicodeString&,CATBoolean&): Returns TRUE when an attribute with a given name is specified on this element or has a default value, FALSE otherwise.
o HasAttributeNS(CATUnicodeString&,CATUnicodeString&,CATBoolean&): 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.
o RemoveAttribute(CATUnicodeString&): Removes an attribute by name.
o RemoveAttributeNS(CATUnicodeString&,CATUnicodeString&): Removes an attribute by local name and namespace URI.
o RemoveAttributeNode(CATIDOMAttr_var&): Removes the specified attribute.
o SetAttribute(CATUnicodeString&,CATUnicodeString&): Adds a new attribute.
o SetAttributeNS(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&): Adds a new attribute.
o SetAttributeNode(CATIDOMAttr_var&): Adds a new attribute.
o SetAttributeNodeNS(CATIDOMAttr_var&,CATIDOMAttr_var&): Adds a new attribute.

Methods

o GetAttribute

public virtual GetAttribute(	const	`iName`,
		`oValue`)

Retrieves an attribute value by name.

Parameters:

iName: The name of the attribute to retrieve.
oValue: The

o GetAttributeNS

public virtual GetAttributeNS(	const	`iNamespaceURI`,
	const	`iLocalName`,
		`oValue`)

Retrieves an attribute value by local name and namespace URI.

Parameters:

iNamespaceURI: The namespace URI of the attribute to retrieve. When it is an empty
iLocalName: The local name of the attribute to retrieve.
oValue: The

o GetAttributeNode

public virtual GetAttributeNode(	const	`iAttributeName`,
		`oAttributeNode`)

Retrieves a CATIDOMAttr node by name.

Parameters:

iAttributeName: The name of the attribute to retrieve.
oAttributeNode: The retrieved
See also:

o GetAttributeNodeNS

public virtual GetAttributeNodeNS(	const	`iNamespaceURI`,
	const	`iLocalName`,
		`oAttribute`)

Retrieves a CATIDOMAttr node by local name and namespace URI.

Parameters:

iNamespaceURI: The namespace URI of the attribute to retrieve. When it is or an empty
iLocalName: The local name of the attribute to retrieve.
oAttribute: The

o GetElementsByTagName

public virtual GetElementsByTagName(	const	`iElementsName`,
		`oListOfElements`)

Returns a CATIDOMNodeList of all descendant elements with a given tag name. The elements are returned in the order in which they would be encountered in a preorder traversal of the CATIDOMElement tree.

Parameters:

iElementsName: The name of the tag to match on. The special value "*" matches all tags.
oListOfElements: A list of matching
See also:

o GetElementsByTagNameNS

public virtual GetElementsByTagNameNS(	const	`iNamespaceURI`,
	const	`iLocalName`,
		`oElementList`)

Returns a CATIDOMNodeList of all the CATIDOMElements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the CATIDOMDocument tree, starting from this node.

Parameters:

iNamespaceURI: The namespace URI of the elements to match on. The special value "*" matches all namespaces. When it is an empty
iLocalName: The local name of the elements to match on. The special value "*" matches all local names.
oElementList: A new

o GetTagName

public virtual GetTagName( oTagName)

Retrieves the name of the element. For example, in:
<elementExample id="demo"> ... </elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM.

Parameters:

oTagName: The retrieved name of the element.

o HasAttribute

public virtual HasAttribute(	const	`iName`,
		`oResult`)

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

Parameters:

iName: The name of the attribute to look for.
oResult: TRUE if an attribute with the given name is specified on this element or has a default value, FALSE otherwise.

o HasAttributeNS

public virtual HasAttributeNS(	const	`iNamespaceURI`,
	const	`iLocalName`,
		`oResult`)

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:

iNamespaceURI: The namespace URI of the attribute to look for.
iLocalName: The local name of the attribute to look for.
oResult: TRUE if an attribute with the given local name and namespace URI is specified or has a default value on this element, FALSE otherwise.

o RemoveAttribute

public virtual RemoveAttribute( const iAttributeName)

Removes an attribute by name. If the removed attribute has a default value it is immediately replaced.

Parameters:

iAttributeName: The name of the attribute to remove.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

o RemoveAttributeNS

public virtual RemoveAttributeNS(	const	`iNamespaceURI`,
	const	`iLocalName`)

Removes an attribute by local name and namespace URI. If the removed attribute has a default value it is immediately replaced.

Parameters:

iNamespaceURI: The namespace URI of the attribute to remove. When it is an empty
iLocalName: The local name of the attribute to remove.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

o RemoveAttributeNode

public virtual RemoveAttributeNode( const iAttributeNodeToRemove)

Removes the specified attribute.

Parameters:

iAttributeNodeToRemove: The

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
	XMLParserERR_2208	NOT_FOUND_ERR: Raised if `iAttributeNodeToRemove` is not an attribute of the element.

See also:

o SetAttribute

public virtual SetAttribute(	const	`iAttributeName`,
	const	`iAttributeValue`)

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 node plus any and nodes, build the appropriate subtree, and use to assign it as the value of an attribute.

Parameters:

iAttributeName: The name of the attribute to create or alter.
iAttributeValue: Value to set in string form.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2205	INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

See also:

o SetAttributeNS

public virtual SetAttributeNS(	const	`iNamespaceURI`,
	const	`iQualifiedName`,
	const	`iValue`)

Adds a new attribute. If an attribute with the same local name and namespace URI is already present in the element, its prefix is changed to be that of the qualifiedName parameter, and 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 a node plus any and nodes, build the appropriate subtree, and use or to assign it as the value of an attribute.

Parameters:

iNamespaceURI: The namespace URI of the attribute to create or alter. When it is an empty
iQualifiedName: The qualified name of the attribute to create or alter.
iValue: The value to set in string form.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2205	INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

o SetAttributeNode

public virtual SetAttributeNode( const iAttributeNode)

Adds a new attribute. If an attribute with that name is already present in the element, it is replaced by the new one.

Parameters:

iAttributeNode: The

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2204	WRONG_DOCUMENT_ERR: Raised if `iAttributeNode` was created from a different document than the one that created the element.
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
	XMLParserERR_2210	INUSE_ATTRIBUTE_ERR: Raised if `iAttributeNode` is already an attribute of another object. The DOM user must explicitly clone nodes to re-use them in other elements.

See also:

o SetAttributeNodeNS

public virtual SetAttributeNodeNS(	const	`iNewAttribute`,
		`oPreviousAttr`)

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:

iNewAttribute: The
oPreviousAttr: If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the previously existing

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2204	WRONG_DOCUMENT_ERR: Raised if `iNewAttribute` was created from a different document than the one that created the element.
	XMLParserERR_2207	NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
	XMLParserERR_2210	INUSE_ATTRIBUTE_ERR: Raised if `iNewAttribute` is already an attribute of another object. The DOM user must explicitly clone nodes to re-use them in other elements.

This object is included in the file: CATIDOMElement.h
If needed, your Imakefile.mk should include the module: CatXmlItfExt