JSWindows (a JavaScript Inheritance Demo) Choices Class

© 15 Feb., 2013, Martin Rinehart

Overview

The Choices class creates and maintains a list where a single item in the list is chosen. Its first use is in the list of windows (or other Wobj objects) in a container. It may also find use in menus where one of a list of menu items is chosen.

A Choices is built from a list of choosable objects. An object is choosable if a user action can convert its state from "not chosen" to "chosen" (and back). Typically the change of state has a visual analog. A user selects a window in a container and the window is shown as the active window.

More precisely, an object is choosable if it implements the choosable interface: a single method, chosen that is called with a single, optional argument, a boolean indicating whether the object is chosen. obj.chosen() (or obj.chosen( true )) tells the object it is selected. The object changes its state to show the selection and makes whatever other changes are required (typically, actions can be performed when chosen that are not available otherwise). chosen( false ) tells the object to revert to the non-chosen state.

The Choices Constructor

A Choices maintains a list of choosable objects and an index number identifying the currently chosen object. The index is -1 if no object is chosen. You create a Choices with two arguments—the list and the index—both optional. (No index chooses the last list object; no list creates an empty list, index -1.)

var choices = new Choices( list, index );

To create a new Choices with specified objects, first object chosen:

var choices = new Choices( [tom, dick, harry], 0 );

To create a new Choices with last object chosen:

var choices = new Choices( [tom, dick, harry] );

To create a new, empty Choices:

var choices = new Choices();

Instance Methods

The add() Method

choices.add( new_choosable );

Adds the new choosable object at the end of the list, but leaves the existing selection intact.

The add_and_choose() Method

choices.add_and_choose( new_choosable );

Adds the new choosable object at the end of the list and "chooses" it.

The choose() Method

choices.choose( object )

Chooses the specified object. The object must be in the list.

The choose_last() Method

choices.choose_last()

Chooses the last object in the list.

The chosen() Method

chosen_obj = choices.chosen();

Returns the currently chosen object.

The del() Method

choices.del( object )

Deletes an object from the list. If the last object in the list had been chosen, the index is decremented and the new last object is chosen. Otherwise, the index is unchanged. (If the deletion comes before the formerly chosen object, this will change the chosen object. It does not change the position of the chosen object in the list.)

The find() Method

choices.find( object )

Used internally, given an object returns its position in the list (or -1 if not in the list).

The show_choices() Method

choices.show_choices()

Notifies each item in the list of its "chosen" or "not chosen" status. (This is the simple, and therefore compact, way of redisplaying the list. A more complex procedure that notified only the formerly chosen and the newly chosen objects could be implemented for very long lists.) As an object may be called repeatedly with obj.chosen( false ) you may wish to maintain a status and exit promptly if the chosen() method is non-trivial:

xxx.chosen = function( choose ) {
    if ( (choose === false) &&
         (this.chosen_status === false) ) {
        return;
    }
    ... non-trivial logic here

The show_choices() method is not called internally (as, for example, when choosing an item). It must be called or the change will not be visible.

The toString() Method

choices.toString()

A very compact report showing the list length and chosen index.

Feedback: MartinRinehart at gmail dot com

# # #