From 9ce4d4d425c47dc1e7c73d68794fe8ac71e407cf Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sat, 29 Nov 2025 23:04:42 +0000 Subject: [PATCH] Update "UI-Component-Hierarchy" --- UI-Component-Hierarchy.md | 242 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 UI-Component-Hierarchy.md diff --git a/UI-Component-Hierarchy.md b/UI-Component-Hierarchy.md new file mode 100644 index 0000000..88882db --- /dev/null +++ b/UI-Component-Hierarchy.md @@ -0,0 +1,242 @@ +# UI Component Hierarchy + +The UI Component Hierarchy defines how visual elements are structured, rendered, and managed in McRogueFace. + +## Quick Reference + +**Key Files:** +- `src/UIDrawable.h` - Base class for all UI components +- `src/UIFrame.h` / `.cpp` - Container with children +- `src/UICaption.h` / `.cpp` - Text rendering +- `src/UISprite.h` / `.cpp` - Image/sprite rendering +- `src/UIGrid.h` / `.cpp` - Tilemap grid (see [[Grid-System]]) +- `src/UIEntity.h` / `.cpp` - Grid entities (see [[Entity-Management]]) +- `src/UIArc.h`, `src/UICircle.h`, `src/UILine.h` - Geometry primitives + +**Related Issues:** +- [#122](../../issues/122) - Parent-Child UI System (Closed - Implemented) +- [#102](../../issues/102) - Global Position Property (Closed - Implemented) +- [#118](../../issues/118) - Scene as Drawable (Open - Tier 2) + +--- + +## Class Hierarchy + +``` +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>` + +**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>` + +**Why std::list?** Allows stable iteration during entity removal. + +**File:** `src/UIEntityCollection.h` + +--- + +## Rendering + +### Z-Index Order + +1. Scene sorts UI elements by z_index (lower = back) +2. Elements rendered in sorted order +3. Children rendered after parents + +### Parent-Child Coordinates + +Children use coordinates relative to their parent's position: + +```python +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: + +```python +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 + +--- + +## Related Systems + +- [[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* \ No newline at end of file