Function Namespace MochiKit.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.
Defined in: Widget.js.

Function Namespace Summary
Constructor Attributes	Constructor Name and Description
	MochiKit.Widget()

Field Summary
Field Attributes	Field Name and Description
<static>	MochiKit.Widget._id Function to return unique identifiers.
<static>	MochiKit.Widget.Classes The registered widget class names and constructor functions.

Method Summary
Method Attributes	Method Name and Description
	_animQueueId() Returns the default visual effect queue identifier.
<static>	MochiKit.Widget._createWidgetTreeElem(node, ids) Creates a DOM node or widget from a parsed XML element.
<static>	MochiKit.Widget._eventHandler(className, methodName) Creates an event handler function that will forward any calls to another function.
<static>	MochiKit.Widget._widgetMixin(node) Adds all functions from a widget class to a DOM node.
	addAll() Adds one or more children to this widget.
	addChildNode(child) Adds a single child DOM node to this widget.
	addClass() Adds the specified CSS class names to this HTML DOM node.
	animate(opts) Performs a visual effect animation on this widget.
	blurAll() Blurs (unfocuses) this DOM node and all relevant child nodes.
<static>	MochiKit.Widget.createWidget(name, attrs) Creates a new widget with the specified name, attributes and child widgets or DOM nodes.
<static>	MochiKit.Widget.createWidgetTree(node, ids) Creates a tree of DOM nodes or widgets from a parsed XML document.
	destroy() The internal widget destructor function.
<static>	MochiKit.Widget.destroyWidget(node) Destroys a widget or a DOM node.
<static>	MochiKit.Widget.emitSignal(node, sig) Emits a signal to any listeners connected with MochiKit.Signal.
	getChildNodes() Returns an array with all child DOM nodes.
	hasClass() Checks if this HTML DOM node has the specified CSS class names.
	hide() Hides this HTML DOM node if it doesn't have an explicit "display" CSS value.
<static>	MochiKit.Widget.isFormField(obj) Checks if the specified object is a form field.
	isHidden() Checks if this HTML DOM node is hidden (with the hide() method).
<static>	MochiKit.Widget.isWidget(obj, className) Checks if the specified object is a widget.
	removeAll() Removes all children to this widget.
	removeChildNode(child) Removes a single child DOM node from this widget.
	removeClass() 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 HTML DOM node if it was previously hidden with the hide() method.
	toggleClass() Toggles adding and removing the specified CSS class names to and from this HTML DOM node.

Function Namespace Detail

MochiKit.Widget()

Field Detail

<static> {Number} MochiKit.Widget._id

Function to return unique identifiers.

<static> MochiKit.Widget.Classes

The registered widget class names and constructor functions. All the default widgets in the MochiKit.Widget namespace are defined here, using their constructor function names. It is possible to override or add new classes by simply modifying this global data object.

Method Detail

{String} _animQueueId()

Returns the default visual effect queue identifier.

Returns:: {String} the the default queue identifier

<static> {Node/Widget} MochiKit.Widget._createWidgetTreeElem(node, ids)

Creates a DOM node or widget from a parsed XML element. This function will call createWidget() for any XML element node with a name corresponding to a widget class. Otherwise the createDOM() function is called. Some basic adjustments will be performed on the element attributes "id", "style", "class", "w", "h" and "a", in order to set these values with the appropriate function instead of as plain attribute strings.

Parameters:
{Node} node: the XML element node
{Object} ids Optional: the optional node id mappings

Returns:: {Node/Widget} the DOM node or widget created

<static> {Function} MochiKit.Widget._eventHandler(className, methodName)

Creates an event handler function that will forward any calls to another function. The other function must exist as a property in a parent widget of the specified class.

Parameters:
{String} className: the parent widget class name, or null to use the same node
{String} methodName: the name of the method to call
{Object} ... Optional: the additional method arguments

Returns:: {Function} a function that forwards calls as specified

<static> {Widget} MochiKit.Widget._widgetMixin(node)

Adds all functions from a widget class to a DOM node. This will also convert the DOM node into a widget by adding the "widget" CSS class and add all the default widget functions from the standard Widget prototype. Functions are added with setdefault, ensuring that existing functions will not be overwritten.

Parameters:
{Node} node: the DOM node to modify
{Object/Function} ... Optional: the widget class or constructor

Returns:: {Widget} the widget DOM node

addAll()

Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined argument. 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

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

addClass()

Adds the specified CSS class names to this HTML DOM node.

Parameters:
{String} ... Optional: the CSS class names to add

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.

<static> {Widget} MochiKit.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 MochiKit.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 MochiKit.Widget.Classes

Returns:: {Widget} the widget DOM node

<static> {Array} MochiKit.Widget.createWidgetTree(node, ids)

Creates a tree of DOM nodes or widgets from a parsed XML document. This function will call createWidget() for any XML element node with a name corresponding to a widget class. Otherwise the createDOM() function is called. Some basic adjustments will be performed on the element attributes "id", "style", "class", "w", "h" and "a", in order to set these values with the appropriate function instead of as plain attribute strings. Text nodes with non-whitespace content will be mapped to HTML DOM text nodes.

Parameters:
{Node/NodeList} node: the XML document, node or node list
{Object} ids Optional: the optional node id mappings

Returns:: {Array} an array of the root DOM nodes or widgets created, or null if no nodes could be created

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.

<static> MochiKit.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> {Boolean} MochiKit.Widget.emitSignal(node, sig)

Emits a signal to any listeners connected with MochiKit.Signal. This function handles errors by logging them to the default error log in MochiKit.Logging.

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

Returns:: {Boolean} true if the signal was processed correctly, or false if an exception was thrown

{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

{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

hide()

Hides this HTML DOM node if it doesn't have an explicit "display" CSS value. This mechanism is safe for all types of HTML elements, since it uses a "widgetHidden" CSS class to hide nodes instead of explicitly setting the CSS display property.

<static> {Boolean} MochiKit.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

{Boolean} isHidden()

Checks if this HTML DOM node is hidden (with the hide() method). This method does NOT check the actual widget visibility (which will be affected by animations for example), but only checks for the "widgetHidden" CSS class.

Returns:: {Boolean} true if the widget is hidden, or false otherwise

<static> {Boolean} MochiKit.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" (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

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.

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

removeClass()

Removes the specified CSS class names from this HTML DOM node.

Parameters:
{String} ... Optional: the CSS class names to remove

setAttrs(attrs)

Updates the widget or HTML DOM node attributes. This method is sometimes overridden by individual widgets to allow modification of widget attributes also available in the constructor.

Parameters:
{Object} attrs: the widget and node attributes to set

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

show()

Shows this HTML DOM node if it was previously hidden with the hide() method. This mechanism is safe for all types of HTML elements, since it uses a "widgetHidden" CSS class to hide nodes instead of explicitly setting the CSS display property.

{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