Home | Class Index

SDK Version: 3.3.0-262647

Documentation generated on 14 June 2013

Class
caplin.dom

Utility

This class provides static, browser agnostic, utility methods for DOM interactions such as adding / removing event listeners, adjusting CSS classes, finding element positions etc.

Constructor Summary

Attributes Name and Description
caplin.dom.Utility()

Method Summary

Attributes Name and Description
<static> void addAndRemoveClassNames(Element eElement, String[] pClassesToAdd, String[] pClassesToRemove)

Adds and/or removes the specified class names from the specified element.
<static> void addClassName(Element eElement, String sClass)

Adds the specified class name to the list of CSS classes on the given element, if the class does not already exist.
<static> int addEventListener(Object oTargetElem, String sEvent, Function fEventListener, boolean bDirectAttachedEvent, bUseCapture)

Registers the specified event function to a particular event using the provided DOM element.
<static> void addScrollListener(Function fScrollListener)

Registers a global listener for mouse scroll events.
<static> Function createMethodEventListener(Object oObject, String sMethod, Array pStaticArguments)

Creates an event listener (a function pointer) that allows a method to be called on an object when that event is fired.
<static> void discard(Element eFirstElement)

Discards one or more elements (all arguments passed will be discarded) by removing children, and removing it from any parentNode.
<static> DOMElement getAncestorElementWithClass(Element eElement, String sClassName)

Returns the first element that contains the given class as part of its className string.
<static> void getComputedStyle(DOMElement eElement, String sStyle)

Computes current style of a DOM Element, converting it to pixels where appropriate.
<static> Object getElementOffsetValues(Object elem)

Returns the bounding rectangle of the specified element.
<static> Object getElementPosition(DOMElement elem)

Returns the absolute position of the element relative to the window in pixels.
<static> DOMElement[] getElementsByClassName(DOMElement eDomElement, String sTagName, String sClassName)

Returns an array of DOM elements that match the specified tag name and class name.
<static> DOMElement getLastChildWithClassName(DOMElement eParent, String sClass)

Returns the last child element that contains the specified CSS class.
<static> Array getMousePosition(Event oEvent)

Returns the mouse position for the specified event
<static> int getNodeIndex(Element eElement)

Returns the node index of the element as it exists in the parent.
<static> String getScrollBarWidth()

Returns the computed current width of scrollBar.
<static> Object getScrollOffset(Element elem)

Returns the scrolled offset of the element (if any) in an object containing a left and top properties.
<static> boolean hasClassName(Element eElement, String sClass)

Returns TRUE if the specified class name exists on the element.
<static> void insertAfter(Element eElement, Element eReferenceElement)

Inserts the specified node immediately after the reference element.
<static> boolean isElementAncestorOfElement(Element ePossibleAncestor, Element ePossibleChildElement)

Checks to see if the specified ancestor element contains the specified child element.
<static> boolean isMouseLeaveOrEnter(Event oEvent, Element eElement)

Determines whether the event is the equivalent of the microsoft mouseleave or mouseenter events.
<static> boolean preventEventDefault(Event oEvent)

Allows the user to prevent the default event, with the use return Utility.preventEventDefault(oEvent);

<static> void removeChild(Element eChildElement)

Removes the specified child from its parent.
<static> void removeClassName(Element eElement, String sClass)

Removes the CSS class name from the specified element.
<static> void removeEventListener(Element oTargetElem, String sEvent, Function fEventListener)

Removes the specified event listener function from the element.
<static> void removeEventListenerById(int nUniqueListenerId)

Removes the DOM event listener that has previously been added via the #addEventListener method.
<static> void replaceClassName(Element eElement, String sCurrentClass, String sNewClass)

Replaces the specified CSS class name on the DOM element with another class.
<static> void setInnerHtml(Element eElement, String sHtml)

Sets the innerHTML of the specified element in an efficient way.
<static> void stopEventPropagation(Event oEvent)

Stops the propagation of an event.

Constructor Detail

► caplin.dom.Utility()

Method Detail

► <static> void addAndRemoveClassNames(Element eElement, String[] pClassesToAdd, String[] pClassesToRemove)

Adds and/or removes the specified class names from the specified element. This operation is performed in a single DOM action, making this more efficient than adding/removing the classes individually. If a class exists in both the add and remove lists, the class will be added to the element.

Parameters
Element eElement The HTML DOM element to make the class changes to.
String[] pClassesToAdd The list of class names that will be added to the list of existing classes.
String[] pClassesToRemove The list of class names that will be removed from the list of existing classes.

► <static> void addClassName(Element eElement, String sClass)

Adds the specified class name to the list of CSS classes on the given element, if the class does not already exist.

Parameters
Element eElement The HTML DOM element to add the CSS class to.
String sClass The class name that will be added to the list of existing classes.

► <static> int addEventListener(Object oTargetElem, String sEvent, Function fEventListener, boolean bDirectAttachedEvent, bUseCapture)

Registers the specified event function to a particular event using the provided DOM element.

Parameters
Object oTargetElem The document element the event will be registered against.
String sEvent The name of the event that will be registered (e.g. 'click', but not 'onclick').
Function fEventListener The function that will be called when the event fires.
boolean bDirectAttachedEvent Whether the simpler form of event registration (e.g. elem.onclick) should be used (false by default). This is still occasionally useful in IE when you want access to the target element and that is different to window.event.srcElement.
bUseCapture
Returns
An event listener id to be used in the method (@link #removeEventListenerById) to remove the newly added event listener or NULL if the event listener could not be added for any reason.
See
#getEventHandlerFromMethod

► <static> void addScrollListener(Function fScrollListener)

Registers a global listener for mouse scroll events.

This method is used rather than #addEventListener since the registration of mouse scroll events differs in IE, Opera, and standards compliant browsers. Furthermore, the event parameter passed through as the first parameter to fScrollListener can be relied upon to exist, even in IE, and has been pre-normalized using the caplin.dom.event.Event#getNormalizedEvent method, since the format of the scroll detail differs so widely.

Parameters
Function fScrollListener

► <static> Function createMethodEventListener(Object oObject, String sMethod, Array pStaticArguments)

Creates an event listener (a function pointer) that allows a method to be called on an object when that event is fired.

Normal event listeners are function pointers which make object-oriented programming difficult. The function pointer returned by this method merely calls the desired method on the specified object so that the this pointer is still available.

Each time an event occurs where this event listener has been attached, the method will be called with a single event parameter, oEvent, which is the browser event object. Optionally, if pStaticArguments is provided then the arguments within this array will be appended to the method parameters for each method call.

The last object passed into the callback sMethod method will be the DOM element which triggered the event firing, for example, the button that was clicked or hovered over.

Parameters
Object oObject the object the method will be called on.
String sMethod the name of the method to call.
Array pStaticArguments Optional The arguments that, if provided, will be appended as parameters to the given method.
Returns
The event function that will invoke the method on the specified class once the event is fired.

► <static> void discard(Element eFirstElement)

Discards one or more elements (all arguments passed will be discarded) by removing children, and removing it from any parentNode.

Parameters
Element eFirstElement First Element DOM Element

► <static> DOMElement getAncestorElementWithClass(Element eElement, String sClassName)

Returns the first element that contains the given class as part of its className string.

Parameters
Element eElement the element to start the search at.
String sClassName the class name to look for.
Returns
The ancestor element with the specified class, or null.

► <static> void getComputedStyle(DOMElement eElement, String sStyle)

Computes current style of a DOM Element, converting it to pixels where appropriate.

Parameters
DOMElement eElement Element to get style for
String sStyle Css style name. IE. border-width
Returns
value with unit, to get the value only use parseInt

► <static> Object getElementOffsetValues(Object elem)

Returns the bounding rectangle of the specified element.

Parameters
Object elem The element to get the bounding recangle for.
Returns
{left:x|right:y}

► <static> Object getElementPosition(DOMElement elem)

Returns the absolute position of the element relative to the window in pixels. The position also takes into account any scrolling of parents.

Parameters
DOMElement elem The DOM element to calculate the position of
Returns
{left:x|top:y}

► <static> DOMElement[] getElementsByClassName(DOMElement eDomElement, String sTagName, String sClassName)

Returns an array of DOM elements that match the specified tag name and class name.

Parameters
DOMElement eDomElement The DOM element that should be used as the root of the search.
String sTagName The tag name (can be *) of elements to search for.
String sClassName The CSS class name of the elements to search for.
Returns
An array of elements that match the specified criteria.

► <static> DOMElement getLastChildWithClassName(DOMElement eParent, String sClass)

Returns the last child element that contains the specified CSS class.

Parameters
DOMElement eParent The parent to use as the root.
String sClass The class of the wanted last child element.
Returns
The last child element or null

► <static> Array getMousePosition(Event oEvent)

Returns the mouse position for the specified event

Parameters
Event oEvent The event object for which to get the mouse co-ordinates
Returns
[x,y]

► <static> int getNodeIndex(Element eElement)

Returns the node index of the element as it exists in the parent.

Parameters
Element eElement The element to get the index for.
Throws
caplin.core.Error
If the specified element does not have a parent.
Returns
the node index

► <static> String getScrollBarWidth()

Returns the computed current width of scrollBar.

Returns
value with unit, to get the value only use parseInt

► <static> Object getScrollOffset(Element elem)

Returns the scrolled offset of the element (if any) in an object containing a left and top properties.

Parameters
Element elem The DOM element to calculate the scrolled offset of.
Returns
{left:x|top:y}

► <static> boolean hasClassName(Element eElement, String sClass)

Returns TRUE if the specified class name exists on the element.

Parameters
Element eElement The DOMElement to check.
String sClass The class name to check.
Returns
TRUE if the specified class name exists on the element.

► <static> void insertAfter(Element eElement, Element eReferenceElement)

Inserts the specified node immediately after the reference element.

This convenience method saves the programmer from having to determine whether to call insertBefore() or appendChild(), depending on whether the reference element is the last child node.

Parameters
Element eElement The element to insert
Element eReferenceElement The reference element to insert the element after.

► <static> boolean isElementAncestorOfElement(Element ePossibleAncestor, Element ePossibleChildElement)

Checks to see if the specified ancestor element contains the specified child element.

Parameters
Element ePossibleAncestor the element that is presumed to be a parent node.
Element ePossibleChildElement the element to start the search at.
Returns
TRUE if the specified ancestor element contains the child element.

► <static> boolean isMouseLeaveOrEnter(Event oEvent, Element eElement)

Determines whether the event is the equivalent of the microsoft mouseleave or mouseenter events. This method assumes the event being passed is a mouseout or mouseenter and has undefined results if this isn't the case.

Parameters
Event oEvent a mouseover or mouseout event object
Element eElement the element we want to test against for mouseenter/mouseleave
Returns
True if the event is either a mouse leave or enter event.

► <static> boolean preventEventDefault(Event oEvent)

Allows the user to prevent the default event, with the use return Utility.preventEventDefault(oEvent);

Parameters
Event oEvent Event passed to your event handler. Note that event handlers are not wrapped so you need to do something like oEvent = oEvent || window.event;
Returns
Always returns false

► <static> void removeChild(Element eChildElement)

Removes the specified child from its parent.

Parameters
Element eChildElement The child to remove.

► <static> void removeClassName(Element eElement, String sClass)

Removes the CSS class name from the specified element.

Parameters
Element eElement The HTML element that the class name should be removed from.
String sClass The CSS class to remove from the element.

► <static> void removeEventListener(Element oTargetElem, String sEvent, Function fEventListener)

Removes the specified event listener function from the element.

Parameters
Element oTargetElem The element to remove the event from.
String sEvent The name of the event to remove the listener from.
Function fEventListener The event listener to remove.
Deprecated
use removeEventListenerById instead
See
#removeEventListenerById to remove an event listener.

► <static> void removeEventListenerById(int nUniqueListenerId)

Removes the DOM event listener that has previously been added via the #addEventListener method.

Parameters
int nUniqueListenerId The event Listener Id that was returned by the method #addEventListener.

► <static> void replaceClassName(Element eElement, String sCurrentClass, String sNewClass)

Replaces the specified CSS class name on the DOM element with another class.

Parameters
Element eElement The HTML DOM element to add the class to.
String sCurrentClass The class name to replace.
String sNewClass The new name of the class.

► <static> void setInnerHtml(Element eElement, String sHtml)

Sets the innerHTML of the specified element in an efficient way.

Parameters
Element eElement the element on which innerHTML needs to be set
String sHtml The HTML that will be set in the element.

► <static> void stopEventPropagation(Event oEvent)

Stops the propagation of an event. This method should be used within an event listener to prevent bubbling of an event up to other event listeners.

Parameters
Event oEvent Event passed to your event handler. Note that event handlers are not wrapped so you need to do something like oEvent = oEvent || window.event;