API Quick Links

Articles and Tutorials

GSUtil

A utility class containing functions for common operations.

Object
   |
   +--GSUtil

Constructor Summary

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

 

Method Summary
<static> Object	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> Object	clone(<Object> obj, <boolean> deep)            Clones the given object.
<static> Object	createContainer(<HTMLElement> parent, <String> className, <int> width, <int> height, <int> left, <int> top, visibility, <int> zIndex)            Creates and positions a content container.
<static> Object	createElement(<String> name)            Creates a DOM element using the namespace-aware createElementNS() method if the browser supports it (uses XHTML namespace), otherwise uses createElement()
<static> Object	createImage(<String> id, <String> src, <int> width, <int> height, <int> left, <int> top, <int> zIndex, <String> className, <String> alt, <String> sizingMethod)            Creates and optionally positions a new DOM image.
<static> Object	createImageMap(<String> name, <String> shape, <Array> coords, <String> href, <String> alt, <String> eventType, <Function> func, <Object> peer)            Creates a DOM representation of an image map.
<static> void	extend(<Object> subClass, <Object> baseClass)            A function used to extend one class with another
<static> Object	findPosX(<Object> obj)            Finds the x coordinate of the object obj relative to the browser window coordinate space
<static> Object	findPosY (<Object> obj)            Finds the y coordinate of the object obj relative to the browser window coordinate space
<static> String	getBaseName(<String> path)            Returns the filename part of the given path
<static> String	getBaseNameWithoutExtension(<String> path)            Returns the filename part of the given path less the file extension if the file has one
<static> Object	getCaseInsensitiveProperty(<Object> obj, <String> name, defaultValue)            Allows an object's properties to be accessed without regard to the property name's case.
<static> GSPoint	getClickPixelCoordinate(<Event> e, <HTMLElement> container)            Returns the pixel coordinate at which the given click event occurred.
<static> Object	getComputedStyle(<Element> element, <String> prop)            Returns the specified computed style for the given element
<static> String	getDirName(<String> path)            Returns the portion of the given path up to, but not including, the last slash '/' character
<static> GSPoint	getElementPosition(<HTMLElement> elem)            Get the position of the upper-left corner of the element relative to the upper-left corner of the window
<static> GSFeature	getFeatureById(<Array> a, <String> id)            Convenience function that returns the feature from the specified array with a matching id.
<static> String	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> number	getMaximum(<Array> ar)            Retrieves the maximum value from a number array
<static> number	getMinimum(<Array> ar)            Retrieves the minimum value from a number array
<static> GSPoint	getMousePos(<MouseEvent> e)            Returns the coordinate (pixels) where the specified mouse event occurred
<static> GSPoint	getOffsetFromAncestor(<HTMLElement> src, <HTMLElement> ancestor)            Returns the pixel offset of the src element from the specified ancestor element.
<static> Array	getPropertyArray(<Array> ar, <String> 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> Object	getWindowSize()            Gets the width/height dimensions of the current browser window.
<static> void	makeUnselectable(<HTMLElement> elem)            Makes the provided HTML element unselectable
<static> void	positionElement(<HTMLElement> elem, <int> left, <int> top, <int> right, <int> bottom)            Sets the position of the specified HTML element
<static> Object	roundNumber(<Number> value, <Number> rlength)            Rounds the given value to the specified number of decimal places
<static> void	setImageSrc(<Object> image, <String> 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> void	setOpacity(obj, opacity)            Sets the opacity of the object specified by obj using the browser-specific extension for this function.
<static> boolean	stringToBoolean(<String> 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> XMLDocument	toXML(<String> str)            Converts the given XML string to an XMLDocument

Constructor Detail

GSUtil

GSUtil()

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

Method Detail

cancelEvent

<static> Object 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.

clone

<static> Object clone(<Object> obj, <boolean> 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.

•  
  obj - the object to be cloned
  deep - a flag indicating that a deep copy of the object should be made when set to true
Parameters:

•  
  a copy of the given object
Returns:

createContainer

<static> Object createContainer(<HTMLElement> parent, <String> className, <int> width, <int> height, <int> left, <int> top, visibility, <int> zIndex)

Creates and positions a content container.

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

createElement

<static> Object createElement(<String> name)

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

•  
  name - the name of the element to create
Parameters:

•  
  a DOM element
Returns:

createImage

<static> Object createImage(<String> id, <String> src, <int> width, <int> height, <int> left, <int> top, <int> zIndex, <String> className, <String> alt, <String> sizingMethod)

Creates and optionally positions a new DOM image. Additionally this function abstracts browser-specific techniques for display of PNG images with alpha transparency.

•  
  id - the image id
  src - the image src URL
  width - the image width
  height - the image height
  left - the x coordinate in the parent's coordinate system at which to anchor this image
  top - the y coordinate in the parent's coordinate system at which to anchor this image
  zIndex - the image's stacking order
  className - an optional CSS class to apply to the image
  alt - optional text to display as a tool-tip when the mouse is over the image
  sizingMethod - the sizing method to apply when rendering PNG images with alpha transparency in IE using the AlphaImageLoader filter
Parameters:

createImageMap

<static> Object createImageMap(<String> name, <String> shape, <Array> coords, <String> href, <String> alt, <String> eventType, <Function> func, <Object> 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

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

extend

<static> void extend(<Object> subClass, <Object> baseClass)

A function used to extend one class with another

•  
  subClass - the inheriting class, or subclass
  baseClass - the class from which to inherit copyright 2006, Kevin Lindsey
Parameters:

findPosX

<static> Object findPosX(<Object> obj)

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

•  
  obj - the object to find the x coordinate of
Parameters:

•  
  the x coordinate of the object specified
Returns:

•  
  - findPoxY
Deprecateduse getClickPixelCoordinate() instead

See:

findPosY

<static> Object findPosY(<Object> obj)

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

•  
  obj - the object to find the y coordinate of
Parameters:

•  
  the y coordinate of the object specified
Returns:

•  
  - findPoxX
Deprecateduse getClickPixelCoordinate() instead

See:

getBaseName

<static> String getBaseName(<String> path)

Returns the filename part of the given path

•  
  path - the path to return the basename for
Parameters:

•  
  the filename part of the given path
Returns:

getBaseNameWithoutExtension

<static> String getBaseNameWithoutExtension(<String> path)

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

•  
  path - the path to return the basename for
Parameters:

•  
  the filename part of the given path
Returns:

getCaseInsensitiveProperty

<static> Object getCaseInsensitiveProperty(<Object> obj, <String> name, defaultValue)

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

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

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

getClickPixelCoordinate

<static> GSPoint getClickPixelCoordinate(<Event> e, <HTMLElement> 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.

•  
  e - the click event to get the pixel coordinate for
  container - an element that is an ancestor of the event src element
Parameters:

•  
  the pixel coordinate of the event
Returns:

getComputedStyle

<static> Object getComputedStyle(<Element> element, <String> prop)

Returns the specified computed style for the given element

•  
  element - the element to compute the style for
  prop - the property to get the value for
Parameters:

getDirName

<static> String getDirName(<String> path)

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

•  
  path - the path to return the dirname for
Parameters:

•  
  the path less the filename portion
Returns:

getElementPosition

<static> GSPoint getElementPosition(<HTMLElement> elem)

Get the position of the upper-left corner of the element relative to the upper-left corner of the window

•  
  elem - the element to get the position for
Parameters:

•  
  the pixel coordinate of the specified element relative to the window object
Returns:

getFeatureById

<static> GSFeature getFeatureById(<Array> a, <String> id)

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

•  
  a - an array of features
  id - the id of the feature to retrieve from the array
Parameters:

•  
  the matching feature or undefined if no match is found
Returns:

getImageSrc

<static> String 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

•  
  the - image to get the source from
Parameters:

•  
  the image source
Returns:

•  
  - setImageSrc()
See:

getMaximum

<static> number getMaximum(<Array> ar)

Retrieves the maximum value from a number array

•  
  ar - the array to retrieve the maximum number from
Parameters:

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

•  
  - getMinimum()
See:

getMinimum

<static> number getMinimum(<Array> ar)

Retrieves the minimum value from a number array

•  
  ar - the array to retrieve the minimum number from
Parameters:

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

•  
  - getMaximum()
See:

getMousePos

<static> GSPoint getMousePos(<MouseEvent> e)

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

•  
  e - the mouse event
Parameters:

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

getOffsetFromAncestor

<static> GSPoint getOffsetFromAncestor(<HTMLElement> src, <HTMLElement> ancestor)

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

•  
  src - the element whose offset from a given ancestor element should be calculated
  ancestor - an ancestor of the src element return the pixel offset of the src element from its ancestor
Parameters:

getPropertyArray

<static> Array getPropertyArray(<Array> ar, <String> 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

•  
  ar - the input array
  propertyName - the name of the property value to be retrieved from the array elements
Parameters:

•  
  an Array of property values
Returns:

getWindowSize

<static> Object getWindowSize()

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

•  
  the browser window dimensions in pixels
Returns:

makeUnselectable

<static> void makeUnselectable(<HTMLElement> elem)

Makes the provided HTML element unselectable

•  
  elem - the HTML element to make unselectable
Parameters:

positionElement

<static> void positionElement(<HTMLElement> elem, <int> left, <int> top, <int> right, <int> bottom)

Sets the position of the specified HTML element

•  
  elem - the HTML element to position
  left - the left position
  top - the top position
  right - the right position
  bottom - the bottom position
Parameters:

roundNumber

<static> Object roundNumber(<Number> value, <Number> rlength)

Rounds the given value to the specified number of decimal places

•  
  value - the value to be rounded
  rlength - the number of decimal places to round to
Parameters:

setImageSrc

<static> void setImageSrc(<Object> image, <String> 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

•  
  image - the image to set the source for
  src - the new source for the image
Parameters:

•  
  - getImageSrc()
See:

setOpacity

<static> void setOpacity(obj, opacity)

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

stringToBoolean

<static> boolean stringToBoolean(<String> 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.

•  
  str - the string value to test
Parameters:

•  
  the boolean equivalent of the given string value
Returns:

toXML

<static> XMLDocument toXML(<String> str)

Converts the given XML string to an XMLDocument

•  
  str - the XML string to be converted
Parameters:

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