User Experience (graphical) library for Nano devices

Introduction

lib_ux is the UX layer for button-based Ledger devices (Nano S, Nano S Plus, Nano X). It provides a flow engine to navigate between screens using the left and right physical buttons, and a collection of predefined layouts built on top of the BAGL (Basic Application Graphic Library) rendering engine.

Flow engine

The flow engine lets an application declare a sequence of screens as a static array of steps, and handles button navigation automatically.

Declaring a flow

Steps are declared with the UX_STEP_* family of macros and assembled into a flow with UX_FLOW():

// Display-only step (icon + two text lines)
UX_STEP_NOCB(step_welcome, pnn,
    { &C_icon_app, "Welcome", "MyApp" });
 
// Step with a confirm callback (icon + bold line)
UX_STEP_CB(step_approve, pb,
    cb_approve(),
    { &C_icon_validate_14, "Approve" });
 
// Step with a reject callback
UX_STEP_CB(step_reject, pb,
    cb_reject(),
    { &C_icon_crossmark, "Reject" });
 
// Assemble into a flow
UX_FLOW(flow_main,
    &step_welcome,
    &step_approve,
    &step_reject);

Then start the flow with:

ux_flow_init(0, flow_main, NULL);

Step macros

Macro	Description
UX_STEP_NOCB	Display-only step, no action on validation
UX_STEP_CB	Step with a C callback on validation (alias: UX_STEP_VALID)
UX_STEP_FLOWCB	Step that jumps to another flow on validation
UX_STEP_TIMEOUT	Step that auto-validates after a timeout (in ms)
UX_STEP_INIT	Invisible step used to run code when the flow reaches this position
UX_STEP_CB_INIT	Step with both a pre-init hook and a validate callback
UX_STEP_NOCB_INIT	Display-only step with a pre-init hook
UX_STEP_NOCB_POSTINIT	Display-only step with a post-init hook

Navigation

Function	Description
ux_flow_init()	Start a flow on a given stack slot
ux_flow_next()	Advance to the next step
ux_flow_prev()	Go back to the previous step

Layouts

A layout describes how text and icons are arranged on the device screen. The layout name encodes the content of each visible line using single letters:

Letter	Content
p	Picture (icon)
b	Bold text line
n	Normal text line

Examples: pb = picture + bold line, bnnn = bold line + 3 normal lines, pbb = picture + 2 bold lines, nnbnn = 2 normal lines + bold line + 2 normal lines.

Paging layouts (paging, nn_paging, bn_paging, bb_paging …) automatically split long text across multiple sub-pages navigated with the buttons.