com.gargoylesoftware.htmlunit.html
Class HtmlElement

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

HtmlBase, HtmlBaseFont, HtmlHead, HtmlHtml, HtmlMeta, HtmlParameter, HtmlScript, HtmlStyle, HtmlTitle, StyledElement

public abstract class HtmlElement
extends DomNamespaceNode

An abstract wrapper for html elements

Version:

$Revision: 1.3 $

Author:

Mike Bowler, Mike J. Bresnahan, David K. Taylor, Christian Sell, David D. Kilzer, Mike Gallaher, Denis N. Antonioli, Marc Guillemot, Ahmed Ashour

See Also:

Serialized Form

Nested Class Summary

static class

HtmlElement.MapEntryWrappingIterator Converts an iteration of plain Map.Entry into an iteration of HtmlAttr.

Field Summary

static java.lang.String	ATTRIBUTE_NOT_DEFINED Constant meaning that the specified attribute was not defined.
static java.lang.String	ATTRIBUTE_VALUE_EMPTY Constant meaning that the specified attribute was found but its value was empty.

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

PROPERTY_ELEMENT, READY_STATE_COMPLETE, READY_STATE_INTERACTIVE, READY_STATE_LOADED, READY_STATE_LOADING, READY_STATE_UNINITIALIZED

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.
DomNode	cloneDomNode(boolean deep) Overrides DomNode.cloneDomNode(boolean) so clone gets its own Map of attributes.
ScriptResult	fireEvent(Event event) Fire the event on the element.
ScriptResult	fireEvent(java.lang.String eventType) Shortcut for fireEvent(Event).
java.util.Iterator	getAttributeEntriesIterator()
java.lang.String	getAttributeValue(java.lang.String attributeName) Return the value of the specified attribute or an empty string.
java.util.Iterator	getChildElementsIterator()
HtmlElement	getEnclosingElement(java.lang.String tagName) Return the element with the given name that enclosed this element or null if this element is no such element is found.
HtmlForm	getEnclosingForm() Return the form that enclosed this element or null if this element is not within a form.
HtmlForm	getEnclosingFormOrDie() Return the form that enclosed this element or throw an exception if this element is not within a form.
org.mozilla.javascript.Function	getEventHandler(java.lang.String eventName) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
HtmlElement	getHtmlElementById(java.lang.String id) Return the html element with the specified id.
java.util.List	getHtmlElementsByAttribute(java.lang.String elementName, java.lang.String attributeName, java.lang.String attributeValue) Search by the specified criteria and return all the HtmlElement that are found
java.util.List	getHtmlElementsByTagName(java.lang.String tagName) Given a list of tag names, return the html elements that correspond to any matching element
java.util.List	getHtmlElementsByTagNames(java.util.List acceptableTagNames) Given a list of tag names, return the html elements that correspond to any matching element
java.lang.String	getId()
java.lang.String	getNodeName() Get the name for the current node.
short	getNodeType() Get the type of the current node.
HtmlElement	getOneHtmlElementByAttribute(java.lang.String elementName, java.lang.String attributeName, java.lang.String attributeValue) Search by the specified criteria and return the first HtmlElement that is found
java.lang.String	getTagName() Return the tag name of this element.
boolean	hasHtmlElementWithId(java.lang.String id) Return true if there is a element with the specified id.
boolean	isAttributeDefined(java.lang.String attributeName) Return true if the specified attribute has been defined.
void	keyDown(int keyCode) Simulate pressing a key on this element
void	keyDown(int keyCode, boolean shiftKey, boolean ctrlKey, boolean altKey) Simulate pressing a key on this element
Page	mouseDown() Simulate clicking the mouse in this element.
Page	mouseDown(boolean shiftKey, boolean ctrlKey, boolean altKey, int button) Simulate clicking the mouse in this element.
Page	mouseMove() Simulate moving the mouse inside this element.
Page	mouseMove(boolean shiftKey, boolean ctrlKey, boolean altKey, int button) Simulate moving the mouse inside this element.
Page	mouseOut() Simulate moving the mouse out of this element.
Page	mouseOut(boolean shiftKey, boolean ctrlKey, boolean altKey, int button) Simulate moving the mouse out of this element.
Page	mouseOver() Simulate moving the mouse over this element.
Page	mouseOver(boolean shiftKey, boolean ctrlKey, boolean altKey, int button) Simulate moving the mouse over this element.
Page	mouseUp() Simulate releasing the mouse click in this element.
Page	mouseUp(boolean shiftKey, boolean ctrlKey, boolean altKey, int button) Simulate releasing the mouse click in this element.
void	removeAttribute(java.lang.String attributeName) Removes an attribute from this element.
void	removeChild(java.lang.String tagName, int i) Removes the ith 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.
void	removeHtmlAttributeChangeListener(HtmlAttributeChangeListener listener) Removes an HtmlAttributeChangeListener from the listener list.
Page	rightClick() Simulate right clicking the mouse in this element.
Page	rightClick(boolean shiftKey, boolean ctrlKey, boolean altKey) Simulate right clicking the mouse in this element.
void	setAttributeValue(java.lang.String attributeName, java.lang.String attributeValue) Set the value of the specified attribute.
void	setEventHandler(java.lang.String eventName, org.mozilla.javascript.Function eventHandler) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
void	setEventHandler(java.lang.String eventName, java.lang.String jsSnippet) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
void	setId(java.lang.String newId) Set the identifier this element.
java.lang.String	toString() Return a string representation of this object

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

getLocalName, getNamespaceURI, getPrefix, getQualifiedName, setPrefix

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

addDomChangeListener, appendDomChild, asText, asXml, getAllHtmlChildElements, getByXPath, getChildIterator, getEndColumnNumber, getEndLineNumber, getFirstDomChild, getLastDomChild, getNextDomSibling, getNodeValue, getPage, getParentDomNode, getPreviousDomSibling, getReadyState, getScriptObject, getStartColumnNumber, getStartLineNumber, insertBefore, remove, removeAllChildren, removeDomChangeListener, replace, setNodeValue, setReadyState, setScriptObject

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ATTRIBUTE_NOT_DEFINED

public static final java.lang.String ATTRIBUTE_NOT_DEFINED

Constant meaning that the specified attribute was not defined.

ATTRIBUTE_VALUE_EMPTY

public static final java.lang.String ATTRIBUTE_VALUE_EMPTY

Constant meaning that the specified attribute was found but its value was empty.

Method Detail

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)

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

cloneDomNode

public DomNode cloneDomNode(boolean deep)

Overrides DomNode.cloneDomNode(boolean) so clone gets its own Map of attributes. Make a clone of this node

Overrides:

cloneDomNode in class DomNode

Parameters:

deep - if true, the clone will be propagated to the whole subtree below this one. Otherwise, the new node will not have any children. The page reference will always be the same as this node's.

Returns:

a new node

fireEvent

public ScriptResult fireEvent(Event event)

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

Parameters:

event - the event to fire.

Returns:

the execution result. null if nothing is executed.

fireEvent

public ScriptResult fireEvent(java.lang.String eventType)

Shortcut for fireEvent(Event).

Parameters:

eventType - the event type (like "load", "click")

Returns:

the execution result. null if nothing is executed.

getAttributeEntriesIterator

public java.util.Iterator getAttributeEntriesIterator()

Returns:

an iterator over the HtmlAttr objects representing the attributes of this element. Each entry holds a string key and a string value. The elements are ordered as found in the html source code.

getAttributeValue

public final java.lang.String getAttributeValue(java.lang.String attributeName)

Return the value of the specified attribute or an empty string. If the result is an empty string then it will be either ATTRIBUTE_NOT_DEFINED if the attribute wasn't specified or ATTRIBUTE_VALUE_EMPTY if the attribute was specified but it was empty.

Parameters:

attributeName - the name of the attribute

Returns:

The value of the attribute or ATTRIBUTE_NOT_DEFINED or ATTRIBUTE_VALUE_EMPTY

getChildElementsIterator

public final java.util.Iterator getChildElementsIterator()

Returns:

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

getEnclosingElement

public HtmlElement getEnclosingElement(java.lang.String tagName)

Return the element with the given name that enclosed this element or null if this element is no such element is found.

Parameters:

tagName - the name of the tag searched (case insensitive)

Returns:

See above

getEnclosingForm

public HtmlForm getEnclosingForm()

Return the form that enclosed this element or null if this element is not within a form.

Returns:

See above

getEnclosingFormOrDie

public HtmlForm getEnclosingFormOrDie()
                               throws java.lang.IllegalStateException

Return the form that enclosed this element or throw an exception if this element is not within a form.

Returns:

See above

Throws:

java.lang.IllegalStateException - If the element is not within a form.

getEventHandler

public final org.mozilla.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.

Overrides:

getEventHandler in class DomNode

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

getHtmlElementById

public HtmlElement getHtmlElementById(java.lang.String id)
                               throws ElementNotFoundException

Return the html element with the specified id. If more than one element has this id (not allowed by the html spec) then return the first one.

Parameters:

id - The id value to search by

Returns:

The html element found

Throws:

ElementNotFoundException - If no element was found that matches the id

getHtmlElementsByAttribute

public final java.util.List getHtmlElementsByAttribute(java.lang.String elementName,
                                                       java.lang.String attributeName,
                                                       java.lang.String attributeValue)

Search by the specified criteria and return all the HtmlElement that are found

Parameters:

elementName - The name of the element

attributeName - The name of the attribute

attributeValue - The value of the attribute

Returns:

A list of HtmlElements

getHtmlElementsByTagName

public final java.util.List getHtmlElementsByTagName(java.lang.String tagName)

Given a list of tag names, return the html elements that correspond to any matching element

Parameters:

tagName - the tag name to match

Returns:

The list of tag names

getHtmlElementsByTagNames

public final java.util.List getHtmlElementsByTagNames(java.util.List acceptableTagNames)

Given a list of tag names, return the html elements that correspond to any matching element

Parameters:

acceptableTagNames - The list of tag names to search by.

Returns:

The list of tag names

getId

public final java.lang.String getId()

Returns:

the identifier of this element.

getNodeName

public java.lang.String getNodeName()

Description copied from class: DomNode

Get the name for the current node.

Specified by:

getNodeName in class DomNode

Returns:

The same value as returned by getTagName(),

getNodeType

public short getNodeType()

Description copied from class: DomNode

Get the type of the current node.

Specified by:

getNodeType in class DomNode

Returns:

the node type

getOneHtmlElementByAttribute

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

Search by the specified criteria and return the first HtmlElement that is found

Parameters:

elementName - The name of the element

attributeName - The name of the attribute

attributeValue - The value of the attribute

Returns:

The HtmlElement

Throws:

ElementNotFoundException - If a particular xml element could not be found in the dom model

getTagName

public java.lang.String getTagName()

Return the tag name of this element. The tag name is the actual html name. For example the tag name for HtmlAnchor is "a" and the tag name for HtmlTable is "table". This tag name will always be in lowercase, no matter what case was used in the original document, when no namespace is defined.

Returns:

the tag name of this element.

hasHtmlElementWithId

public boolean hasHtmlElementWithId(java.lang.String id)

Return true if there is a element 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 getHtmlElementById() internally so writing code like the following would be extremely inefficient.

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

Parameters:

id - The id to search by

Returns:

true if an element was found with the specified id.

isAttributeDefined

public boolean isAttributeDefined(java.lang.String attributeName)

Return true if the specified attribute has been defined. This is neccessary in order to distinguish between an attribute that is set to an empty string and one that was not defined at all.

Parameters:

attributeName - The attribute to check

Returns:

true if the attribute is defined

keyDown

public void keyDown(int keyCode)

Simulate pressing a key on this element

Parameters:

keyCode - the key you wish to press

keyDown

public void keyDown(int keyCode,
                    boolean shiftKey,
                    boolean ctrlKey,
                    boolean altKey)

Simulate pressing a key on this element

Parameters:

keyCode - the key you wish to press

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

mouseDown

public Page mouseDown()

Simulate clicking the mouse in this element.

Returns:

The page that occupies this window after the mouse is clicked in this element. It may be the same window or it may be a freshly loaded one.

mouseDown

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

Simulate clicking the mouse in this element.

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

button - the button code, must be MouseEvent.BUTTON_LEFT, MouseEvent.BUTTON_MIDDLE or MouseEvent.BUTTON_RIGHT

Returns:

The page that occupies this window after the mouse is clicked in this element. It may be the same window or it may be a freshly loaded one.

mouseMove

public Page mouseMove()

Simulate moving the mouse inside this element.

Returns:

The page that occupies this window after the mouse moves inside this element. It may be the same window or it may be a freshly loaded one.

mouseMove

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

Simulate moving the mouse inside this element.

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

button - the button code, must be MouseEvent.BUTTON_LEFT, MouseEvent.BUTTON_MIDDLE or MouseEvent.BUTTON_RIGHT

Returns:

The page that occupies this window after the mouse moves inside this element. It may be the same window or it may be a freshly loaded one.

mouseOut

public Page mouseOut()

Simulate moving the mouse out of this element.

Returns:

The page that occupies this window after the mouse moves out of this element. It may be the same window or it may be a freshly loaded one.

mouseOut

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

Simulate moving the mouse out of this element.

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

button - the button code, must be MouseEvent.BUTTON_LEFT, MouseEvent.BUTTON_MIDDLE or MouseEvent.BUTTON_RIGHT

Returns:

The page that occupies this window after the mouse moves out of this element. It may be the same window or it may be a freshly loaded one.

mouseOver

public Page mouseOver()

Simulate moving the mouse over this element.

Returns:

The page that occupies this window after the mouse moves over this element. It may be the same window or it may be a freshly loaded one.

mouseOver

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

Simulate moving the mouse over this element.

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

button - the button code, must be MouseEvent.BUTTON_LEFT, MouseEvent.BUTTON_MIDDLE or MouseEvent.BUTTON_RIGHT

Returns:

The page that occupies this window after the mouse moves over this element. It may be the same window or it may be a freshly loaded one.

mouseUp

public Page mouseUp()

Simulate releasing the mouse click in this element.

Returns:

The page that occupies this window after the mouse click is released in this element. It may be the same window or it may be a freshly loaded one.

mouseUp

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

Simulate releasing the mouse click in this element.

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

button - the button code, must be MouseEvent.BUTTON_LEFT, MouseEvent.BUTTON_MIDDLE or MouseEvent.BUTTON_RIGHT

Returns:

The page that occupies this window after the mouse click is released in this element. It may be the same window or it may be a freshly loaded one.

removeAttribute

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

Removes an attribute from this element.

Parameters:

attributeName - the attribute attributeName

removeChild

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

Removes the ith 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

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.

Overrides:

removeEventHandler in class DomNode

Parameters:

eventName - Name of the event such as "onclick" or "onblur", etc.

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)

rightClick

public Page rightClick()

Simulate right clicking the mouse in this element.

Returns:

The page that occupies this window after the mouse is right clicked in this element. It may be the same window or it may be a freshly loaded one.

rightClick

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

Simulate right clicking the mouse in this element.

This is equivalent to calling mouseDown(boolean, boolean, boolean, int), then mouseUp(boolean, boolean, boolean, int)

Parameters:

shiftKey - true if SHIFT is pressed

ctrlKey - true if CTRL is pressed

altKey - true if ALT is pressed

Returns:

The page that occupies this window after the mouse is right clicked in this element. It may be the same window or it may be a freshly loaded one.

setAttributeValue

public final void setAttributeValue(java.lang.String attributeName,
                                    java.lang.String attributeValue)

Set the value of the specified attribute.

Parameters:

attributeName - the name of the attribute

attributeValue - The value of the attribute

setEventHandler

public final void setEventHandler(java.lang.String eventName,
                                  org.mozilla.javascript.Function eventHandler)

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

Overrides:

setEventHandler in class DomNode

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"

Overrides:

setEventHandler in class DomNode

Parameters:

eventName - Name of event such as "onclick" or "onblur", etc.

jsSnippet - executable javascript code

setId

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

Set the identifier this element.

Parameters:

newId - The new identifier of this element.

toString

public java.lang.String toString()

Return a string representation of this object

Overrides:

toString in class java.lang.Object

Returns:

See above