Selection handling is offered by multiple widgets in qooxdoo such as lists or trees. They typically include the mixin MSelectionHandling offer several methods for handling selections both user input (through mouse and keyboard) actions and programmatically (through APIs).

On this page we will use a simple list to demonstrate the selection handling.

var list = new qx.ui.form.List;
var item;
for(var i=1; i<=10; i++)
{
  item = new qx.ui.form.ListItem("item " + i);
  list.add(item);
}

One can choose one of four different selection modes. The important difference between the types is that two types allow a selection to be a range of items and the other two allow only one item to be selected.

• single: Only one element or none at all can be selected.
• one: If possible always exactly one item is selected. The first item is selected per default.
• multi: Multiple items can be selected by using the modifier keys together with mouse or keyboard actions. This type also allows empty selections.
• adaptive: Easy Web-2.0 selection mode: multiple items can be selected without modifier keys. Empty selections are possible.

list.setSelectionMode("multi");

This options change the way a selection is created or modified. Per default items can be selected by holding down the mouse button and hovering them or by holding down the modifier key and pressing the arrow keys to traverse them.

• Quick: One item can be selected by hovering it (no need to click on it or hit keys) Only possible for modes single and one.
• Drag: Multiselection of items through dragging the mouse in pressed states. Only possible for the modes multi and additive.

list.setDragSelection(true);

A changeSelection (API Viewer) event is fired every time the selection was modified. It contains the selection under the data property.

list.addListener("changeSelection", function(e)
{
  var value = e.getData();
  alert("Your selection:\n" + value);
}, this);

• selectAll(): Adds all items to the selection. Only available in Multi and Addaptive selections.
• select(item): Selects the given item. Replaces current selection completely with the new item.
• selectRange(start, end): Selects a range from start to end.

// Select all items inside the list:
list.selectAll();
 
// Read all entries from list:
var children = list.getChildren();
 
// Replace the selection with the first item in list:
list.select(children[0]);
 
// Select both second and third item:
list.selectRange(children[1], children[2]);

• replaceSelection(range): Replaces current selection with the given items. Usefully for Adaptive selections, since the selection will be replaced by calling select() etc. anyway in other modes.

• getSelectedItem() returns the selected item (only for selection modes one and single).
• getSelection() returns an array containing the selected item(s).
• getSortedSelection() does the same as getSelection() but the items inside the array are sorted by the index in the container of the selection (the assigned widget).