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 messageclick
). The supported messages arefocus_xxx
,select
andunselect
. Some of these messages require a message parameterpos
orstep
, which is set via the parameteraction_pos
oraction_step
, respectively. Default value: "" - action_pos
-
When the button's action (i.e. the message sent to the list) is
focus_pos
,select
orunselect
, then supply the required message parampos
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 paramstep
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 eventclick
,disable
- set the element'sdisabled
property totrue
, and set it tofalse
after a delay supplied via paramback_delay
,change_class
- add a styling class to the button (class name is supplied via paramalt_class
), and after a delay supplied via paramback_delay
remove the added class.
- when_no_progress
-
Tells what the button should do when the list fires an event
no_next
orno_prev
(fired when an attempt is made to focus outside the list range in the respective direction).
Note that when this button'saction
param is"focus_next"
, the button will react only tono_next
list events, and if the button'saction
param is"focus_prev"
, the button will react only tono_prev
list events.
Supply a string containing space-separated commands, where the following commands are supported:fire
- fire an eventno_progress
,disable
- set the element'sdisabled
property totrue
, and set it tofalse
after a delay supplied via paramback_delay
,change_class
- add a styling class to the button (class name is supplied via paramalt_class
), and after a delay supplied via paramback_delay
remove the added class.
- when_on_border
-
Tells what the button should do when the list fires an event
last_reached
,first_reached
orborder_left
(fired when the list's focus reaches or leaves the last/first item, respectively).
Note that when this button'saction
param is"focus_next"
, the button will react only tolast_reached
andborder_left
list events, and if the button'saction
param is"focus_prev"
, the button will react only tofirst_reached
andborder_left
list events.
Supply a string containing space-separated commands, where the following commands are supported:fire
- fire eventsborder_reached
andborder_left
,disable
- set the element'sdisabled
property totrue
when the border (i.e. first or last item) is reached, and set it tofalse
when the border is left,change_class
- add a styling class to the button (class name is supplied via paramalt_class
) when the border is reached, and remove the added class when the border is left.
- back_delay
-
Delay in milliseconds before the
disable
andchange_class
effects are undone afterclick
andno_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 thelistButton()
controller, the latter will not create its event listeners on the list. Send this message when thelist()
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 thewhen_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
andclassList
properties ifdisable
andchange_class
commands are present in thewhen_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 thelist()
controller.
Changes Log
- Controller introduced in v.0.80