Selectable


 

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

 

 


 

1 - Description:

 

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

 

 


 

2 - Visual Design:

 

N/A

 


 

 

3 - Functional Specifications/Requirements:

 

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

 

  1. selected
  2. focused

 

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

 


 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

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

 

     4.2 Recommended transformed HTML markup

 

     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 

 

     4.3 Accessibility recommendation

 

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

 

     4.4 CSS & Theme

 

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 


 

5 - Latest version of plugin:

 

Default (featuring nested): 

http://jquery-ui.googlecode.com/svn/branches/labs/selectable/demos/selectable/default.html

 


 

6 - Open issues being discussed

 

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