UIDrawable (base class)
├── UIFrame    - Rectangle container with children
├── UICaption  - Text labels
├── UISprite   - Images and sprite sheets
├── UIGrid     - Tilemap rendering
├── UIEntity   - Grid-based game entities
├── UIArc      - Arc/partial circle outline
├── UICircle   - Filled/outlined circle
└── UILine     - Line segment

UIDrawable (Base Class)

All UI components inherit from UIDrawable, providing a consistent interface for positioning, visibility, hierarchy, and interaction.

Implementation: src/UIDrawable.h

Position and Geometry

Property	Type	Description
`pos`	`(x, y)`	Position as tuple
`x`, `y`	`float`	Position components
`w`, `h`	`float`	Dimensions (where applicable)
`bounds`	`(x, y, w, h)`	Bounding rectangle
`global_bounds`	`(x, y, w, h)`	Bounds in screen coordinates
`global_position`	`(x, y)`	Position in screen coordinates (accounts for parent chain)

Methods:

move(dx, dy) - Relative movement
resize(w, h) - Change dimensions
get_bounds() - Returns bounding rectangle

Hierarchy

Property	Type	Description
`parent`	`UIDrawable`	Parent element (read-only, set automatically)
`z_index`	`int`	Render order (higher = front)

Children are positioned relative to their parent. When a child is added to a Frame's children collection, its parent property is set automatically. The global_position property computes absolute screen coordinates by walking the parent chain.

Visibility

Property	Type	Description
`visible`	`bool`	Show/hide element
`opacity`	`float`	Transparency (0.0 = invisible, 1.0 = opaque)

Interaction

Property	Type	Description
`on_click`	`callable`	Click handler: `(x, y, button) -> None`
`on_enter`	`callable`	Mouse enter handler: `() -> None`
`on_exit`	`callable`	Mouse exit handler: `() -> None`
`on_move`	`callable`	Mouse move handler: `(x, y) -> None`
`hovered`	`bool`	Whether mouse is over element (read-only)

Utility

Property	Type	Description
`name`	`str`	Optional identifier for debugging/lookup

Concrete Types

UIFrame

Rectangle container that can hold child elements. Primary building block for UI layouts.

Unique properties: children (UICollection), fill_color, outline_color, outline_thickness, clip_children

File: src/UIFrame.h

UICaption

Text rendering with font support.

Unique properties: text, font, font_size, fill_color

File: src/UICaption.h

UISprite

Image and sprite sheet rendering.

Unique properties: texture, sprite_index, scale_x, scale_y

File: src/UISprite.h

UIGrid

Tilemap container for roguelike game maps. Manages layers, entities, FOV, and pathfinding.

Unique properties: grid_size, center, zoom, layers, entities, fill_color

See: Grid-System for complete documentation.

UIEntity

Game entities that live on grids. Have grid-relative positioning and sprite animation.

Unique properties: grid_x, grid_y, sprite_index, grid (parent grid reference)

See: Entity-Management for complete documentation.

UIArc

Partial circle outline (arc segment).

Unique properties: center, radius, start_angle, end_angle, color, thickness

UICircle

Filled or outlined circle.

Unique properties: center, radius, fill_color, outline, outline_color

UILine

Line segment between two points.

Unique properties: start, end, color, thickness

Collections

UICollection

Container for Frame, Caption, Sprite, Grid, and geometry primitives.

Type: std::vector<std::shared_ptr<UIDrawable>>

Features:

Python sequence protocol (indexing, slicing, iteration)
Append, remove, extend operations
Preserves z_index order for rendering
Automatically sets parent on added children

File: src/UICollection.h

UIEntityCollection

Container specifically for Entity objects on a Grid.

Type: std::list<std::shared_ptr<UIEntity>>

Why std::list? Allows stable iteration during entity removal.

File: src/UIEntityCollection.h

Rendering

Z-Index Order

Scene sorts UI elements by z_index (lower = back)
Elements rendered in sorted order
Children rendered after parents

Parent-Child Coordinates

Children use coordinates relative to their parent's position:

frame = mcrfpy.Frame(pos=(100, 100), size=(200, 150))
label = mcrfpy.Caption(pos=(10, 10), text="Hello")  # At (110, 110) on screen
frame.children.append(label)

print(label.pos)             # (10, 10) - relative
print(label.global_position) # (110, 110) - absolute

Type Preservation

Challenge: Shared Pointer Type Loss

When retrieving from collections, the Python type may need reconstruction:

frame.children.append(my_sprite)  # my_sprite is Sprite
obj = frame.children[0]           # Returns correct Sprite type

Solution: RET_PY_INSTANCE macro in UIDrawable.h handles type dispatch.

File: src/UIDrawable.h::RET_PY_INSTANCE

Common Patterns

For detailed UI patterns and examples, see:

UI-Widget-Patterns - Buttons, dialogs, menus, HUD elements
Grid-Interaction-Patterns - Grid clicks, entity selection, context menus

Animation-System - All UIDrawable properties are animatable
Python-Binding-Layer - How UI classes are exposed to Python
Grid-System - UIGrid specifics
Input-and-Events - Event dispatch and handling

Last updated: 2025-11-29

UI Component Hierarchy

Quick Reference

Class Hierarchy