Function Namespace GSUtil

A collection of utility functions.

Function Namespace Summary
Constructor Attributes	Constructor Name and Description
	GSUtil() `GSUtil` should not be instantiated, all of its methods are called statically.

Method Summary
Method Attributes	Method Name and Description
<static>	GSUtil.addThousandsSeparators(value) Add thousands separators (commas) to a number
<static>	GSUtil.arrayToJson(a) Serializes the specified array to a JSON string
<static>	GSUtil.bind(func, object) Wraps the specified function in another function, locking its execution scope to the provided scope object.
<static>	GSUtil.bindAsEventListener(func, object) An event-specific variant of the bind function.
<static>	GSUtil.cancelEvent(e) Used to nullify an event by stopping it from propagating to ancestors in the DOM and cancels any default action associated with the event.
<static>	GSUtil.clone(obj, deep) Clones the given object.
<static>	GSUtil.createContainer(parent, className, width, height, left, top, zIndex, zIndex) Creates and positions a content container.
<static>	GSUtil.createElement(name, properties) Creates a DOM element using the namespace-aware `createElementNS()` method if the browser supports it (uses XHTML namespace), otherwise uses `createElement()`
<static>	GSUtil.createImageMap(name, shape, coords, href, alt, eventType, func, peer) Creates a DOM representation of an image map.
<static>	GSUtil.escapeHTML(str) Replaces ampersands, angle brackets and quotes with HTML entities
<static>	GSUtil.extend(subClass, baseClass) A function used to extend one class with another.
<static>	GSUtil.findPosX(obj) Finds the x coordinate of the object `obj` relative to the browser window coordinate space
<static>	GSUtil.findPosY(obj) Finds the y coordinate of the object `obj` relative to the browser window coordinate space
<static>	GSUtil.getBaseName(path) Returns the filename part of the given path
<static>	GSUtil.getBaseNameWithoutExtension(path) Returns the filename part of the given path less the file extension if the file has one
<static>	GSUtil.getCaseInsensitiveProperty(obj, name, defaultValue) Allows an object's properties to be accessed without regard to the property name's case.
<static>	GSUtil.getComputedStyle(element, prop) Returns the specified computed style for the given element
<static>	GSUtil.getDirName(path) Returns the portion of the given path up to, but not including, the last slash '/' character
<static>	GSUtil.getElementPosition(elem, ancestor) Get the position of the upper-left corner of the element relative to either the upper-left corner of the window or an ancestor element
<static>	GSUtil.getFeatureById(a, id) Convenience function that returns the feature from the specified array with a matching id.
<static>	GSUtil.getImageSrc(image) Returns the image source as a String where the image given may either by an HTMLImageElement or a DIV using the AlphaImageLoader to load the image resource
<static>	GSUtil.getMaximum(ar) Retrieves the maximum value from a number array
<static>	GSUtil.getMinimum(ar) Retrieves the minimum value from a number array
<static>	GSUtil.getMinimumBoundingRectangle(features) Gets the minimum bounding rectangle for a collection of map features
<static>	GSUtil.getMousePixelCoordinate(e, container) Returns the pixel coordinate at which the given click event occurred.
<static>	GSUtil.getMousePos(e) Returns the coordinate (pixels) where the specified mouse event occurred
<static>	GSUtil.getOffsetFromAncestor(src, ancestor) Returns the pixel offset of the src element from the specified ancestor element.
<static>	GSUtil.getPropertyArray(ar, propertyName) Returns an array of values for the property specified by `propertyName` by extracting the property value from each of the input array's elements
<static>	GSUtil.getTouchPixelCoordinate(touch, container) Returns the pixel coordinate at which the given touch event occurred.
<static>	GSUtil.getWindowSize() Gets the width/height dimensions of the current browser window.
<static>	GSUtil.include(baseClass, properties) Adds the passed in properties to the base Class prototype
<static>	GSUtil.innerXHTML(element, xhtml) Parses an XHTML string into a DOM fragment and appends it to the target element
<static>	GSUtil.makeUnselectable(elem) Makes the provided HTML element unselectable
<static>	GSUtil.merge(source, target) Copies all properties of the source object to the target object
<static>	GSUtil.objToJson(obj) Serializes the specified object to a JSON string
<static>	GSUtil.positionElement(elem, left, top, right, bottom) Sets the position of the specified HTML element
<static>	GSUtil.reverseString(value) Takes a string and reverses it
<static>	GSUtil.roundNumber(value, rlength) Rounds the given value to the specified number of decimal places
<static>	GSUtil.serialize(val) Returns a string representation of the specified value
<static>	GSUtil.setAttribute(element, name, value) Sets an element's attribute value using the namespace-aware `setAttributeNS()` method if the browser supports it (uses XHTML namespace), otherwise uses `setAttribute()`
<static>	GSUtil.setImageSrc(image, src) Sets the image source where the image given may either by an HTMLImageElement or a DIV using the AlphaImageLoader to load the image resource
<static>	GSUtil.setOpacity(obj, opacity) Sets the opacity of the object specified by `obj` using the browser-specific extension for this function.
<static>	GSUtil.setStyles(element, styles) Sets all styles specified in the `styles` hash on to the provided element
<static>	GSUtil.stringToBoolean(str) Returns the boolean equivalents for the string values `true, false, yes, no`, or uses the standard javascript rules for string to boolean conversion if the value of `str` is not one of these values.
<static>	GSUtil.toCC(obj) Converts property names containing dashes '-' to camel case
<static>	GSUtil.toXML(str) Converts the given XML string to an XMLDocument
<static>	GSUtil.translateElement(elem, left, top) Translate the specified HTML element.

Function Namespace Detail

GSUtil()

GSUtil should not be instantiated, all of its methods are called statically.

Method Detail

<static> {String} GSUtil.addThousandsSeparators(value)

Add thousands separators (commas) to a number

Parameters:
{Number} value: the value to have thousands separators added to

Returns:: {String} the number with thousands separators added

<static> {String} GSUtil.arrayToJson(a)

Serializes the specified array to a JSON string

Parameters:
{Array} a: the array to serialize

Returns:: {String} the serialized value

<static> {Function} GSUtil.bind(func, object)

Wraps the specified function in another function, locking its execution scope to the provided scope object. Any additional arguments passed to this function will be prepended to the argument list at execution time

Parameters:
{Function} func: the function to bind
{Object} object: the object that will be bound to the this keyword within the wrapped function

Returns:: {Function} the bound function

<static> {Function} GSUtil.bindAsEventListener(func, object)

An event-specific variant of the bind function. Ensures the bound function will always receive the current event object as the first argument at execution time

Parameters:
{Function} func: the function to bind
{Object} object: the object that will be bound to the this keyword within the wrapped function

Returns:: {Function} the bound function

<static> GSUtil.cancelEvent(e)

Used to nullify an event by stopping it from propagating to ancestors in the DOM and cancels any default action associated with the event.

Parameters:
{Event} e: the mouse event to cancel

<static> {Object} GSUtil.clone(obj, deep)

Clones the given object. By default this function makes a shallow copy of the object. Takes an optional argument deep, that when true will make a deep copy of the target object.

Parameters:
{Object} obj: the object to be cloned
{boolean} deep: a flag indicating that a deep copy of the object should be made when set to true

Returns:: {Object} a copy of the given object

<static> {HTMLElement} GSUtil.createContainer(parent, className, width, height, left, top, zIndex, zIndex)

Creates and positions a content container.

Parameters:
{HTMLElement} parent: the parent element the new container should be appended to
{String} className: the CSS class name to use for the new container (optional)
{int} width: the width of the new container in pixels
{int} height: the height of the new container in pixels
{int} left: the x axis offset of the new container relative to its parent elements top left corner
{int} top: the y axis offset of the new container relative to its parent elements
{int} zIndex: the zIndex value for the container top left corner
zIndex

Returns:: {HTMLElement} the container element

<static> {HTMLElement} GSUtil.createElement(name, properties)

Creates a DOM element using the namespace-aware createElementNS() method if the browser supports it (uses XHTML namespace), otherwise uses createElement()

Parameters:
{String} name: the name of the element to create
{Object} properties Optional: an object literal with key-value pairs representing the properties and values to set for the element
{Object} properties.styles: CSS styles to set on the element
{Object} properties.events: event listeners to set on the element
{mixed} properties.name: where properties.name can be the name of any property to set on the element

Returns:: {HTMLElement} a DOM element

<static> {HTMLElement} GSUtil.createImageMap(name, shape, coords, href, alt, eventType, func, peer)

Creates a DOM representation of an image map. If a function is specified it is added to the area of the image map as an onclick handler

Parameters:
{String} name: the name of this image map
{String} shape: the shape of the image map area (rect, poly, circle)
{Array} coords: the coordinates describing the area of the shape
{String} href: the link to assign to the image map's shape
{String} alt: text to display when the mouse runs over the area of the shape
{String} eventType: the type of event that should trigger the specified function
{Function} func: an optional function that can be assigned to the area of the image map as an onclick handler
{Object} peer: reference to the Javascript object that owns this map

Returns:: {HTMLElement} the image map element

<static> {String} GSUtil.escapeHTML(str)

Replaces ampersands, angle brackets and quotes with HTML entities

Parameters:
{String} str: the string to process

Returns:: {String} the input string escaped as HTML

<static> GSUtil.extend(subClass, baseClass)

A function used to extend one class with another. This function is described in detail on Kevin Lindsay's website: http://kevlindev.com

Parameters:
{Object} subClass: the inheriting class, or subclass
{Object} baseClass: the class from which to inherit

<static> {int} GSUtil.findPosX(obj)

Finds the x coordinate of the object obj relative to the browser window coordinate space

Parameters:
{Object} obj: the object to find the x coordinate of

Deprecated:
use #getMousePixelCoordinate instead

Returns:: {int} the x coordinate of the object specified

See:: GSUtil#findPoxY

<static> {int} GSUtil.findPosY(obj)

Finds the y coordinate of the object obj relative to the browser window coordinate space

Parameters:
{Object} obj: the object to find the y coordinate of

Deprecated:
use #getMousePixelCoordinate instead

Returns:: {int} the y coordinate of the object specified

See:: #findPoxX

<static> {String} GSUtil.getBaseName(path)

Returns the filename part of the given path

Parameters:
{String} path: the path to return the basename for

Returns:: {String} the filename part of the given path

<static> {String} GSUtil.getBaseNameWithoutExtension(path)

Returns the filename part of the given path less the file extension if the file has one

Parameters:
{String} path: the path to return the basename for

Returns:: {String} the filename part of the given path

<static> GSUtil.getCaseInsensitiveProperty(obj, name, defaultValue)

Allows an object's properties to be accessed without regard to the property name's case.

Parameters:
{Object} obj: the object to retrieve the property from
{String} name: the name of the property
defaultValue: an optional default value that should be used if the named property is undefined

Returns:: the property value or undefined if no property of this name exists and a default value has not been supplied

<static> GSUtil.getComputedStyle(element, prop)

Returns the specified computed style for the given element

Parameters:
{Element} element: the element to compute the style for
{String} prop: the property to get the value for

Returns:: the requested style

<static> {String} GSUtil.getDirName(path)

Returns the portion of the given path up to, but not including, the last slash '/' character

Parameters:
{String} path: the path to return the dirname for

Returns:: {String} the path less the filename portion

<static> {GSPoint} GSUtil.getElementPosition(elem, ancestor)

Get the position of the upper-left corner of the element relative to either the upper-left corner of the window or an ancestor element

Parameters:
{HTMLElement} elem: the element to get the position for
{HTMLElement} ancestor: an optional ancestor element to calculate the element's position relative to

Returns:: {GSPoint} the pixel coordinate of the specified element relative to the window object

<static> {GSMapFeature} GSUtil.getFeatureById(a, id)

Convenience function that returns the feature from the specified array with a matching id. If no match is found undefined is returned

Parameters:
{Array} a: an array of features
{String} id: the id of the feature to retrieve from the array

Returns:: {GSMapFeature} the matching feature or undefined if no match is found

<static> {String} GSUtil.getImageSrc(image)

Returns the image source as a String where the image given may either by an HTMLImageElement or a DIV using the AlphaImageLoader to load the image resource

Parameters:
{Object} image: the image to get the source from

Returns:: {String} the image source

See:: #setImageSrc

<static> {number} GSUtil.getMaximum(ar)

Retrieves the maximum value from a number array

Parameters:
{Array} ar: the array to retrieve the maximum number from

Returns:: {number} the maximum value from the array or -Infinity if the array has no values

See:: #getMinimum

<static> {number} GSUtil.getMinimum(ar)

Retrieves the minimum value from a number array

Parameters:
{Array} ar: the array to retrieve the minimum number from

Returns:: {number} the minimum value from the array or Infinity if the array has no values

See:: #getMaximum

<static> {GSBounds} GSUtil.getMinimumBoundingRectangle(features)

Gets the minimum bounding rectangle for a collection of map features

Parameters:
{Array} features: an array of features to calculate the minimum bounding rectangle for

Returns:: {GSBounds} the minimum bounding rectangle

<static> {GSPoint} GSUtil.getMousePixelCoordinate(e, container)

Returns the pixel coordinate at which the given click event occurred. If the container parameter is provided the coordinate returned will be relative to the container's coordinate space otherwise it will be relative to the upper-left corner of the window.

Parameters:
{Event} e: the click event to get the pixel coordinate for
{HTMLElement} container: an element that is an ancestor of the event src element

Returns:: {GSPoint} the pixel coordinate of the event

<static> {GSPoint} GSUtil.getMousePos(e)

Returns the coordinate (pixels) where the specified mouse event occurred

Parameters:
{MouseEvent} e: the mouse event

Returns:: {GSPoint} the coordinate (pixels) where the specified mouse event occurred

<static> {GSPoint} GSUtil.getOffsetFromAncestor(src, ancestor)

Returns the pixel offset of the src element from the specified ancestor element.

Parameters:
{HTMLElement} src: the element whose offset from a given ancestor element should be calculated
{HTMLElement} ancestor: an ancestor of the src element

Returns:: {GSPoint} the pixel offset of the src element from its ancestor

<static> {Array} GSUtil.getPropertyArray(ar, propertyName)

Returns an array of values for the property specified by propertyName by extracting the property value from each of the input array's elements

Parameters:
{Array} ar: the input array
{String} propertyName: the name of the property value to be retrieved from the array elements

Returns:: {Array} an Array of property values

<static> {GSPoint} GSUtil.getTouchPixelCoordinate(touch, container)

Returns the pixel coordinate at which the given touch event occurred. If the container parameter is provided the coordinate returned will be relative to the container's coordinate space otherwise it will be relative to the upper-left corner of the window.

Parameters:
{Touch} touch: the touch event to get the pixel coordinate for
{HTMLElement} container: an element that is an ancestor of the event src element

Returns:: {GSPoint} the pixel coordinate of the event

<static> {Object} GSUtil.getWindowSize()

Gets the width/height dimensions of the current browser window.

Returns:: {Object} an object with width and height properties specified in pixels

<static> GSUtil.include(baseClass, properties)

Adds the passed in properties to the base Class prototype

Parameters:
{Object} baseClass: the class whose prototype is to be modified
{Object} properties: the properties to add to the base class

<static> GSUtil.innerXHTML(element, xhtml)

Parses an XHTML string into a DOM fragment and appends it to the target element

Parameters:
{HTMLElement} element: the element the XHTML content should be appended to
{String} xhtml: the XHTML content to be appended

<static> GSUtil.makeUnselectable(elem)

Makes the provided HTML element unselectable

Parameters:
{HTMLElement} elem: the HTML element to make unselectable

<static> {Object} GSUtil.merge(source, target)

Copies all properties of the source object to the target object

Parameters:
{Object} source: the object whose properties will be copied to the target object
{Object} target: the object that will receive the properties from the source object

Returns:: {Object} the modified target object

<static> {String} GSUtil.objToJson(obj)

Serializes the specified object to a JSON string

Parameters:
{Obj} obj: the object to serialize

Returns:: {String} the serialized value

<static> GSUtil.positionElement(elem, left, top, right, bottom)

Sets the position of the specified HTML element

Parameters:
{HTMLElement} elem: the HTML element to position
{int} left: the left position
{int} top: the top position
{int} right: the right position
{int} bottom: the bottom position

<static> {String} GSUtil.reverseString(value)

Takes a string and reverses it

Parameters:
{String} value: the string to be reversed

Returns:: {String} the reversed string

<static> {Number} GSUtil.roundNumber(value, rlength)

Rounds the given value to the specified number of decimal places

Parameters:
{Number} value: the value to be rounded
{Number} rlength: the number of decimal places to round to

Returns:: {Number} the rounded number

<static> {String} GSUtil.serialize(val)

Returns a string representation of the specified value

Parameters:
{Mixed} val: the value to serialize

Returns:: {String} the serialized value

<static> GSUtil.setAttribute(element, name, value)

Sets an element's attribute value using the namespace-aware setAttributeNS() method if the browser supports it (uses XHTML namespace), otherwise uses setAttribute()

Parameters:
element
name
value

<static> GSUtil.setImageSrc(image, src)

Sets the image source where the image given may either by an HTMLImageElement or a DIV using the AlphaImageLoader to load the image resource

Parameters:
{Object} image: the image to set the source for
{String} src: the new source for the image

See:: #getImageSrc

<static> GSUtil.setOpacity(obj, opacity)

Sets the opacity of the object specified by obj using the browser-specific extension for this function.

Parameters:
obj
opacity

<static> GSUtil.setStyles(element, styles)

Sets all styles specified in the styles hash on to the provided element

Parameters:
{HTMLElement} element: the element to set the styles on
{Object} styles: a hash of the styles to set

<static> {boolean} GSUtil.stringToBoolean(str)

Returns the boolean equivalents for the string values true, false, yes, no, or uses the standard javascript rules for string to boolean conversion if the value of str is not one of these values.

Parameters:
{String} str: the string value to test

Returns:: {boolean} the boolean equivalent of the given string value

<static> {Object} GSUtil.toCC(obj)

Converts property names containing dashes '-' to camel case

Parameters:
{Object} obj: the object with property names to convert

Returns:: {Object} the fixed object

<static> {XMLDocument} GSUtil.toXML(str)

Converts the given XML string to an XMLDocument

Parameters:
{String} str: the XML string to be converted

Returns:: {XMLDocument} an XMLDocument or undefined if the string was not successfully parsed

<static> GSUtil.translateElement(elem, left, top)

Translate the specified HTML element. If the browser supports the translate CSS transform then that will be used instead of the "left" and "top" properties for performance benefit.

Parameters:
{HTMLElement} elem: the HTML element to position
{int} left: the left position
{int} top: the top position