<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date: 2001/11/26 22:34:21 $ $Revision: 1.1.1.1 $ -->
<!--[ Element object description ]-->
<interface name="Element" inherits="Node" id="ID-745549614">
  <descr><p>The <code>Element</code> interface represents an <termref def="dt-element">element</termref> in an HTML
      or XML document. Elements may have attributes associated with them; since the
    <code>Element</code> interface inherits from <code>Node</code>, the generic
    <code>Node</code> interface attribute <code>attributes</code> may be used
    to retrieve the set of all attributes for an element. There are methods on
    the <code>Element</code> interface to retrieve either an <code>Attr</code>
    object by name or an attribute value by name. In XML, where an attribute
    value may contain entity references, an <code>Attr</code> 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 <termref def="dt-convenience">convenience</termref>.</p>

    <note><p>In DOM Level 2, the method <code>normalize</code> is
	inherited from the <code>Node</code> interface where it was
	moved.</p></note>
    </descr>


  <attribute type="DOMString" name="tagName" readonly="yes" id="ID-104682815">
    <descr><p>The name of the element. For example, in:  
<eg role="code">
&lt;elementExample id="demo"&gt; 
        ... 
&lt;/elementExample&gt; ,
</eg>
     <code>tagName</code> has the value
     <code>"elementExample"</code>. Note that this is
     case-preserving in XML, as are all of the operations of the DOM.
     The HTML DOM returns the <code>tagName</code> of an HTML element
     in the canonical uppercase form, regardless of the case in the 
     source HTML document. </p>
    </descr>
  </attribute>

  <method name="getAttribute" id="ID-666EE0F9">
    <descr><p>Retrieves an attribute value by name.</p></descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the attribute to retrieve.</p></descr>
      </param>
    </parameters>
    <returns type="DOMString">
      <descr><p>The <code>Attr</code> value as a string, or the empty string if
        that attribute does not have a specified or default value.</p></descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
  <method name="setAttribute" id="ID-F68F082">
    <descr><p>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 <code>Attr</code> node plus any <code>Text</code> and
      <code>EntityReference</code> nodes, build the appropriate subtree, and
      use <code>setAttributeNode</code> to assign it as the value of an
      attribute.</p>
      <p>To set an attribute with a qualified name and namespace URI, use
	the <code>setAttributeNS</code> method.</p>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the attribute to create or alter.</p></descr>
      </param>
      <param name="value" type="DOMString" attr="in">
	<descr><p>Value to set in string form.</p></descr>
      </param>
    </parameters>
    <returns type="void">
        <descr><p></p></descr>      
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
	an illegal character.</p>
	<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="removeAttribute" id="ID-6D6AC0F9">
    <descr><p>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.</p>
      <p>To remove an attribute by local name and namespace URI, use
	the <code>removeAttributeNS</code> method.</p>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the attribute to remove.</p></descr>
      </param>
    </parameters>
    <returns type="void">
        <descr><p></p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
	readonly.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="getAttributeNode" id="ID-217A91B8">
    <descr><p>Retrieves an attribute node by name.</p>
      <p>To retrieve an attribute node by qualified name and namespace URI, use
	the <code>getAttributeNodeNS</code> method.</p>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name (<code>nodeName</code>) of the attribute to
	  retrieve.</p></descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>The <code>Attr</code> node with the specified
        name (<code>nodeName</code>) or <code>null</code> if there is no such
	attribute.</p></descr> 
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
  <method name="setAttributeNode" id="ID-887236154">
    <descr><p>Adds a new attribute node. If an attribute with that name
      (<code>nodeName</code>) is already present in the element, it is replaced
      by the new one.</p>
      <p>To add a new attribute node with a qualified name and namespace URI,
	use the <code>setAttributeNodeNS</code> method.</p>
     </descr>
    <parameters>
      <param name="newAttr" type="Attr" attr="in">
	<descr><p>The <code>Attr</code> node to add to the attribute
	    list.</p></descr>
      </param>
    </parameters>
    <returns type="Attr">
         <descr><p>If the <code>newAttr</code> attribute replaces
	   an existing attribute, the replaced <code>Attr</code> node is
	   returned, otherwise <code>null</code> is returned.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
	created from a different document than the one that created the
	element.</p>
        <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
	<p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already
	an attribute of another <code>Element</code> object. The
	DOM user must explicitly clone <code>Attr</code>
	nodes to re-use them in other elements.</p></descr>
      </exception>
    </raises>
  </method>
  <method name="removeAttributeNode" id="ID-D589198">
    <descr><p>Removes the specified attribute node. If the removed
          <code>Attr</code> 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.</p>
    </descr>
    <parameters>
      <param name="oldAttr" type="Attr" attr="in">
	<descr><p>The <code>Attr</code> node to remove from the attribute
	    list.</p></descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>The <code>Attr</code> node that was removed.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
	readonly.</p>
        <p>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute of
	the element.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="getElementsByTagName" id="ID-1938918D">
    <descr><p>Returns a <code>NodeList</code> of all <termref def="dt-descendant">descendant</termref>
        <code>Elements</code> with a given tag name, in the order in which they
        are encountered in a preorder traversal of this <code>Element</code>
        tree.</p></descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the tag to match on. The special value "*"
	    matches all tags.</p></descr>
      </param>
    </parameters>
    <returns type="NodeList">
      <descr><p>A list of matching <code>Element</code> nodes.</p></descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>

  <!-- ****** DOM Level 2 additions ****** -->
  <method name="getAttributeNS" id="ID-ElGetAttrNS" since="DOM Level 2">
    <descr><p>Retrieves an attribute value by local name and namespace
	URI. HTML-only DOM implementations do not need to implement this
	method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to retrieve.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    attribute to retrieve.</p>
	</descr>
      </param>
    </parameters>
    <returns type="DOMString">
      <descr><p>The <code>Attr</code> value as a string, or the empty string if
        that attribute does not have a specified or default value.</p></descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
  <method name="setAttributeNS" id="ID-ElSetAttrNS" since="DOM Level 2">
    <descr><p>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 <code>qualifiedName</code>, and
	its value is changed to be the <code>value</code> 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
	<code>Attr</code> node plus any <code>Text</code> and
	<code>EntityReference</code> nodes, build the appropriate subtree, and
	use <code>setAttributeNodeNS</code> or <code>setAttributeNode</code> to
	assign it as the value of an attribute.</p>
      <p>HTML-only DOM implementations do not need to implement this
        method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to create or alter.</p>
	</descr>
      </param>
      <param name="qualifiedName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
	    of the attribute to create or alter.</p>
	</descr>
      </param>
      <param name="value" type="DOMString" attr="in">
	<descr><p>The value to set in string form.</p></descr>
      </param>
    </parameters>
    <returns type="void">
      <descr><p></p></descr>      
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
	    contains an illegal character.</p>
	  <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
	  <p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
	    malformed, if the <code>qualifiedName</code> has a prefix and
	    the <code>namespaceURI</code> is <code>null</code>, if the 
            <code>qualifiedName</code> has a prefix that is
	    "xml" and the <code>namespaceURI</code> is different from
	    "<loc href='xml-ns;'>xml-ns;</loc>", or if the
	    <code>qualifiedName</code> is "xmlns" and the
	    <code>namespaceURI</code> is different from
	    "<loc href='xmlns-ns;'>xmlns-ns;</loc>".</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="removeAttributeNS" id="ID-ElRemAtNS" since="DOM Level 2">
    <descr><p>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.</p>
	<p>HTML-only DOM implementations do not need to implement this
	  method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to remove.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    attribute to remove.</p>
	</descr>
      </param>
    </parameters>
    <returns type="void">
      <descr><p></p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
	    readonly.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="getAttributeNodeNS" id="ID-ElGetAtNodeNS" since="DOM Level 2">
    <descr><p>Retrieves an <code>Attr</code> node by local name and namespace
	URI. HTML-only DOM implementations do not need to implement this
	method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to retrieve.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    attribute to retrieve.</p>
	</descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>The <code>Attr</code> node with the specified attribute local
	  name and namespace URI or <code>null</code> if there is no such
	  attribute.</p>
      </descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
  <method name="setAttributeNodeNS" id="ID-ElSetAtNodeNS" since="DOM Level 2">
    <descr><p>Adds a new attribute. If an attribute with that local name and
	that namespace URI is already present in the element, it is replaced by
	the new one.</p>
	<p>HTML-only DOM implementations do not need to implement this
	  method.</p>
    </descr>
    <parameters>
      <param name="newAttr" type="Attr" attr="in">
	<descr><p>The <code>Attr</code> node to add to the attribute list.</p>
	</descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>If the <code>newAttr</code> attribute replaces an existing
	  attribute with the same <termref def='dt-localname'>local
	    name</termref> and <termref def='dt-namespaceURI'>namespace
	    URI</termref>, the replaced <code>Attr</code> node is
	  returned, otherwise <code>null</code> is returned.</p>
      </descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
	    created from a different document than the one that created the
	    element.</p>
	  <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
	  <p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
	    attribute of another <code>Element</code> object. The DOM user
	    must explicitly clone <code>Attr</code> nodes to re-use them in
	    other elements.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="getElementsByTagNameNS" id="ID-A6C90942" since="DOM Level 2">
    <descr><p>Returns a <code>NodeList</code> of all the <termref def="dt-descendant">descendant</termref>
        <code>Elements</code> with a given local name and namespace URI in the
        order in which they are encountered in a preorder traversal of this
        <code>Element</code> tree.</p>
	<p>HTML-only DOM implementations do not need to implement this
	  method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the elements to match on. The special value "*" matches all
	    namespaces.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    elements to match on. The special value "*" matches all local
	    names.</p>
	</descr>
      </param>
    </parameters>
    <returns type="NodeList">
      <descr><p>A new <code>NodeList</code> object containing all the matched
	  <code>Elements</code>.</p>
      </descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>
  <method name="hasAttribute" id="ID-ElHasAttr" since="DOM Level 2">
    <descr><p>Returns <code>true</code> when an attribute with a given name is
      specified on this element or has a default value, <code>false</code>
      otherwise.</p>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the attribute to look for.</p></descr>
      </param>
    </parameters>
    <returns type="boolean">
      <descr><p><code>true</code> if an attribute with the given name is
        specified on this element or has a default value, <code>false</code>
        otherwise.</p>
      </descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
  <method name="hasAttributeNS" id="ID-ElHasAttrNS" since="DOM Level 2">
    <descr><p>Returns <code>true</code> when an attribute with a given local
       name and namespace URI is specified on this element or has a default
       value, <code>false</code> otherwise. HTML-only DOM implementations do
       not need to implement this method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to look for.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    attribute to look for.</p>
	</descr>
      </param>
    </parameters>
    <returns type="boolean">
      <descr><p><code>true</code> if an attribute with the given local name and
        namespace URI is specified or has a default value on this element,
        <code>false</code> otherwise.</p>
      </descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>
</interface>
      
