Class Index | File Index

Classes


Class dijit.Widget


Defined in: _Widget.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Field Summary
Field Attributes Field Name and Description
<private>  
Path to a blank 1x1 image.
<private>  
attributeMap addendum for event handlers that should be connected only on first use
<private>  
startup() has completed.
 
TODO check formatting of paragraphs here.
 
Root CSS class of the widget (ex: dijitTextBox), used to construct CSS classes to indicate widget state.
 

Designates where children of the source DOM node will be placed.

<constant>  
dir
Bi-directional support, as defined by the [HTML DIR](http://www.w3.org/TR/html401/struct/dirlang.html#adef-dir) attribute.
 
This is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's dojoAttachPoint syntax, but the domNode property is the canonical "top level" node in widget UI.
 
id
A unique, opaque ID string that can be assigned by users or by the system.
<constant>  
Rarely used.
<private>  
List of nodes that correctly handle click events via native browser support, and don't need dijit's help
<constant>  
pointer to original DOM node
 
HTML style attributes as cssText string or name/value hash
 
HTML title attribute.
 
When this widget's title attribute is used to for a tab label, accordion pane title, etc.
Method Summary
Method Attributes Method Name and Description
<private>  
Step during widget creation to copy all widget attributes to the DOM as per attributeMap and _setXXXAttr functions.
<private>  
_attrToDom(attr, value)

Reflect a widget attribute (title, tabIndex, duration etc.

<private>  
Helper function for get() and set().
<private>  
This is where widgets do processing for when they stop being active, such as changing CSS classes.
<private>  
_onConnect(event)
Called when someone connects to one of my handlers.
<private>  
This is where widgets do processing for when they are active, such as changing CSS classes.
<private>  
Internal method called when this widget is made visible.
<private>  
Custom setter for the CSS "class" attribute
<private>  
Sets the style attribute of the widget according to value, which is either a hash like {height: "5px", width: "3px"} or a plain string Determines which node to set the style on based on style setting in attributeMap.
 
attr(name, value)
 
Construct the UI for this widget, setting this.domNode.
 
connect(obj, event, method)
Connects specified obj/event to specified method of this object and registers for disconnect() on widget destroy.
<private>  
create(params, srcNodeRef)
Kick off the life-cycle of a widget.
 
destroy(preserveDom)
Destroy this widget but not its descendants
 
destroyDescendants(preserveDom)
Recursively destroy the children of this widget and their descendants.
 
destroyRecursive(preserveDom)
Destroy this widget and its descendants

This is the generic "destructor" function that all widget users should call to cleanly discard with a widget.

 
destroyRendering(preserveDom)
Destroys the DOM nodes associated with this widget
 
disconnect(handles)
Disconnects handle created by `connect`.
 
get(name)
Get a property from a widget.
 
Returns all the widgets contained by this, i.e.
 
Returns all the widgets contained by this, i.e.
 
Return true if this widget can currently be focused and false if not.
 
Return this widget's explicit or implicit orientation (true for LTR, false for RTL)
 
[callback] Called when the widget stops being "active" because focus moved to something outside of it, or the user clicked somewhere outside of it, or the widget was
 
onClick(event)
[callback] Connect to this function to receive notifications of mouse click events.
 
[callback] Called when another widget becomes the selected pane in a `dijit.layout.TabContainer`, `dijit.layout.StackContainer`, `dijit.layout.AccordionContainer`, etc.
 
onDblClick(event)
[callback] Connect to this function to receive notifications of mouse doubleclick events.
 
[callback] Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.
 
onKeyDown(event)
[callback] Connect to this function to receive notifications of keys being pressed down.
 
onKeyPress(event)
[callback] Connect to this function to receive notifications of printable keys being typed.
 
onKeyUp(event)
[callback] Connect to this function to receive notifications of printable keys being released.
 
onMouseDown(event)
[callback] Connect to this function to receive notifications of when the mouse button is pressed down.
 
onMouseEnter(event)
[callback] Connect to this function to receive notifications of when the mouse moves onto this widget.
 
onMouseLeave(event)
[callback] Connect to this function to receive notifications of when the mouse moves off of this widget.
 
onMouseMove(event)
[callback] Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.
 
onMouseOut(event)
[callback] Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.
 
onMouseOver(event)
[callback] Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.
 
onMouseUp(event)
[callback] Connect to this function to receive notifications of when the mouse button is released.
 
[callback] Called when this widget becomes the selected pane in a `dijit.layout.TabContainer`, `dijit.layout.StackContainer`, `dijit.layout.AccordionContainer`, etc.
 
placeAt(reference, position)
Place this widget's domNode reference somewhere in the DOM based on standard dojo.place conventions, or passing a Widget reference that contains and addChild member.
 
Processing after the DOM fragment is created.
 
Called after the parameters to the widget have been read-in, but before the widget template is instantiated.
<private>  
postscript(params, srcNodeRef)
Kicks off widget instantiation.
 
set(name, value)
Set a property on a widget Sets named properties on a widget which may potentially be handled by a setter in the widget.
 
setAttribute(attr, value)
 
Processing after the DOM fragment is added to the document Called after a widget and its children have been created and added to the page, and all related widgets have finished their create() cycle, up through postCreate().
 
subscribe(topic, method)
Subscribes to the specified topic and calls the specified method of this object and registers for unsubscribe() on widget destroy.
 
Returns a string that represents the widget.
 
Stub function.
 
unsubscribe(handle)
Unsubscribes handle created by this.subscribe.
Class Detail
dijit.Widget()
Field Detail
<private> {String} _blankGif
Path to a blank 1x1 image. Used by <img> nodes in templates that really get their image via CSS background-image.

<private> {Object} _deferredConnects
attributeMap addendum for event handlers that should be connected only on first use

<private> {Boolean} _started
startup() has completed.

{Object} attributeMap
TODO check formatting of paragraphs here. attributeMap sets up a "binding" between attributes (aka properties) of the widget and the widget's DOM. Changes to widget attributes listed in attributeMap will be reflected into the DOM. For example, calling attr('title', 'hello') on a TitlePane will automatically cause the TitlePane's DOM to update with the new title. attributeMap is a hash where the key is an attribute of the widget, and the value reflects a binding to a: If the value is an array, then each element in the array matches one of the formats of the above list. There are also some shorthands for backwards compatibility:

{String} baseClass
Root CSS class of the widget (ex: dijitTextBox), used to construct CSS classes to indicate widget state.

{DOMNode} containerNode

Designates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes and widgets.

In templated widgets, "containerNode" is set via a dojoAttachPoint assignment.

containerNode must be defined for any widget that accepts innerHTML (like ContentPane or BorderContainer or even Button), and conversely is null for widgets that don't, like TextBox.


<constant> {String} dir
Bi-directional support, as defined by the [HTML DIR](http://www.w3.org/TR/html401/struct/dirlang.html#adef-dir) attribute. Either left-to-right "ltr" or right-to-left "rtl". If undefined, widgets renders in page's default direction.

{DOMNode} domNode
This is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's dojoAttachPoint syntax, but the domNode property is the canonical "top level" node in widget UI.

{String} id
A unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.

<constant> {String} lang
Rarely used. Overrides the default Dojo locale used to render this widget, as defined by the [HTML LANG](http://www.w3.org/TR/html401/struct/dirlang.html#adef-lang) attribute. Value must be among the list of locales specified during by the Dojo bootstrap, formatted according to [RFC 3066](http://www.ietf.org/rfc/rfc3066.txt) (like en-us).

<private> {String[]} nodesWithKeyClick
List of nodes that correctly handle click events via native browser support, and don't need dijit's help

<constant> {DOMNode} srcNodeRef
pointer to original DOM node

{String|Object} style
HTML style attributes as cssText string or name/value hash

{String} title
HTML title attribute. For form widgets this specifies a tooltip to display when hovering over the widget (just like the native HTML title attribute). For TitlePane or for when this widget is a child of a TabContainer, AccordionContainer, etc., it's used to specify the tab label, accordion pane title, etc.

{String} tooltip
When this widget's title attribute is used to for a tab label, accordion pane title, etc., this specifies the tooltip to appear when the mouse is hovered over that text.
Method Detail
<private> _applyAttributes()
Step during widget creation to copy all widget attributes to the DOM as per attributeMap and _setXXXAttr functions.

Skips over blank/false attribute values, unless they were explicitly specified as parameters to the widget, since those are the default anyway, and setting tabIndex="" is different than not setting tabIndex at all.

It processes the attributes in the attribute map first, and then it goes through and processes the attributes for the _setXXXAttr functions that have been specified


<private> _attrToDom(attr, value)

Reflect a widget attribute (title, tabIndex, duration etc.) to the widget DOM, as specified in attributeMap.

Also sets this["attr"] to the new value. Note some attributes like "type" cannot be processed this way as they are not mutable.

Parameters:
{String} attr
{String} value

<private> _getAttrNames(name)
Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.
Parameters:
{String} name

<private> _onBlur()
This is where widgets do processing for when they stop being active, such as changing CSS classes. See onBlur() for more details.

<private> _onConnect(event)
Called when someone connects to one of my handlers. "Turn on" that handler if it isn't active yet. This is also called for every single initialization parameter so need to do nothing for parameters like "id".
Parameters:
{String} event

<private> _onFocus(e)
This is where widgets do processing for when they are active, such as changing CSS classes. See onFocus() for more details.
Parameters:
e

<private> _onShow()
Internal method called when this widget is made visible. See `onShow` for details.

<private> _setClassAttr(value)
Custom setter for the CSS "class" attribute
Parameters:
{String} value

<private> _setStyleAttr(value)
Sets the style attribute of the widget according to value, which is either a hash like {height: "5px", width: "3px"} or a plain string Determines which node to set the style on based on style setting in attributeMap.
Parameters:
{String|Object} value

attr(name, value)
Parameters:
{String|Object} name
{Object?} value
Deprecated:
use get() or set() directly

buildRendering()
Construct the UI for this widget, setting this.domNode. Most widgets will mixin `dijit._Templated`, which implements this method.

{Handle} connect(obj, event, method)
Connects specified obj/event to specified method of this object and registers for disconnect() on widget destroy. Provide widget-specific analog to dojo.connect, except with the implicit use of this widget as the target object. This version of connect also provides a special "ondijitclick" event which triggers on a click or space or enter keyup

	var btn = new dijit.form.Button();
	// when foo.bar() is called, call the listener we're going to
	// provide in the scope of btn
	btn.connect(foo, "bar", function(){
		console.debug(this.toString());
	});
Parameters:
{Object|null} obj
{String|Function} event
{String|Function} method
Returns:
{Handle} A handle that can be passed to `disconnect` in order to disconnect before the widget is destroyed.

<private> create(params, srcNodeRef)
Kick off the life-cycle of a widget.

Create calls a number of widget methods (postMixInProperties, buildRendering, postCreate, etc.), some of which of you'll want to override. See for a discussion of the widget creation lifecycle.

Of course, adventurous developers could override create entirely, but this should only be done as a last resort.

Parameters:
{Object} params
Hash of initialization parameters for widget, including scalar values (like title, duration etc.) and functions, typically callbacks like onClick.
{DomNode|String} srcNodeRef Optional
If a srcNodeRef (DOM node) is specified:
  • use srcNodeRef.innerHTML as my contents
  • if this is a behavioral widget then apply behavior to that srcNodeRef
  • otherwise, replace srcNodeRef with my generated DOM tree

destroy(preserveDom)
Destroy this widget but not its descendants
Parameters:
{Boolean} preserveDom Optional
If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._Templated widgets.

destroyDescendants(preserveDom)
Recursively destroy the children of this widget and their descendants.
Parameters:
{Boolean} preserveDom Optional
If true, the preserveDom attribute is passed to all descendant widget's .destroy() method. Not for use with _Templated widgets.

destroyRecursive(preserveDom)
Destroy this widget and its descendants

This is the generic "destructor" function that all widget users should call to cleanly discard with a widget. Once a widget is destroyed, it is removed from the manager object.

Parameters:
{Boolean} preserveDom Optional
If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._Templated widgets.

destroyRendering(preserveDom)
Destroys the DOM nodes associated with this widget
Parameters:
{Boolean} preserveDom Optional
If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._Templated widgets.

disconnect(handles)
Disconnects handle created by `connect`. Also removes handle from this widget's list of connects.
Parameters:
{dijit.Widget.Handle} handles

get(name)
Get a property from a widget. Get a named property from a widget. The property may potentially be retrieved via a getter method. If no getter is defined, this just retrieves the object's property. For example, if the widget has a properties "foo" and "bar" and a method named "_getFooAttr", calling: myWidget.get("foo"); would be equivalent to writing: widget._getFooAttr();myWidget.get("bar"); would be equivalent to writing: widget.bar;
Parameters:
{Object} name
the property to get

{dijit.Widget[]} getChildren()
Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode. Does not return nested widgets, nor widgets that are part of this widget's template.
Returns:
{dijit.Widget[]}

{dijit.Widget[]} getDescendants()
Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode. This method should generally be avoided as it returns widgets declared in templates, which are supposed to be internal/hidden, but it's left here for back-compat reasons.
Returns:
{dijit.Widget[]}

{Boolean} isFocusable()
Return true if this widget can currently be focused and false if not.
Returns:
{Boolean}

{Boolean} isLeftToRight()
Return this widget's explicit or implicit orientation (true for LTR, false for RTL)
Returns:
{Boolean}

onBlur()
[callback] Called when the widget stops being "active" because focus moved to something outside of it, or the user clicked somewhere outside of it, or the widget was

onClick(event)
[callback] Connect to this function to receive notifications of mouse click events.
Parameters:
{Event} event
mouse event

{Boolean} onClose()
[callback] Called when another widget becomes the selected pane in a `dijit.layout.TabContainer`, `dijit.layout.StackContainer`, `dijit.layout.AccordionContainer`, etc. Also called to indicate hide of a `dijit.Dialog`, `dijit.TooltipDialog`, or `dijit.TitlePane`. onHide: function(){ }, /**

Called when this widget is being displayed as a popup (ex: a Calendar popped up from a DateTextBox), and it is hidden. This is called from the dijit.popup code, and should not be called directly.

Also used as a parameter for children of `dijit.layout.StackContainer` or subclasses. Callback if a user tries to close the child. Child will be closed if this function returns true.

Returns:
{Boolean}

onDblClick(event)
[callback] Connect to this function to receive notifications of mouse doubleclick events.
Parameters:
{Event} event
mouse event

onFocus()
[callback] Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.

onKeyDown(event)
[callback] Connect to this function to receive notifications of keys being pressed down.
Parameters:
{Event} event
key event

onKeyPress(event)
[callback] Connect to this function to receive notifications of printable keys being typed.
Parameters:
{Event} event
key event

onKeyUp(event)
[callback] Connect to this function to receive notifications of printable keys being released.
Parameters:
{Event} event
key event

onMouseDown(event)
[callback] Connect to this function to receive notifications of when the mouse button is pressed down.
Parameters:
{Event} event
mouse event

onMouseEnter(event)
[callback] Connect to this function to receive notifications of when the mouse moves onto this widget.
Parameters:
{Event} event
mouse event

onMouseLeave(event)
[callback] Connect to this function to receive notifications of when the mouse moves off of this widget.
Parameters:
{Event} event
mouse event

onMouseMove(event)
[callback] Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.
Parameters:
{Event} event
mouse event

onMouseOut(event)
[callback] Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.
Parameters:
{Event} event
mouse event

onMouseOver(event)
[callback] Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.
Parameters:
{Event} event
mouse event

onMouseUp(event)
[callback] Connect to this function to receive notifications of when the mouse button is released.
Parameters:
{Event} event
mouse event

onShow()
[callback] Called when this widget becomes the selected pane in a `dijit.layout.TabContainer`, `dijit.layout.StackContainer`, `dijit.layout.AccordionContainer`, etc. Also called to indicate display of a `dijit.Dialog`, `dijit.TooltipDialog`, or `dijit.TitlePane`.

{dijit.Widget} placeAt(reference, position)
Place this widget's domNode reference somewhere in the DOM based on standard dojo.place conventions, or passing a Widget reference that contains and addChild member.

A convenience function provided in all Widgets, providing a simple shorthand mechanism to put an existing (or newly created) Widget somewhere in the dom, and allow chaining.

	// create a Button with no srcNodeRef, and place it in the body:
	var button = new dijit.form.Button({ label:"click" }).placeAt(dojo.body());
	// now, 'button' is still the widget reference to the newly created button
	dojo.connect(button, "onClick", function(e){ console.log('click'); });
	// create a button out of a node with id="src" and append it to id="wrapper":
	var button = new dijit.form.Button({},"src").placeAt("wrapper");
	// place a new button as the first element of some div
	var button = new dijit.form.Button({ label:"click" }).placeAt("wrapper","first");
	// create a contentpane and add it to a TabContainer
	var tc = dijit.byId("myTabs");
	new dijit.layout.ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)
Parameters:
{String|DomNode|Widget} reference
The String id of a domNode, a domNode reference, or a reference to a Widget posessing an addChild method.
{String|Integer} position Optional
If passed a string or domNode reference, the position argument accepts a string just as dojo.place does, one of: "first", "last", "before", or "after". If passed a Widget reference, and that widget reference has an ".addChild" method, it will be called passing this widget instance into that method, supplying the optional position index passed.
Returns:
{dijit.Widget} Provides a useful return of the newly created dijit.Widget instance so you can "chain" this function by instantiating, placing, then saving the return value to a variable.

postCreate()
Processing after the DOM fragment is created.

Called after the DOM fragment has been created, but not necessarily added to the document. Do not include any operations which rely on node dimensions or placement.


postMixInProperties()
Called after the parameters to the widget have been read-in, but before the widget template is instantiated. Especially useful to set properties that are referenced in the widget template.

<private> postscript(params, srcNodeRef)
Kicks off widget instantiation. See create() for details.
Parameters:
{Object|null} params
{DomNode|String} srcNodeRef

set(name, value)
Set a property on a widget Sets named properties on a widget which may potentially be handled by a setter in the widget. For example, if the widget has a properties "foo" and "bar" and a method named "_setFooAttr", calling: myWidget.set("foo", "Howdy!"); would be equivalent to writing: widget._setFooAttr("Howdy!"); and: myWidget.set("bar", 3); would be equivalent to writing: widget.bar = 3; set() may also be called with a hash of name/value pairs, ex:
		myWidget.set({
		foo: "Howdy",
		bar: 3
	})
This is equivalent to calling set(foo, "Howdy") and set(bar, 3)
Parameters:
{Object} name
The property to set.
{Object} value
The value to set in the property.

setAttribute(attr, value)
Parameters:
{String} attr
{anything} value
Deprecated:
Use set() instead

startup()
Processing after the DOM fragment is added to the document Called after a widget and its children have been created and added to the page, and all related widgets have finished their create() cycle, up through postCreate(). This is useful for composite widgets that need to control or layout sub-widgets. Many layout widgets can use this as a wiring phase.

subscribe(topic, method)
Subscribes to the specified topic and calls the specified method of this object and registers for unsubscribe() on widget destroy. Provide widget-specific analog to dojo.subscribe, except with the implicit use of this widget as the target object.

	var btn = new dijit.form.Button();
	// when /my/topic is published, this button changes its label to
  // be the parameter of the topic.
	btn.subscribe("/my/topic", function(v){
		this.set("label", v);
	});
Parameters:
{String} topic
{String|Function} method

{String} toString()
Returns a string that represents the widget. When a widget is cast to a string, this method will be used to generate the output. Currently, it does not implement any sort of reversible serialization.
Returns:
{String}

uninitialize()
Stub function. Override to implement custom widget tear-down behavior.

unsubscribe(handle)
Unsubscribes handle created by this.subscribe. Also removes handle from this widget's list of subscriptions
Parameters:
{Object} handle

Documentation generated by JsDoc Toolkit 2.3.2 on Mon Sep 20 2010 21:52:25 GMT+0900 (JST)