This widget displays hierarchical data from a store.
Parameter | Type | Description |
---|---|---|
params | Object | null | Hash of initialization parameters for widget, including scalar values (like title, duration etc.) and functions, typically callbacks like onClick. The hash can contain any of the widget's properties, excluding read-only properties. |
srcNodeRef | DOMNode | String |
Optional If a srcNodeRef (DOM node) is specified:
|
See the dijit/Tree reference documentation for more information.
List of connections associated with data-dojo-attach-event=... in the template
List of widget attribute names associated with data-dojo-attach-point=... in the template, ex: ["containerNode", "labelNode"]
Path to a blank 1x1 image.
Used by <img>
nodes in templates that really get their image via CSS background-image.
Hash mapping key code (arrow keys and home/end key) to functions to handle those keys. Usually not used directly, as subclasses can instead override _onLeftArrow() etc.
Number of pixels to indent tree nodes (relative to parent node). Default is 19 but can be overridden by setting CSS class dijitTreeIndent and calling resize() or startup() on tree after it's in the DOM.
Not normally use, but this flag can be set by the app if the server has already rendered the template, i.e. already inlining the template for the widget into the main page. Reduces _TemplatedMixin to just function like _AttachMixin.
True if mouse was pressed while over this widget, and hasn't been released yet
Object to which attach points and events will be scoped. Defaults to 'this'.
Deprecated. Instead of attributeMap, widget should have a _setXXXAttr attribute for each XXX attribute to be mapped to the DOM.
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 set('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:
DOM node attribute
focus: {node: "focusNode", type: "attribute"} Maps this.focus to this.focusNode.focus
DOM node innerHTML
title: { node: "titleNode", type: "innerHTML" } Maps this.title to this.titleNode.innerHTML
DOM node innerText
title: { node: "titleNode", type: "innerText" } Maps this.title to this.titleNode.innerText
DOM node CSS class
myClass: { node: "domNode", type: "class" } Maps this.myClass to this.domNode.className
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:
1 | "focusNode" ---> { node: "focusNode" , type: "attribute" } |
Set to a positive value to allow drag and drop "between" nodes.
If during DnD mouse is over a (target) node but less than betweenThreshold pixels from the bottom edge, dropping the the dragged node will make it the next sibling of the target node, rather than the child.
Similarly, if mouse is over a target node but less that betweenThreshold pixels from the top edge, dropping the dragged node will make it the target node's previous sibling rather than the target node's child.
Deprecated. This information should be specified in the model. One ore more attributes that holds children of a tree node
Designates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes and widgets. For example, for myWidget:
1 2 3 4 5 | < div data-dojo-type = myWidget > < b > here's a plain DOM node < span data-dojo-type = subWidget >and a widget</ span > < i > and another plain DOM node </ i > </ div > |
containerNode would point to:
1 2 3 | < b > here's a plain DOM node < span data-dojo-type = subWidget >and a widget</ span > < i > and another plain DOM node </ i > |
In templated widgets, "containerNode" is set via a data-dojo-attach-point 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.
Subclasses may define a cssStateNodes property that lists sub-nodes within the widget that need CSS classes applied on mouse hover/press and focus.
Each entry in this optional hash is a an attach-point name (like "upArrowButton") mapped to a CSS class name (like "dijitUpArrowButton"). Example:
1 2 3 4 | { "upArrowButton" : "dijitUpArrowButton" , "downArrowButton" : "dijitDownArrowButton" } |
The above will set the CSS class dijitUpArrowButton to the this.upArrowButton DOMNode when it
is hovered, etc.
Bi-directional support, as defined by the HTML DIR attribute. Either left-to-right "ltr" or right-to-left "rtl". If undefined, widgets renders in page's default direction.
This is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's data-dojo-attach-point syntax, but the domNode property is the canonical "top level" node in widget UI.
Number of pixels mouse moves before it's considered the start of a drag operation
This widget or a widget it contains has focus, or is "active" because it was recently clicked.
The currently focused child widget, or null if there isn't one
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.
Deprecated. Use dijit/tree/ForestStoreModel directly instead. Used in conjunction with query parameter. If a query is specified (rather than a root node id), and a label is also specified, then a fake root node is created and displayed, with this label.
Interface to read tree data, get notifications of changes to tree data, and for handling drop operations (i.e drag and drop onto the tree)
If multiple characters are typed where each keystroke happens within multiCharSearchDuration of the previous keystroke, search for nodes matching all the keystrokes.
For example, typing "ab" will search for entries starting with "ab" unless the delay between "a" and "b" is greater than multiCharSearchDuration.
Parameter to dndController, see dijit/tree/dndSource.onDndCancel(). Generally this doesn't need to be set.
Parameter to dndController, see dijit/tree/dndSource.onDndDrop(). Generally this doesn't need to be set.
If true, clicking a folder node's label will open it, rather than calling onClick()
If true, double-clicking a folder node's label will open it, rather than calling onDblClick()
The document this widget belongs to. If not specified to constructor, will default to srcNodeRef.ownerDocument, or if no sourceRef specified, then to the document global
Full paths from rootNode to selected nodes expressed as array of items or array of ids. Since setting the paths may be asynchronous (because of waiting on dojo.data), set("paths", ...) returns a Promise to indicate when the set is complete.
Deprecated. User should specify query to the model directly instead. Specifies datastore query to return the root item or top items for the tree.
The currently selected items in this tree.
This property can only be set (via set('selectedItems', ...)) when that item is already
visible in the tree. (I.e. the tree has already been expanded to show that node.)
Should generally use paths
attribute to set the selected items instead.
Deprecated. Use "model" parameter instead. The store to get data to display in the tree.
Tab index of the container; same as HTML tabIndex attribute. Note then when user tabs into the container, focus is immediately moved to the first item in the container.
Path to template (HTML file) for this widget relative to dojo.baseUrl. Deprecated: use templateString with require([... "dojo/text!..."], ...) instead
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. In this case it's interpreted as HTML.
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.
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
nodeWidget | Object | An object with the following properties:
|
||||||||||
e | Event | |||||||||||
doOpen | Boolean | |||||||||||
func | String |
Size container to match widest TreeNode, so that highlighting with scrolling works (#13141, #16132)
Step during widget creation to copy widget attributes to the DOM according to attributeMap and _setXXXAttr objects, and also to call custom _setXXXAttr() methods.
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.
For backwards-compatibility reasons attributeMap overrides _setXXXAttr when _setXXXAttr is a hash/string/array, but _setXXXAttr as a functions override attributeMap.
Roughly corresponding to dojo/on, this is the default function for processing a data-dojo-attach-event. Meant to attach to DOMNodes, not to widgets.
Parameter | Type | Description |
---|---|---|
node | DOMNode | The node to setup a listener on. |
type | String | Event name like "click". |
func | undefined |
Iterate through the dom nodes and attach functions and nodes accordingly.
Map widget properties and functions to the handlers specified in the dom node and it's descendants. This function iterates over all nodes and looks for these properties:
Parameter | Type | Description |
---|---|---|
rootNode | DomNode | The node to search for properties. All descendants will be searched. |
Reflect a widget attribute (title, tabIndex, duration etc.) to the widget DOM, as specified by commands parameter. If commands isn't specified then it's looked up from attributeMap. Note some attributes like "type" cannot be processed this way as they are not mutable.
Parameter | Type | Description |
---|---|---|
attr | String | Name of member variable (ex: "focusNode" maps to this.focusNode) pointing to DOMNode inside the widget, or alternately pointing to a subwidget |
value | String | |
commands | Object |
Optional
|
Internal helper for directly changing an attribute value.
Directly change the value of an attribute on an object, bypassing any accessor setter. Also handles the calling of watch and emitting events. It is designed to be used by descendant class when there are two values of attributes that are linked, but calling .set() is not appropriate.
Parameter | Type | Description |
---|---|---|
name | String | The property to set. |
value | Mixed | The value to set in the property. |
Internal helper for directly changing an attribute value.
Called when the user has requested to collapse the node
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
node | Object | An object with the following properties:
|
Promise that resolves when the node has finished closing
creates a TreeNode
Developers can override this method to define their own TreeNode class; However it will probably be removed in a future release in favor of a way of just specifying a widget for the label, rather than one that contains the children too.
Parameter | Type | Description |
---|---|---|
args | Object |
Handler for CSS event on this.domNode. Sets hovering and active properties depending on mouse state, which triggers _setStateClass() to set appropriate CSS classes for this.domNode.
Parameter | Type | Description |
---|---|---|
event | Event |
Detach and clean up the attachments made in _attachtempalteNodes.
Escape a value to be inserted into the template, either into an attribute value (ex: foo="${bar}") or as inner text of an element (ex: ${foo})
Parameter | Type | Description |
---|---|---|
val | String |
Called when the user has requested to expand the node
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
node | Object | An object with the following properties:
|
Promise that resolves when the node is loaded and opened and (if persist=true) all it's descendants that were previously opened too
Relocate source contents to templated container node. this.containerNode must be able to receive children, or exceptions will be thrown.
Parameter | Type | Description |
---|---|---|
source | DomNode |
Helper function to get value for specified property stored by this._set(), i.e. for properties with custom setters. Used mainly by custom getters.
For example, CheckBox._getValueAttr() calls this._get("value").
Parameter | Type | Description |
---|---|---|
name | String |
Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.
Parameter | Type | Description |
---|---|---|
name | undefined |
Returns the next descendant, compared to "child".
Parameter | Type | Description |
---|---|---|
node | Widget | The current widget |
Returns the next or previous focusable descendant, compared to "child". Implements and extends _KeyNavMixin._getNextFocusableChild() for a _Container.
Parameter | Type | Description |
---|---|---|
child | Widget | The current widget |
dir | Integer |
|
Get next visible node
Parameter | Type | Description |
---|---|---|
node | undefined |
Collect metadata about this widget (only once per class, not once per instance):
1 2 | - list of attributes with custom setters, storing in this .constructor._setterAttrs - generate this .constructor._onMap, mapping names like "mousedown" to functions like onMouseDown |
Perform a search of the widget's options based on the user's keyboard activity
Called on keypress (and sometimes keydown), searches through this widget's children looking for items that match the user's typed search string. Multiple characters typed within 1 sec of each other are combined for multicharacter searching.
Parameter | Type | Description |
---|---|---|
evt | Event | |
keyChar | String |
Compares the searchString to the widget's text label, returning:
1 2 3 | * -1: a high priority match and stop searching * 0: not a match * 1: a match but keep looking for a higher priority match |
Parameter | Type | Description |
---|---|---|
item | dijit/_WidgetBase | |
searchString | String |
Initial load of the tree. Load root node (possibly hidden) and it's children.
Process data-dojo-attach-point and data-dojo-attach-event for given node or widget. Returns true if caller should process baseNode's children too.
Parameter | Type | Description |
---|---|---|
baseNode | DOMNode | Widget | |
getAttrFunc | Function | Function to get the specified property for a given DomNode/Widget. |
attachFunc | Function |
Optional Attaches an event handler from the specified node/widget to specified function. |
Publish a message for this widget/topic
Parameter | Type | Description |
---|---|---|
topicName | String | |
message | Object |
Helper function to set new value for specified property, and call handlers registered with watch() if the value has changed.
Parameter | Type | Description |
---|---|---|
name | String | |
value | anything |
Singular variant of _setPathsAttr
Parameter | Type | Description |
---|---|---|
path | Item[] | String[] |
Select the tree nodes identified by passed paths.
Parameter | Type | Description |
---|---|---|
paths | Item[][] | String[][] | Array of arrays of items or item id's |
Promise to indicate when the set is complete
Select tree nodes related to passed items. WARNING: if model use multi-parented items or desired tree node isn't already loaded behavior is undefined. Use set('paths', ...) instead.
Parameter | Type | Description |
---|---|---|
items | Items or ids |
Marks the specified TreeNodes as selected.
Parameter | Type | Description |
---|---|---|
nodes | Object | TreeNodes to mark. |
Update the visual state of the widget by setting the css classes on this.domNode (or this.stateNode if defined) by combining this.baseClass with various suffixes that represent the current widget state(s).
In the case where a widget has multiple states, it sets the class based on all possible combinations. For example, an invalid form widget that is being hovered will be "dijitInput dijitInputInvalid dijitInputHover dijitInputInvalidHover".
The widget may have one or more of the following states, determined by this.state, this.checked, this.valid, and this.selected:
In addition, it may have one or more of the following states, based on this.disabled and flags set in _onMouse (this.active, this.hovering) and from focus manager (this.focused):
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.
Parameter | Type | Description |
---|---|---|
value | String | Object |
Called at the start of an operation that will change what's displayed.
Parameter | Type | Description |
---|---|---|
p | Promise | Boolean | Promise that tells when the operation will complete. Alternately, if it's just a Boolean, it signifies that the operation was synchronous, and already completed. |
Query or set expanded state for an node
Parameter | Type | Description |
---|---|---|
node | undefined | |
expanded | undefined |
User specified a store&query rather than model, so create model from store/query
Does substitution of ${foo} type properties in template string
Parameter | Type | Description |
---|---|---|
tmpl | undefined |
Handler for hover/active mouse event on widget's subnode
Parameter | Type | Description |
---|---|---|
node | undefined | |
clazz | undefined | |
evt | undefined |
Track mouse/focus events on specified node and set CSS class on that node to indicate current state. Usually not called directly, but via cssStateNodes attribute.
Given class=foo, will set the following CSS class on the node
Note that it won't set any classes if the widget is disabled.
Parameter | Type | Description |
---|---|---|
node | DomNode | Should be a sub-node of the widget, not the top node (this.domNode), since the top node is handled specially and automatically just by mixing in this class. |
clazz | String | CSS class name (ex: dijitSliderUpArrow) |
This method is deprecated, use get() or set() directly.
Parameter | Type | Description |
---|---|---|
name | String | Object | The property to get or set. If an object is passed here and not a string, its keys are used as names of attributes to be set and the value of the object as values to set in the widget. |
value | Object |
Optional Optional. If provided, attr() operates as a setter. If omitted, the current value of the named property is returned. |
Construct the UI for this widget, setting this.domNode.
Most widgets will mixin dijit._TemplatedMixin
, which implements this method.
Collapse all nodes in the tree
Promise that resolves when all nodes have collapsed
Deprecated, will be removed in 2.0, use this.own(on(...)) or this.own(aspect.after(...)) instead.
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.
Events connected with this.connect
are disconnected upon
destruction.
Parameter | Type | Description |
---|---|---|
obj | Object | null | |
event | String | Function | |
method | String | Function |
A handle that can be passed to disconnect
in order to disconnect before
the widget is destroyed.
1 2 3 4 5 6 | var btn = new 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()); }); |
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 http://dojotoolkit.org/reference-guide/dijit/_WidgetBase.html 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.
Parameter | Type | Description |
---|---|---|
params | Object | null | Hash of initialization parameters for widget, including scalar values (like title, duration etc.) and functions, typically callbacks like onClick. The hash can contain any of the widget's properties, excluding read-only properties. |
srcNodeRef | DOMNode | String |
Optional If a srcNodeRef (DOM node) is specified:
|
Wrapper to setTimeout to avoid deferred functions executing after the originating widget has been destroyed. Returns an object handle with a remove method (that returns null) (replaces clearTimeout).
Parameter | Type | Description |
---|---|---|
fcn | Function | Function reference. |
delay | Number |
Optional Delay, defaults to 0. |
Recursively destroy the children of this widget and their descendants.
Parameter | Type | Description |
---|---|---|
preserveDom | Boolean |
Optional If true, the preserveDom attribute is passed to all descendant widget's .destroy() method. Not for use with _Templated widgets. |
Destroys the DOM nodes associated with this widget.
Parameter | Type | Description |
---|---|---|
preserveDom | Boolean |
Optional If true, this method will leave the original DOM structure alone during tear-down. Note: this will not work with _Templated widgets yet. |
Deprecated, will be removed in 2.0, use handle.remove() instead.
Disconnects handle created by connect
.
Parameter | Type | Description |
---|---|---|
handle | undefined |
Class to use as as the dnd controller. Specifying this class enables DnD. Generally you should specify this as dijit/tree/dndSource. Setting of dijit/tree/_dndSelector handles selection only (no actual DnD).
Used by widgets to signal that a synthetic event occurred, ex:
1 | myWidget.emit( "attrmodified-selectedChildWidget" , {}). |
Emits an event on this.domNode named type.toLowerCase(), based on eventObj. Also calls onType() method, if present, and returns value from that method. By default passes eventObj to callback, but will pass callbackArgs instead, if specified. Modifies eventObj by adding missing parameters (bubbles, cancelable, widget).
Parameter | Type | Description |
---|---|---|
type | String | |
eventObj | Object |
Optional
|
callbackArgs | Array |
Optional
|
Expand all nodes in the tree
Promise that resolves when all nodes have expanded
Default focus() implementation: focus the previously focused child, or first child. Some applications may want to change this method to focus the [first] selected child.
Focus specified child widget.
Parameter | Type | Description |
---|---|---|
widget | dijit/_WidgetBase | Reference to container's child widget |
last | Boolean | If true and if widget has multiple focusable nodes, focus the last one instead of the first one |
Focus on the specified node (which must be visible)
Parameter | Type | Description |
---|---|---|
node | _tree.Node |
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 properties foo
and bar
and a method named _getFooAttr()
, calling:
myWidget.get("foo")
would be equivalent to calling
widget._getFooAttr()
and myWidget.get("bar")
would be equivalent to the expression
widget.bar2
Parameter | Type | Description |
---|---|---|
name | undefined | The property to get. |
Returns all direct children of this widget, i.e. all widgets underneath this.containerNode whose parent is this widget. Note that it does not return all descendants, but rather just direct children. Analogous to Node.childNodes, except containing widgets rather than DOMNodes.
The result intentionally excludes internally created widgets (a.k.a. supporting widgets) outside of this.containerNode.
Note that the array returned is a simple array. Application code should not assume existence of methods like forEach().
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.
Overridable function to return CSS class name to display icon
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
Overridable function to return CSS styles to display icon
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
Object suitable for input to dojo.style() like {backgroundImage: "url(...)"}
Deprecated. This should be specified on the model itself.
Overridable function that return array of child items of given parent item, or if parentItem==null then return top items in tree
Parameter | Type | Description |
---|---|---|
parentItem | undefined | |
onComplete | undefined |
Overridable function to get the label for a tree node (given the item)
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item |
Overridable function to return CSS class name to display label
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
CSS class name
Overridable function to return CSS styles to display label
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
Object suitable for input to dojo.style() like {color: "red", background: "green"}
Returns all tree nodes that refer to an item
Parameter | Type | Description |
---|---|---|
item | Item or id |
Array of tree nodes that refer to passed item
Overridable function to return CSS class name to display row
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
CSS class name
Overridable function to return CSS styles to display row
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item | |
opened | Boolean |
Object suitable for input to dojo.style() like {background-color: "#bbb"}
Overridable function to get the tooltip for a tree node (given the item)
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item |
check whether a dom node is the expandoNode for a particular TreeNode widget
Parameter | Type | Description |
---|---|---|
node | undefined | |
widget | undefined |
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)
Returns objects passed to Tree.model.newItem()
based on DnD nodes
dropped onto the tree. Developer must override this method to enable
dropping from external sources onto this Tree, unless the Tree.model's items
happen to look like {id: 123, name: "Apple" } with no other attributes.
For each node in nodes[], which came from source, create a hash of name/value pairs to be passed to Tree.model.newItem(). Returns array of those hashes.
Parameter | Type | Description |
---|---|---|
nodes | DomNode[] | The DOMNodes dragged from the source container |
target | DomNode | The target TreeNode.rowNode |
source | dojo/dnd/Source | The source container the nodes were dragged from, perhaps another Tree or a plain dojo/dnd/Source |
Array of name/value hashes for each new item to be added to the Tree, like:
1 2 3 4 | [ { id: 123, label: "apple" , foo: "bar" }, { id: 456, label: "pear" , zaz: "bam" } ] |
Deprecated. This should be specified on the model itself.
Overridable function to tell if an item has or may have children. Controls whether or not +/- expando icon is shown. (For efficiency reasons we may not want to check if an element actually has children until user clicks the expando node)
Parameter | Type | Description |
---|---|---|
item | dojo/data/Item |
Parameter | Type | Description |
---|---|---|
type | String | Function | protected |
func | Function |
Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.
The array of specified handles, so you can do for example:
1 | var handle = this .own(on(...))[0]; |
Place this widget somewhere in the DOM based on standard domConstruct.place() conventions.
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.
Parameter | Type | Description |
---|---|---|
reference | String | DomNode | DocumentFragment | dijit/_WidgetBase | Widget, DOMNode, DocumentFragment, or id of widget or DOMNode |
position | String | Int |
Optional If reference is a widget (or id of widget), and that widget has an ".addChild" method, it will be called passing this widget instance into that method, supplying the optional position index passed. In this case position (if specified) should be an integer. If reference is a DOMNode (or id matching a DOMNode but not a widget), the position argument can be a numeric index or a string "first", "last", "before", or "after", same as dojo/dom-construct::place(). |
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.
1 2 3 4 | // create a Button with no srcNodeRef, and place it in the body: var button = new Button({ label: "click" }).placeAt(win.body()); // now, 'button' is still the widget reference to the newly created button button.on( "click" , function (e){ console.log( 'click' ); })); |
1 2 | // create a button out of a node with id="src" and append it to id="wrapper": var button = new Button({}, "src" ).placeAt( "wrapper" ); |
1 2 | // place a new button as the first element of some div var button = new Button({ label: "click" }).placeAt( "wrapper" , "first" ); |
1 2 3 | // create a contentpane and add it to a TabContainer var tc = dijit.byId( "myTabs" ); new ContentPane({ href: "foo.html" , title: "Wow!" }).placeAt(tc) |
Kicks off widget instantiation. See create() for details.
Parameter | Type | Description |
---|---|---|
params | Object |
Optional
|
srcNodeRef | DomNode | String |
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 properties foo
and bar
and a method named _setFooAttr()
, calling
myWidget.set("foo", "Howdy!")
would be equivalent to calling
widget._setFooAttr("Howdy!")
and myWidget.set("bar", 3)
would be equivalent to the statement widget.bar = 3;
set() may also be called with a hash of name/value pairs, ex:
1 2 3 4 | myWidget.set({ foo: "Howdy" , bar: 3 }); |
This is equivalent to calling set(foo, "Howdy")
and set(bar, 3)
Parameter | Type | Description |
---|---|---|
name | undefined | The property to set. |
value | undefined | The value to set in the property. |
Set a property on a widget
Deprecated. Use set() instead.
Parameter | Type | Description |
---|---|---|
attr | String | |
value | anything |
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().
Note that startup() may be called while the widget is still hidden, for example if the widget is inside a hidden dijit/Dialog or an unselected tab of a dijit/layout/TabContainer. For widgets that need to do layout, it's best to put that layout code inside resize(), and then extend dijit/layout/_LayoutWidget so that resize() is called when the widget is visible.
Deprecated, will be removed in 2.0, use this.own(topic.subscribe()) instead.
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.
Parameter | Type | Description |
---|---|---|
t | String | The topic |
method | Function | The callback |
1 2 3 4 5 6 | var btn = new 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); }); |
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.
Deprecated. Override destroy() instead to implement custom widget tear-down behavior.
Deprecated, will be removed in 2.0, use handle.remove() instead.
Unsubscribes handle created by this.subscribe. Also removes handle from this widget's list of subscriptions
Parameter | Type | Description |
---|---|---|
handle | Object |
Watches a property for changes
Parameter | Type | Description |
---|---|---|
name | String |
Optional Indicates the property to watch. This is optional (the callback may be the only parameter), and if omitted, all the properties will be watched |
callback | Function | The function to execute when the property changes. This will be called after the property has been changed. The callback will be called with the |this| set to the instance, the first argument as the name of the property, the second argument as the old value and the third argument as the new value. |
An object handle for the watch. The unwatch method of this object can be used to discontinue watching this property:
1 2 | var watchHandle = obj.watch( "foo" , callback); watchHandle.unwatch(); // callback won't be called now |
This is where widgets do processing for when they stop being active, such as changing CSS classes. See onBlur() for more details.
1 2 3 4 5 6 | var btn = new 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); }); |
Called when focus leaves a child widget to go to a sibling widget. Used to be used by MenuBase.js (remove for 2.0)
Parameter | Type | Description |
---|---|---|
widget | dijit/_WidgetBase |
1 2 3 4 5 6 | var btn = new 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); }); |
Called when a child widget gets focus, either by user clicking it, or programatically by arrow key handling code.
It marks that the current node is the selected one, and the previously selected node no longer is.
Parameter | Type | Description |
---|---|---|
child | dijit/_WidgetBase |
1 2 3 4 5 6 | var btn = new 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); }); |
Translates click events into commands for the controller to process
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
nodeWidget | Object | An object with the following properties:
|
||||||||||
e | Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Handler for when the container itself gets focus.
Initially the container itself has a tabIndex, but when it gets focus, switch focus to first child.
TODO for 2.0 (or earlier): Instead of having the container tabbable, always maintain a single child widget as tabbable, Requires code in startup(), addChild(), and removeChild(). That would avoid various issues like #17347.
Parameter | Type | Description |
---|---|---|
evt | undefined |
1 2 3 4 5 6 | var btn = new 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); }); |
When a key is pressed, if it's an arrow key etc. then it's handled here.
Parameter | Type | Description |
---|---|---|
evt | undefined |
1 2 3 4 5 6 | var btn = new 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); }); |
When a printable key is pressed, it's handled here, searching by letter.
Parameter | Type | Description |
---|---|---|
evt | undefined |
1 2 3 4 5 6 | var btn = new 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); }); |
Translates double-click events into commands for the controller to process
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
nodeWidget | Object | An object with the following properties:
|
||||||||||
e | Event |
1 2 3 4 5 6 | var btn = new 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); }); |
down arrow pressed; get next visible node, set focus there
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
evt | Event | |||||||||||
node | Object | An object with the following properties:
|
1 2 3 4 5 6 | var btn = new 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); }); |
User clicked the +/- icon; expand or collapse my children.
Parameter | Type | Description |
---|---|---|
message | Object |
1 2 3 4 5 6 | var btn = new 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); }); |
This is where widgets do processing for when they are active, such as changing CSS classes. See onFocus() for more details.
1 2 3 4 5 6 | var btn = new 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); }); |
Processes notification of a change to an item's scalar values like label
Parameter | Type | Description |
---|---|---|
item | Item |
1 2 3 4 5 6 | var btn = new 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); }); |
Processes notification of a change to an item's children
Parameter | Type | Description |
---|---|---|
parent | dojo/data/Item | |
newChildrenList | dojo/data/Item[] |
1 2 3 4 5 6 | var btn = new 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); }); |
Processes notification of a deletion of an item. Not called from new dojo.store interface but there's cleanup code in setChildItems() instead.
Parameter | Type | Description |
---|---|---|
item | Item |
1 2 3 4 5 6 | var btn = new 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); }); |
Left arrow pressed. If not collapsed, collapse, else move to parent.
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
evt | Event | |||||||||||
node | Object | An object with the following properties:
|
1 2 3 4 5 6 | var btn = new 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); }); |
Maps on() type parameter (ex: "mousemove") to method name (ex: "onMouseMove"). If type is a synthetic event like touch.press then returns undefined.
Parameter | Type | Description |
---|---|---|
type | String | Function |
1 2 3 4 5 6 | var btn = new 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); }); |
Called when mouse is over a node (onmouseenter event), this is monitored by the DND code
Parameter | Type | Description |
---|---|---|
node | dijit/_WidgetBase |
1 2 3 4 5 6 | var btn = new 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); }); |
Called when mouse leaves a node (onmouseleave event), this is monitored by the DND code
Parameter | Type | Description |
---|---|---|
node | dijit/_WidgetBase |
1 2 3 4 5 6 | var btn = new 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); }); |
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
nodeWidget | Object | An object with the following properties:
|
||||||||||
e | Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Right arrow pressed; go to child node
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
evt | Event | |||||||||||
node | Object | An object with the following properties:
|
1 2 3 4 5 6 | var btn = new 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); }); |
Internal method called when this widget is made visible.
See onShow
for details.
1 2 3 4 5 6 | var btn = new 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); }); |
Up arrow pressed; move to previous visible node
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
evt | Event | |||||||||||
node | Object | An object with the following properties:
|
1 2 3 4 5 6 | var btn = new 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); }); |
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 hidden.
1 2 3 4 5 6 | var btn = new 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); }); |
Callback when a tree node is clicked
Parameter | Type | Description |
---|---|---|
item | Object | Object from the dojo/store corresponding to this TreeNode |
node | Object | The TreeNode itself |
evt | Event | The event |
1 2 3 4 5 6 | var btn = new 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); }); |
Callback when a node is closed
Parameter | Type | Description |
---|---|---|
item | Object | Object from the dojo/store corresponding to this TreeNode |
node | Object | The TreeNode itself |
1 2 3 4 5 6 | var btn = new 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); }); |
Callback when a tree node is double-clicked
Parameter | Type | Description |
---|---|---|
item | Object | Object from the dojo/store corresponding to this TreeNode |
node | Object | The TreeNode itself |
evt | Event | The event |
1 2 3 4 5 6 | var btn = new 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); }); |
Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.
1 2 3 4 5 6 | var btn = new 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); }); |
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
.
1 2 3 4 5 6 | var btn = new 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); }); |
When a key is pressed that matches a child item, this method is called so that a widget can take appropriate action is necessary.
Parameter | Type | Description |
---|---|---|
item | dijit/_WidgetBase | |
evt | Event | |
searchString | String | |
numMatches | Number |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of keys being pressed down.
Parameter | Type | Description |
---|---|---|
event | undefined | key Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of printable keys being typed.
Parameter | Type | Description |
---|---|---|
event | undefined | key Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of keys being released.
Parameter | Type | Description |
---|---|---|
event | undefined | key Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Called when tree finishes loading and expanding.
If persist == true the loading may encompass many levels of fetches from the data store, each asynchronous. Waits for all to finish.
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse button is pressed down.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse moves onto this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse moves off of this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Connect to this function to receive notifications of when the mouse button is released.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
1 2 3 4 5 6 | var btn = new 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); }); |
Callback when a node is opened
Parameter | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
item | dojo/data/Item | |||||||||||
node | Object | An object with the following properties:
|
1 2 3 4 5 6 | var btn = new 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); }); |
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
.
1 2 3 4 5 6 | var btn = new 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); }); |