Skip to main content
Version: Matrix OS 3.2

UI Framework

Preview notice​

The MatrixOS Python API is in preview and is subject to change; it may contain errors.

Development Status

You can only use the UI Utilities API in OS 3.0. The UI Framework & Components wrapper in Python is not ready for the OS 3.0 release.

Overview​

The UI system in MatrixOS provides a framework for creating interactive user interfaces on the 8x8 LED grid. The UI class serves as a container for UI components and handles rendering, input events, and lifecycle management. The UI API is available as MatrixOS.UI and related components.

The Python UI API is implemented in Applications/Python/PikaPython/MatrixOS_UI.py with type hints in Applications/Python/PikaPython/_MatrixOS_UI.pyi.

UI Class​

MatrixOS.UI()​

class UI:
    def __init__(self, *val) -> None

Creates a new UI instance for building interactive interfaces.

UI Control Methods​

MatrixOS.UI.Start​

def Start(self) -> bool

Starts the UI, making it active and visible on the device.

Returns:

  • bool: True if successful

MatrixOS.UI.SetName​

def SetName(self, name: str) -> bool

Sets the name/title of the UI.

Parameters:

  • name (str): UI name or title

Returns:

  • bool: True if successful

MatrixOS.UI.SetColor​

def SetColor(self, color: Color) -> bool

Sets the default color theme for the UI.

Parameters:

  • color (Color): Default UI color

Returns:

  • bool: True if successful

MatrixOS.UI.ShouldCreatenewLEDLayer​

def ShouldCreatenewLEDLayer(self, create: bool) -> bool

Configures whether the UI should create its own LED layer.

Parameters:

  • create (bool): True to create new layer, False to use existing

Returns:

  • bool: True if successful

Callback Configuration​

MatrixOS.UI.SetSetupFunc​

def SetSetupFunc(self, setupFunc: any) -> bool

Sets the setup callback function, called once when UI starts.

Parameters:

  • setupFunc (function): Setup callback function

Returns:

  • bool: True if successful

MatrixOS.UI.SetLoopFunc​

def SetLoopFunc(self, loopFunc: any) -> bool

Sets the loop callback function, called repeatedly while UI is active.

Parameters:

  • loopFunc (function): Loop callback function

Returns:

  • bool: True if successful

MatrixOS.UI.SetEndFunc​

def SetEndFunc(self, endFunc: any) -> bool

Sets the end callback function, called when UI exits.

Parameters:

  • endFunc (function): End callback function

Returns:

  • bool: True if successful

MatrixOS.UI.SetPreRenderFunc​

def SetPreRenderFunc(self, pre_renderFunc: any) -> bool

Sets the pre-render callback, called before each frame render.

Parameters:

  • pre_renderFunc (function): Pre-render callback function

Returns:

  • bool: True if successful

MatrixOS.UI.SetPostRenderFunc​

def SetPostRenderFunc(self, post_renderFunc: any) -> bool

Sets the post-render callback, called after each frame render.

Parameters:

  • post_renderFunc (function): Post-render callback function

Returns:

  • bool: True if successful

MatrixOS.UI.SetKeyEventHandler​

def SetKeyEventHandler(self, key_event_handler: any) -> bool

Sets the key event handler for processing input events.

Parameters:

  • key_event_handler (function): Key event handler function

Returns:

  • bool: True if successful

Component Management​

MatrixOS.UI.AddUIComponent​

def AddUIComponent(self, uiComponent: UIComponent, xy: Point) -> bool

Adds a UI component to the interface at the specified position.

Parameters:

  • uiComponent (UIComponent): Component to add
  • xy (Point): Position to place the component

Returns:

  • bool: True if successful

MatrixOS.UI.ClearUIComponents​

def ClearUIComponents(self) -> bool

Removes all UI components from the interface.

Returns:

  • bool: True if successful

UI Configuration​

MatrixOS.UI.AllowExit​

def AllowExit(self, allow: bool) -> bool

Configures whether the UI can be exited by the user.

Parameters:

  • allow (bool): True to allow exit, False to prevent

Returns:

  • bool: True if successful

MatrixOS.UI.SetFPS​

def SetFPS(self, fps: int) -> bool

Sets the frame rate for UI updates.

Parameters:

  • fps (int): Target frames per second

Returns:

  • bool: True if successful

UI Components​

The UI system includes several pre-built components:

UIButton​

Interactive button with press and hold callbacks.

UISelector​

Value selector with multiple lighting modes and directions.

UI4pxNumber​

4-pixel number display component.

See individual component documentation for detailed usage information.

Comments