Using the UI service¶

The UI service renders graphical overlays on top of the regular Kanzi application content. These overlays display runtime information about the Kanzi Engine or application, and help identify issues with the content.

The UI service provides a BasicUI screen system for lightweight 2D overlays. The BasicUI system includes two built-in screens, and you can register custom screens through the API. Other services, such as the Log service, can also register their own BasicUI screens.

Platform support¶

The UI service builds from sources on all known Kanzi target platforms.

How the UI service works¶

The UI service renders overlays by adding a custom node (MonitorUINode2D) into the Kanzi node tree. This node draws in the foreground rendering phase, on top of all regular content.

The overlay system is organized around screens. Each screen is a set of callbacks for drawing and handling input. Only one screen is active at a time. You select the active screen using the basicui command.

The service supports touch and key input. When the UI overlay is visible, it captures input events and routes them to the input handlers of the active screen. Screens that do not need input can use the default no-op handlers.

Showing and hiding the overlay¶

The ui command controls overlay visibility:

ui              Show current visibility status for all node trees
ui 1            Show the overlay on all node trees
ui 0            Hide the overlay on all node trees
ui 1 0          Show the overlay on node tree 0 only
ui 0 1          Hide the overlay on node tree 1 only

The optional node tree index is useful when the application has multiple registered root nodes.

Switching screens¶

The basicui command controls which screen is active:

basicui         List all registered screens and show the current selection
basicui 0       Switch to screen 0 (Default BasicUI screen)
basicui 1       Switch to screen 1 (Colored overlay screen)

Setting the font scale¶

The default font size for the BasicUI overlay is 12pt, which can be too small on high-DPI devices such as Android tablets. The font scale multiplier adjusts the text size used by all BasicUI screens.

Set the initial font scale in kanzimonitor.cfg:

UIFontScale = 2.0

At runtime, use the fontscale command to get or set the scale:

fontscale           Show the current font scale
fontscale 2.0       Set the font scale to 2.0x
fontscale 1.5       Set the font scale to 1.5x

Changing the font scale recreates the font resources at the new size, so text remains crisp at any scale.

Built-in screens¶

The UI service registers two built-in BasicUI screens:

Default BasicUI screen (index 0) – Displays a welcome message indicating the UI is loaded.
Colored overlay screen (index 1) – Displays a semi-transparent blue overlay covering the output area. Useful for verifying that the overlay is rendering correctly.

Other services can add additional screens. The Log service registers a Log screen that displays recent log entries on-screen. See Using the Log service.

Adding custom screens¶

You can register custom BasicUI screens through the UI service API.

A screen consists of a draw function (required) and optional touch and key input handlers:

// Draw function: called every frame when the screen is active.
void myScreenDraw(BasicUI& basicUI, void* userData,
                  const kanzi::Matrix3x3& transform,
                  const kanzi::Vector2& outputSize)
{
    // Use basicUI.drawText() and basicUI.drawSquare() for rendering.
    // Use basicUI.getDomain() to access the Kanzi Domain.
    basicUI.drawText("Hello from my screen", transform, outputSize);
}

// Touch input handler (optional).
void myScreenTouch(BasicUI& basicUI, void* userData,
                   const kanzi::InputManipulator::TouchInfo& touchInfo) { }

// Key input handler (optional).
void myScreenKey(BasicUI& basicUI, void* userData,
                 const kanzi::KeyEvent& event) { }

To register the screen:

KanziMonitorModule* module = getKanziMonitorModule(domain);
UIService* uiService = module->getUIService();
uiService->addBasicUIScreen("My custom screen", myUserData,
                            myScreenDraw, myScreenTouch, myScreenKey);

The touch and key input handlers are optional. If omitted, the screen uses default no-op handlers.

The BasicUI object provides two drawing primitives:

drawText(text, transform, outputSize) – Renders text at the position specified by the transform.
drawSquare(pos, size, color, transform, outputSize) – Draws a solid colored rectangle.

Screens can access the Kanzi Domain through basicUI.getDomain() to query engine state, resources, or any other domain information needed for rendering.

Available commands¶

Command	Description
`ui`	Controls the Kanzi Monitor UI service visibility. Usage: `ui [0\|1] [nodetree]`
`basicui`	Controls the Kanzi Monitor BasicUI screen. Usage: `basicui [index]`
`fontscale`	Gets or sets the BasicUI font scale. Usage: `fontscale [scale]`