Build Your First App

A PixelUI App derives from IApplication. ViewManager constructs, switches, and destroys Apps. The App draws its page, handles input not consumed by Widgets, and registers its Widgets and callbacks in lifecycle methods.

1. Minimal App

#include "core/app/IApplication.h"
#include "core/app/app_system.h"
#include "widgets/text_button/text_button.h"

class HelloApp final : public IApplication {
public:
    HelloApp(PixelUI& ui, void*)
        : ui_(ui), closeButton_(ui, 38, 36, 52, 16, "Back") {}

    void onEnter(ExitCallback exitCallback) override {
        // Preserve the exit callback supplied by ViewManager.
        IApplication::onEnter(exitCallback);

        closeButton_.setCallback([this]() { requestExit(); });
        closeButton_.onLoad();
        ui_.addWidgetToFocusManager(&closeButton_);
        ui_.markDirty();
    }

    void draw() override {
        U8G2& display = ui_.getU8G2();
        display.setFont(u8g2_font_6x10_tf);
        display.drawStr(32, 20, "Hello PixelUI");
        closeButton_.draw();
    }

    bool handleInput(InputEvent event) override {
        if (event == InputEvent::BACK) {
            requestExit();
            return true;
        }
        return false;
    }

private:
    PixelUI& ui_;
    TextButton closeButton_;
};

// A 24 x 24 XBM uses 24 * 3 = 72 bytes. Use an empty placeholder here.
static const uint8_t hello_icon_bits[72] = {};

AppItem helloApp = AppItem::make<HelloApp>("Hello", hello_icon_bits);

AppItem::make<T>() expects a T(PixelUI&, void*) constructor by default. The second argument is a non-owning launch parameter and may be ignored when unused.

2. Lifecycle

Callback	When it runs	Appropriate work
Constructor	The App is created in the arena	Construct members; do not publish `this` or member pointers to managers
`onEnter()`	The App becomes topmost; after fade when one exists	Set callbacks, call `onLoad()`, register Widgets, start Animations
`onPause()`	Another App is pushed above it	Pause work managed by this App
`onResume()`	The upper App exits	Resume App-level state such as continuous drawing
`onExit()`	Before the App leaves the stack and is destroyed	Undo external state managed by this App
Destructor	After `onExit()`	Release internal resources

Do not omit IApplication::onEnter(exitCallback), or requestExit() will have no exit function to call.

3. Input routing

The approximate order of ui.handleInput(event) is:

1	PixelUI FocusManager -> active Popup -> top App

Only events not consumed by Widgets reach HelloApp::handleInput(). This is normally where an App handles BACK and page-wide keys.

4. Register and launch

AppManager::getInstance().registerApp(helloApp); // register

ViewManager& views = *ui.getViewManagerPtr();
const auto result = views.launch(helloApp, nullptr); // launch

if (result != ViewManager::LaunchResult::Ok) {
    show_launch_error(result);
}

A page that does not belong in the launcher can be started directly with views.push<HelloApp>(ui, nullptr). See App lifecycle and ViewManager for both launch paths and their failure results.

5. Launch parameters

struct HelloParameters {
    const char* message;
};

class ParameterApp final : public IApplication {
public:
    ParameterApp(PixelUI& ui, void* raw)
        : ui_(ui), params_(static_cast<HelloParameters*>(raw)) {}

private:
    PixelUI& ui_;
    HelloParameters* params_; // non-owning
};

parameters has no type information and does not extend object lifetime. Like the pointer returned by getCurrentApp(), it is non-owning. If an App retains a launch parameter, the target object must outlive the App. Never pass the address of a local variable from a function that is about to return. See Callbacks and object lifetime for the general rule.