Alien::GvaScript::ChoiceList(3)

NAME
Alien::GvaScript::ChoiceList - Dropdown list of choices with navigation

SYNOPSIS
  var choiceList = new GvaScript.ChoiceList(["foo", "bar", "buz"]);
  choiceList.fillContainer($('myChoiceDiv'));

DESCRIPTION
Displays a list of "choices", handles navigation in those choices, and generates events when a choice is highlighted, then selected, or when the list display is cancelled.

At any moment the choiceList is bound to maximum one "container", and highlights exactly one choice in the list.

BEHAVIOUR
Once a choice list is displayed, the user can move the mouse over the list, thus highlighting various choices; then click on the highlighted choice to select it. Alternatively, the user can navigate the list with keys "DOWN", "UP", "HOME", "END", and then use either "RETURN" (for selecting) or "ESCAPE" (for cancelling).

CONSTRUCTOR
  var choiceList = new GvaScript.ChoiceList(choices, options);

  Choices
The choice list must be an array. Each item in the list is either

a plain string
    this string will be displayed in the choice list

an inline object
    this object is supposed to have a "label" property, which will be displayed in the choice list. Actually, this is the default name for the property; it can be changed in the constructor options.

    The "label" property may contain rich HTML, i.e. including formatting tags.

  Options
The options to construct an choiceList object are :

labelField
    Name of the field that contains the HTML to display (default is "label").

idForChoices
    Prefix that will be used to generate ids for choice elements in the generated HTML. The default is "CL_choice", so choice elements will have ids "CL_choice.0", "CL_choice.1", etc.

keymap
    If defined, the choiceList will add rules to the supplied keymap, instead of creating a new one.

scrollCount
    How many items to skip when hitting the "PAGE_UP" or "PAGE_DOWN" keys. Default is 5

mouseovernavi
    Boolean indicating whether the choices would be selected/deselected with the mouseover event. Default is "true"

classes
    Classes that will be assigned to choice elements in the generated HTML. Possible classes are "choiceItem" (default value "CL_choiceItem") and "choiceHighlight" (default value "CL_highlight").

htmlWrapper
    Callback function for generating HTML for the choiceList. This function is called with some pre-built HTML containing all current choices; the wrapper has a chance to modify that HTML for example for adding classes, borders or table headers. Default is the identity function.

choiceItemTagName
    HTML tag name for generating a choice entry in the choice list. Default is "div". Set it to "tr" if you want the choice list to be displayed as a table (but then you also have to open and close the table within the "htmlWrapper" callback).

METHODS

  destroy
  choiceList.destroy();

This method removes all handlers attached to different events on the choice list container. Call this method when the choice list container is removed from the DOM.

  fillContainer
  choiceList.fillContainer(someDiv);

This method generates HTML from the choice list, and inserts it in the "innerHTML" of the supplied container; furthermore, it registers a keymap on that container in order to manage navigation from keyboard ("DOWN", "UP", etc.).

EVENTS

  onHighlight
This event is triggered when a choice in the list is highlighted. The event handler may use "event.index" to know the index of the highlighted choice.

  onPing
This event is triggered when a choice in the list is "ping-ed", i.e. either by clicking or by pressing the "RETURN" key. Usually this means "select", but it is up to the event handler to decide how to interpret the event. The event handler may use "event.index" to know the index of the ping-ed choice.

  onCancel
This event is triggered when the user presses the "ESCAPE" key.