## com.gargoylesoftware.htmlunit.html
Class HtmlElement

    java.lang.Object
      com.gargoylesoftware.htmlunit.html.DomNode
          com.gargoylesoftware.htmlunit.html.DomNamespaceNode
              com.gargoylesoftware.htmlunit.html.DomElement
                  com.gargoylesoftware.htmlunit.html.HtmlElement

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, org.w3c.dom.Element, org.w3c.dom.Node

Direct Known Subclasses:
  HtmlBackgroundSound, HtmlBase, HtmlBaseFont, HtmlCanvas, HtmlEmbed, HtmlExample, HtmlHead, HtmlHtml, HtmlListing, HtmlMarquee, HtmlMeta, HtmlNoBreak, HtmlParameter, HtmlPlainText, HtmlScript, HtmlStrong, HtmlStyle, HtmlTitle, HtmlWordBreak, StyledElement

    public abstract class HtmlElement

extends DomElement

An abstract wrapper for HTML elements.

Version:
  $Revision: 4792 $
Author:
  Mike Bowler, Mike J. Bresnahan, David K. Taylor, Christian Sell, David D. Kilzer, Mike Gallaher, Denis N. Antonioli, Marc Guillemot, Ahmed Ashour, Daniel Gredler, Dmitri Zoubkov, Sudhan Moghe
See Also:
  Serialized Form

Nested Class Summary
`protected class` `HtmlElement.ChildElementsIterator` An iterator over the HtmlElement children.

Nested classes/interfaces inherited from class com.gargoylesoftware.htmlunit.html.DomNode
`DomNode.ChildIterator, DomNode.DescendantElementsIterator`

Field Summary
`static java.lang.Short` `TAB_INDEX_OUT_OF_BOUNDS` Constant indicating that a tab index value is out of bounds (less than `0` or greater than `32767`).

Fields inherited from class com.gargoylesoftware.htmlunit.html.DomElement
`ATTRIBUTE_NOT_DEFINED, ATTRIBUTE_VALUE_EMPTY`

Fields inherited from class com.gargoylesoftware.htmlunit.html.DomNode
`AS_TEXT_BLANK, AS_TEXT_BLOCK_SEPARATOR, AS_TEXT_NEW_LINE, AS_TEXT_TAB, PROPERTY_ELEMENT, READY_STATE_COMPLETE, READY_STATE_INTERACTIVE, READY_STATE_LOADED, READY_STATE_LOADING, READY_STATE_UNINITIALIZED`

Fields inherited from interface org.w3c.dom.Node

`ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

Constructor Summary
`protected` `HtmlElement(java.lang.String namespaceURI, java.lang.String qualifiedName, SgmlPage page, java.util.Map<java.lang.String,DomAttr> attributes)` Creates an instance.

Method Summary
`void` `addHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)` Adds an HtmlAttributeChangeListener to the listener list.
`HtmlElement` `appendChildIfNoneExists(java.lang.String tagName)` Appends a child element to this HTML element with the specified tag name if this HTML element does not already have a child with that tag name.
`void` `blur()` Removes focus from this element.
`protected void` `checkChildHierarchy(org.w3c.dom.Node childNode)` Check for insertion errors for a new child node.

`

`<P extends Page> P`

`

`click()`
Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked.

`

`<P extends Page> P`

`

`click(boolean shiftKey, boolean ctrlKey, boolean altKey)`
Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked.

`

`<P extends Page> P`

`

`click(com.gargoylesoftware.htmlunit.javascript.host.Event event)`
INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked.

`

`<P extends Page> P`

`

`dblClick()`
Simulates double-clicking on this element, returning the page in the window that has the focus after the element has been clicked.

`

`<P extends Page> P`

`

`dblClick(boolean shiftKey, boolean ctrlKey, boolean altKey)`
Simulates double-clicking on this element, returning the page in the window that has the focus after the element has been clicked.

`protected Page` `doClickAction(Page defaultPage)` This method will be called if there either wasn't an `onclick` handler, or if there was one, but the result of that handler wasn't `false`.
`protected void` `doType(char c, boolean shiftKey, boolean ctrlKey, boolean altKey)` Performs the effective type action, called after the keyPress event and before the keyUp event.
`ScriptResult` `fireEvent(com.gargoylesoftware.htmlunit.javascript.host.Event event)` Fires the event on the element.
`ScriptResult` `fireEvent(java.lang.String eventType)` Shortcut for `fireEvent(Event)`.
`protected void` `fireHtmlAttributeAdded(HtmlAttributeChangeEvent event)` Support for reporting HTML attribute changes.
`protected void` `fireHtmlAttributeRemoved(HtmlAttributeChangeEvent event)` Support for reporting HTML attribute changes.
`protected void` `fireHtmlAttributeReplaced(HtmlAttributeChangeEvent event)` Support for reporting HTML attribute changes.
`void` `focus()` Sets the focus on this element.
`java.lang.Iterable<HtmlElement>` `getChildElements()`

`

`<E extends HtmlElement> E`

`

`getElementById(java.lang.String id)`
Returns the element in this element's page with the specified ID.

`

`<E extends HtmlElement> java.util.List<E>`

`

`getElementsByAttribute(java.lang.String elementName, java.lang.String attributeName, java.lang.String attributeValue)`
Returns all elements which are descendants of this element and match the specified search criteria.

`HtmlElement` `getEnclosingElement(java.lang.String tagName)` Returns the first element with the specified tag name that is an ancestor to this element, or `null` if no such element is found.
`HtmlForm` `getEnclosingForm()` Returns the form which contains this element, or `null` if this element is not inside of a form.
`HtmlForm` `getEnclosingFormOrDie()` Returns the form which contains this element.
`net.sourceforge.htmlunit.corejs.javascript.Function` `getEventHandler(java.lang.String eventName)` INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Return a Function to be executed when a given event occurs.

`

`<E extends HtmlElement> java.util.List<E>`

`

`getHtmlElementsByTagName(java.lang.String tagName)`
Returns the HTML elements that are descendants of this element and that have the specified tag name.

`java.util.List<HtmlElement>` `getHtmlElementsByTagNames(java.util.List<java.lang.String> tagNames)` Returns the HTML elements that are descendants of this element and that have one of the specified tag names.
`java.lang.String` `getId()`
`java.lang.String` `getLangAttribute()` Returns the value of the attribute "lang".
`java.lang.String` `getNodeName()` Returns this node's node name.
`java.lang.String` `getOnClickAttribute()` Returns the value of the attribute "onclick".
`java.lang.String` `getOnDblClickAttribute()` Returns the value of the attribute "ondblclick".

`

`<E extends HtmlElement> E`

`

`getOneHtmlElementByAttribute(java.lang.String elementName, java.lang.String attributeName, java.lang.String attributeValue)`
Searches for an element based on the specified criteria, returning the first element which matches said criteria.

`java.lang.String` `getOnKeyDownAttribute()` Returns the value of the attribute "onkeydown".
`java.lang.String` `getOnKeyPressAttribute()` Returns the value of the attribute "onkeypress".
`java.lang.String` `getOnKeyUpAttribute()` Returns the value of the attribute "onkeyup".
`java.lang.String` `getOnMouseDownAttribute()` Returns the value of the attribute "onmousedown".
`java.lang.String` `getOnMouseMoveAttribute()` Returns the value of the attribute "onmousemove".
`java.lang.String` `getOnMouseOutAttribute()` Returns the value of the attribute "onmouseout".
`java.lang.String` `getOnMouseOverAttribute()` Returns the value of the attribute "onmouseover".
`java.lang.String` `getOnMouseUpAttribute()` Returns the value of the attribute "onmouseup".
`java.lang.Short` `getTabIndex()` Returns this element's tab index, if it has one.
`java.lang.String` `getTextDirectionAttribute()` Returns the value of the attribute "dir".
`java.lang.String` `getXmlLangAttribute()` Returns the value of the attribute "xml:lang".
`boolean` `hasHtmlElementWithId(java.lang.String id)` Returns `true` if there is an element in this element's page with the specified ID.
`protected boolean` `isAttributeCaseSensitive()` Indicates if the attribute names are case sensitive.
`protected boolean` `isStateUpdateFirst()` Returns `true` if state updates should be done before onclick event handling.
`protected boolean` `isSubmittableByEnter()` Returns `true` if clicking Enter (ASCII 10, or '\n') should submit the enclosed form (if any).
`Page` `mouseDown()` Simulates clicking the mouse on this element, returning the page which this element's window contains after the mouse click.
`Page` `mouseDown(boolean shiftKey, boolean ctrlKey, boolean altKey, int button)` Simulates clicking the mouse on this element, returning the page which this element's window contains after the mouse click.
`Page` `mouseMove()` Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseMove(boolean shiftKey, boolean ctrlKey, boolean altKey, int button)` Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseOut()` Simulates moving the mouse out of this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseOut(boolean shiftKey, boolean ctrlKey, boolean altKey, int button)` Simulates moving the mouse out of this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseOver()` Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseOver(boolean shiftKey, boolean ctrlKey, boolean altKey, int button)` Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move.
`Page` `mouseUp()` Simulates releasing the mouse click on this element, returning the page which this element's window contains after the mouse click release.
`Page` `mouseUp(boolean shiftKey, boolean ctrlKey, boolean altKey, int button)` Simulates releasing the mouse click on this element, returning the page which this element's window contains after the mouse click release.
`protected void` `preventDefault()` This method is called if the current fired event is canceled by `preventDefault()` in FireFox, or by returning `false` in Internet Explorer.
`void` `removeAttribute(java.lang.String attributeName)` Removes an attribute specified by name from this element.
`void` `removeChild(java.lang.String tagName, int i)` Removes the `i`th child element with the specified tag name from all relationships, if possible.
`void` `removeEventHandler(java.lang.String eventName)` INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Removes the specified event handler.
`void` `removeHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)` Removes an HtmlAttributeChangeListener from the listener list.
`Page` `rightClick()` Simulates right clicking the mouse on this element, returning the page which this element's window contains after the mouse click.
`Page` `rightClick(boolean shiftKey, boolean ctrlKey, boolean altKey)` Simulates right clicking the mouse on this element, returning the page which this element's window contains after the mouse click.
`void` `setAttributeNS(java.lang.String namespaceURI, java.lang.String qualifiedName, java.lang.String attributeValue)` Sets the value of the specified attribute.
`void` `setEventHandler(java.lang.String eventName, net.sourceforge.htmlunit.corejs.javascript.Function eventHandler)` INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Register a Function as an event handler.
`void` `setEventHandler(java.lang.String eventName, java.lang.String jsSnippet)` INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Register a snippet of JavaScript code as an event handler.
`void` `setId(java.lang.String newId)` Sets the identifier this element.
`java.lang.String` `toString()` Returns a string representation of this object.
`Page` `type(char c)` Simulates typing the specified character while this element has focus, returning the page contained by this element's window after typing.
`Page` `type(char c, boolean shiftKey, boolean ctrlKey, boolean altKey)` Simulates typing the specified character while this element has focus, returning the page contained by this element's window after typing.
`void` `type(java.lang.String text)` Simulates typing the specified text while this element has focus.
`void` `type(java.lang.String text, boolean shiftKey, boolean ctrlKey, boolean altKey)` Simulates typing the specified text while this element has focus.

Methods inherited from class com.gargoylesoftware.htmlunit.html.DomElement

`cloneNode, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getAttributes, getAttributesMap, getElementsByTagName, getElementsByTagNameNS, getNodeType, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, hasAttributes, isEmptyXmlTagExpanded, namespaces, printOpeningTagContentAsXml, printXml, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS`

Methods inherited from class com.gargoylesoftware.htmlunit.html.DomNamespaceNode
`getLocalName, getNamespaceURI, getPrefix, getQualifiedName, setPrefix`

Methods inherited from class com.gargoylesoftware.htmlunit.html.DomNode

`addDomChangeListener, appendChild, asText, asXml, compareDocumentPosition, fireNodeAdded, fireNodeDeleted, getAllHtmlChildElements, getAncestors, getBaseURI, getByXPath, getCanonicalXPath, getChildNodes, getChildren, getEndColumnNumber, getEndLineNumber, getFeature, getFirstByXPath, getFirstChild, getLastChild, getNextSibling, getNodeValue, getOwnerDocument, getPage, getParentNode, getPreviousSibling, getReadyState, getScriptObject, getStartColumnNumber, getStartLineNumber, getTextContent, getUserData, hasChildNodes, insertBefore, insertBefore, isAncestorOf, isBlock, isDefaultNamespace, isDisplayed, isEqualNode, isSameNode, isSupported, isTrimmedText, lookupNamespaceURI, lookupPrefix, normalize, notifyIncorrectness, onAddedToPage, onAllChildrenAddedToPage, printChildrenAsXml, remove, removeAllChildren, removeChild, removeDomChangeListener, replace, replaceChild, selectNodes, selectSingleNode, setNextSibling, setNodeValue, setParentNode, setPreviousSibling, setReadyState, setScriptObject, setTextContent, setUserData`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface org.w3c.dom.Node

`appendChild, compareDocumentPosition, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

Field Detail

### TAB_INDEX_OUT_OF_BOUNDS

    public static final java.lang.Short TAB_INDEX_OUT_OF_BOUNDS

  Constant indicating that a tab index value is out of bounds (less than `0` or greater than `32767`).

  See Also:
    `getTabIndex()`

Constructor Detail

### HtmlElement

    protected HtmlElement(java.lang.String namespaceURI,
                          java.lang.String qualifiedName,
                          SgmlPage page,
                          java.util.Map<java.lang.String,DomAttr> attributes)

  Creates an instance.

  Parameters:
    `namespaceURI` - the URI that identifies an XML namespace
    `qualifiedName` - the qualified name of the element type to instantiate
    `page` - the page that contains this element
    `attributes` - a map ready initialized with the attributes for this element, or `null`. The map will be stored as is, not copied.

Method Detail

### setAttributeNS

    public void setAttributeNS(java.lang.String namespaceURI,
                               java.lang.String qualifiedName,
                               java.lang.String attributeValue)

  Sets the value of the specified attribute. This method may be overridden by subclasses which are interested in specific attribute value changes, but such methods must invoke `super.setAttributeValue()`, and should consider the value of the `cloning` parameter when deciding whether or not to execute custom logic.

  Specified by:
    `setAttributeNS` in interface `org.w3c.dom.Element`
  Overrides:
    `setAttributeNS` in class `DomElement`
  Parameters:
    `namespaceURI` - the URI that identifies an XML namespace
    `qualifiedName` - the qualified name of the attribute
    `attributeValue` - the value of the attribute

### getHtmlElementsByTagNames

    public final java.util.List<HtmlElement> getHtmlElementsByTagNames(java.util.List<java.lang.String> tagNames)

  Returns the HTML elements that are descendants of this element and that have one of the specified tag names.

  Parameters:
    `tagNames` - the tag names to match (case-insensitive)
  Returns:
    the HTML elements that are descendants of this element and that have one of the specified tag name

### getHtmlElementsByTagName

    public final <E extends HtmlElement> java.util.List<E> getHtmlElementsByTagName(java.lang.String tagName)

  Returns the HTML elements that are descendants of this element and that have the specified tag name.

  Type Parameters:
    `E` - the sub-element type
  Parameters:
    `tagName` - the tag name to match (case-insensitive)
  Returns:
    the HTML elements that are descendants of this element and that have the specified tag name

### removeAttribute

    public final void removeAttribute(java.lang.String attributeName)

  Removes an attribute specified by name from this element.

  Specified by:
    `removeAttribute` in interface `org.w3c.dom.Element`
  Overrides:
    `removeAttribute` in class `DomElement`
  Parameters:
    `attributeName` - the attribute attributeName

### fireHtmlAttributeAdded

    protected void fireHtmlAttributeAdded(HtmlAttributeChangeEvent event)

  Support for reporting HTML attribute changes. This method can be called when an attribute has been added and it will send the appropriate `HtmlAttributeChangeEvent` to any registered `HtmlAttributeChangeListener`s. Note that this method recursively calls this element's parent's `fireHtmlAttributeAdded(HtmlAttributeChangeEvent)` method.

  Parameters:
    `event` - the event
  See Also:
    `addHtmlAttributeChangeListener(HtmlAttributeChangeListener)`

### fireHtmlAttributeReplaced

    protected void fireHtmlAttributeReplaced(HtmlAttributeChangeEvent event)

  Support for reporting HTML attribute changes. This method can be called when an attribute has been replaced and it will send the appropriate `HtmlAttributeChangeEvent` to any registered `HtmlAttributeChangeListener`s. Note that this method recursively calls this element's parent's `fireHtmlAttributeReplaced(HtmlAttributeChangeEvent)` method.

  Parameters:
    `event` - the event
  See Also:
    `addHtmlAttributeChangeListener(HtmlAttributeChangeListener)`

### fireHtmlAttributeRemoved

    protected void fireHtmlAttributeRemoved(HtmlAttributeChangeEvent event)

  Support for reporting HTML attribute changes. This method can be called when an attribute has been removed and it will send the appropriate `HtmlAttributeChangeEvent` to any registered `HtmlAttributeChangeListener`s. Note that this method recursively calls this element's parent's `fireHtmlAttributeRemoved(HtmlAttributeChangeEvent)` method.

  Parameters:
    `event` - the event
  See Also:
    `addHtmlAttributeChangeListener(HtmlAttributeChangeListener)`

### getNodeName

    public java.lang.String getNodeName()

  Description copied from class: `DomElement`
  Returns this node's node name.

  Specified by:
    `getNodeName` in interface `org.w3c.dom.Node`
  Overrides:
    `getNodeName` in class `DomElement`
  Returns:
    the same value as returned by `DomElement.getTagName()`

### getId

    public final java.lang.String getId()

  Returns:
    the identifier of this element

### setId

    public final void setId(java.lang.String newId)

  Sets the identifier this element.

  Parameters:
    `newId` - the new identifier of this element

### getTabIndex

    public java.lang.Short getTabIndex()

  Returns this element's tab index, if it has one. If the tab index is outside of the valid range (less than `0` or greater than `32767`), this method returns `TAB_INDEX_OUT_OF_BOUNDS`. If this element does not have a tab index, or its tab index is otherwise invalid, this method returns `null`.

  Returns:
    this element's tab index

### getEnclosingElement

    public HtmlElement getEnclosingElement(java.lang.String tagName)

  Returns the first element with the specified tag name that is an ancestor to this element, or `null` if no such element is found.

  Parameters:
    `tagName` - the name of the tag searched (case insensitive)
  Returns:
    the first element with the specified tag name that is an ancestor to this element

### getEnclosingForm

    public HtmlForm getEnclosingForm()

  Returns the form which contains this element, or `null` if this element is not inside of a form.

  Returns:
    the form which contains this element

### getEnclosingFormOrDie

    public HtmlForm getEnclosingFormOrDie()
                                   throws java.lang.IllegalStateException

  Returns the form which contains this element. If this element is not inside a form, this method throws an `IllegalStateException`.

  Returns:
    the form which contains this element
  Throws:
    `java.lang.IllegalStateException` - if the element is not inside a form

### type

    public void type(java.lang.String text)
              throws java.io.IOException

  Simulates typing the specified text while this element has focus. Note that for some elements, typing '\n' submits the enclosed form.

  Parameters:
    `text` - the text you with to simulate typing
  Throws:
    `java.io.IOException` - If an IO error occurs

### type

    public void type(java.lang.String text,
                     boolean shiftKey,
                     boolean ctrlKey,
                     boolean altKey)
              throws java.io.IOException

  Simulates typing the specified text while this element has focus. Note that for some elements, typing '\n' submits the enclosed form.

  Parameters:
    `text` - the text you with to simulate typing
    `shiftKey` - true if SHIFT is pressed
    `ctrlKey` - true if CTRL is pressed
    `altKey` - true if ALT is pressed
  Throws:
    `java.io.IOException` - If an IO error occurs

### type

    public Page type(char c)
              throws java.io.IOException

  Simulates typing the specified character while this element has focus, returning the page contained by this element's window after typing. Note that it may or may not be the same as the original page, depending on the JavaScript event handlers, etc. Note also that for some elements, typing `'\n'` submits the enclosed form.

  Parameters:
    `c` - the character you with to simulate typing
  Returns:
    the page that occupies this window after typing
  Throws:
    `java.io.IOException` - if an IO error occurs

### type

    public Page type(char c,
                     boolean shiftKey,
                     boolean ctrlKey,
                     boolean altKey)
              throws java.io.IOException

  Simulates typing the specified character while this element has focus, returning the page contained by this element's window after typing. Note that it may or may not be the same as the original page, depending on the JavaScript event handlers, etc. Note also that for some elements, typing `'\n'` submits the enclosed form.

  Parameters:
    `c` - the character you with to simulate typing
    `shiftKey` - `true` if SHIFT is pressed during the typing
    `ctrlKey` - `true` if CTRL is pressed during the typing
    `altKey` - `true` if ALT is pressed during the typing
  Returns:
    the page that occupies this window after typing
  Throws:
    `java.io.IOException` - if an IO error occurs

### doType

    protected void doType(char c,
                          boolean shiftKey,
                          boolean ctrlKey,
                          boolean altKey)

  Performs the effective type action, called after the keyPress event and before the keyUp event.

  Parameters:
    `c` - the character you with to simulate typing
    `shiftKey` - `true` if SHIFT is pressed during the typing
    `ctrlKey` - `true` if CTRL is pressed during the typing
    `altKey` - `true` if ALT is pressed during the typing

### isSubmittableByEnter

    protected boolean isSubmittableByEnter()

  Returns `true` if clicking Enter (ASCII 10, or '\n') should submit the enclosed form (if any). The default implementation returns `false`.

  Returns:
    `true` if clicking Enter should submit the enclosed form (if any)

### toString

    public java.lang.String toString()

  Returns a string representation of this object.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    a string representation of this object

### getOneHtmlElementByAttribute

    public final <E extends HtmlElement> E getOneHtmlElementByAttribute(java.lang.String elementName,
                                                                        java.lang.String attributeName,
                                                                        java.lang.String attributeValue)
                                                             throws ElementNotFoundException

  Searches for an element based on the specified criteria, returning the first element which matches said criteria. Only elements which are descendants of this element are included in the search.

  Type Parameters:
    `E` - the sub-element type
  Parameters:
    `elementName` - the name of the element to search for
    `attributeName` - the name of the attribute to search for
    `attributeValue` - the value of the attribute to search for
  Returns:
    the first element which matches the specified search criteria
  Throws:
    `ElementNotFoundException` - if no element matches the specified search criteria

### getElementById

    public <E extends HtmlElement> E getElementById(java.lang.String id)
                                         throws ElementNotFoundException

  Returns the element in this element's page with the specified ID. If more than one element has the specified ID (not allowed by the HTML spec), this method returns the first one.

  Type Parameters:
    `E` - the sub-element type
  Parameters:
    `id` - the ID value to search for
  Returns:
    the element in this element's page with the specified ID
  Throws:
    `ElementNotFoundException` - if no element has the specified ID

### hasHtmlElementWithId

    public boolean hasHtmlElementWithId(java.lang.String id)

  Returns `true` if there is an element in this element's page with the specified ID. This method is intended for situations where it is enough to know whether a specific element is present in the document.

  Implementation Note: This method calls `getElementById(String)` internally, so writing code such as the following would be extremely inefficient:

       if (hasHtmlElementWithId(id)) {
           HtmlElement element = getHtmlElementWithId(id)
           ...
       }

  Parameters:
    `id` - the id to search for
  Returns:
    `true` if there is an element in this element's page with the specified ID

### getElementsByAttribute

    public final <E extends HtmlElement> java.util.List<E> getElementsByAttribute(java.lang.String elementName,
                                                                                  java.lang.String attributeName,
                                                                                  java.lang.String attributeValue)

  Returns all elements which are descendants of this element and match the specified search criteria.

  Type Parameters:
    `E` - the sub-element type
  Parameters:
    `elementName` - the name of the element to search for
    `attributeName` - the name of the attribute to search for
    `attributeValue` - the value of the attribute to search for
  Returns:
    all elements which are descendants of this element and match the specified search criteria

### appendChildIfNoneExists

    public final HtmlElement appendChildIfNoneExists(java.lang.String tagName)

  Appends a child element to this HTML element with the specified tag name if this HTML element does not already have a child with that tag name. Returns the appended child element, or the first existent child element with the specified tag name if none was appended.

  Parameters:
    `tagName` - the tag name of the child to append
  Returns:
    the added child, or the first existing child if none was added

### removeChild

    public final void removeChild(java.lang.String tagName,
                                  int i)

  Removes the `i`th child element with the specified tag name from all relationships, if possible.

  Parameters:
    `tagName` - the tag name of the child to remove
    `i` - the index of the child to remove

### getChildElements

    public final java.lang.Iterable<HtmlElement> getChildElements()

  Returns:
    an Iterable over the HtmlElement children of this object, i.e. excluding the non-element nodes

### getEventHandler

    public final net.sourceforge.htmlunit.corejs.javascript.Function getEventHandler(java.lang.String eventName)

  INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
  Return a Function to be executed when a given event occurs.

  Parameters:
    `eventName` - Name of event such as "onclick" or "onblur", etc
  Returns:
    a Rhino JavaScript executable Function, or `null` if no event handler has been defined

### setEventHandler

    public final void setEventHandler(java.lang.String eventName,
                                      net.sourceforge.htmlunit.corejs.javascript.Function eventHandler)

  INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
  Register a Function as an event handler.

  Parameters:
    `eventName` - Name of event such as "onclick" or "onblur", etc
    `eventHandler` - a Rhino JavaScript executable Function

### setEventHandler

    public final void setEventHandler(java.lang.String eventName,
                                      java.lang.String jsSnippet)

  INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
  Register a snippet of JavaScript code as an event handler. The JavaScript code will be wrapped inside a unique function declaration which provides one argument named "event"

  Parameters:
    `eventName` - Name of event such as "onclick" or "onblur", etc
    `jsSnippet` - executable JavaScript code

### removeEventHandler

    public final void removeEventHandler(java.lang.String eventName)

  INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
  Removes the specified event handler.

  Parameters:
    `eventName` - Name of the event such as "onclick" or "onblur", etc

### addHtmlAttributeChangeListener

    public void addHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)

  Adds an HtmlAttributeChangeListener to the listener list. The listener is registered for all attributes of this HtmlElement, as well as descendant elements.

  Parameters:
    `listener` - the attribute change listener to be added
  See Also:
    `removeHtmlAttributeChangeListener(HtmlAttributeChangeListener)`

### removeHtmlAttributeChangeListener

    public void removeHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)

  Removes an HtmlAttributeChangeListener from the listener list. This method should be used to remove HtmlAttributeChangeListener that were registered for all attributes of this HtmlElement, as well as descendant elements.

  Parameters:
    `listener` - the attribute change listener to be removed
  See Also:
    `addHtmlAttributeChangeListener(HtmlAttributeChangeListener)`

### fireEvent

    public ScriptResult fireEvent(java.lang.String eventType)

  Shortcut for `fireEvent(Event)`.

  Parameters:
    `eventType` - the event type (like "load", "click")
  Returns:
    the execution result, or `null` if nothing is executed

### fireEvent

    public ScriptResult fireEvent(com.gargoylesoftware.htmlunit.javascript.host.Event event)

  Fires the event on the element. Nothing is done if JavaScript is disabled.

  Parameters:
    `event` - the event to fire
  Returns:
    the execution result, or `null` if nothing is executed

### preventDefault

    protected void preventDefault()

  This method is called if the current fired event is canceled by `preventDefault()` in FireFox, or by returning `false` in Internet Explorer. The default implementation does nothing.

### mouseOver

    public Page mouseOver()

  Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse move

### mouseOver

    public Page mouseOver(boolean shiftKey,
                          boolean ctrlKey,
                          boolean altKey,
                          int button)

  Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse move
    `ctrlKey` - `true` if CTRL is pressed during the mouse move
    `altKey` - `true` if ALT is pressed during the mouse move
    `button` - the button code, must be `MouseEvent.BUTTON_LEFT`, `MouseEvent.BUTTON_MIDDLE` or `MouseEvent.BUTTON_RIGHT`
  Returns:
    the page which this element's window contains after the mouse move

### mouseMove

    public Page mouseMove()

  Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse move

### mouseMove

    public Page mouseMove(boolean shiftKey,
                          boolean ctrlKey,
                          boolean altKey,
                          int button)

  Simulates moving the mouse over this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse move
    `ctrlKey` - `true` if CTRL is pressed during the mouse move
    `altKey` - `true` if ALT is pressed during the mouse move
    `button` - the button code, must be `MouseEvent.BUTTON_LEFT`, `MouseEvent.BUTTON_MIDDLE` or `MouseEvent.BUTTON_RIGHT`
  Returns:
    the page which this element's window contains after the mouse move

### mouseOut

    public Page mouseOut()

  Simulates moving the mouse out of this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse move

### mouseOut

    public Page mouseOut(boolean shiftKey,
                         boolean ctrlKey,
                         boolean altKey,
                         int button)

  Simulates moving the mouse out of this element, returning the page which this element's window contains after the mouse move. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse move
    `ctrlKey` - `true` if CTRL is pressed during the mouse move
    `altKey` - `true` if ALT is pressed during the mouse move
    `button` - the button code, must be `MouseEvent.BUTTON_LEFT`, `MouseEvent.BUTTON_MIDDLE` or `MouseEvent.BUTTON_RIGHT`
  Returns:
    the page which this element's window contains after the mouse move

### mouseDown

    public Page mouseDown()

  Simulates clicking the mouse on this element, returning the page which this element's window contains after the mouse click. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse click

### mouseDown

    public Page mouseDown(boolean shiftKey,
                          boolean ctrlKey,
                          boolean altKey,
                          int button)

  Simulates clicking the mouse on this element, returning the page which this element's window contains after the mouse click. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse click
    `ctrlKey` - `true` if CTRL is pressed during the mouse click
    `altKey` - `true` if ALT is pressed during the mouse click
    `button` - the button code, must be `MouseEvent.BUTTON_LEFT`, `MouseEvent.BUTTON_MIDDLE` or `MouseEvent.BUTTON_RIGHT`
  Returns:
    the page which this element's window contains after the mouse click

### mouseUp

    public Page mouseUp()

  Simulates releasing the mouse click on this element, returning the page which this element's window contains after the mouse click release. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse click release

### mouseUp

    public Page mouseUp(boolean shiftKey,
                        boolean ctrlKey,
                        boolean altKey,
                        int button)

  Simulates releasing the mouse click on this element, returning the page which this element's window contains after the mouse click release. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse click release
    `ctrlKey` - `true` if CTRL is pressed during the mouse click release
    `altKey` - `true` if ALT is pressed during the mouse click release
    `button` - the button code, must be `MouseEvent.BUTTON_LEFT`, `MouseEvent.BUTTON_MIDDLE` or `MouseEvent.BUTTON_RIGHT`
  Returns:
    the page which this element's window contains after the mouse click release

### rightClick

    public Page rightClick()

  Simulates right clicking the mouse on this element, returning the page which this element's window contains after the mouse click. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Returns:
    the page which this element's window contains after the mouse click

### rightClick

    public Page rightClick(boolean shiftKey,
                           boolean ctrlKey,
                           boolean altKey)

  Simulates right clicking the mouse on this element, returning the page which this element's window contains after the mouse click. The returned page may or may not be the same as the original page, depending on JavaScript event handlers, etc.

  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the mouse click
    `ctrlKey` - `true` if CTRL is pressed during the mouse click
    `altKey` - `true` if ALT is pressed during the mouse click
  Returns:
    the page which this element's window contains after the mouse click

### blur

    public void blur()

  Removes focus from this element.

### focus

    public void focus()

  Sets the focus on this element.

### checkChildHierarchy

    protected void checkChildHierarchy(org.w3c.dom.Node childNode)
                                throws org.w3c.dom.DOMException

  Check for insertion errors for a new child node. This is overridden by derived classes to enforce which types of children are allowed.

  Overrides:
    `checkChildHierarchy` in class `DomNode`
  Parameters:
    `childNode` - the new child node that is being inserted below this node
  Throws:
    `org.w3c.dom.DOMException` - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors or this node itself, or if this node is of type Document and the DOM application attempts to insert a second DocumentType or Element node. WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

### isAttributeCaseSensitive

    protected boolean isAttributeCaseSensitive()

  Indicates if the attribute names are case sensitive.

  Overrides:
    `isAttributeCaseSensitive` in class `DomElement`
  Returns:
    `false`

### click

    public <P extends Page> P click()
                         throws java.io.IOException

  Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked. Note that the returned page may or may not be the same as the original page, depending on the type of element being clicked, the presence of JavaScript action listeners, etc.

  Type Parameters:
    `P` - the page type
  Returns:
    the page that occupies this element's window after the element has been clicked
  Throws:
    `java.io.IOException` - if an IO error occurs

### click

    public <P extends Page> P click(boolean shiftKey,
                                    boolean ctrlKey,
                                    boolean altKey)
                         throws java.io.IOException

  Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked. Note that the returned page may or may not be the same as the original page, depending on the type of element being clicked, the presence of JavaScript action listeners, etc.

  Type Parameters:
    `P` - the page type
  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the click
    `ctrlKey` - `true` if CTRL is pressed during the click
    `altKey` - `true` if ALT is pressed during the click
  Returns:
    the page that occupies this element's window after the element has been clicked
  Throws:
    `java.io.IOException` - if an IO error occurs

### click

    public <P extends Page> P click(com.gargoylesoftware.htmlunit.javascript.host.Event event)
                         throws java.io.IOException

  INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
  Simulates clicking on this element, returning the page in the window that has the focus after the element has been clicked. Note that the returned page may or may not be the same as the original page, depending on the type of element being clicked, the presence of JavaScript action listeners, etc.

  Type Parameters:
    `P` - the page type
  Parameters:
    `event` - the click event used
  Returns:
    the page that occupies this element's window after the element has been clicked
  Throws:
    `java.io.IOException` - if an IO error occurs

### dblClick

    public <P extends Page> P dblClick()
                            throws java.io.IOException

  Simulates double-clicking on this element, returning the page in the window that has the focus after the element has been clicked. Note that the returned page may or may not be the same as the original page, depending on the type of element being clicked, the presence of JavaScript action listeners, etc. Note also that `click()` is automatically called first.

  Type Parameters:
    `P` - the page type
  Returns:
    the page that occupies this element's window after the element has been double-clicked
  Throws:
    `java.io.IOException` - if an IO error occurs

### dblClick

    public <P extends Page> P dblClick(boolean shiftKey,
                                       boolean ctrlKey,
                                       boolean altKey)
                            throws java.io.IOException

  Simulates double-clicking on this element, returning the page in the window that has the focus after the element has been clicked. Note that the returned page may or may not be the same as the original page, depending on the type of element being clicked, the presence of JavaScript action listeners, etc. Note also that `click(boolean, boolean, boolean)` is automatically called first.

  Type Parameters:
    `P` - the page type
  Parameters:
    `shiftKey` - `true` if SHIFT is pressed during the double-click
    `ctrlKey` - `true` if CTRL is pressed during the double-click
    `altKey` - `true` if ALT is pressed during the double-click
  Returns:
    the page that occupies this element's window after the element has been double-clicked
  Throws:
    `java.io.IOException` - if an IO error occurs

### doClickAction

    protected Page doClickAction(Page defaultPage)
                          throws java.io.IOException

  This method will be called if there either wasn't an `onclick` handler, or if there was one, but the result of that handler wasn't `false`. This is the default behavior of clicking the element.

  The default implementation returns the current page. Subclasses requiring different behavior (like `HtmlSubmitInput`) will override this method.

  Parameters:
    `defaultPage` - the default page to return if the action does not load a new page
  Returns:
    the page that is currently loaded after execution of this method
  Throws:
    `java.io.IOException` - if an IO error occurs

### getLangAttribute

    public final java.lang.String getLangAttribute()

  Returns the value of the attribute "lang". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "lang" or an empty string if that attribute isn't defined

### getXmlLangAttribute

    public final java.lang.String getXmlLangAttribute()

  Returns the value of the attribute "xml:lang". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "xml:lang" or an empty string if that attribute isn't defined

### getTextDirectionAttribute

    public final java.lang.String getTextDirectionAttribute()

  Returns the value of the attribute "dir". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "dir" or an empty string if that attribute isn't defined

### getOnClickAttribute

    public final java.lang.String getOnClickAttribute()

  Returns the value of the attribute "onclick". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onclick" or an empty string if that attribute isn't defined

### getOnDblClickAttribute

    public final java.lang.String getOnDblClickAttribute()

  Returns the value of the attribute "ondblclick". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "ondblclick" or an empty string if that attribute isn't defined

### getOnMouseDownAttribute

    public final java.lang.String getOnMouseDownAttribute()

  Returns the value of the attribute "onmousedown". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onmousedown" or an empty string if that attribute isn't defined

### getOnMouseUpAttribute

    public final java.lang.String getOnMouseUpAttribute()

  Returns the value of the attribute "onmouseup". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onmouseup" or an empty string if that attribute isn't defined

### getOnMouseOverAttribute

    public final java.lang.String getOnMouseOverAttribute()

  Returns the value of the attribute "onmouseover". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onmouseover" or an empty string if that attribute isn't defined

### getOnMouseMoveAttribute

    public final java.lang.String getOnMouseMoveAttribute()

  Returns the value of the attribute "onmousemove". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onmousemove" or an empty string if that attribute isn't defined

### getOnMouseOutAttribute

    public final java.lang.String getOnMouseOutAttribute()

  Returns the value of the attribute "onmouseout". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onmouseout" or an empty string if that attribute isn't defined

### getOnKeyPressAttribute

    public final java.lang.String getOnKeyPressAttribute()

  Returns the value of the attribute "onkeypress". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onkeypress" or an empty string if that attribute isn't defined

### getOnKeyDownAttribute

    public final java.lang.String getOnKeyDownAttribute()

  Returns the value of the attribute "onkeydown". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onkeydown" or an empty string if that attribute isn't defined

### getOnKeyUpAttribute

    public final java.lang.String getOnKeyUpAttribute()

  Returns the value of the attribute "onkeyup". Refer to the HTML 4.01 documentation for details on the use of this attribute.

  Returns:
    the value of the attribute "onkeyup" or an empty string if that attribute isn't defined

### isStateUpdateFirst

    protected boolean isStateUpdateFirst()

  Returns `true` if state updates should be done before onclick event handling. This method returns `false` by default, and is expected to be overridden to return `true` by derived classes like `HtmlCheckBoxInput`.

  Returns:
    `true` if state updates should be done before onclick event handling

Copyright © 2002-2011 Gargoyle Software Inc.. All Rights Reserved.