dojox/form/MultiComboBox (version 1.10)

dijit/form/ValidationTextBox, dijit/form/ComboBoxMixin

Summary

A ComboBox that accepts multiple inputs on a single line

Usage

var foo = new MultiComboBox(params,srcNodeRef);
dijit/form/ValidationTextBox
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, replace srcNodeRef with my generated DOM tree.

See the dojox/form/MultiComboBox reference documentation for more information.

Property Summary

  • __skipInputEvent
  • _aroundNodeThe node to display the popup around.
  • _arrowWrapperNodeWill set CSS class dijitUpArrow, dijitDownArrow, dijitRightArrow etc. on this node depending on where the drop down is set to be positioned.
  • _attachEventsList of connections associated with data-dojo-attach-event=... in the template
  • _attachPointsList of widget attribute names associated with data-dojo-attach-point=... in the template, ex: ["containerNode", "labelNode"]
  • _attrPairNames
  • _blankGifPath to a blank 1x1 image.
  • _blankValue
  • _buttonInputDisabled
  • _buttonNodeThe button/icon/node to click to display the drop down.
  • _focusManager
  • _maskValidSubsetError
  • _onChangeActiveIndicates that changes to the value should call onChange() callback.
  • _popupStateNodeThe node to set the aria-expanded class on.
  • _previousMatches
  • _renderedNot 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.
  • _setClassAttr
  • _setDirAttr
  • _setIdAttr
  • _setLangAttr
  • _setTabIndexAttr
  • _setTypeAttr
  • _singleNodeTemplate
  • _skipNodeCache
  • _startedstartup() has completed.
  • _stopClickEventsWhen set to false, the click events will not be stopped, in case you want to use them in your subclass
  • activeTrue if mouse was pressed while over this widget, and hasn't been released yet
  • altCorresponds to the native HTML <input> element's attribute.
  • aria-label
  • attachScopeObject to which attach points and events will be scoped.
  • attributeMapDeprecated.
  • autoCompleteIf user types in a partial string, and then tab out of the <input> box, automatically copy the first entry displayed in the drop down list to the <input> field
  • autoWidthSet to true to make the drop down at least as wide as this widget.
  • baseClass
  • class
  • constraintsuser-defined object needed to pass parameters to the validator functions
  • containerNodeDesignates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes and widgets.
  • cssStateNodesSubclasses may define a cssStateNodes property that lists sub-nodes within the widget that need CSS classes applied on mouse hover/press and focus.
  • delimiterThe character to use to separate items in the ComboBox input
  • dirBi-directional support, as defined by the HTML DIR attribute.
  • disabledShould this widget respond to user input?
  • displayedValueFor subclasses like ComboBox where the displayed value (ex: Kentucky) and the serialized value (ex: KY) are different, this represents the displayed value.
  • domNodeThis is our visible representation of the widget!
  • dropDownThe widget to display as a popup.
  • dropDownPositionThis variable controls the position of the drop down.
  • fetchPropertiesMixin to the store's fetch.
  • focusedThis widget or a widget it contains has focus, or is "active" because it was recently clicked.
  • forceWidthSet to true to make the drop down exactly as wide as this widget.
  • hasDownArrowSet this textbox to have a down arrow button, to display the drop down list.
  • highlightMatchOne of: "first", "all" or "none".
  • hoveringTrue if cursor is over this widget
  • idA unique, opaque ID string that can be assigned by users or by the system.
  • ignoreCaseSet true if the query should ignore case when matching possible items
  • intermediateChangesFires onChange for each value change or only on demand
  • invalidMessageThe message to display if value is invalid.
  • itemThis is the item returned by the dojo/store/api/Store implementation that provides the data for this ComboBox, it's the currently selected item.
  • labelAttrThe entries in the drop down list come from this attribute in the dojo.data items.
  • labelTypeSpecifies how to interpret the labelAttr in the data store items.
  • langRarely used.
  • listAlternate to specifying a store.
  • lowercaseConverts all characters to lowercase if true.
  • maxHeightThe max height for our dropdown.
  • maxLengthHTML INPUT tag maxLength declaration.
  • messageCurrently error/prompt message.
  • missingMessageThe message to display if value is empty and the field is required.
  • nameName used when submitting form; same as "name" attribute or plain HTML elements
  • ownerDocumentThe document this widget belongs to.
  • pageSizeArgument to data provider.
  • patternThis defines the regular expression used to validate the input.
  • placeHolderDefines a hint to help users fill out the input field (as defined in HTML 5).
  • promptMessageIf defined, display this hint string immediately on focus to the textbox, if empty.
  • propercaseConverts the first character of each word to uppercase if true.
  • queryA query that can be passed to store to initially filter the items.
  • queryExprThis specifies what query is sent to the data store, based on what the user has typed.
  • readOnlyShould this widget respond to user input?
  • regExp
  • requiredUser is required to enter data into this field.
  • scrollOnFocusOn focus, should this widget scroll into view?
  • searchAttrSearch for items in the data store where this attribute (in the item) matches what the user typed
  • searchContainerNode
  • searchDelayDelay in milliseconds between when user types something and we start searching based on that value
  • selectOnClickIf true, all text will be selected when focused with mouse
  • srcNodeRefpointer to original DOM node
  • stateShows current state (ie, validation result) of input (""=Normal, Incomplete, or Error)
  • storeReference to data provider object used by this ComboBox.
  • styleHTML style attributes as cssText string or name/value hash
  • tabIndexOrder fields are traversed when user hits the tab key
  • templatePathPath to template (HTML file) for this widget relative to dojo.baseUrl.
  • templateString
  • titleHTML title attribute.
  • tooltipWhen 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.
  • tooltipPositionSee description of dijit/Tooltip.defaultPosition for details on this parameter.
  • trimRemoves leading and trailing whitespace if true.
  • typeCorresponds to the native HTML <input> element's attribute.
  • uppercaseConverts all characters to uppercase if true.
  • valueCorresponds to the native HTML <input> element's attribute.

Method Summary

  • _abortQuery()
  • _addPreviousMatches(text)
  • _announceOption(node) a11y code that puts the highlighted option in the textbox.
  • _applyAttributes() Step during widget creation to copy widget attributes to the DOM according to attributeMap and _setXXXAttr objects, and also to call custom _setXXXAttr() methods.
  • _attach(node,type,func) Roughly corresponding to dojo/on, this is the default function for processing a data-dojo-attach-event.
  • _attachTemplateNodes(rootNode) Iterate through the dom nodes and attach functions and nodes accordingly.
  • _attrToDom(attr,value,commands) Reflect a widget attribute (title, tabIndex, duration etc.) to the widget DOM, as specified by commands parameter.
  • _autoCompleteText(text)
  • _beforeFillContent()
  • _changeAttrValue(name,value) Internal helper for directly changing an attribute value.
  • _cleanupDelimiters(text)
  • _computeRegexp(constraints) Hook to get the current regExp and to compute the partial validation RE.
  • _cssMouseEvent(event) Handler for CSS event on this.domNode.
  • _deprecateRegExp(attr,value)
  • _detachTemplateNodes() Detach and clean up the attachments made in _attachtempalteNodes.
  • _escapeHtml(str)
  • _escapeValue(val) 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})
  • _fillContent(source) Relocate source contents to templated container node. this.containerNode must be able to receive children, or exceptions will be thrown.
  • _get(name) Helper function to get value for specified property stored by this._set(), i.e. for properties with custom setters.
  • _getAttrNames(name) Helper function for get() and set().
  • _getCaretPos(element)
  • _getDisplayedValueAttr() Hook so get('displayedValue') works.
  • _getMenuLabelFromItem(item)
  • _getValueAttr() Hook so get('value') works as we like.
  • _getValueField() Helper for postMixInProperties() to set this.value based on data inlined into the markup.
  • _handleOnChange(newValue,priorityChange) Called when the value of the widget is set.
  • _introspect() Collect metadata about this widget (only once per class, not once per instance): - list of attributes with custom setters, storing in this.constructor._setterAttrs - generate this.constructor._onMap, mapping names like "mousedown" to functions like onMouseDown
  • _isEmpty(value) Checks for whitespace
  • _isTextSelected()
  • _isValidSubset() Returns true if the value is either already valid or could be made valid by appending characters.
  • _layoutHackIE7() Work around table sizing bugs on IE7 by forcing redraw
  • _openResultList(results,query,options) Callback when a search completes.
  • _patternToRegExp(pattern) Helper function to convert a simple pattern to a regular expression for matching.
  • _processInput(evt) Default action handler for user input events
  • _processTemplateNode(baseNode,getAttrFunc,attachFunc) Process data-dojo-attach-point and data-dojo-attach-event for given node or widget.
  • _refreshState()
  • _selectOption(target) Menu callback function, called when an item in the menu is selected.
  • _set(name,value) Helper function to set new value for specified property, and call handlers registered with watch() if the value has changed.
  • _setBlurValue()
  • _setCaretPos(element,location)
  • _setConstraintsAttr(constraints)
  • _setDisabledAttr(value)
  • _setDisplayedValueAttr()
  • _setFocusedAttr(val)
  • _setHasDownArrowAttr(val)
  • _setItemAttr(item,priorityChange,displayedValue) Set the displayed valued in the input box, and the hidden value that gets submitted, based on a dojo.data store item.
  • _setListAttr(list)
  • _setMessageAttr(message)
  • _setOwnerDocumentAttr(val)
  • _setPatternAttr(pattern)
  • _setPlaceHolderAttr(v)
  • _setReadOnlyAttr(value)
  • _setRegExpAttr(value)
  • _setRegExpGenAttr(newFcn)
  • _setRequiredAttr(value)
  • _setStateClass() 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).
  • _setStoreAttr(store)
  • _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
  • _setValueAttr(value)
  • _showResultList()
  • _startSearch(text)
  • _startSearchAll()
  • _startSearchFromInput()
  • _stringRepl(tmpl) Does substitution of ${foo} type properties in template string
  • _subnodeCssMouseEvent(node,clazz,evt) Handler for hover/active mouse event on widget's subnode
  • _trackMouseState(node,clazz) Track mouse/focus events on specified node and set CSS class on that node to indicate current state.
  • _updatePlaceHolder()
  • attr(name,value) This method is deprecated, use get() or set() directly.
  • buildRendering() Construct the UI for this widget, setting this.domNode.
  • closeDropDown(focus) Closes the drop down on this widget
  • compare(val1,val2) Compare 2 values (as returned by get('value') for this widget).
  • connect(obj,event,method) Deprecated, will be removed in 2.0, use this.own(on(...)) or this.own(aspect.after(...)) instead.
  • create(params,srcNodeRef) Kick off the life-cycle of a widget
  • defer(fcn,delay) Wrapper to setTimeout to avoid deferred functions executing after the originating widget has been destroyed.
  • destroy()
  • destroyDescendants(preserveDom) Recursively destroy the children of this widget and their descendants.
  • destroyRecursive(preserveDom) Destroy this widget and its descendants
  • destroyRendering(preserveDom) Destroys the DOM nodes associated with this widget.
  • disconnect(handle) Deprecated, will be removed in 2.0, use handle.remove() instead.
  • displayMessage(message) Overridable method to display validation errors/hints.
  • doHighlight(label,find) Highlights the string entered by the user in the menu.
  • dropDownClass() Dropdown widget class used to select a date/time.
  • emit(type,eventObj,callbackArgs) Used by widgets to signal that a synthetic event occurred, ex: myWidget.emit("attrmodified-selectedChildWidget", {}).
  • filter(val) Auto-corrections (such as trimming) that are applied to textbox value on blur or form submit.
  • focus() Put focus on this widget
  • format(value,constraints) Replaceable function to convert a value to a properly formatted string.
  • get(name) Get a property from a widget.
  • getChildren() Returns all direct children of this widget, i.e. all widgets underneath this.containerNode whose parent is this widget.
  • getDescendants() Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode.
  • getDisplayedValue() Deprecated.
  • getErrorMessage(isFocused) Return an error message to show if appropriate
  • getParent() Returns the parent widget of this widget.
  • getPromptMessage(isFocused) Return a hint message to show when widget is first focused
  • getValue() Deprecated.
  • isFocusable() Return true if this widget can currently be focused and false if not
  • isLeftToRight() Return this widget's explicit or implicit orientation (true for LTR, false for RTL)
  • isLoaded() Returns true if the dropdown exists and it's data is loaded.
  • isValid(isFocused) Tests if value is valid.
  • labelFunc(item,store) Computes the label to display based on the dojo.data store item.
  • loadAndOpenDropDown() Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then opens the drop down.
  • loadDropDown(loadCallback) Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then calls the given callback.
  • on(type,func)
  • openDropDown() Opens the dropdown for this widget.
  • own() Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.
  • parse(value,constraints) Replaceable function to convert a formatted string to a value
  • placeAt(reference,position) Place this widget somewhere in the DOM based on standard domConstruct.place() conventions.
  • postCreate()
  • postMixInProperties()
  • postscript(params,srcNodeRef) Kicks off widget instantiation.
  • regExpGen(constraints) Deprecated.
  • reset()
  • set(name,value) Set a property on a widget
  • setAttribute(attr,value) Deprecated.
  • setDisabled(disabled) Deprecated.
  • setDisplayedValue(value) Deprecated.
  • setValue(value) Deprecated.
  • startup()
  • subscribe(t,method) Deprecated, will be removed in 2.0, use this.own(topic.subscribe()) instead.
  • toggleDropDown() Callback when the user presses the down arrow button or presses the down arrow key to open/close the drop down.
  • toString() Returns a string that represents the widget.
  • undo() Restore the value to the last value passed to onChange
  • uninitialize() Deprecated.
  • unsubscribe(handle) Deprecated, will be removed in 2.0, use handle.remove() instead.
  • validate(isFocused) Called by oninit, onblur, and onkeypress.
  • validator(value,constraints) Overridable function used to validate the text input against the regular expression.
  • watch(name,callback) Watches a property for changes

Event Summary

  • _onBlur()
  • _onDropDownClick(e)
  • _onDropDownMouseDown(e) Callback when the user mousedown/touchstart on the arrow icon.
  • _onDropDownMouseUp(e) Callback on mouseup/touchend after mousedown/touchstart on the arrow icon.
  • _onFocus(by)
  • _onInput(evt) Called AFTER the input event has happened See if the placeHolder text should be removed or added while editing.
  • _onKey(e) Callback when the user presses a key while focused on the button node
  • _onKeyUp()
  • _onMap(type) Maps on() type parameter (ex: "mousemove") to method name (ex: "onMouseMove").
  • _onShow() Internal method called when this widget is made visible.
  • onBlur() 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.
  • onChange(newValue) Callback when this widget's value is changed.
  • onClick(event) Connect to this function to receive notifications of mouse click events.
  • onClose() Called when this widget is being displayed as a popup (ex: a Calendar popped up from a DateTextBox), and it is hidden.
  • onDblClick(event) Connect to this function to receive notifications of mouse double click events.
  • onFocus() Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.
  • onHide() Called when another widget becomes the selected pane in a dijit/layout/TabContainer, dijit/layout/StackContainer, dijit/layout/AccordionContainer, etc.
  • onInput(event) Connect to this function to receive notifications of various user data-input events.
  • onKeyDown(event) Connect to this function to receive notifications of keys being pressed down.
  • onKeyPress(event) Connect to this function to receive notifications of printable keys being typed.
  • onKeyUp(event) Connect to this function to receive notifications of keys being released.
  • onMouseDown(event) Connect to this function to receive notifications of when the mouse button is pressed down.
  • onMouseEnter(event) Connect to this function to receive notifications of when the mouse moves onto this widget.
  • onMouseLeave(event) Connect to this function to receive notifications of when the mouse moves off of this widget.
  • onMouseMove(event) Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.
  • onMouseOut(event) Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.
  • onMouseOver(event) Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.
  • onMouseUp(event) Connect to this function to receive notifications of when the mouse button is released.
  • onSearch(results,query,options) Callback when a search completes.
  • onShow() Called when this widget becomes the selected pane in a dijit/layout/TabContainer, dijit/layout/StackContainer, dijit/layout/AccordionContainer, etc.

Properties

__skipInputEvent
_aroundNode
Defined by: dijit/_HasDropDown

The node to display the popup around. Can be set via a data-dojo-attach-point assignment. If missing, then domNode will be used.

_arrowWrapperNode
Defined by: dijit/_HasDropDown

Will set CSS class dijitUpArrow, dijitDownArrow, dijitRightArrow etc. on this node depending on where the drop down is set to be positioned. Can be set via a data-dojo-attach-point assignment. If missing, then _buttonNode will be used.

_attachEvents
Defined by: dijit/_AttachMixin

List of connections associated with data-dojo-attach-event=... in the template

_attachPoints
Defined by: dijit/_AttachMixin

List of widget attribute names associated with data-dojo-attach-point=... in the template, ex: ["containerNode", "labelNode"]

_attrPairNames
Defined by: dijit/_WidgetBase
_blankGif
Defined by: dijit/_WidgetBase

Path to a blank 1x1 image. Used by <img> nodes in templates that really get their image via CSS background-image.

_blankValue
_buttonInputDisabled
Defined by: dijit/form/TextBox
_buttonNode
Defined by: dijit/_HasDropDown

The button/icon/node to click to display the drop down. Can be set via a data-dojo-attach-point assignment. If missing, then either focusNode or domNode (if focusNode is also missing) will be used.

_focusManager
Defined by: dijit/_FocusMixin
_maskValidSubsetError
_onChangeActive

Indicates that changes to the value should call onChange() callback. This is false during widget initialization, to avoid calling onChange() when the initial value is set.

_popupStateNode
Defined by: dijit/_HasDropDown

The node to set the aria-expanded class on. Also sets popupActive class but that will be removed in 2.0. Can be set via a data-dojo-attach-point assignment. If missing, then focusNode or _buttonNode (if focusNode is missing) will be used.

_previousMatches
_rendered
Defined by: dijit/_TemplatedMixin

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.

_setClassAttr
Defined by: dijit/_WidgetBase
_setDirAttr
Defined by: dijit/_WidgetBase
_setIdAttr
Defined by: dijit/_WidgetBase
_setLangAttr
Defined by: dijit/_WidgetBase
_setTabIndexAttr
_setTypeAttr
Defined by: dijit/_WidgetBase
_singleNodeTemplate
Defined by: dijit/form/TextBox
_skipNodeCache
Defined by: dijit/_TemplatedMixin
_started
Defined by: dijit/_WidgetBase

startup() has completed.

_stopClickEvents
Defined by: dijit/_HasDropDown

When set to false, the click events will not be stopped, in case you want to use them in your subclass

active
Defined by: dijit/_CssStateMixin

True if mouse was pressed while over this widget, and hasn't been released yet

alt

Corresponds to the native HTML <input> element's attribute.

aria-label
attachScope
Defined by: dijit/_AttachMixin

Object to which attach points and events will be scoped. Defaults to 'this'.

attributeMap
Defined by: dijit/_WidgetBase

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:

  • string --> { node: string, type: "attribute" }, for example:
"focusNode" ---> { node: "focusNode", type: "attribute" }
  • "" --> { node: "domNode", type: "attribute" }
autoComplete

If user types in a partial string, and then tab out of the <input> box, automatically copy the first entry displayed in the drop down list to the <input> field

autoWidth
Defined by: dijit/_HasDropDown

Set to true to make the drop down at least as wide as this widget. Set to false if the drop down should just be its default width.

baseClass
Defined by: dijit/form/TextBox
class
Defined by: dijit/_WidgetBase
constraints

user-defined object needed to pass parameters to the validator functions

containerNode
Defined by: dijit/_WidgetBase

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:

<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:

<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.

cssStateNodes
Defined by: dijit/_CssStateMixin

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:

{
    "upArrowButton": "dijitUpArrowButton",
    "downArrowButton": "dijitDownArrowButton"
}

The above will set the CSS class dijitUpArrowButton to the this.upArrowButton DOMNode when it

is hovered, etc.

delimiter

The character to use to separate items in the ComboBox input

dir
Defined by: dijit/_WidgetBase

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.

disabled

Should this widget respond to user input? In markup, this is specified as "disabled='disabled'", or just "disabled".

displayedValue

For subclasses like ComboBox where the displayed value (ex: Kentucky) and the serialized value (ex: KY) are different, this represents the displayed value.

Setting 'displayedValue' through set('displayedValue', ...) updates 'value', and vice-versa. Otherwise 'value' is updated from 'displayedValue' periodically, like onBlur etc.

TODO: move declaration to MappedTextBox? Problem is that ComboBox references displayedValue, for benefit of FilteringSelect.

domNode
Defined by: dijit/_WidgetBase

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.

dropDown
Defined by: dijit/_HasDropDown

The widget to display as a popup. This widget must be defined before the startup function is called.

dropDownPosition
Defined by: dijit/_HasDropDown

This variable controls the position of the drop down. It's an array of strings with the following values:

  • before: places drop down to the left of the target node/widget, or to the right in the case of RTL scripts like Hebrew and Arabic
  • after: places drop down to the right of the target node/widget, or to the left in the case of RTL scripts like Hebrew and Arabic
  • above: drop down goes above target node
  • below: drop down goes below target node

The list is positions is tried, in order, until a position is found where the drop down fits within the viewport.

fetchProperties

Mixin to the store's fetch. For example, to set the sort order of the ComboBox menu, pass:

{ sort: [{attribute:"name",descending: true}] }

To override the default queryOptions so that deep=false, do:

{ queryOptions: {ignoreCase: true, deep: false} }
focused
Defined by: dijit/_FocusMixin

This widget or a widget it contains has focus, or is "active" because it was recently clicked.

forceWidth
Defined by: dijit/_HasDropDown

Set to true to make the drop down exactly as wide as this widget. Overrides autoWidth.

hasDownArrow

Set this textbox to have a down arrow button, to display the drop down list. Defaults to true.

highlightMatch

One of: "first", "all" or "none".

If the ComboBox/FilteringSelect opens with the search results and the searched string can be found, it will be highlighted. If set to "all" then will probably want to change queryExpr parameter to '${0}'

Highlighting is only performed when labelType is "text", so as to not interfere with any HTML markup an HTML label might contain.

hovering
Defined by: dijit/_CssStateMixin

True if cursor is over this widget

id
Defined by: dijit/_WidgetBase

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.

ignoreCase

Set true if the query should ignore case when matching possible items

intermediateChanges

Fires onChange for each value change or only on demand

invalidMessage

The message to display if value is invalid. The translated string value is read from the message file by default. Set to "" to use the promptMessage instead.

item

This is the item returned by the dojo/store/api/Store implementation that provides the data for this ComboBox, it's the currently selected item.

labelAttr

The entries in the drop down list come from this attribute in the dojo.data items. If not specified, the searchAttr attribute is used instead.

labelType

Specifies how to interpret the labelAttr in the data store items. Can be "html" or "text".

lang
Defined by: dijit/_WidgetBase

Rarely used. Overrides the default Dojo locale used to render this widget, as defined by the HTML LANG attribute. Value must be among the list of locales specified during by the Dojo bootstrap, formatted according to RFC 3066 (like en-us).

list

Alternate to specifying a store. Id of a dijit/form/DataList widget.

lowercase

Converts all characters to lowercase if true. Default is false.

maxHeight
Defined by: dijit/_HasDropDown

The max height for our dropdown. Any dropdown taller than this will have scrollbars. Set to 0 for no max height, or -1 to limit height to available space in viewport

maxLength

HTML INPUT tag maxLength declaration.

message

Currently error/prompt message. When using the default tooltip implementation, this will only be displayed when the field is focused.

missingMessage

The message to display if value is empty and the field is required. The translated string value is read from the message file by default. Set to "" to use the invalidMessage instead.

name

Name used when submitting form; same as "name" attribute or plain HTML elements

ownerDocument
Defined by: dijit/_WidgetBase

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

pageSize

Argument to data provider. Specifies maximum number of search results to return per query

pattern

This defines the regular expression used to validate the input. Do not add leading ^ or $ characters since the widget adds these. A function may be used to generate a valid pattern when dependent on constraints or other runtime factors. set('pattern', String|Function).

placeHolder

Defines a hint to help users fill out the input field (as defined in HTML 5). This should only contain plain text (no html markup).

promptMessage

If defined, display this hint string immediately on focus to the textbox, if empty. Also displays if the textbox value is Incomplete (not yet valid but will be with additional input). Think of this like a tooltip that tells the user what to do, not an error message that tells the user what they've done wrong.

Message disappears when user starts typing.

propercase

Converts the first character of each word to uppercase if true.

query

A query that can be passed to store to initially filter the items. ComboBox overwrites any reference to the searchAttr and sets it to the queryExpr with the user's input substituted.

queryExpr

This specifies what query is sent to the data store, based on what the user has typed. Changing this expression will modify whether the results are only exact matches, a "starting with" match, etc. ${0} will be substituted for the user text. * is used for wildcards. ${0}* means "starts with", *${0}* means "contains", ${0} means "is"

readOnly

Should this widget respond to user input? In markup, this is specified as "readOnly". Similar to disabled except readOnly form values are submitted.

regExp
required

User is required to enter data into this field.

scrollOnFocus

On focus, should this widget scroll into view?

searchAttr

Search for items in the data store where this attribute (in the item) matches what the user typed

searchContainerNode
Defined by: dijit/_TemplatedMixin
searchDelay

Delay in milliseconds between when user types something and we start searching based on that value

selectOnClick

If true, all text will be selected when focused with mouse

srcNodeRef
Defined by: dijit/_WidgetBase

pointer to original DOM node

state

Shows current state (ie, validation result) of input (""=Normal, Incomplete, or Error)

store

Reference to data provider object used by this ComboBox.

Should be dojo/store/api/Store, but dojo/data/api/Read supported for backwards compatibility.

style
Defined by: dijit/_WidgetBase

HTML style attributes as cssText string or name/value hash

tabIndex

Order fields are traversed when user hits the tab key

templatePath
Defined by: dijit/_TemplatedMixin

Path to template (HTML file) for this widget relative to dojo.baseUrl. Deprecated: use templateString with require([... "dojo/text!..."], ...) instead

templateString
title
Defined by: dijit/_WidgetBase

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.

tooltip
Defined by: dijit/_WidgetBase

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.

tooltipPosition

See description of dijit/Tooltip.defaultPosition for details on this parameter.

trim

Removes leading and trailing whitespace if true. Default is false.

type

Corresponds to the native HTML <input> element's attribute.

uppercase

Converts all characters to uppercase if true. Default is false.

value

Corresponds to the native HTML <input> element's attribute.

Methods

_abortQuery()
_addPreviousMatches(text)
Parameter Type Description
text String
Returns:undefined
_announceOption(node)

a11y code that puts the highlighted option in the textbox. This way screen readers will know what is happening in the menu.

Parameter Type Description
node Node
_applyAttributes()
Defined by dijit/_WidgetBase

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.

_attach(node,type,func)
Defined by dijit/_AttachMixin

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
Returns:undefined
_attachTemplateNodes(rootNode)
Defined by dijit/_AttachMixin

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:

  • dojoAttachPoint/data-dojo-attach-point
  • dojoAttachEvent/data-dojo-attach-event
Parameter Type Description
rootNode DomNode

The node to search for properties. All descendants will be searched.

_attrToDom(attr,value,commands)
Defined by dijit/_WidgetBase

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
_autoCompleteText(text)
Parameter Type Description
text String
_beforeFillContent()
Defined by dijit/_AttachMixin
_changeAttrValue(name,value)
Defined by dojo/Stateful

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.

Returns:function

Internal helper for directly changing an attribute value.

_cleanupDelimiters(text)
Parameter Type Description
text String
Returns:undefined
_computeRegexp(constraints)

Hook to get the current regExp and to compute the partial validation RE.

Parameter Type Description
constraints Object

An object with the following properties:

  • locale (String):

    locale used for validation, picks up value from this widget's lang attribute

  • _flags_ (anything):

    various flags passed to pattern function

Returns:undefined
_cssMouseEvent(event)

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
_deprecateRegExp(attr,value)
Parameter Type Description
attr undefined
value undefined
_detachTemplateNodes()
Defined by dijit/_AttachMixin

Detach and clean up the attachments made in _attachtempalteNodes.

_escapeHtml(str)
Parameter Type Description
str String
Returns:undefined
_escapeValue(val)

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
Returns:undefined
_fillContent(source)

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
_get(name)
Defined by dijit/_WidgetBase

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
Returns:undefined
_getAttrNames(name)
Defined by dijit/_WidgetBase

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:undefined | object
_getCaretPos(element)
Parameter Type Description
element DomNode
Returns:undefined
_getDisplayedValueAttr()

Hook so get('displayedValue') works.

Returns the displayed value (what the user sees on the screen), after filtering (ie, trimming spaces etc.).

For some subclasses of TextBox (like ComboBox), the displayed value is different from the serialized value that's actually sent to the server (see dijit/form/ValidationTextBox.serialize())

Returns:undefined
_getMenuLabelFromItem(item)
Parameter Type Description
item Item
Returns:object
_getValueAttr()

Hook so get('value') works as we like.

For dijit/form/TextBox this basically returns the value of the <input>.

For dijit/form/MappedTextBox subclasses, which have both a "displayed value" and a separate "submit value", This treats the "displayed value" as the master value, computing the submit value from it via this.parse().

Returns:undefined
_getValueField()

Helper for postMixInProperties() to set this.value based on data inlined into the markup. Returns the attribute name in the item (in dijit/form/_ComboBoxDataStore) to use as the value.

Returns:undefined
_handleOnChange(newValue,priorityChange)

Called when the value of the widget is set. Calls onChange() if appropriate

Parameter Type Description
newValue anything

the new value

priorityChange Boolean
Optional

For a slider, for example, dragging the slider is priorityChange==false, but on mouse up, it's priorityChange==true. If intermediateChanges==false, onChange is only called form priorityChange=true events.

_introspect()
Defined by dijit/_WidgetBase

Collect metadata about this widget (only once per class, not once per instance):

- list of attributes with custom setters, storing in this.constructor._setterAttrs
- generate this.constructor._onMap, mapping names like "mousedown" to functions like onMouseDown
_isEmpty(value)

Checks for whitespace

Parameter Type Description
value undefined
Returns:undefined
_isTextSelected()
Defined by dijit/form/TextBox
_isValidSubset()

Returns true if the value is either already valid or could be made valid by appending characters. This is used for validation while the user [may be] still typing.

Returns:boolean
_layoutHackIE7()

Work around table sizing bugs on IE7 by forcing redraw

_openResultList(results,query,options)

Callback when a search completes.

  1. generates drop-down list and calls _showResultList() to display it
  2. if this result list is from user pressing "more choices"/"previous choices" then tell screen reader to announce new option
Parameter Type Description
results Object
query Object
options Object
_patternToRegExp(pattern)

Helper function to convert a simple pattern to a regular expression for matching.

Returns a regular expression object that conforms to the defined conversion rules. For example:

  • ca -> /^ca.$/
  • ca -> /^.ca.$/
  • c\a -> /^.c*a.*$/
  • c\a? -> /^.c*a..*$/

and so on.

Parameter Type Description
pattern dojo/string

A simple matching pattern to convert that follows basic rules:

    • Means match anything, so ca* means match anything starting with ca
  • ? Means match single character. So, b?b will match to bob and bab, and so on.
  • \ is an escape character. So for example, * means do not treat as a match, but literal character .

To use a \ as a character in the string, it must be escaped. So in the pattern it should be represented by \ to be treated as an ordinary \ character instead of an escape.

Returns:instance
_processInput(evt)

Default action handler for user input events

Parameter Type Description
evt Event
_processTemplateNode(baseNode,getAttrFunc,attachFunc)
Defined by dijit/_AttachMixin

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.

Returns:boolean
_refreshState()
_selectOption(target)

Menu callback function, called when an item in the menu is selected.

Parameter Type Description
target DomNode
_set(name,value)
Defined by dijit/_WidgetBase

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
_setBlurValue()
_setCaretPos(element,location)
Parameter Type Description
element DomNode
location Number
_setConstraintsAttr(constraints)
Parameter Type Description
constraints Object

An object with the following properties:

  • locale (String):

    locale used for validation, picks up value from this widget's lang attribute

  • _flags_ (anything):

    various flags passed to pattern function

_setDisabledAttr(value)
Parameter Type Description
value Boolean
_setDisplayedValueAttr()
_setFocusedAttr(val)
Defined by dijit/_Widget
Parameter Type Description
val undefined
_setHasDownArrowAttr(val)
Parameter Type Description
val Boolean
_setItemAttr(item,priorityChange,displayedValue)

Set the displayed valued in the input box, and the hidden value that gets submitted, based on a dojo.data store item.

Users shouldn't call this function; they should be calling set('item', value)

Parameter Type Description
item item
priorityChange Boolean
Optional
displayedValue String
Optional
_setListAttr(list)
Parameter Type Description
list undefined
_setMessageAttr(message)
Parameter Type Description
message String
_setOwnerDocumentAttr(val)
Defined by dijit/_WidgetBase
Parameter Type Description
val undefined
_setPatternAttr(pattern)
Parameter Type Description
pattern String | Function
_setPlaceHolderAttr(v)
Defined by dijit/form/TextBox
Parameter Type Description
v undefined
_setReadOnlyAttr(value)
Parameter Type Description
value Boolean
_setRegExpAttr(value)
Parameter Type Description
value String
_setRegExpGenAttr(newFcn)
Parameter Type Description
newFcn Function
_setRequiredAttr(value)
Parameter Type Description
value Boolean
_setStateClass()

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:

  • Error - ValidationTextBox sets this.state to "Error" if the current input value is invalid
  • Incomplete - ValidationTextBox sets this.state to "Incomplete" if the current input value is not finished yet
  • Checked - ex: a checkmark or a ToggleButton in a checked state, will have this.checked==true
  • Selected - ex: currently selected tab will have this.selected==true

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):

  • Disabled - if the widget is disabled
  • Active - if the mouse (or space/enter key?) is being pressed down
  • Focused - if the widget has focus
  • Hover - if the mouse is over the widget
_setStoreAttr(store)
Parameter Type Description
store undefined
_setStyleAttr(value)
Defined by dijit/_WidgetBase

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
_setValueAttr(value)
Parameter Type Description
value undefined
_showResultList()
_startSearch(text)
Parameter Type Description
text String
_startSearchAll()
_startSearchFromInput()
_stringRepl(tmpl)

Does substitution of ${foo} type properties in template string

Parameter Type Description
tmpl undefined
Returns:undefined
_subnodeCssMouseEvent(node,clazz,evt)

Handler for hover/active mouse event on widget's subnode

Parameter Type Description
node undefined
clazz undefined
evt undefined
_trackMouseState(node,clazz)

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

  • fooActive: if the user is currently pressing down the mouse button while over the node
  • fooHover: if the user is hovering the mouse over the node, but not pressing down a button
  • fooFocus: if the node is focused

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)

_updatePlaceHolder()
Defined by dijit/form/TextBox
attr(name,value)
Defined by dijit/_Widget

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.

Returns:undefined
buildRendering()
Defined by dijit/_WidgetBase

Construct the UI for this widget, setting this.domNode. Most widgets will mixin dijit._TemplatedMixin, which implements this method.

closeDropDown(focus)
Defined by dijit/_HasDropDown

Closes the drop down on this widget

Parameter Type Description
focus Boolean

If true, refocuses the button widget

compare(val1,val2)

Compare 2 values (as returned by get('value') for this widget).

Parameter Type Description
val1 anything
val2 anything
Returns:number
connect(obj,event,method)
Defined by dijit/_WidgetBase

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
Returns:any | undefined

A handle that can be passed to disconnect in order to disconnect before the widget is destroyed.

Examples

Example 1

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());
});
create(params,srcNodeRef)
Defined by dijit/_WidgetBase

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:

  • 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
defer(fcn,delay)
Defined by dijit/_WidgetBase

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.

Returns:object
destroy()
destroyDescendants(preserveDom)
Defined by dijit/_WidgetBase

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.

destroyRecursive(preserveDom)
Defined by dijit/_WidgetBase

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.

Parameter Type Description
preserveDom Boolean
Optional

If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._TemplatedMixin widgets.

destroyRendering(preserveDom)
Defined by dijit/_WidgetBase

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.

disconnect(handle)
Defined by dijit/_WidgetBase

Deprecated, will be removed in 2.0, use handle.remove() instead.

Disconnects handle created by connect.

Parameter Type Description
handle undefined
displayMessage(message)

Overridable method to display validation errors/hints. By default uses a tooltip.

Parameter Type Description
message String
doHighlight(label,find)

Highlights the string entered by the user in the menu. By default this highlights the first occurrence found. Override this method to implement your custom highlighting.

Parameter Type Description
label String
find String
Returns:undefined
dropDownClass()

Dropdown widget class used to select a date/time. Subclasses should specify this.

emit(type,eventObj,callbackArgs)
Defined by dijit/_WidgetBase

Used by widgets to signal that a synthetic event occurred, ex:

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
Returns:undefined
filter(val)

Auto-corrections (such as trimming) that are applied to textbox value on blur or form submit.

For MappedTextBox subclasses, this is called twice

  • once with the display value
  • once the value as set/returned by set('value', ...)

and get('value'), ex: a Number for NumberTextBox.

In the latter case it does corrections like converting null to NaN. In the former case the NumberTextBox.filter() method calls this.inherited() to execute standard trimming code in TextBox.filter().

TODO: break this into two methods in 2.0

Parameter Type Description
val undefined
Returns:undefined
focus()

Put focus on this widget

format(value,constraints)

Replaceable function to convert a value to a properly formatted string.

Parameter Type Description
value String
constraints Object
Returns:string
get(name)
Defined by dijit/_WidgetBase

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:undefined
getChildren()
Defined by dijit/_WidgetBase

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:Array
getDescendants()
Defined by dijit/_Widget

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:Array
getDisplayedValue()
Defined by dijit/form/TextBox

Deprecated. Use get('displayedValue') instead.

Returns:undefined
getErrorMessage(isFocused)

Return an error message to show if appropriate

Parameter Type Description
isFocused Boolean
Returns:undefined
getParent()
Defined by dijit/_WidgetBase

Returns the parent widget of this widget.

Returns:undefined
getPromptMessage(isFocused)

Return a hint message to show when widget is first focused

Parameter Type Description
isFocused Boolean
Returns:undefined
getValue()

Deprecated. Use get('value') instead.

Returns:undefined
isFocusable()
Defined by dijit/_WidgetBase

Return true if this widget can currently be focused and false if not

Returns:undefined
isLeftToRight()
Defined by dijit/_WidgetBase

Return this widget's explicit or implicit orientation (true for LTR, false for RTL)

Returns:undefined
isLoaded()
Defined by dijit/_HasDropDown

Returns true if the dropdown exists and it's data is loaded. This can be overridden in order to force a call to loadDropDown().

Returns:boolean
isValid(isFocused)

Tests if value is valid. Can override with your own routine in a subclass.

Parameter Type Description
isFocused Boolean
Returns:undefined
labelFunc(item,store)

Computes the label to display based on the dojo.data store item.

Parameter Type Description
item Object

The item from the store

store dojo/store/api/Store

The store.

Returns:any | undefined

The label that the ComboBox should display

loadAndOpenDropDown()
Defined by dijit/_HasDropDown

Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then opens the drop down. This is basically a callback when the user presses the down arrow button to open the drop down.

Returns:Deferred | instance

Deferred for the drop down widget that fires when drop down is created and loaded

loadDropDown(loadCallback)
Defined by dijit/_HasDropDown

Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then calls the given callback.

Parameter Type Description
loadCallback Function
on(type,func)
Defined by dijit/_Widget
Parameter Type Description
type String | Function

protected

func Function
Returns:undefined
openDropDown()
Defined by dijit/_HasDropDown

Opens the dropdown for this widget. To be called only when this.dropDown has been created and is ready to display (ie, it's data is loaded).

Returns:any | undefined

return value of dijit/popup.open()

own()
Defined by dijit/Destroyable

Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.

Returns:any | undefined

The array of specified handles, so you can do for example:

var handle = this.own(on(...))[0];
parse(value,constraints)

Replaceable function to convert a formatted string to a value

Parameter Type Description
value String
constraints Object
Returns:String
placeAt(reference,position)
Defined by dijit/_WidgetBase

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().

Returns:dijit/_WidgetBase | function

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.

Examples

Example 1

// 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'); }));

Example 2

// create a button out of a node with id="src" and append it to id="wrapper":
var button = new Button({},"src").placeAt("wrapper");

Example 3

// place a new button as the first element of some div
var button = new Button({ label:"click" }).placeAt("wrapper","first");

Example 4

// create a contentpane and add it to a TabContainer
var tc = dijit.byId("myTabs");
new ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)
postCreate()
Defined by dijit/form/TextBox
postMixInProperties()
postscript(params,srcNodeRef)
Defined by dijit/_WidgetBase

Kicks off widget instantiation. See create() for details.

Parameter Type Description
params Object
Optional
srcNodeRef DomNode | String
regExpGen(constraints)

Deprecated. Use set('pattern', Function) instead.

Parameter Type Description
constraints Object

An object with the following properties:

  • locale (String):

    locale used for validation, picks up value from this widget's lang attribute

  • _flags_ (anything):

    various flags passed to pattern function

reset()
set(name,value)
Defined by dijit/_WidgetBase

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:

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.

Returns:function | string

Set a property on a widget

setAttribute(attr,value)
Defined by dijit/_Widget

Deprecated. Use set() instead.

Parameter Type Description
attr String
value anything
setDisabled(disabled)

Deprecated. Use set('disabled', ...) instead.

Parameter Type Description
disabled Boolean
setDisplayedValue(value)
Defined by dijit/form/TextBox

Deprecated. Use set('displayedValue', ...) instead.

Parameter Type Description
value String
setValue(value)

Deprecated. Use set('value', ...) instead.

Parameter Type Description
value String
startup()
subscribe(t,method)
Defined by dijit/_WidgetBase

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

Returns:undefined

Examples

Example 1

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);
});
toggleDropDown()
Defined by dijit/_HasDropDown

Callback when the user presses the down arrow button or presses the down arrow key to open/close the drop down. Toggle the drop-down widget; if it is up, close it, if not, open it

toString()
Defined by dijit/_WidgetBase

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
undo()

Restore the value to the last value passed to onChange

uninitialize()
Defined by dijit/_WidgetBase

Deprecated. Override destroy() instead to implement custom widget tear-down behavior.

Returns:boolean
unsubscribe(handle)
Defined by dijit/_WidgetBase

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
validate(isFocused)

Called by oninit, onblur, and onkeypress.

Show missing or invalid messages if appropriate, and highlight textbox field.

Parameter Type Description
isFocused Boolean
Returns:undefined
validator(value,constraints)

Overridable function used to validate the text input against the regular expression.

Parameter Type Description
value anything
constraints Object

An object with the following properties:

  • locale (String):

    locale used for validation, picks up value from this widget's lang attribute

  • _flags_ (anything):

    various flags passed to pattern function

Returns:undefined
watch(name,callback)
Defined by dojo/Stateful

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.

Returns:any | object

An object handle for the watch. The unwatch method of this object can be used to discontinue watching this property:

var watchHandle = obj.watch("foo", callback);
watchHandle.unwatch(); // callback won't be called now

Events

_onBlur()

Examples

Example 1

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);
});
_onDropDownClick(e)
Defined by: dijit/_HasDropDown
Parameter Type Description
e Event

Examples

Example 1

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);
});
_onDropDownMouseDown(e)
Defined by: dijit/_HasDropDown

Callback when the user mousedown/touchstart on the arrow icon.

Parameter Type Description
e Event

Examples

Example 1

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);
});
_onDropDownMouseUp(e)
Defined by: dijit/_HasDropDown

Callback on mouseup/touchend after mousedown/touchstart on the arrow icon. Note that this function is called regardless of what node the event occurred on (but only after a mousedown/touchstart on the arrow).

If the drop down is a simple menu and the cursor is over the menu, we execute it, otherwise, we focus our drop down widget. If the event is missing, then we are not a mouseup event.

This is useful for the common mouse movement pattern with native browser <select> nodes:

  1. mouse down on the select node (probably on the arrow)
  2. move mouse to a menu item while holding down the mouse button
  3. mouse up. this selects the menu item as though the user had clicked it.
Parameter Type Description
e Event
Optional

Examples

Example 1

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);
});
_onFocus(by)
Defined by: dijit/form/TextBox
Parameter Type Description
by String

Examples

Example 1

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);
});
_onInput(evt)
Defined by: dijit/form/TextBox

Called AFTER the input event has happened See if the placeHolder text should be removed or added while editing.

Parameter Type Description
evt Event

Examples

Example 1

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);
});
_onKey(e)
Defined by: dijit/_HasDropDown

Callback when the user presses a key while focused on the button node

Parameter Type Description
e Event

Examples

Example 1

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);
});
_onKeyUp()
Defined by: dijit/_HasDropDown

Examples

Example 1

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);
});
_onMap(type)
Defined by: dijit/_WidgetBase

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
Returns:undefined

Examples

Example 1

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);
});
_onShow()
Defined by: dijit/_Widget

Internal method called when this widget is made visible. See onShow for details.

Examples

Example 1

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);
});
onBlur()
Defined by: dijit/_FocusMixin

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.

Examples

Example 1

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);
});
onChange(newValue)

Callback when this widget's value is changed.

Parameter Type Description
newValue undefined

Examples

Example 1

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);
});
onClick(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of mouse click events.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onClose()
Defined by: dijit/_Widget

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

Examples

Example 1

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);
});
onDblClick(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of mouse double click events.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onFocus()
Defined by: dijit/_FocusMixin

Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.

Examples

Example 1

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);
});
onHide()
Defined by: dijit/_Widget

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.

Examples

Example 1

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);
});
onInput(event)

Connect to this function to receive notifications of various user data-input events. Return false to cancel the event and prevent it from being processed.

Parameter Type Description
event undefined

keydown | keypress | cut | paste | input

Examples

Example 1

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);
});
onKeyDown(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of keys being pressed down.

Parameter Type Description
event undefined

key Event

Examples

Example 1

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);
});
onKeyPress(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of printable keys being typed.

Parameter Type Description
event undefined

key Event

Examples

Example 1

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);
});
onKeyUp(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of keys being released.

Parameter Type Description
event undefined

key Event

Examples

Example 1

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);
});
onMouseDown(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of when the mouse button is pressed down.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onMouseEnter(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of when the mouse moves onto this widget.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onMouseLeave(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of when the mouse moves off of this widget.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onMouseMove(event)
Defined by: dijit/_Widget

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

Examples

Example 1

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);
});
onMouseOut(event)
Defined by: dijit/_Widget

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

Examples

Example 1

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);
});
onMouseOver(event)
Defined by: dijit/_Widget

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

Examples

Example 1

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);
});
onMouseUp(event)
Defined by: dijit/_Widget

Connect to this function to receive notifications of when the mouse button is released.

Parameter Type Description
event undefined

mouse Event

Examples

Example 1

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);
});
onSearch(results,query,options)

Callback when a search completes.

Parameter Type Description
results Object

An array of items from the originating _SearchMixin's store.

query Object

A copy of the originating _SearchMixin's query property.

options Object

The additional parameters sent to the originating _SearchMixin's store, including: start, count, queryOptions.

Examples

Example 1

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);
});
onShow()
Defined by: dijit/_Widget

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.

Examples

Example 1

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);
});
Error in the documentation? Can’t find what you are looking for? Let us know!