type: interaction
release: 1.5
status: refactor in planning/development
documentation: http://docs.jquery.com/UI/Selectable
demo: http://jqueryui.com/demos/selectable
in-progress refactor demo: http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/default.html
This interaction makes a set of items (descendants of a common container) mouse and keyboard selectable. A first attempt that only features mouse selecting (with some keyboard interaction) is already part of the current releases, documentation can be found here: http://docs.jquery.com/UI/Selectable
N/A
Selecting items basically can be done using the mouse only, keyboard only, or a combination of both. Since all OS file managers have differences in implementation, it's important to know about these differences and be able to judge them. For instance, some behavioral differences between Explorer(win)/Finder(mac) are simply bugs, and should be fixed by our implementation, while others need to be handled individually for different operating systems (i.e. using the apple/cmd key instead ctrl on mac).
Functional requirements / Specifications
To better understand how a selection works, you have to know that there are often multiple states an item can have. In our environment, only two states are really relevant (there's a third under the hood called latestWithoutModifier, but it's not really related to the actual experience):
The 'focus' works very similar to the focus web developers know. Only one item can be focused at the time, and it is always the current context item. For instance, if you click on a selectable item, it's not only selected but also focused. There are situations though when the focus is not connected to a selection: Try opening Windows Explorer, and then hold down the Control key + up/down to move the dotted outline around the items, then try a shift selection. You'll see that the focused item is the anchor for the new shift selection. Important to note is that OS X does not have the focus state (at least not exposed in any way).
Below are the different ways to select or unselect items in a selectable:
The drag problem
Every selectable implementation needs to be flexible enough to allow a selection to be dragged. However, a lot of detail in the implementation is actually required to make this possible - in fact it's so difficult that it seems that the OS X guys simply didn't manage to get it right. In OS X' Finder, you can of course drag items, but if you have multiple selected items, you cannot deselect them by clicking on one of those selected items (without holding modifiers). Let me explain to you why that is:
Both a selection and a drag are usually initiated on the 'mousedown' event. That means, as soon as you hold down your mouse button, the clicked item is selected. Since the order of events often can't be controlled, it means that without any special handling, the following would happen: With a selection of multiple items, you try to initiate a drag - the selectable though also listens for the mousedown, and handles it as click, therefore before the drag can happen, the other items around your selection are deselected. In order to prevent this, you must do the following: If you click on an item within a selection of multiple items, the selection action must occur on mouseup instead on mousedown. Linux/Windows get that right - OS X doesn't.
Functional changes of existing functionality in the refactor:
No significant features of the old selectable were removed during the refactor, meaning that everything can be achieved like before, but the style might be slightly different sometimes. See below the list of specific changes on existing functionality:
Options/Methods/Events
Used to retrieve what the selectable items are in the root element.
Disables or enables keyboard selection (this does not affect mouse+key combinations).
Disables or enables the lasso (can be optionally configured via hash).
distance (Integer | default: 1)
Only related to lasso. Specifies the distance needed to drag before a drag is initiated
delay (Integer | default: 0)
Only related to lasso. Specifies the delay in time needed before a drag is initiated.
cancel (Selector | default: ':input, option')
Only related to lasso. Doesn't allow to initiate the lasso on specific element types
tolerance ('touch', 'fit', 'intersect' | default: 'touch')
Only related to lasso. Specifies at what overlap the item is selected/deselected.
appendTo (String, Selector | default: 'body')
Only related to lasso. Determines to where the lasso is appended
Selects a specific item or multiple items. 'item' can be an index, a jQuery selector or DOM element.
If no second argument is passed, all items are deselected. If a second argument is passed, only the passed elements are deselected. 'item' can be an index, a jQuery selector or DOM element.
Refreshes the list of items. Must be called when new items are added to the list, or items have been removed.
Selects the next item.
Selects the previous item.
jQuery object that includes the current selected list of elements.
If items are unselected, this is the list of unselected items.
If items are being added to the selection, this is the list of added items.
lasso (Boolean, only for for mouse select events)
If a lasso is used to select elements, the 'select' event includes this boolean.
(Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )
(The HTML markup structure and classes that will be used by the scripts in the enhanced version)
(Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices)
(Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.)
Default (featuring nested):
http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/default.html
(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)
Some tests scenarios that should be written up into unit tests:
On http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/display-grid.html
1. Lasso from 1 to 2 (actual: selects 1 and 2)
2. Hold Ctrl
3. Ctrl+lasso from 4 to 5 (actual: focuses 4, selects 5. Expected: selects 4 and 5)
4. Ctrl+lasso from 7 to 8 (actual: focuses 7, selects 8. Expected: selects 7 and 8)
(Actual: 1, 2, 5, 8 selected. Expected: 1, 2, 4, 5, 7, 8 selected)
On http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/display-grid.html
1. Click 2 (actual: selects 2)
2. Hold Shift
3. Shift+click 5 (actual: selects 2-5)
4. Shift+click 8 (actual: selects 2-8)
5. Release Shift (actual: 2-8 selected)
On http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/display-grid.html
1. Click 2 (actual: selects 2)
2. Ctrl+down to 5 (actual: moves focus to 5 without selecting)
3. Ctrl+down to 8 (actual: moves focus to 8 without selecting)
4. Shift+space (actual: nothing happens. Expected: 2-8 selected)
This works with Ctrl+click on 2 followed by shift+click on 8. Same should work with keyboard only.
On http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/display-grid.html sequence
1. Click 1 (actual: selects 1)
2. Hold Ctrl
3. Ctrl+click 5 (actual: adds 5 to selection)
4. Ctrl+click 9 (actual: adds 9 to selection)
5. Release Ctrl (actual: 1, 5, 9 selected)
Bug:
If you use ctrl+arrows to move the selector, you can use ctrl+spacebar to toggle the selection of an element, but once you do, it locks up. You can no longer toggle selection nor ctrl+arrow navigate the cursor. This bug is present on FF3.5/win but not IE6/win
Bug:
Currently, clicking on a selectable element does not focus it.
A note from Maggie:
"For the selectable items, all state classes should be considered mutually exclusive - only one should be applied at a time. This includes the state classes for -hover, -active, and -focus."