Module Duplex.UIButtonStrip

The UIButtonStrip is an array of buttons that control an active index/range, especially useful for controlling a sequence with an a looped region.

In addition to the basic setrange() and setindex() methods, there's two additional methods, start/stop_blink(), which are used by the Matrix app to display that a pattern has been scheduled.

Usage

This control has a number of interaction modes:

  1. MODE_NORMAL - set range/index using button combinations

    In this mode, you set the index by pressing a button and releasing it, or set the range by pressing multiple buttons at the same time, and then releasing either.

    To toggle the range on/off, you press and hold a button for a moment, until the "button_held" event is triggered - this will toggle the range on/off (note that when turned on in this way, it's length is always one, as this length is otherwise unobtainable).

    Events

    • onindexchange
    • onrangechange

    Note: it is possible to return "false" to leave the index/range unchanged

    Supported input methods

    • "button"

  2. MODE_INDEX - togglebutton compatible mode, only index can be set

    Events

    • onindexchange

    Note: it is possible to return "false" to leave the index unchanged

    Supported input methods

    • "button"
    • "togglebutton"

  3. MODE_BASIC - free mode, supply your own logic

It's up to you to decide what happens when events are received

Events
- on_press(idx)
- on_release(idx)*
- on_hold(idx)*

* "togglebutton" not supported for this type of event

Supported input methods
- "button"
- "togglebutton"

Display logic

For color displays, it's possible to differentiate between the index and range

[ ] = Background
[x] = Selected index
[o] = Range

[x][o][o][o][ ][ ] <- Index set to 1, range set to 1,4
[o][o][x][o][ ][ ] <- Index set to 3, range set to 1,4
[o][o][o][o][ ][x] <- Index set to 6, range set to 1,4

For monochromatic devices / LED buttons, if the "index" color
is identical to the "range" color, the draw() method will use
an alternative/inverted color scheme:

[ ]     = Background
[x]/[ ] = Selected index
[x]     = Range

[ ][x][x][x][ ][ ] <- Index set to 1, range set to 1,4
[x][x][ ][x][ ][ ] <- Index set to 3, range set to 1,4
[ ][ ][x][ ][ ][ ] <- Index set to 3, range set to 3,3
[x][x][x][x][ ][x] <- Index set to 6, range set to 1,4

Functions

__init (app, map) Initialize the UIButtonStrip class
do_press (msg) User pressed a button
do_release (msg) User released a button
do_hold (msg) User held a button
draw () Update the appearance - inherited from UIComponent
set_index (idx, skip_event) Set the current index
get_index () Get the current index
set_range (idx1, idx2, skip_event) Set the current range (swap values if needed, first should be lowest)
get_range () Get the current range
_in_range (idx) Check if provided index is within the current range
set_steps (steps) Set the number of steps Will display the strip "stretched" along it's axis Sets the number of steps, in case the buttonstrip is larger than the number of steps it is controlling (like having 8 buttons to control 4 steps).
get_steps () Get the number of steps
start_blink (idx) Start blinking behaviour for one of the buttons
pause_blink () Pause blinking behaviour
stop_blink () Stop blinking behaviour
_toggle_blink () Toggle the control's blinking behaviour
set_orientation (value) Set the control's orientation
get_orientation () Get the orientation
set_size (size) Override UIComponent with this method
add_listeners ()

Add event listeners

DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.BUTTON_RELEASED
DEVICE_EVENT.BUTTON_HELD
remove_listeners () Remove previously attached event listeners
_determine_index_by_pos (column, row) Determine the control's index by it's position


Functions

__init (app, map)
Initialize the UIButtonStrip class

Parameters:

do_press (msg)
User pressed a button

Parameters:

Returns:

    self or nil if not handled
do_release (msg)
User released a button

Parameters:

Returns:

    self or nil if not handled
do_hold (msg)
User held a button

Parameters:

draw ()
Update the appearance - inherited from UIComponent

See also:

set_index (idx, skip_event)
Set the current index

Parameters:

  • idx (int) the index to set
  • skip_event (bool) if true, invoke the event handler
get_index ()
Get the current index

Returns:

    int
set_range (idx1, idx2, skip_event)
Set the current range (swap values if needed, first should be lowest)

Parameters:

  • idx1 (int) range 1
  • idx2 (int) range 2
  • skip_event (bool) if true, invoke the event handler
get_range ()
Get the current range

Returns:

    Table containing upper/lower index
_in_range (idx)
Check if provided index is within the current range

Parameters:

  • idx

Returns:

    bool
set_steps (steps)
Set the number of steps Will display the strip "stretched" along it's axis Sets the number of steps, in case the buttonstrip is larger than the number of steps it is controlling (like having 8 buttons to control 4 steps).

Parameters:

  • steps (int)
get_steps ()
Get the number of steps

Returns:

    int
start_blink (idx)
Start blinking behaviour for one of the buttons

Parameters:

  • idx (int) the button index
pause_blink ()
Pause blinking behaviour
stop_blink ()
Stop blinking behaviour
_toggle_blink ()
Toggle the control's blinking behaviour
set_orientation (value)
Set the control's orientation

Parameters:

get_orientation ()
Get the orientation

Returns:

    Duplex.Globals.ORIENTATION
set_size (size)
Override UIComponent with this method

Parameters:

  • size (int) the size in units

See also:

add_listeners ()

Add event listeners

DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.BUTTON_RELEASED
DEVICE_EVENT.BUTTON_HELD

See also:

remove_listeners ()
Remove previously attached event listeners

See also:

_determine_index_by_pos (column, row)
Determine the control's index by it's position

Parameters:

  • column (int)
  • row (int)

Returns:

    int
generated by LDoc 1.4.2