---
title: "Captured source: Local Gui"
description: "Captured source: Local Gui Original ticket source file: local-gui.h. ``c / @file gui.h @brief GUI system APIs. / #pragma once #include #include \"widget.h\" #ifdef cplusplus extern \"C\" {…"
doc_version: 1
last_updated: 2026-10-15
canonical_url: "http://parc.yolo.scapegoat.dev/note/projects/2026/08/03/busybar-firmware-sources/local-gui-h"
---

# Captured source: Local Gui

Captured source: Local Gui Original ticket source file: local-gui.h. ``c / @file gui.h @brief GUI system APIs. / #pragma once #include <input/input.h> #include "widget.h" #ifdef cplusplus extern "C" {…

## Content

# Captured source: Local Gui

Original ticket source file: `local-gui.h`.

```c
/**
 * @file gui.h
 * @brief GUI system APIs.
 */
#pragma once

#include <input/input.h>

#include "widget.h"

#ifdef __cplusplus
extern "C" {
#endif

#define RECORD_GUI "gui"

/** Enumeration of available display identifiers. */
typedef enum {
    GuiDisplayIdFront = 0, /**< Front (main display) */
    GuiDisplayIdBack, /**< Back (greyscale) display */
    GuiDisplayIdMax, /**< Special value, equal to display number */
} GuiDisplayId;

/** Enumeration of available layer identifiers. */
typedef enum {
    GuiLayerIdSystem = 0, /**< System layer - for displaying statuses and other persistent info */
    GuiLayerIdTop, /**< Top layer - for displaying dialog windows and overlays */
    GuiLayerIdMain, /**< Main layer - for displaying regular applications */
    GuiLayerIdBottom, /**< Bottom layer - visible only if there is nothing on layers above it */
    GuiLayerIdMax, /**< Special value, not to be used in application code */
} GuiLayerId;

/** Gui opaque type declaration. */
typedef struct Gui Gui;

/** GuiLayer opaque type declaration. */
typedef struct GuiLayer GuiLayer;

/**
 * @brief Display parameters descriptor.
 *
 * Holds the static geometry and buffer configuration for a physical display.
 */
typedef struct {
    size_t width; /**< Display width in pixels. */
    size_t height; /**< Display height in pixels. */
    size_t bits_per_pixel; /**< Colour depth (bits per pixel). */
    size_t buffer_size; /**< Frame buffer size in bytes. */
} GuiDisplayParameters;

/**
 * @brief Input callback function type.
 *
 * @param[in] event pointer to the input event that has occurred
 * @param[in,out] context pointer to a user-specific object, given upon callback registration
 * @returns true if the event was consumed (handled) by the recipient, false otherwise
 */
typedef bool (*GuiInputCallback)(const InputEvent* event, void* context);

/**
 * @brief Lock the GUI system.
 *
 * @warning This function MUST be called BEFORE ANY Gui-related function calls.
 *          Examples include, but not limited to: creating, deleting and modifying of Widgets,
 *          adding or removing of active widgets, etc.
 *          Failure to do so will result in possible instabilities and crashes.
 *
 * @param[in,out] instance pointer to the Gui instance to lock
 */
void gui_lock(Gui* instance);

/**
 * @brief Unlock the GUI system.
 *
 * @warning This function MUST be called AFTER calling gui_lock() and performing the
 *          required Gui-related calls. Failure to do so will result in Gui lockup.
 *
 * @param[in,out] instance pointer to the Gui instance to unlock
 */
void gui_unlock(Gui* instance);

/**
 * @brief Get a GUI layer by its identifier.
 *
 * @param[in,out] instance pointer to the Gui instance
 * @param[in] layer_id identifier of the layer to retrieve
 * @return pointer to the requested GuiLayer, or NULL on invalid arguments
 */
GuiLayer* gui_get_layer(Gui* instance, GuiLayerId layer_id);

/**
 * @brief Get the root widget of a Layer on a certain display.
 *
 * A root widget cannot be moved, resized or used as the input event source.
 *
 * @param[in,out] layer pointer to the GuiLayer instance
 * @param[in] display_id identifier of the display required
 * @return pointer to the root widget
 */
Widget* gui_layer_get_root_widget(GuiLayer* layer, GuiDisplayId display_id);

/**
 * @brief Register a callback to report for unhandled input events on a certain layer.
 *
 * @param[in,out] layer pointer to the layer to be modified
 * @param[in] callback pointer to the function to be called upon eligible events
 * @param[in,out] context pointer to a user-specific object (will be passed to the callback)
 */
void gui_layer_add_input_callback(GuiLayer* layer, GuiInputCallback callback, void* context);

/**
 * @brief Unregister a previously registered input callback.
 *
 * @param[in,out] layer pointer to the layer to be modified
 * @param[in] callback pointer to the function to be unregistered
 */
void gui_layer_remove_input_callback(GuiLayer* layer, GuiInputCallback callback);

/**
 * @brief Returns pointer to frame buffer for requested display
 *
 * @param[in,out] instance pointer to the Gui instance
 * @param[in] display_id identifier of the display which frame buffer required
 * @return pointer to the frame buffer
 */
const uint8_t* gui_display_get_frame_buffer(Gui* instance, GuiDisplayId display_id);

/**
 * @brief Get the static parameters for a given display.
 *
 * @param[in] display_id identifier of the display to query
 * @return pointer to the GuiDisplayParameters for the requested display
 * @see GuiDisplayParameters
 */
const GuiDisplayParameters* gui_display_get_parameters(GuiDisplayId display_id);

/**
 * @brief Shorthand for automatically locking and unlocking the GUI.
 *
 * @param[in,out] gui pointer to the Gui instance
 * @param[in] code the code to execute when the Gui will be in locked state
 */
#define with_gui(gui, code) \
    {                       \
        gui_lock(gui);      \
        {code};             \
        gui_unlock(gui);    \
    }

#ifdef __cplusplus
}
#endif

```

## Sitemap

- [Home](http://parc.yolo.scapegoat.dev/)
- [Home markdown mirror](http://parc.yolo.scapegoat.dev/index.md)
- [Markdown sitemap](http://parc.yolo.scapegoat.dev/sitemap.md)