Function Namespace RapidContext.Widget

The base class for the HTML user interface widgets. The Widget class shouldn't be instantiated directly, instead one of the subclasses should be instantiated.

Source code: RapidContext_Widget.js

Function Namespace Summary
 
Field Summary
<static>  
RapidContext.Widget.Classes
The global widget registry.
Method Summary
 
Adds one or more children to this widget.
 
addChildNode(child)
Adds a single child DOM node to this widget.
 
Adds the specified CSS class names to this HTML DOM node.
 
animate(opts)
Performs a visual effect animation on this widget.
 
Blurs (unfocuses) this DOM node and all relevant child nodes.
<static>  
RapidContext.Widget.createWidget(name, attrs)
Creates a new widget with the specified name, attributes and child widgets or DOM nodes.
 
The internal widget destructor function.
<static>  
RapidContext.Widget.destroyWidget(node)
Destroys a widget or a DOM node.
 
Disables this widget if it was previously enabled.
<static>  
RapidContext.Widget.emitSignal(node, sig)
Emits an asynchronous signal to any listeners connected with MochiKit.Signal.
 
Enables this widget if it was previously disabled.
 
Returns an array with all child DOM nodes.
 
Checks if this HTML DOM node has the specified CSS class names.
 
hide()
Hides this widget node if it was previously visible.
 
Checks if this widget is disabled.
<static>  
RapidContext.Widget.isFormField(obj)
Checks if the specified object is a form field.
 
Checks if this widget node is hidden.
<static>  
RapidContext.Widget.isWidget(obj, className)
Checks if the specified object is a widget.
 
Removes all children to this widget.
 
Removes a single child DOM node from this widget.
 
Removes the specified CSS class names from this HTML DOM node.
 
setAttrs(attrs)
Updates the widget or HTML DOM node attributes.
 
setStyle(styles)
Updates the CSS styles of this HTML DOM node.
 
show()
Shows this widget node if it was previously hidden.
 
Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
 
uid()
Returns the unique identifier for this DOM node.
Function Namespace Detail
RapidContext.Widget()
Field Detail
<static> RapidContext.Widget.Classes
The global widget registry. This is a widget lookup table where all widgets should have an entry. The entries should be added as the JavaScript file are loaded. Each widget is indexed by the widget name (class name) and point to the constructor function.
Method Detail
<static> {Boolean} RapidContext.Widget.isWidget(obj, className)
Checks if the specified object is a widget. Any non-null object that looks like a DOM node and has the element class widget will cause this function to return true. Otherwise, false will be returned. As an option, this function can also check if the widget has a certain class by checking for an additional CSS class widget<className> (which is a standard followed by all widgets).
Parameters:
{Object} obj
the object to check
{String} className Optional
the optional widget class name
Returns:
{Boolean} true if the object looks like a widget, or false otherwise

<static> {Boolean} RapidContext.Widget.isFormField(obj)
Checks if the specified object is a form field. Any non-null object that looks like a DOM node and is either an standard HTML form field (<input>, <textarea> or <select>) or one with a value property will cause this function to return true. Otherwise, false will be returned.
Parameters:
{Object} obj
the object to check
Returns:
{Boolean} true if the object looks like a form field, or false otherwise

<static> {Widget} RapidContext.Widget.createWidget(name, attrs)
Creates a new widget with the specified name, attributes and child widgets or DOM nodes. The widget class name must have been registered in the RapidContext.Widget.Classes lookup table, or an exception will be thrown. This function is identical to calling the constructor function directly.
Parameters:
{String} name
the widget class name
{Object} attrs
the widget and node attributes
{Object} ... Optional
the child widgets or DOM nodes
Throws:
{ReferenceError}
if the widget class name couldn't be found in RapidContext.Widget.Classes
Returns:
{Widget} the widget DOM node

<static> RapidContext.Widget.destroyWidget(node)
Destroys a widget or a DOM node. This function will remove the DOM node from the tree, disconnect all signals and call all widget destructor functions. The same procedure will also be applied recursively to all child nodes. Once destroyed, all references to the widget object should be cleared in order for the browser to be able to reclaim the memory used.
Parameters:
{Widget/Node/Array} node
the (widget) DOM node or list

<static> RapidContext.Widget.emitSignal(node, sig)
Emits an asynchronous signal to any listeners connected with MochiKit.Signal.

Note that this function is an internal helper function for the widgets and shouldn't be called by external code.
Parameters:
{Widget} node
the widget DOM node
{String} sig
the signal name (onclick or similar)
{Object} ... Optional
the optional signal arguments
Deprecated:
Use _fireEvent() instead to emit proper Event object.

{String} uid()
Returns the unique identifier for this DOM node. If a node id has already been set, that id will be returned. Otherwise a new id will be generated and assigned to the widget DOM node.
Returns:
{String} the the unique DOM node identifier

destroy()
The internal widget destructor function. This method should only be called by destroyWidget() and may be overridden by subclasses. By default this method does nothing.

setAttrs(attrs)
Updates the widget or HTML DOM node attributes. This method is sometimes overridden by individual widgets to allow modification of additional widget attributes.
Parameters:
{Object} attrs
the widget and node attributes to set
{Boolean} attrs.disabled Optional
the disabled widget flag
{Boolean} attrs.hidden Optional
the hidden widget flag
{String} attrs.class Optional
the CSS class names

setStyle(styles)
Updates the CSS styles of this HTML DOM node. This method is identical to MochiKit.Style.setStyle, but uses this as the first argument.
widget.setStyle({ "font-size": "bold", "color": "red" });
Parameters:
{Object} styles
an object with the styles to set

{Boolean} hasClass()
Checks if this HTML DOM node has the specified CSS class names. Note that more than one CSS class name may be checked, in which case all must be present.
Parameters:
{String} ... Optional
the CSS class names to check
Returns:
{Boolean} true if all CSS classes were present, or false otherwise

addClass()
Adds the specified CSS class names to this HTML DOM node.
Parameters:
{String} ... Optional
the CSS class names to add

removeClass()
Removes the specified CSS class names from this HTML DOM node. Note that this method will not remove any class starting with widget.
Parameters:
{String} ... Optional
the CSS class names to remove

{Boolean} toggleClass()
Toggles adding and removing the specified CSS class names to and from this HTML DOM node. If all the CSS classes are already set, they will be removed. Otherwise they will be added.
Parameters:
{String} ... Optional
the CSS class names to remove
Returns:
{Boolean} true if the CSS classes were added, or false otherwise

{Boolean} isDisabled()
Checks if this widget is disabled. This method checks both the widgetDisabled CSS class and the disabled property. Changes to the disabled status can be made with enable(), disable() or setAttrs().
Returns:
{Boolean} true if the widget is disabled, or false otherwise

enable()
Enables this widget if it was previously disabled. This is equivalent to calling setAttrs({ disabled: false }).

disable()
Disables this widget if it was previously enabled. This method is equivalent to calling setAttrs({ disabled: true }).

{Boolean} isHidden()
Checks if this widget node is hidden. This method checks for the existence of the widgetHidden CSS class. It does NOT check the actual widget visibility (the display style property set by animations for example).
Returns:
{Boolean} true if the widget is hidden, or false otherwise

show()
Shows this widget node if it was previously hidden. This method is equivalent to calling setAttrs({ hidden: false }). It is safe for all types of widgets, since it only removes the widgetHidden CSS class instead of setting the display style property.

hide()
Hides this widget node if it was previously visible. This method is equivalent to calling setAttrs({ hidden: true }). It is safe for all types of widgets, since it only adds the widgetHidden CSS class instead of setting the display style property.

animate(opts)
Performs a visual effect animation on this widget. This is implemented using the MochiKit.Visual effect package. All options sent to this function will be passed on to the appropriate MochiKit.Visual function.
widget.animate({ effect: "fade", duration: 0.5 });
widget.animate({ effect: "Move", transition: "spring", y: 300 });
Parameters:
{Object} opts
the visual effect options
{String} opts.effect
the MochiKit.Visual effect name
{String} opts.queue
the MochiKit.Visual queue handling, defaults to replace and a unique scope for each widget (see MochiKit.Visual for full options)

blurAll()
Blurs (unfocuses) this DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.

{Array} getChildNodes()
Returns an array with all child DOM nodes. Note that the array is a real JavaScript array, not a dynamic NodeList. This method is sometimes overridden by child widgets in order to hide intermediate DOM nodes required by the widget.
Returns:
{Array} the array of child DOM nodes

addChildNode(child)
Adds a single child DOM node to this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.
Parameters:
{Widget/Node} child
the DOM node to add

removeChildNode(child)
Removes a single child DOM node from this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.

Note that this method will NOT destroy the removed child widget, so care must be taken to ensure proper child widget destruction.
Parameters:
{Widget/Node} child
the DOM node to remove

addAll()
Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined arguments. Any DOM nodes or widgets will be added to the end, and other objects will be converted to a text node first. Subclasses should normally override the addChildNode() method instead of this one, since that is the basis for DOM node insertion.
Parameters:
{Object} ... Optional
the children to add

removeAll()
Removes all children to this widget. This method will also destroy and child widgets and disconnect all signal listeners. This method uses the getChildNodes() and removeChildNode() methods to find and remove the individual child nodes.