Skip to main content
Version: Matrix OS 4.0 🚧

UI Framework

The UI framework provides a set of classes and utilities for creating interactive user interfaces (GUIs) on Matrix OS.

The header file for this framework is located in OS/UI/UI.h and the implementation is in OS/UI/UI.cpp.

Overview​

The UI framework provides a default way for creating user interfaces with customizable components, event handling, and rendering. It supports features like layered rendering, custom input event handling, and modular setup.

You can add different UI components into the UI framework to create a user interface. The UI framework will manage the rendering and interaction of these components.

Additionally, there are some pre made UI interfaces that you can use directly, like color picker, number selector, text scroll, etc. See the UI Utilities documentation for more information.

Key Features​

  • Customizable rendering and update rate.
  • Modular setup with function hooks for setup, loop, pre-render, post-render, and end tasks.
  • Support for layered UI components.
  • Event-driven design for handling input events.

Basic Usage​

  1. Create a UI object. with a name and color (used for text scroll color). Optionally, you can make the UI render on a new LED layer, useful if you want to preserve the previous display state. - Constructor

  2. Create UI components (buttons, sliders, etc.) and add them to the UI object. - AddUIComponent()

  3. Start the UI object. - Start()

Optionally, you can customize the UI behavior by setting input event handlers, function hooks, and refresh rate, etc. - Event Handling Methods, Function Hook Setters Methods, Utilities Methods

Example​

This example creates a small menu with one button. AddUIComponent takes a pointer, so keep component objects alive until menu.Start() returns.

void HelloNative::OpenMenu() {
  UI menu("Menu", Color::Cyan, true);

  UIButton colorButton;
  colorButton.SetName("Color");
  colorButton.SetColorFunc([&]() -> Color { return color; });
  colorButton.OnPress([&]() {
    MatrixOS::UIUtility::ColorPicker(color);
  });

  menu.AddUIComponent(&colorButton, Point(0, 0));

  menu.AllowExit(false);
  menu.SetInputEventHandler([&](InputEvent* inputEvent) -> bool {
    if (inputEvent->id == InputId::FunctionKey() &&
        inputEvent->inputClass == InputClass::Keypad)
    {
      if (inputEvent->keypad.state == KeypadState::Hold)
      {
        Exit();
        return true;
      }
      if (inputEvent->keypad.state == KeypadState::Released)
      {
        menu.Exit();
        return true;
      }
    }

    return false;
  });

  menu.Start();
}

Constructor​

UI​

UI();
UI(string name, Color color = Color(0xFFFFFF), bool newLedLayer = true);

Creates a new UI instance.

Parameters:

  • name (string): The name of the UI.
  • color (Color, optional): The name color. Default is white (0xFFFFFF).
  • newLedLayer (bool, optional): If true, creates a new LED layer. Default is true.

Lifecycle Methods​

Start​

void Start();

Starts the UI.

Exit​

void Exit();

Exits the UI. You can call this from a UI component event handler to exit the UI.

Component Management Methods​

AddUIComponent​

void AddUIComponent(UIComponent* uiComponent, Point xy);

Adds a UI component to the UI.

Parameters:

  • uiComponent (UIComponent*): The component to add.
  • xy (Point): The position of the component.

ClearUIComponents​

void ClearUIComponents();

Removes all UI components.

Event Handling Methods​

SetInputEventHandler​

void SetInputEventHandler(std::function<bool(InputEvent*)> inputEventHandler);

Sets the custom input event handler. This will be called before the default input handling. If the handler returns true, the default UI input handling will be skipped.

Parameters:

  • inputEventHandler (std::function<bool(InputEvent*)>): The handler function.

Function Hook Setters Methods​

SetSetupFunc​

void SetSetupFunc(std::function<void()> setup_func);

Sets the optional setup function hook. This function is called once when the UI is started.

Parameters:

  • setup_func (std::function<void()>): The setup function.

SetLoopFunc​

void SetLoopFunc(std::function<void()> loop_func);

Sets the optional loop function hook. This function is called repeatedly during the UI loop.

This happens before the pre-render function. The difference is that the loop function is called before cleaning the display buffer.

Parameters:

  • loop_func (std::function<void()>): The loop function.

SetEndFunc​

void SetEndFunc(std::function<void()> end_func);

Sets the optional end function hook. This function is called when the UI is exited.

Parameters:

  • end_func (std::function<void()>): The end function.

SetPreRenderFunc​

void SetPreRenderFunc(std::function<void()> pre_render_func);

Sets the optional pre-render function hook. This function is called before rendering. Similar to the loop function, but after cleaning the display buffer, so you can render some background before the UI components.

Parameters:

  • pre_render_func (std::function<void()>): The pre-render function.

SetPostRenderFunc​

void SetPostRenderFunc(std::function<void()> post_render_func);

Sets the optional post-render function hook. This function is called after rendering. You can use this function to render some overlay on top of the UI components.

Parameters:

  • post_render_func (std::function<void()>): The post-render function.

Utilities Methods​

SetFPS​

void SetFPS(uint16_t fps);

Sets the update rate of the UI.

Parameters:

  • fps (uint16_t): Frames per second.

AllowExit​

void AllowExit(bool allow);

Enables or disables the ability to exit the UI by pressing the function key.

By default, press the function key wull exit the UI. This function allows you to customize the exit behavior.

For example. If you want to exit the application when the function key is hold down, and exit the UI is released (but before the hold down time threshold).

Parameters:

  • allow (bool): If true, allows exiting the UI.

Static Methods​

CleanUpUIs​

static void CleanUpUIs();

Cleans up all registered UIs. This is privately used mostly to free up all UIs when the application exits.

Comments