UI API
Overviewβ
MatrixOS.UI exposes common Matrix OS UI utilities and components to Python.
Selector Constantsβ
Direction constants:
DIRECTION_RIGHT_THEN_DOWNDIRECTION_DOWN_THEN_RIGHTDIRECTION_LEFT_THEN_DOWNDIRECTION_DOWN_THEN_LEFTDIRECTION_UP_THEN_RIGHTDIRECTION_RIGHT_THEN_UPDIRECTION_UP_THEN_LEFTDIRECTION_LEFT_THEN_UP
Lit mode constants:
LIT_EQUALLIT_LESS_EQUAL_THANLIT_GREATER_EQUAL_THANLIT_ALWAYS
Utility Methodsβ
MatrixOS.UI.text_scrollβ
text_scroll(text: str, color: ColorLike, speed: int = 10, loop: bool = False) -> None
Shows scrolling text.
Parameters:
text: Text to show.color: Packed RGB integer, RGB tuple, or RGBW tuple.speed: Scroll speed.loop: Whether the scroll should loop.
MatrixOS.UI.color_pickerβ
color_picker(color: ColorLike, shade: bool = True) -> int | None
Opens the Matrix OS color picker.
Parameters:
color: Initial color.shade: Whether to show shade controls.
Returns:
int | None: Packed RGB color when confirmed, orNonewhen cancelled.
MatrixOS.UI.number_selectorβ
number_selector(value: int, color: ColorLike, name: str, lower_limit: int = INT_MIN, upper_limit: int = INT_MAX) -> int
Opens a number selector.
Parameters:
value: Initial value.color: UI color.name: Label shown by the selector.lower_limit: Minimum value.upper_limit: Maximum value.
Returns:
int: Selected value.
MatrixOS.UI.UIβ
MatrixOS.UI.UI(name: str = "", color: ColorLike = MatrixOS.Color(255, 255, 255), new_layer: bool = True)
Creates a UI container.
Parameters:
name: UI name.color: UI accent color.new_layer: Whether the UI should create a new LED layer.
ui.startβ
start() -> None
Starts the UI and returns after the UI exits.
ui.exitβ
exit() -> None
Requests the UI to exit.
ui.closeβ
close() -> bool
Releases the native UI object and attached components.
Returns:
bool:Truewhen closed.
ui.set_nameβ
set_name(name: str) -> None
Sets the UI name.
ui.set_colorβ
set_color(color: ColorLike) -> None
Sets the UI accent color.
ui.set_new_layerβ
set_new_layer(create: bool) -> None
Controls whether the UI creates a new LED layer.
ui.allow_exitβ
allow_exit(allow: bool) -> None
Controls whether the user can exit the UI.
ui.set_fpsβ
set_fps(fps: int) -> None
Sets the UI frame rate.
ui.addβ
add(component, position: tuple[int, int]) -> None
Adds a component at a position.
Parameters:
component:Button,Selector,Number,Toggle, orCustomComponent.position: Component origin(x, y).
ui.clearβ
clear() -> None
Removes all components from the UI.
ui.set_setup_funcβ
set_setup_func(callback) -> None
Sets a callback called when the UI starts. The callback receives no arguments.
ui.set_loop_funcβ
set_loop_func(callback) -> None
Sets a UI loop callback. The callback receives no arguments.
ui.set_global_loop_funcβ
set_global_loop_func(callback) -> None
Sets a global loop callback. The callback receives no arguments.
ui.set_pre_render_funcβ
set_pre_render_func(callback) -> None
Sets a callback called before rendering. The callback receives no arguments.
ui.set_post_render_funcβ
set_post_render_func(callback) -> None
Sets a callback called after rendering. The callback receives no arguments.
ui.set_end_funcβ
set_end_func(callback) -> None
Sets a callback called when the UI ends. The callback receives no arguments.
ui.set_input_handlerβ
set_input_handler(callback) -> None
Sets a callback for input events.
Callback:
- Called as
callback(event). - Return a truthy value to consume the event.
Simple Settings UIβ
import MatrixOS
KEY_SPEED = "HelloPython speed"
# Create a modal settings UI on its own LED layer.
settings = MatrixOS.UI.UI("Settings", (0, 255, 255), True)
# An 8x1 selector gives one row of speed choices.
selector = MatrixOS.UI.Selector((8, 1), 8)
selector.set_name("Speed")
selector.set_color((0, 255, 255))
# Restore the last saved value, or use 3 the first time.
selector.set_value(MatrixOS.NVS.get(KEY_SPEED, 3))
def save_speed(value):
# Persist changes immediately when the selector changes.
MatrixOS.NVS.set(KEY_SPEED, value)
selector.on_change(save_speed)
# Put the selector on the bottom row and start the UI.
settings.add(selector, (0, 7))
settings.start()
Shared Component Methodsβ
Button, Selector, Number, Toggle, and CustomComponent support these methods.
component.closeβ
close() -> bool
Closes a component that is not currently attached to a UI.
Returns:
bool:Truewhen closed. ReturnsFalseif the component is still attached.
component.set_enabledβ
set_enabled(enabled: bool) -> None
Enables or disables the component.
component.set_enable_funcβ
set_enable_func(callback) -> None
Sets a callback that controls whether the component is enabled.
Callback:
- Called as
callback(). - Return truthy to enable the component.
MatrixOS.UI.Buttonβ
MatrixOS.UI.Button(name: str = "", color: ColorLike = MatrixOS.Color(255, 255, 255))
Creates a button component.
button.set_nameβ
set_name(name: str) -> None
Sets the button name.
button.set_colorβ
set_color(color: ColorLike) -> None
Sets the button color.
button.set_sizeβ
set_size(size: tuple[int, int]) -> None
Sets the button size.
button.set_color_funcβ
set_color_func(callback) -> None
Sets a dynamic color callback.
Callback: Called as callback() and should return a color.
button.on_pressβ
on_press(callback) -> None
Sets the press callback.
Callback: Called as callback().
button.on_holdβ
on_hold(callback) -> None
Sets the hold callback.
Callback: Called as callback().
MatrixOS.UI.Selectorβ
MatrixOS.UI.Selector(dimension: tuple[int, int] = (1, 1), count: int = 1)
Creates a selector component.
selector.set_valueβ
set_value(value: int) -> None
Sets the selected value.
selector.get_valueβ
get_value() -> int
Returns the selected value.
selector.set_value_funcβ
set_value_func(callback) -> None
Sets a dynamic value callback.
Callback: Called as callback() and should return an integer.
selector.on_changeβ
on_change(callback) -> None
Sets a callback called after the value changes.
Callback: Called as callback(value).
selector.set_dimensionβ
set_dimension(dimension: tuple[int, int]) -> None
Sets the selector dimensions.
selector.set_nameβ
set_name(name: str) -> None
Sets the selector name.
selector.set_countβ
set_count(count: int) -> None
Sets the number of selectable items.
selector.set_directionβ
set_direction(direction: int) -> None
Sets the selector traversal direction. Use one of the DIRECTION_* constants.
selector.set_lit_modeβ
set_lit_mode(lit_mode: int) -> None
Sets how selector items are lit. Use one of the LIT_* constants.
selector.set_colorβ
set_color(color: ColorLike) -> None
Sets the selector color.
selector.set_color_funcβ
set_color_func(callback) -> None
Sets a dynamic selector color callback.
Callback: Called as callback() and should return a color.
selector.set_individual_color_funcβ
set_individual_color_func(callback) -> None
Sets a per-item color callback.
Callback: Called as callback(index) and should return a color.
selector.set_name_funcβ
set_name_func(callback) -> None
Sets a per-item name callback.
Callback: Called as callback(index) and should return a string.
MatrixOS.UI.Numberβ
MatrixOS.UI.Number(digits: int = 1)
Creates a 4-pixel digit number component.
number.set_valueβ
set_value(value: int) -> None
Sets the displayed value.
number.get_valueβ
get_value() -> int
Returns the current displayed value.
number.set_value_funcβ
set_value_func(callback) -> None
Sets a dynamic value callback.
Callback: Called as callback() and should return an integer.
number.set_nameβ
set_name(name: str) -> None
Sets the component name.
number.set_colorβ
set_color(color: ColorLike) -> None
Sets the primary digit color.
number.set_alternative_colorβ
set_alternative_color(color: ColorLike) -> None
Sets the alternate digit color.
number.set_digitsβ
set_digits(digits: int) -> None
Sets the number of displayed digits.
number.set_spacingβ
set_spacing(spacing: int) -> None
Sets spacing between digits.
number.set_color_funcβ
set_color_func(callback) -> None
Sets a per-digit color callback.
Callback: Called as callback(index) and should return a color.
MatrixOS.UI.Toggleβ
MatrixOS.UI.Toggle(name: str = "", value: bool = False)
Creates a toggle component.
toggle.set_valueβ
set_value(value: bool) -> None
Sets the toggle value.
toggle.get_valueβ
get_value() -> bool
Returns the toggle value.
toggle.set_nameβ
set_name(name: str) -> None
Sets the toggle name.
toggle.set_colorβ
set_color(color: ColorLike) -> None
Sets the toggle color.
toggle.set_color_funcβ
set_color_func(callback) -> None
Sets a dynamic color callback.
Callback: Called as callback() and should return a color.
toggle.set_sizeβ
set_size(size: tuple[int, int]) -> None
Sets the toggle size.
toggle.on_pressβ
on_press(callback) -> None
Sets the press callback.
Callback: Called as callback(value) with the new boolean value.
toggle.on_holdβ
on_hold(callback) -> None
Sets the hold callback.
Callback: Called as callback().
MatrixOS.UI.CustomComponentβ
MatrixOS.UI.CustomComponent(dimension: tuple[int, int] = (1, 1))
Creates a lightweight Python-defined UI component.
custom_component.set_sizeβ
set_size(size: tuple[int, int]) -> None
Sets the component size.
custom_component.set_render_funcβ
set_render_func(callback) -> None
Sets the render callback.
Callback:
- Called as
callback(origin). originis the component origin point.- Return truthy when the component handled rendering.
custom_component.set_key_funcβ
set_key_func(callback) -> None
Sets the key callback.
Callback:
- Called as
callback(xy, keypad). xyis relative to the component origin.keypadhas the same shape asevent["keypad"]fromMatrixOS.Input.- Return truthy to consume the event.
Comments