widget (cellium v0.1.0)

View Source

Base widget module providing common widget functionality.

This module defines the fundamental widget structure and common operations used by all widget types in Cellium. Every widget is represented as a map with specific required and optional keys.

Widget Structure

All widgets are maps containing:

  • type: Either widget or container
  • widget_type: Specific widget type (text, button, checkbox, etc.)
  • id: Unique identifier
  • color: Foreground color (default: white)
  • background-color: Background color (default: from ?DEFAULT_BG_COLOR)
  • padding: Padding map with top, bottom, left, right
  • focusable: Whether the widget can receive focus

Common Properties

Layout Properties

  • x, y: Position (set by layout system)
  • width, height: Dimensions (set by layout system)
  • size: Fixed size in layout direction
  • expand: Request to fill available space

Visual Properties

  • color: Foreground color atom (black, red, green, yellow, blue, magenta, cyan, white)
  • background-color: Background color atom
  • Bright variants: bright_black, bright_red, etc.

Focus Properties

  • focusable: Can this widget receive focus?
  • focused: Is this widget currently focused? (set by layout)
  • has_focus: Does this widget or a child have focus? (set by layout)

Creating Widgets

Specific widget modules call widget:new() and add their own properties:

button:new(my_button, "Click Me")
% Calls widget:new() internally and adds button-specific fields

Summary

Functions

color_to_int(Color)

Converts color atoms to their integer or atom representation.

create(WidgetMap)

Creates and registers a widget with the focus manager if it is focusable.

destroy(WidgetMap)

Destroys a widget and unregisters it from the focus manager if it is focusable.

destroy_tree(WidgetMap)

Destroys a widget tree recursively, including all children.

find_widget/2

Finds a widget with the given ID in a widget tree. Returns the widget map or undefined if not found.

get_common_props(Widget)

Extracts common rendering properties from a widget map.

new()

Creates a new base widget map with default values.

Functions

color_to_int(Color)

-spec color_to_int(Color :: atom() | integer()) -> integer() | atom().

Converts color atoms to their integer or atom representation.

Accepts color atoms (black, red, green, yellow, blue, magenta, cyan, white) and their bright variants, RGB tuples, or integers. Returns the color value for use in rendering.

create(WidgetMap)

-spec create(map()) -> map().

Creates and registers a widget with the focus manager if it is focusable.

If the widget has focusable => true, registers it with the focus manager for keyboard navigation support.

destroy(WidgetMap)

-spec destroy(map()) -> ok.

Destroys a widget and unregisters it from the focus manager if it is focusable.

This function should be called when a widget is being removed from the UI to ensure it is properly cleaned up. If the widget has focusable => true, it will be unregistered from the focus manager.

This is the counterpart to create/1 and should be called when transitioning between screens or removing widgets from the widget tree.

destroy_tree(WidgetMap)

-spec destroy_tree(map()) -> ok.

Destroys a widget tree recursively, including all children.

This function destroys a widget and all its children (if it's a container). It walks the widget tree depth-first, destroying children before parents. Each focusable widget will be unregistered from the focus manager.

Use this when removing an entire screen or container hierarchy.

find_widget/2

-spec find_widget(term(), map()) -> map() | undefined.

Finds a widget with the given ID in a widget tree. Returns the widget map or undefined if not found.

get_common_props(Widget)

-spec get_common_props(Widget :: map()) ->
                          #{x := integer(),
                            y := integer(),
                            fg := integer() | atom(),
                            bg := integer() | atom()}.

Extracts common rendering properties from a widget map.

Retrieves the position and color properties needed for rendering, applying default values when properties are not explicitly set. This provides a consistent interface for all widgets to access their rendering properties.

Default values:

  • x: 0
  • y: 0
  • background-color: value of ?DEFAULT_BG_COLOR macro
  • color: value of ?DEFAULT_FG_COLOR macro

Returns a map with keys x, y, fg (foreground), and bg (background).

new()

-spec new() -> map().

Creates a new base widget map with default values.

This is typically called by specific widget constructors who then add their own fields to customize the widget.

Default values:

  • type: widget
  • widget_type: override_me (should be set by specific widget)
  • color: white
  • padding: all sides set to 0
  • id: override_me (should be set by specific widget)
  • focusable: false