Jx

Jx is a global singleton object that contains the entire Jx library within it.  All Jx functions, attributes and classes are accessed through the global Jx object.  Jx should not create any other global variables, if you discover that it does then please report it as a bug

Summary
Jx is a global singleton object that contains the entire Jx library within it.
controls whether Jx uses a single, combined CSS file or individual ones.
This is the URL that Jx was loaded from, it is automatically calculated from the script tag src property that included Jx.
an object containing a list of CSS files to be included to make the loaded Jx components function correctly
an object containing a list of CSS files to be included to make the loaded Jx components function correctly
Individual components of Jx call this function to get their style sheets imported at run time.
Static method that applies the PNG Filter Hack for IE browsers when showing 24bit PNG’s.
Jx.Listener is a mix-in class that performs common listener functions for objects that support listeners.
add a listener to the provided list.
remove a listener from the provided list.
call each listener with a given method and event.
Jx.UniqueId is used to assign unique ids to selected elements This is used to solve a problem where multiple external html fragments are loaded into the DOM via ajax at runtime.
an array of references obtained from by registering ids
initialize the UniqueId object.
removes all registered ids
searches the domObj for each of the ids passed in and obtains a unique reference to them so that subsequent calls to getObj will return the right object.
return an object by id if it was previously registered
Jx.Action is a utility class that provides a mechanism to separate the user interface code from the implementation code for a particular piece of functionality.
an array of property change listeners attached to this action
whether the action (and its associated interface object) is currently enabled or not.
construct a new instance of Jx.Action that invokes a function when activated
add a property change listener to this action.
remove a property change listener from this action.
return whether the action is currently enabled or not.
set the state of this action.
convenience function to bind an item to this action.
convenience function to undo a binding between an object and this action.
placeholder function to conform to the ActionListener interface.
Element is a global object provided by the prototype.js library.
return the size of the content area of an element.
return the size of the border area of an element.
set either or both of the width and height of an element to the provided size.
set either or both of the width and height of an element to the provided size.
returns the padding for each edge of an element
returns the border size for each edge of an element
returns the margin size for each edge of an element
safely parse a number and return its integer value.
return the dimensions of the browser client area.
returns the width of the browser client area
returns the height of the browser client area
toggles an element’s display style property so it can be measured.
ContentLoader is a mix-in class that provides a consistent mechanism for other Jx controls to load content in one of four different ways:
tracks the load state of the content, specifically useful in the case of remote content.
callback function that handles remote content
callback function that handles failure to load remote content
triggers loading of content based on parameters passed in the options parameter.

Properties

{Boolean} COMBINED_CSS

controls whether Jx uses a single, combined CSS file or individual ones.  The combined version is used automatically if the combined or compressed version of Jx is used, otherwise separate ones are used.

{String} baseURL

This is the URL that Jx was loaded from, it is automatically calculated from the script tag src property that included Jx.

{Object} importRules

an object containing a list of CSS files to be included to make the loaded Jx components function correctly

{Object} importRules

an object containing a list of CSS files to be included to make the loaded Jx components function correctly

Functions

addStyleSheet

Jx.addStyleSheet = function(styleSheet,
ieOnly)

Individual components of Jx call this function to get their style sheets imported at run time.

Parameters

styleSheet {String} the relative path to the CSS file (relative to <Jx.baseURL>).

ieOnly {Boolean} if true, then the style sheet is only loaded if the browser is Internet Explorer.

applyPNGFilter

Jx.applyPNGFilter = function(o)

Static method that applies the PNG Filter Hack for IE browsers when showing 24bit PNG’s.  Used automatically for img tags with a class of png24.

The filter is applied using a nifty feature of IE that allows javascript to be executed as part of a CSS style rule - this ensures that the hack only gets applied on IE browsers.

Parameters

object {Object} the object (img) to which the filter needs to be applied.

Jx. Listener

Jx.Listener is a mix-in class that performs common listener functions for objects that support listeners.  It is intended to be added to existing classes using the following syntax:

Object.extends( MyClass.prototype, Jx.Listener.prototype)

The Jx.Listener class functions provide support for managing a list of listeners (add, remove) and dispatching events to listeners (processEvent).

Summary
add a listener to the provided list.
remove a listener from the provided list.
call each listener with a given method and event.

Functions

addListener

addListener: function (list,
obj)

add a listener to the provided list.

Parameters

list {Array} the array of listeners to add the listener to.

object {Object} the object to add as a listener.

removeListener

removeListener: function(list,
obj)

remove a listener from the provided list.

Parameters

list {Array} the array of listeners to remove the listener from.

obj {Object} the object to remove as a listener.

processEvent

processEvent: function(list,
fnName,
obj)

call each listener with a given method and event.

Parameters

list {Array} the array of listeners to call.

fnName {String} the name of a function to call on each listener.

obj {Object} an object to pass to each listener.

Jx. UniqueId

Jx.UniqueId is used to assign unique ids to selected elements This is used to solve a problem where multiple external html fragments are loaded into the DOM via ajax at runtime.  It is not always possible to ensure that every element has a unique id.  This is not a problem if you are using id for CSS styling but if you are using it to access elements using $() then you may get unexpected results.

Jx.UniqueId is a mix-in class.  Extend an existing class to enable it to handle unique ids.  Register the ids that you want to be unique and then get a reference to those objects through the interface exposed by this class.

The class retrieves the elements by id by walking a dom object and retains references to each of the actual DOM objects you have registered.

Summary
an array of references obtained from by registering ids
initialize the UniqueId object.
removes all registered ids
searches the domObj for each of the ids passed in and obtains a unique reference to them so that subsequent calls to getObj will return the right object.
return an object by id if it was previously registered

Properties

{Array} uniqueIdRefs

an array of references obtained from by registering ids

Functions

initUniqueId

initUniqueId: function()

initialize the UniqueId object.  This must be called prior to calling the registerIds function.  Typically, it is called in the constructor of an object that includes Jx.UniqueId.

deregisterIds

deregisterIds: function()

removes all registered ids

registerIds

registerIds: function (aIds,
domObj)

searches the domObj for each of the ids passed in and obtains a unique reference to them so that subsequent calls to getObj will return the right object.

Parameters

aIds {Array} an array of strings containing ids of DOM elements to register.

domObj {Object} an HTML element reference to search for unique ids within

getObj

getObj: function(id)

return an object by id if it was previously registered

Parameters

id {String} the original registered id to get the DOM object for

Returns

{Object} returns an object or null if the requested id did not exist in the original DOM object or if the id was not registered.

Jx. Action

Jx.Action is a utility class that provides a mechanism to separate the user interface code from the implementation code for a particular piece of functionality.  A Jx.Action is used primarily as the basis for clickable UI elements such as Jx.Button and Jx.MenuItem that need to execute a particular function when the user clicks them.  The Jx.Action includes a mechanism for controlling the state of the action, allowing an application to enable or disable an action at any time.  A single Jx.Action may be used with multiple buttons and menu items, allowing the application to easily keep various user interface elements synchronized without having to explicitly maintain all of them.

A new instance of Jx.Action is created by passing a function object to the constructor.  The function object may be a function name or the result of using the Prototype bind() function.

For example

//Example 1:
//use a function reference directly
function myFunction() { alert('my function'); }
var action = new Jx.Action(myFunction);

//Example 2:
//use a function bound to an object through bind()
var myClass = Class.create();
myClass.prototype = {
initialize: function() {this.x = 1;},
getX: function() {alert(this.x); }
};

var myInstance = new myClass();
var action = new Jx.Action(myInstance.getX.bind(myInstance));

To enable or disable a Jx.Action (and consequently update any associated buttons or menu items), use the setEnabled([true|false]) method.

For example

//disable an action
action.setEnabled(false);
Summary
an array of property change listeners attached to this action
whether the action (and its associated interface object) is currently enabled or not.
construct a new instance of Jx.Action that invokes a function when activated
add a property change listener to this action.
remove a property change listener from this action.
return whether the action is currently enabled or not.
set the state of this action.
convenience function to bind an item to this action.
convenience function to undo a binding between an object and this action.
placeholder function to conform to the ActionListener interface.

Properties

{Array} pcl

an array of property change listeners attached to this action

{Boolean} enabled

whether the action (and its associated interface object) is currently enabled or not.  This is controlled through the setEnabled function

Functions

initialize

initialize: function(f)

construct a new instance of Jx.Action that invokes a function when activated

Parameter: {Function} f

the function that this action triggers

addPropertyChangeListener

addPropertyChangeListener: function(obj)

add a property change listener to this action.  When the enabled state of the action changes, all property change listeners are notified through their propertyChanged method.

Parameter: {Object} obj

the object to notify of property changes

removePropertyChangeListener

removePropertyChangeListener: function(obj)

remove a property change listener from this action.

Parameter: {Object} obj

the property change listener to remove.

isEnabled

isEnabled: function()

return whether the action is currently enabled or not.

Return: {Boolean}

setEnabled

setEnabled: function(b)

set the state of this action.

Parameter: {Boolean} b

a boolean value to set enabled state of this action to.

bindTo

bindTo : function(item)

convenience function to bind an item to this action.  This adds the item as a property change listener to the action and adds the action as an ActionListener to the item.

Parameter: {Object} item

the object to bind the action to.

unbindFrom

unbindFrom: function(item)

convenience function to undo a binding between an object and this action.

Parameter: {Object} item

the object to unbind from this action.

actionPerformed

actionPerformed : function(obj)

placeholder function to conform to the ActionListener interface.

Parameter: {Object} obj

the object that performed the action.

Element

Element is a global object provided by the prototype.js library.  The functions documented here are extensions to the Element object provided by Jx to make cross-browser compatibility easier to achieve.

Summary
return the size of the content area of an element.
return the size of the border area of an element.
set either or both of the width and height of an element to the provided size.
set either or both of the width and height of an element to the provided size.
returns the padding for each edge of an element
returns the border size for each edge of an element
returns the margin size for each edge of an element
safely parse a number and return its integer value.
return the dimensions of the browser client area.
returns the width of the browser client area
returns the height of the browser client area
toggles an element’s display style property so it can be measured.

Functions

getContentBoxSize

getContentBoxSize : function(elem)

return the size of the content area of an element.  This is the size of the element less margins, padding, and borders.

Parameter: {Object} elem

the element to get the content size of.

Return: {Object} an object with two properties, width and height, that are the size of the content area of the measured element.

getBorderBoxSize

getBorderBoxSize: function(elem)

return the size of the border area of an element.  This is the size of the element less margins.

Parameter: {Object} elem

the element to get the border sizing of.

Return: {Object} an object with two properties, width and height, that are the size of the border area of the measured element.

setContentBoxSize

setContentBoxSize : function(elem,
size)

set either or both of the width and height of an element to the provided size.  This function ensures that the content area of the element is the requested size and the resulting size of the element may be larger depending on padding and borders.

Parameter: {Object} elem

the element to set the content area of.

Parameter: {Object} size

an object with a width and/or height property that is the size to set the content area of the element to.

setBorderBoxSize

setBorderBoxSize : function(elem,
size)

set either or both of the width and height of an element to the provided size.  This function ensures that the border size of the element is the requested size and the resulting content areaof the element may be larger depending on padding and borders.

Parameter: {Object} elem

the element to set the border size of.

Parameter: {Object} size

an object with a width and/or height property that is the size to set the content area of the element to.

getPaddingSize

getPaddingSize : function (elem)

returns the padding for each edge of an element

Parameter: elem

The element to get the padding for.

Return: {Object} an object with properties left, top, right and bottom that contain the associated padding values.

getBorderSize

getBorderSize : function(elem)

returns the border size for each edge of an element

Parameter: elem

The element to get the borders for.

Return: {Object} an object with properties left, top, right and bottom that contain the associated border values.

getMarginSize

getMarginSize : function(elem)

returns the margin size for each edge of an element

Parameter: elem

The element to get the margins for.

Return: {Object} an object with properties left, top, right and bottom that contain the associated margin values.

getNumber

getNumber: function(n)

safely parse a number and return its integer value.  A NaN value returns 0.  CSS size values are also parsed correctly.

Parameter: {Mixed} n

the string or object to parse.

Return: {Integer} the integer value that the parameter represents

getPageDimensions

getPageDimensions: function()

return the dimensions of the browser client area.

Return: {Object} an object containing a width and height property that represent the width and height of the browser client area.

getInsideWindowWidth

getInsideWindowWidth: function()

returns the width of the browser client area

Return: {Integer} the width of the browser client area

getInsideWindowHeight

getInsideWindowHeight: function()

returns the height of the browser client area

Return: {Integer} the height of the browser client area

toggleMeasurable

toggleMeasurable: function(elem)

toggles an element’s display style property so it can be measured.  If the element has display: none, it is changed to display: block and made temporarily visible so that it can be measured.  Calling this function a second time with the same element will revert the changes.  This allows an element to be measured in various ways.

Parameter: {Object} elem

the element to measure.

Jx. ContentLoader

ContentLoader is a mix-in class that provides a consistent mechanism for other Jx controls to load content in one of four different ways:

  • using an existing element, by id
  • using an existing element, by object reference
  • using an HTML string
  • using a URL to get the content remotely
Summary
tracks the load state of the content, specifically useful in the case of remote content.
callback function that handles remote content
callback function that handles failure to load remote content
triggers loading of content based on parameters passed in the options parameter.

Properties

bContentLoaded

tracks the load state of the content, specifically useful in the case of remote content.

Functions

contentLoaded

contentLoaded: function(element,
options,
r)

callback function that handles remote content

Parameter: element

the element to put the content into

Parameter: options

the options that were passed to loadContent originally, only used to get the optional onContentLoaded callback function.

Parameter: r

the XmlHttpRequest object that has the content.

contentLoadFailed

contentLoadFailed: function(options,
r)

callback function that handles failure to load remote content

Parameter: options

the options that were passed to loadContent originally, only used to get the optional onContentLoadedFailed callback function.

Parameter: r

the XmlHttpRequest object that has the failure code

loadContent

loadContent: function(element,
options)

triggers loading of content based on parameters passed in the options parameter.  The options parameter can have the following attributes:

contentan HTMLElement object, it is appended to the element.
contentIDa string containing the ID of an HTML element to append to the element.
contentHTMLa string containing HTML that is inserted as the innerHTML of the element.
contentURLa string containing a URL to some content.  The content is loaded using an XmlHttpRequest and inserted into the element when it is loaded.  The url must be to the same domain as the current page, otherwise the same domain policy will prevent loading of the content.
onContentLoadeda function object that is called when the content has been successfully loaded.  Primarily useful when using the contentURL method of loading content.
onContentLoadFaileda function object that is called if the content fails to load, primarily useful when using the contentURL method of loading content.

Parameter: element

the element to insert the content into

Parameter: options

an object containing the attributes indicating what content to load.

Jx.addStyleSheet = function(styleSheet,
ieOnly)
Individual components of Jx call this function to get their style sheets imported at run time.
Jx.applyPNGFilter = function(o)
Static method that applies the PNG Filter Hack for IE browsers when showing 24bit PNG’s.
addListener: function (list,
obj)
add a listener to the provided list.
removeListener: function(list,
obj)
remove a listener from the provided list.
processEvent: function(list,
fnName,
obj)
call each listener with a given method and event.
initUniqueId: function()
initialize the UniqueId object.
deregisterIds: function()
removes all registered ids
registerIds: function (aIds,
domObj)
searches the domObj for each of the ids passed in and obtains a unique reference to them so that subsequent calls to getObj will return the right object.
getObj: function(id)
return an object by id if it was previously registered
initialize: function(f)
construct a new instance of Jx.Action that invokes a function when activated
addPropertyChangeListener: function(obj)
add a property change listener to this action.
removePropertyChangeListener: function(obj)
remove a property change listener from this action.
isEnabled: function()
return whether the action is currently enabled or not.
setEnabled: function(b)
set the state of this action.
bindTo : function(item)
convenience function to bind an item to this action.
unbindFrom: function(item)
convenience function to undo a binding between an object and this action.
actionPerformed : function(obj)
placeholder function to conform to the ActionListener interface.
getContentBoxSize : function(elem)
return the size of the content area of an element.
getBorderBoxSize: function(elem)
return the size of the border area of an element.
setContentBoxSize : function(elem,
size)
set either or both of the width and height of an element to the provided size.
setBorderBoxSize : function(elem,
size)
set either or both of the width and height of an element to the provided size.
getPaddingSize : function (elem)
returns the padding for each edge of an element
getBorderSize : function(elem)
returns the border size for each edge of an element
getMarginSize : function(elem)
returns the margin size for each edge of an element
getNumber: function(n)
safely parse a number and return its integer value.
getPageDimensions: function()
return the dimensions of the browser client area.
getInsideWindowWidth: function()
returns the width of the browser client area
getInsideWindowHeight: function()
returns the height of the browser client area
toggleMeasurable: function(elem)
toggles an element’s display style property so it can be measured.
contentLoaded: function(element,
options,
r)
callback function that handles remote content
contentLoadFailed: function(options,
r)
callback function that handles failure to load remote content
loadContent: function(element,
options)
triggers loading of content based on parameters passed in the options parameter.