Update "UI-Component-Hierarchy"
parent
0d178594ff
commit
9ce4d4d425
|
|
@ -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<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
|
||||
|
||||
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*
|
||||
Loading…
Reference in New Issue