controllerList

Description

Manages a list of elements. This list is used by other controllers and allows several controllers to work with a common list of elements. Apart from the list's members, the controller keeps track of focus and selection. The controller receives messages to update/add/remove items and change the current focus or selection. In all these cases, events are fired in order to notify the listening controllers for the changes.

Does not apply any transforms.

Parameters

Visit page Controller # Common Parameters for documentation on the parameters, common to all controllers: id, paused and disabled.

Parameters of list():

items

A string supplying where to take the list's items from. Currently, the only supported value is "children", which tells the controller that the items are this element's direct-child DOM nodes. Default value: "children"

circular

Tells if navigation of the list items is circular. If not, when trying to focus outside of the list rage, the current focus will not change and an event no_prev or no_next will be fired. Default value: true

select_multiple

Is simultaneous selection of multiple items allowed. If true, then this.selected = [selected_index, ...], else this.selected = single_selected_index (-1 if no item is selected). Default value: false

Accepted Messages

Visit page Controller # Common Messages for documentation on the messages, accepted by all controllers: pause, unpause, enable, disable, params and remove.

Messages accepted by list():

update

Order scanning the DOM tree in order to update the list. The controller fires an event update with parameters telling which items were added, and which - removed, from the list. Message params: none

reset

Initializes focus and selection variables. The first item in the list is focused and selection is emptied. Message params: none

insert

Inserts one or more elements in the list. Note that if these elements are not children of this element, they will be removed from the list upon the next update message. Message params: {pos: <index at which to insert>, items: [<reference to DOM element>, ...]}

remove

Removes one or more elements from the list. Note that if these elements are children of this element, they will be added again to the list upon the next update message. Message params: {pos: <first index>, length: <number of items to remove>}

focus_pos

Order focus of the item with index supplied in the message parameter pos. Message params: {pos: <index to focus>}

focus_step

Move the focus forwards or backwards with the supplied step. If the list is not circular and the focus index tries to go outside the list range, the controller fires the respective event - no_prev or no_next. Message params: {step: <number of items>}

focus_first, focus_last, focus_next, focus_prev

Order focus of the first, list, next or previous item, respectively. For messages focus_next and focus_prev, if the list is not circular and the focus index tries to go outside the list range, the controller fires the respective event - no_next or no_prev. Message params: none

select

Select the currently-focused item or the item with a supplied index if message_params.pos is present. Message params: {pos: <index to select>}

unselect

Unselect the currently-focused item or the item with a supplied index if message_params.pos is present. Message params: {pos: <index to unselect>}

Generated Events

Visit page Controller # Common Events for documentation on the events, generated by all controllers: frame, remove, paused, unpaused enabled and disabled.

Events fired by list():

update

Fired upon finishing the update (ordered with message update), no matter if the list actually changed. The event's parameters inserted and removed contain information about which items were added to, and which - removed from the list. Both are arrays of objects, where each object represents a block of elements with consequtive indexes in the list in the format:
Event params: {inserted: [<element_block>, ...], removed: [<element_block>, ...]}

reset

Fired upon message reset. Event params: none

focus

Fired upon changing focus (messages focus_xxx). The event's params contain information about which is the newly-focused item (param focused), and what is the step (i.e. new position relative to last position) of the focus (param step). Event params: {focused: <focused item index>, step: <size of focus change>}

select

Fired upon changing selection (messages select/unselect). The event's param selected contains the index of the newly-selected item (when the controller has its param select_multiple set to false), or an array of such indexes (when param select_multiple is true). Event params: {selected: <selected item index or [array of indexes]>}

first_reached

Fired upon focusing the first item. Event params: none

last_reached

Fired upon focusing the last item. Event params: none

border_left

Fired upon the focus moving from the first or last item to an item with an 'inner' index. Event params: none

no_prev

Fired upon trying to focus item with index less than 0 when the list is not circular. Event params: none

no_next

Fired upon trying to focus item with index higher than the last index when the list is not circular. Event params: none

Interaction with DOM

• Transforms: Does not apply any CSS transforms.
• CSS: Works with any styling. Does not set any style properties.
• Events: Does not set event listeners.

Changes Log

1. Controller introduced in v.0.80

See Also