Module Duplex.UIComponent

UIComponent is the basic building block from which you create a user interface.

All classes that extend this class are prefixed with 'UI': UIButton, UISlider etc.

This class, and all the classes extending it, are not to be confused with the Renoise viewbuilder API, which creates actual on-screen controls. The virtual control surface (the on-screen representation of your hardware) is a static representation of the device interface, as defined by the control-map.

UIComponents, on the other hand, are a little more abstract. They can basically be created, moved around and resized while the application is running. Imagine creating an instance of a "UISlider" which you then assign a size of 8 vertical units, and assign to the middle of a Launchpad grid? For all that matters, you will think of this as being a slider, and operate it as such. But in reality, the slider is made from 8 different buttons that "know" about each other.

For examples on how to create/handle events with UIComponents, see either the UISlider or the UIButton class (both extensions of this class).

Changes

0.99.4

- Allow UIComponent instances to store last message in 'msg'
  (this is optional, but can improve things in the output stage)

0.99.3

- Refactored force_refresh method into base-class
- UIComponent:test() now include test for active state and group-name

0.99.2

- floor and ceiling for numeric values (UISlider, UIPad etc.)
- supply "map" argument when creating instance (saves typing)

0.98.17

- UIComponent event handlers should always return <code>false</code> when actively
  rejecting an event (such as when the application is sleeping/inactive),
  allowing the MIDI message to be passed on to Renoise

0.98.14

- Message now sent directly to the UIComponents

0.95

- When a UIComponent is resized, invalidate it
- When a UIComponent is resized to a smaller size, remove canvas-points by
  using an additional "clear" buffer from the Canvas class. The "clear" buffer
  is then applied during the next Display refresh

0.9

- First release

Functions

__init (app, map) Initialize the UIComponent class
invalidate () Request update on next refresh
draw () Update the control's visual appearance.
force_refresh () Force a complete update (redraw entire canvas on next update)
disable () Make associated viewbuilder widget(s) become inactive
enable () Make associated viewbuilder widget(s) become active
add_listeners () Attach listeners to the events (override this with your own implementation)
remove_listeners () Remove previously attached event listeners (override this with your own implementation)
set_size (width, height) Method to set the control's size in units - it is important to use this instead of setting width/height directly, as this method will resize Canvas
set_pos (x, y) Set the position using x/y or index within group
set_palette (palette) Set palette, invalidate if changed
set_group (group_name) Set the group that this component belongs to
test (msg) Perform simple "inside square" hit test
_get_widgets () Retrieve the viewbuilder widgets that we are associated with
_get_ui_params () Retrieve the control-map nodes that we are associated with
__eq (other) Compare with another instance (only check for object identity)
__tostring () Output the type of UIComponent

Tables

self.palette (table) default palette

Fields

self.canvas (Duplex.Canvas)
self.group_name (string) required, control-map group name
self.app (Duplex.Application) required, containing application
self.x_pos (int) position within display
self.floor (number) the minimum value for this component when a value is output to the device, this is used for scaling from our "local" value to the "external" one (only applies to components that output a numeric value)
self.ceiling (number) the maximum value for this component when a value is output to the device, this is used for scaling from our "local" value to the "external" one (only applies to components that output a numeric value)
self.width (int) internal width (always use set_size)
self.height (int) internal height (always use set_size)
self.tooltip (string) tooltip, displayed in the virtual UI
self.midi_mapping (string) link to a renoise midi-mapping - don't forget to register a similarly named mapping with renoise.tool():addmidimapping
self.dirty (bool) request refresh on next update
self.msg (bool) most recent message
self._active (bool) false if enabled state was changed - see (disable or (enable


Functions

__init (app, map)
Initialize the UIComponent class

Parameters:

invalidate ()
Request update on next refresh
draw ()
Update the control's visual appearance. We are not communicating directly with the device through this method, but rather perform modifications to the Canvas (which is translated into something the device can understand)
force_refresh ()
Force a complete update (redraw entire canvas on next update)
disable ()
Make associated viewbuilder widget(s) become inactive
enable ()
Make associated viewbuilder widget(s) become active
add_listeners ()
Attach listeners to the events (override this with your own implementation)
remove_listeners ()
Remove previously attached event listeners (override this with your own implementation)
set_size (width, height)
Method to set the control's size in units - it is important to use this instead of setting width/height directly, as this method will resize Canvas

Parameters:

  • width (int)
  • height (int)
set_pos (x, y)
Set the position using x/y or index within group

Parameters:

  • x (int)
  • y (int) optional, leave out to specify index via x parameter
set_palette (palette)
Set palette, invalidate if changed

Parameters:

  • palette (table), e.g {foreground={color={0x00,0x00,0x00}}}
set_group (group_name)
Set the group that this component belongs to

Parameters:

  • group_name (string)
test (msg)
Perform simple "inside square" hit test

Parameters:

Returns:

    (bool), true if inside area
_get_widgets ()
Retrieve the viewbuilder widgets that we are associated with

Returns:

    (table) renoise.Views.Control,...
_get_ui_params ()
Retrieve the control-map nodes that we are associated with

Returns:

    (table)
__eq (other)
Compare with another instance (only check for object identity)

Parameters:

Returns:

    bool
__tostring ()
Output the type of UIComponent

Returns:

    string

Tables

self.palette
(table) default palette

Fields

self.canvas
(Duplex.Canvas)
self.group_name
(string) required, control-map group name
self.app
(Duplex.Application) required, containing application
self.x_pos
(int) position within display
self.floor
(number) the minimum value for this component when a value is output to the device, this is used for scaling from our "local" value to the "external" one (only applies to components that output a numeric value)
self.ceiling
(number) the maximum value for this component when a value is output to the device, this is used for scaling from our "local" value to the "external" one (only applies to components that output a numeric value)
self.width
(int) internal width (always use set_size)
self.height
(int) internal height (always use set_size)
self.tooltip
(string) tooltip, displayed in the virtual UI
self.midi_mapping
(string) link to a renoise midi-mapping - don't forget to register a similarly named mapping with renoise.tool():addmidimapping
self.dirty
(bool) request refresh on next update
self.msg
(bool) most recent message
self._active
(bool) false if enabled state was changed - see (disable or (enable
generated by LDoc 1.4.2