DOM_Element nodes.
*
* Assume the following XML document:<elementExample id="demo">
* <subelement1/>
* <subelement2><subsubelement/></subelement2>
* </elementExample>
* When represented using DOM, the top node is an DOM_Element node
* for "elementExample", which contains two child DOM_Element nodes,
* one for "subelement1" and one for "subelement2". "subelement1" contains no
* child nodes.
*
Elements may have attributes associated with them; since the
* DOM_Element interface inherits from DOM_Node, the generic
* DOM_Node interface method getAttributes may be used
* to retrieve the set of all attributes for an element. There are methods on
* the DOM_Element interface to retrieve either an DOM_Attr
* object by name or an attribute value by name. In XML, where an attribute
* value may contain entity references, an DOM_Attr 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.
*/
class CDOM_EXPORT DOM_Element: public DOM_Node {
private:
public:
/** @name Constructors and assignment operator */
//@{
/**
* Default constructor for DOM_Element. The resulting object does not
* refer to an actual Element node; it will compare == to 0, and is similar
* to a null object reference variable in Java. It may subsequently be
* assigned to refer to an actual Element node.
*
* New comment nodes are created by DOM_Document::createElement().
*
*/
DOM_Element();
/**
* Copy constructor. Creates a new DOM_Element that refers to the
* same underlying actual element as the original.
*
* @param other The object to be copied
*/
DOM_Element(const DOM_Element &other);
/**
* Assignment operator.
*
* @param other The object to be copied.
*/
DOM_Element & operator = (const DOM_Element &other);
/**
* Assignment operator. This overloaded variant is provided for
* the sole purpose of setting a DOM_Node reference variable to
* zero. Nulling out a reference variable in this way will decrement
* the reference count on the underlying Node object that the variable
* formerly referenced. This effect is normally obtained when reference
* variable goes out of scope, but zeroing them can be useful for
* global instances, or for local instances that will remain in scope
* for an extended time, when the storage belonging to the underlying
* node needs to be reclaimed.
*
* @param val Only a value of 0, or null, is allowed.
*/
DOM_Element & operator = (const DOM_NullPtr *val);
//@}
/** @name Destructor. */
//@{
/**
* Destructor. The object being destroyed is the reference
* object, not the underlying Element itself.
*
*/
~DOM_Element();
//@}
/** @name Getter functions. */
//@{
/**
* 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.
*/
DOMString getTagName() const;
/**
* Retrieves an attribute value by name.
*
* @param name The name of the attribute to retrieve.
* @return The DOM_Attr value as a string, or the empty string if
* that attribute does not have a specified or default value.
*/
DOMString getAttribute(const DOMString &name) const;
/**
* Retrieves an DOM_Attr node by name.
*
* @param name The name (nodeName) of the attribute to retrieve.
* @return The DOM_Attr node with the specified name (nodeName) or
* null if there is no such attribute.
*/
DOM_Attr getAttributeNode(const DOMString &name) const;
/**
* Returns a NodeList of all descendant elements with a given
* tag name, in the order in which they would be encountered in a preorder
* traversal of the DOM_Element tree.
*
* @param name The name of the tag to match on. The special value "*"
* matches all tags.
* @return A list of matching DOM_Element nodes.
*/
DOM_NodeList getElementsByTagName(const DOMString &name) const;
//@}
/** @name Set functions. */
//@{
/**
* 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
* DOM_Attr node plus any Text and
* EntityReference nodes, build the appropriate subtree, and
* use setAttributeNode to assign it as the value of an
* attribute.
* @param name The name of the attribute to create or alter.
* @param value Value to set in string form.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*/
void setAttribute(const DOMString &name,
const DOMString &value);
/**
* Adds a new attribute.
*
* If an attribute with that name (nodeName) is already present
* in the element, it is replaced by the new one.
* @param newAttr The DOM_Attr node to add to the attribute list.
* @return If the newAttr attribute replaces an existing
* attribute, the replaced
* DOM_Attr node is returned, otherwise null is
* returned.
* @exception DOMException
* WRONG_DOCUMENT_ERR: Raised if newAttr was created from a
* different document than the one that created the element.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an
* attribute of another DOM_Element object. The DOM user must
* explicitly clone DOM_Attr nodes to re-use them in other
* elements.
*/
DOM_Attr setAttributeNode(DOM_Attr newAttr);
//@}
/** @name Functions which modify the Element. */
//@{
/**
* Removes the specified attribute node.
* If the removed DOM_Attr
* 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.
*
* @param oldAttr The DOM_Attr node to remove from the attribute
* list.
* @return The DOM_Attr node that was removed.
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*
NOT_FOUND_ERR: Raised if oldAttr is not an attribute
* of the element.
*/
DOM_Attr removeAttributeNode(DOM_Attr oldAttr);
/**
* 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.
To remove an attribute by local
* name and namespace URI, use the removeAttributeNS method.
* @param name The name of the attribute to remove.
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*/
void removeAttribute(const DOMString &name);
//@}
/** @name Functions introduced in DOM Level 2. */
//@{
/**
* Retrieves an attribute value by local name and namespace URI.
*
* @param namespaceURI The namespace URI of
* the attribute to retrieve.
* @param localName The local name of the
* attribute to retrieve.
* @return The DOM_Attr value as a string, or an null if
* that attribute does not have a specified or default value.
*/
DOMString getAttributeNS(const DOMString &namespaceURI,
const DOMString &localName) const;
/**
* Adds a new attribute. If an attribute with the same
* local name and namespace URI is already present on the element, its prefix
* is changed to be the prefix part of the qualifiedName, and
* its value is changed to be 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 DOM_Attr
* node plus any DOM_Text and DOM_EntityReference
* nodes, build the appropriate subtree, and use
* setAttributeNodeNS or setAttributeNode to assign
* it as the value of an attribute.
*
* @param namespaceURI The namespace URI of
* the attribute to create or alter.
* @param qualifiedName The qualified name of the
* attribute to create or alter.
* @param value The value to set in string form.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an
* illegal character.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*
* NAMESPACE_ERR: Raised if the qualifiedName is
* malformed, if the qualifiedName has a prefix and the
* namespaceURI is null or an empty string,
* if the qualifiedName has a prefix that is "xml" and the
* namespaceURI is different from
* "http://www.w3.org/XML/1998/namespace", if the
* qualifiedName has a prefix that is "xmlns" and the
* namespaceURI is different from
* "http://www.w3.org/2000/xmlns/", or if the
* qualifiedName is "xmlns" and the
* namespaceURI is different from
* "http://www.w3.org/2000/xmlns/".
*/
void setAttributeNS(const DOMString &namespaceURI,
const DOMString &qualifiedName, const DOMString &value);
/**
* 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.
*
* @param namespaceURI The namespace URI of
* the attribute to remove.
* @param localName The local name of the
* attribute to remove.
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*/
void removeAttributeNS(const DOMString &namespaceURI,
const DOMString &localName);
/**
* Retrieves an DOM_Attr node by local name and namespace URI.
*
* @param namespaceURI The namespace URI of
* the attribute to retrieve.
* @param localName The local name of the
* attribute to retrieve.
* @return The DOM_Attr node with the specified attribute local
* name and namespace URI or null if there is no such attribute.
*/
DOM_Attr getAttributeNodeNS(const DOMString &namespaceURI,
const DOMString &localName) const;
/**
* 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.
*
* @param newAttr The DOM_Attr node to add to the attribute list.
* @return If the newAttr attribute replaces an existing
* attribute with the same local name and namespace URI,
* the replaced DOM_Attr node is
* returned, otherwise null is returned.
* @exception DOMException
* WRONG_DOCUMENT_ERR: Raised if newAttr was created from a
* different document than the one that created the element.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an
* attribute of another DOM_Element object. The DOM user must
* explicitly clone DOM_Attr nodes to re-use them in other
* elements.
*/
DOM_Attr setAttributeNodeNS(DOM_Attr newAttr);
/**
* Returns a DOM_NodeList of all the DOM_Elements
* with a given local name and namespace URI in the order in which they
* would be encountered in a preorder traversal of the
* DOM_Document tree, starting from this node.
*
* @param namespaceURI The namespace URI of
* the elements to match on. The special value "*" matches all
* namespaces.
* @param localName The local name of the
* elements to match on. The special value "*" matches all local names.
* @return A new DOM_NodeList object containing all the matched
* DOM_Elements.
*/
DOM_NodeList getElementsByTagNameNS(const DOMString &namespaceURI,
const DOMString &localName) const;
/**
* Returns whether this node (if it is an element) has any attributes.
* @return true if this node has any attributes,
* false otherwise.
*/
bool hasAttributes() const;
/**
* Returns true when an attribute with a given name is
* specified on this element or has a default value, false
* otherwise.
* @param name The name of the attribute to look for.
* @return true if an attribute with the given name is
* specified on this element or has a default value, false
* otherwise.
*/
bool hasAttribute(const DOMString &name) 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.
* @param namespaceURI The namespace URI of the attribute to look for.
* @param localName The local name of the attribute to look for.
* @return true if an attribute with the given local name
* and namespace URI is specified or has a default value on this
* element, false otherwise.
* @since DOM Level 2
*/
bool hasAttributeNS(const DOMString &namespaceURI,
const DOMString &localName) const;
//@}
protected:
DOM_Element(ElementImpl *impl);
friend class DOM_Document;
friend class DOM_Attr;
};
XERCES_CPP_NAMESPACE_END
#endif