controllerListButton


listButton(list, action, action_pos, action_step,
           when_clicked, when_no_progress, when_on_border,
           back_delay, alt_class)

listButton.messages = [update, click]
listButton.events   = [click, no_progress,
                       border_reached, border_left]

Description

Adds functionality to a button (or any element) that makes it behave as a commanding button to a supplied list() controller. The button, upon being clicked, sends a message supplied by parameter action to the list.

The parameters when_clicked, when_no_progress and when_on_border tell what should happen to the button when clicked or when the list's current focus reaches the list border or tries to pass it. In these cases, the listButton() controller can make the button element disabled, change its styling or fire an event that can be handled by other controllers (that will perform some hiding animation, for example).

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

list

A string supplying the controller ID of the source list of items, to which messages are sent and from which events are received. If the list() controller is attached on another element, then the string should contain the space-separated element's and controller's IDs:
list: "element_id list_id" Default value: ""

action

Message to send to the list() controller upon the button being clicked (or receiving message click). The supported messages are focus_xxx, select and unselect. Some of these messages require a message parameter pos or step, which is set via the parameter action_pos or action_step, respectively. Default value: ""

action_pos

When the button's action (i.e. the message sent to the list) is focus_pos, select or unselect, then supply the required message param pos here. Default value: -1

action_step

When the button's action (i.e. the message sent to the list) is focus_step, then supply the required message param step here. Default value: 0

when_clicked

Tells what the button should do when clicked, apart from sending the message to the list() controller. Supply a string containing space-separated commands, where the following commands are supported:

fire - fire an event click,
disable - set the element's disabled property to true, and set it to false after a delay supplied via param back_delay,
change_class - add a styling class to the button (class name is supplied via param alt_class), and after a delay supplied via param back_delay remove the added class.

Default value: "fire"

when_no_progress

Tells what the button should do when the list fires an event no_next or no_prev (fired when an attempt is made to focus outside the list range in the respective direction).
Note that when this button's action param is "focus_next", the button will react only to no_next list events, and if the button's action param is "focus_prev", the button will react only to no_prev list events.
Supply a string containing space-separated commands, where the following commands are supported:

fire - fire an event no_progress,
disable - set the element's disabled property to true, and set it to false after a delay supplied via param back_delay,
change_class - add a styling class to the button (class name is supplied via param alt_class), and after a delay supplied via param back_delay remove the added class.

Default value: "fire"

when_on_border

Tells what the button should do when the list fires an event last_reached, first_reached or border_left (fired when the list's focus reaches or leaves the last/first item, respectively).
Note that when this button's action param is "focus_next", the button will react only to last_reached and border_left list events, and if the button's action param is "focus_prev", the button will react only to first_reached and border_left list events.
Supply a string containing space-separated commands, where the following commands are supported:

fire - fire events border_reached and border_left,
disable - set the element's disabled property to true when the border (i.e. first or last item) is reached, and set it to false when the border is left,
change_class - add a styling class to the button (class name is supplied via param alt_class) when the border is reached, and remove the added class when the border is left.

Default value: "fire"

back_delay

Delay in milliseconds before the disable and change_class effects are undone after click and no_progress events. Default value: 200

alt_class

Name of a style class to be applied by the change_class command. Default value: ""

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

update: In the rare case when the list() controller is not created at the time of event-initializing of the listButton() controller, the latter will not create its event listeners on the list. Send this message when the list() controller is instantiated, to add the event listeners on it, effectively "linking" the button to the list. Message params: none
click: Tell the controller that the button is clicked. Message params: none

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

click: Fired upon the button being clicked or the controller receiving message click from the outside. The event is fired only if the when_clicked param contains the command "fire". Event params: none
no_progress: Fired when an attempt is made to focus outside the list items' range in either direction. The event is fired only if the when_no_progress param contains the command "fire". See the paramter's description for more details. Event params: none
border_reached: Fired when the focus reaches the first or last item in the list. The event is fired only if the when_on_border param contains the command "fire". See the paramter's description for more details. Event params: none
border_left: Fired when the focus leaves the first or last item in the list. The event is fired only if the when_on_border param contains the command "fire". See the paramter's description for more details. Event params: none

Interaction with DOM

Transforms: Does not apply any CSS transforms.
CSS: Works with any styling. Modifies the button element's disabled and classList properties if disable and change_class commands are present in the when_xxx controller parameters.
Events: Sets a DOM event listener for the click event on the button element, and also sets a behave3d listener for all events on the list() controller.

Changes Log

Controller introduced in v.0.80

controllerListButton

Description

Parameters

Accepted Messages

Generated Events

Interaction with DOM

Changes Log

See Also