Module Duplex.UISlider

The Slider supports different input methods: buttons or faders/dials.

Dial mode / fader mode

In most cases, you would specify a UISlider to take control of either a dial/encoder or fader. 

 _    _______
| |  |xxxx   | <- UISlider, mapped to horizontally aligned fader
| |   ¯¯¯¯¯¯¯  <- UISlider, mapped to vertically aligned fader
|x|   _
|x|  ( )       <- UISlider mapped to "dial"
 ¯    ¯

Specify an "on_change" function to handle events from the slider.

Button mode

In button mode, each value-step of the slider is assigned to a separate button. The size of the resulting slider is determined by the size you specify when creating the slider (or, by using the set_size() after the slider has been created). 

 _    _______
|_|  |x|x|x| | <- horizontally aligned UISlider (mapped to 4 buttons)
|_|   ¯¯¯¯¯¯¯  <- vertically aligned UISlider (mapped to 4 buttons)
|x|   _
|x|  | |       <- single-button UISlider (toggles min/max value)
 ¯    ¯
 _ _ _ _
|x|x|x|x|      <- two-dimensional UISlider, possible when
|x|x|_|_|         orientation is set to ORIENTATION.NONE
                  (minimum in upper-left, max in lower right corner)

To map a slider onto button(s), you must also specify an "on_press" event handler. The method does not have to do anything special, but without it, the slider will never receive any events from the device.

In "button mode", you also have an additional property called "toggleable". Setting this to true will enable you to toggle off any active button, and thus gain an extra value-step from any series of buttons.

Other features

  • Built-in quantize for MIDI devices (only output when values change)
  • Built-in support for relative encoder/dials. The actual type of relative encoder is specified in your control-map (see Duplex.Globals.PARAM_MODE)

Examples

Duplex comes with a sample configuration for the UISlider. Launch the duplex browser and choose Custombuilt > UISlider Demo

Changelog

0.99.5

- Added support for 14-bit CC and NRPN (absolute/relative modes)
- Encoder acceleration (amount specified in Duplex prefs)

0.99

- Got rid of "dimmed" method (just call set_palette instead)
- Support ORIENTATION.NONE for two-dimensional layout

Functions

__init (app, map) Initialize the UISlider class
do_press (msg) A button was pressed
do_change (msg) A value was changed (slider, dial) set index + precise value within the index
output_quantize (val, mode) Check if parameter-quantization is in force
set_value (val, skip_event) Set the value (will also update the index)
set_index (idx, skip_event) Set index (will also update the value)
set_orientation (value) Set the slider orientation (only relevant when assigned to buttons)
get_orientation () Get the orientation
set_size (size, opt) Override UIComponent with this method
test (msg) Expanded UIComponent test
draw () Update the appearance - inherited from UIComponent
set_pos (x, y) Set the position using x/y or index within group
add_listeners ()

Add event listeners

DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.VALUE_CHANGED
remove_listeners () Remove previously attached event listeners
_determine_index_by_pos (column, row) Determine index by position, depends on orientation
_invoke_handler () Trigger the external handler method
_detect_button_mode () Detect if the control is assigned to button widget(s)

Tables

palette default palette (only relevant for button mode)

Fields

self._button_mode (bool) this flag indicates that input method is a button
self.value current value, between 0 and .ceiling
self.steps (int), set the number of steps to quantize the value (this value is automatically set when we assign a size)
self.index (int) the selected index, between 0 - number of steps
self.toggleable (bool) if true, press twice to switch to deselected state only applies when input method is a button
self.flipped (bool) flip top/bottom direction
self._orientation slider is ORIENTATION.VERTICAL or ORIENTATION.HORIZONTAL?
self._size (int) the size in units (can be > 1 when input method is a button) (always call set_size() method to set this value)
self._cached_index internal values
self.slider_acceleration the amount of acceleration applied to relative motion


Functions

__init (app, map)
Initialize the UISlider class

Parameters:

do_press (msg)
A button was pressed

Parameters:

Returns:

    self or nil
do_change (msg)
A value was changed (slider, dial) set index + precise value within the index

Parameters:

Returns:

    self or nil
output_quantize (val, mode)
Check if parameter-quantization is in force

Parameters:

Returns:

    (bool) true when the message can pass, false when not
set_value (val, skip_event)
Set the value (will also update the index)

Parameters:

  • val (float), a number between 0 and .ceiling
  • skip_event (bool) skip event handler
set_index (idx, skip_event)
Set index (will also update the value)

Parameters:

  • idx (integer)
  • skip_event (bool) skip event handler
set_orientation (value)
Set the slider orientation (only relevant when assigned to buttons)

Parameters:

get_orientation ()
Get the orientation

Returns:

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

Parameters:

  • size (int)
  • opt (int), optional height (only when using ORIENTATION.NONE)

See also:

test (msg)
Expanded UIComponent test

Parameters:

Returns:

    bool, false when criteria is not met

See also:

draw ()
Update the appearance - inherited from UIComponent

See also:

set_pos (x, y)
Set the position using x/y or index within group

Parameters:

  • x
  • y

See also:

add_listeners ()

Add event listeners

DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.VALUE_CHANGED

See also:

remove_listeners ()
Remove previously attached event listeners

See also:

_determine_index_by_pos (column, row)
Determine index by position, depends on orientation

Parameters:

  • column (Number)
  • row (Number)
_invoke_handler ()
Trigger the external handler method

Returns:

    true when message was handled, false when not
_detect_button_mode ()
Detect if the control is assigned to button widget(s)

Tables

palette
default palette (only relevant for button mode)

Fields:

  • background The background color
  • tip The active point
  • track The track color

Fields

self._button_mode
(bool) this flag indicates that input method is a button
self.value
current value, between 0 and .ceiling
self.steps
(int), set the number of steps to quantize the value (this value is automatically set when we assign a size)
self.index
(int) the selected index, between 0 - number of steps
self.toggleable
(bool) if true, press twice to switch to deselected state only applies when input method is a button
self.flipped
(bool) flip top/bottom direction
self._orientation
slider is ORIENTATION.VERTICAL or ORIENTATION.HORIZONTAL? (use setorientation() method to set this value) self.orientation = ORIENTATION.VERTICAL
self._size
(int) the size in units (can be > 1 when input method is a button) (always call set_size() method to set this value)
self._cached_index
internal values
self.slider_acceleration
the amount of acceleration applied to relative motion
generated by LDoc 1.4.2