Selection

Selection

The Selection module adds selection capability to a list or grid. The resulting instance(s) will include a selection property representing the selected items. This mixin will also fire batched dgrid-select and dgrid-deselect events, which will possess a rows property containing an array of Row objects (with id, data, and element). For example:

require([
    "dojo/_base/declare", "dgrid/OnDemandGrid", "dgrid/Selection"
], function(declare, OnDemandGrid, Selection){
    var grid = declare([OnDemandGrid, Selection])({
        selectionMode: "single",
        // ...
    }, "grid");
    grid.on("dgrid-select", function(event){
        // Get the rows that were just selected
        var rows = event.rows;
        // ...
        
        // Iterate through all currently-selected items
        for(var id in grid.selection){
            if (grid.selection[id]) {
                // ...
            }
        }
    });
    grid.on("dgrid-deselect", function(event){
        // Get the rows that were just deselected
        var rows = event.rows;
        // ...
    });
});

APIs

The Selection mixin supports the following additional instance properties and methods.

Property Summary

Property	Description
selection	The object containing the IDs of the selected objects. The property names correspond to object ids and values are true or false depending on whether an item is selected.
selectionMode	String indicating the mode of selection. The following values are acceptable: extended (default setting; follows common ctrl and shift key practices for selection), single (only allows one row to be selected at a time), multiple- (similar to extended, but normal clicks add selection without removing previous selections), none (nothing can be selected by user interaction; only programmatic selection or selection via selectors is allowed).
allowTextSelection	Optional boolean indicating whether normal text selection within grid cells should be prevented. By default, text selection is prevented unless selectionMode is set to none; setting this property to true or false will enable or disable text selection regardless of selectionMode.
deselectOnRefresh	Determines whether calls to refresh (including sorts) also clear the current selection; true by default.
allowSelectAll	Determines whether the "select-all" action should be permitted via a checkbox selector column or the Ctrl/Cmd+A keyboard shortcut; defaults to false.

Method Summary

Method	Description
allowSelect(row)	Returns a boolean indicating whether the given row should be selectable; designed to be overridden.
select(row[, toRow])	Programmatically selects a row or range of rows.
deselect(row[, toRow])	Programmatically deselects a row or range of rows.
selectAll()	Programmatically selects all rows in the component. Note that only rows that have actually been loaded will be represented in the selection object.
clearSelection()	Programmatically deselects all rows in the component.
isSelected(row)	Returns true if the given row is selected.

Note: The select, deselect, and isSelected methods can be passed any type of argument acceptable to List's row method; see the List APIs for more information.

Events

As indicated above, the Selection mixin will emit two custom events:

• dgrid-select: Emitted when one or more rows are selected
• dgrid-deselect: Emitted when one or more rows are deselected

Note that this means that when a user interaction results in the selection being changed from one row to another, both events will be fired (with the dgrid-deselected event firing first).

Both of these events expose the following properties (note that rows is always an array, even if only one row was (de)selected.) :

• grid: The Grid (or List) instance in which the event occurred
• rows: Array containing any rows affected by the event
• parentType: If the event was triggered by user interaction, this property indicates what type of event originally triggered the event