dojox/widget/Selection (version 1.10)

dojo/Stateful

Summary

Base class for widgets that manage a list of selected data items.

Usage

var foo = new Selection();
dojox/widget/Selection

See the dojox/widget/Selection reference documentation for more information.

Property Summary

  • _attrPairNamesUsed across all instances a hash to cache attribute names and their getter and setter names.
  • selectedItemIn single selection mode, the selected item or in multiple selection mode the last selected item.
  • selectedItemsThe list of selected items.
  • selectionModeValid values are: "none": No selection can be done. "single": Only one item can be selected at a time. "multiple": Several item can be selected using the control key modifier.

Method Summary

Event Summary

  • onChange() Called when the selection changed.

Properties

_attrPairNames
Defined by: dojo/Stateful

Used across all instances a hash to cache attribute names and their getter and setter names.

selectedItem

In single selection mode, the selected item or in multiple selection mode the last selected item. Warning: Do not use this property directly, make sure to call set() or get() methods.

selectedItems

The list of selected items. Warning: Do not use this property directly, make sure to call set() or get() methods.

selectionMode

Valid values are:

  1. "none": No selection can be done.
  2. "single": Only one item can be selected at a time.
  3. "multiple": Several item can be selected using the control key modifier. Default value is "single".

Methods

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

_get(name,names)
Defined by dojo/Stateful

Private function that does a get based off a hash of names

Parameter Type Description
name undefined
names undefined

Hash of names of custom attributes

Returns:undefined
_getAttrNames(name)
Defined by dojo/Stateful

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
_getSelectedItemsAttr()
Returns:Array
_setSelectedItemAttr(value)
Parameter Type Description
value undefined
_setSelectedItemsAttr(value)
Parameter Type Description
value undefined
_setSelectionModeAttr(value)
Parameter Type Description
value undefined
dispatchChange(oldSelectedItem,newSelectedItem,renderer,triggerEvent)

Dispatch a selection change event.

Parameter Type Description
oldSelectedItem Object

The previously selectedItem.

newSelectedItem Object

The new selectedItem.

renderer Object

The visual renderer of the selected/deselected item.

triggerEvent Event

The event that lead to the selection of the item.

get(name)
Defined by dojo/Stateful

Get a property on a Stateful instance.

Get a named property on a Stateful object. The property may potentially be retrieved via a getter method in subclasses. In the base class this just retrieves the object's property.

Parameter Type Description
name String

The property to get.

Returns:any | undefined

The property value on this Stateful instance.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful({foo: 3});
    stateful.get("foo") // returns 3
    stateful.foo // returns 3
});
getIdentity(item)

This function must be implemented to return the id of a item.

Parameter Type Description
item Object

The item to query the identity for.

isItemSelected(item)

Returns whether an item is selected or not.

Parameter Type Description
item Object

The item to test the selection for.

Returns:boolean | undefined
postscript(params)
Defined by dojo/Stateful
Parameter Type Description
params Object
Optional
selectFromEvent(e,item,renderer,dispatch)

Applies selection triggered by an user interaction

Parameter Type Description
e Event

The source event of the user interaction.

item Object

The render item that has been selected/deselected.

renderer Object

The visual renderer of the selected/deselected item.

dispatch Boolean

Whether an event must be dispatched or not.

Returns:Boolean | boolean

Returns true if the selection has changed and false otherwise.

set(name,value)
Defined by dojo/Stateful

Set a property on a Stateful instance

Sets named properties on a stateful object and notifies any watchers of the property. A programmatic setter may be defined in subclasses.

Parameter Type Description
name String

The property to set.

value Object

The value to set in the property.

Returns:any | function

The function returns this dojo.Stateful instance.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex:

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

setItemSelected(item,value)

Change the selection state of an item.

Parameter Type Description
item Object

The item to change the selection state for.

value Boolean

True to select the item, false to deselect it.

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

onChange()

Called when the selection changed.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex:

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

Error in the documentation? Can’t find what you are looking for? Let us know!