GroveEngine/plans/PLAN_UI_MODULE.md

UIModule - Plan d'implémentation

Vue d'ensemble

Module UI déclaratif avec configuration JSON, hiérarchie de widgets retained-mode, et intégration IIO pour le rendu et les événements.

Architecture

modules/UIModule/
├── UIModule.cpp/h              # Module principal IModule
├── Core/
│   ├── UIContext.cpp/h         # État global (focus, hover, active, drag)
│   ├── UILayout.cpp/h          # Système de layout (flexbox-like)
│   ├── UIStyle.cpp/h           # Thèmes, couleurs, marges, fonts
│   └── UITree.cpp/h            # Arbre de widgets, parsing JSON
├── Widgets/
│   ├── UIWidget.h              # Interface de base
│   ├── UIPanel.cpp/h           # Container avec children + layout
│   ├── UIButton.cpp/h          # Bouton cliquable
│   ├── UILabel.cpp/h           # Texte statique/dynamique
│   ├── UIImage.cpp/h           # Affichage texture
│   ├── UISlider.cpp/h          # Slider horizontal/vertical
│   ├── UICheckbox.cpp/h        # Toggle on/off
│   ├── UITextInput.cpp/h       # Champ de saisie texte
│   └── UIProgressBar.cpp/h     # Barre de progression
└── Rendering/
    └── UIRenderer.cpp/h        # Génère sprites/text via IIO topics

Phases d'implémentation

Phase 1: Core Foundation

Objectif: Infrastructure de base, rendu d'un panel simple

Fichiers:

• UIModule.cpp/h - Module IModule avec setConfiguration/process/shutdown
• Core/UIWidget.h - Interface de base pour tous les widgets
• Core/UIContext.cpp/h - État global UI
• Core/UITree.cpp/h - Chargement JSON → arbre de widgets
• Widgets/UIPanel.cpp/h - Premier widget container
• Widgets/UILabel.cpp/h - Affichage texte simple
• Rendering/UIRenderer.cpp/h - Envoi des sprites/text via IIO

Topics IIO:

• Subscribe: input:mouse, input:keyboard
• Publish: render:sprite, render:text

Test: Afficher un panel avec un label "Hello UI"

---

Phase 2: Layout System

Objectif: Positionnement automatique des widgets

Composants:

• Layout modes: vertical, horizontal, stack (superposé), absolute
• Propriétés: padding, margin, spacing, align, justify
• Sizing: width, height, minWidth, maxWidth, flex

Algorithme:

1. Mesure récursive (bottom-up) - calcul des tailles préférées
2. Layout récursif (top-down) - assignation des positions finales

JSON exemple:

{
  "type": "panel",
  "layout": "vertical",
  "padding": 10,
  "spacing": 5,
  "align": "center",
  "children": [...]
}

---

Phase 3: Interaction & Events

Objectif: Boutons cliquables, gestion du focus

Composants:

• UIButton.cpp/h - États: normal, hover, pressed, disabled
• Hit testing récursif (point → widget)
• Propagation d'événements (bubble up)
• Focus management (tab navigation)

Events IIO (publish):

• ui:click - { widgetId, x, y }
• ui:hover - { widgetId, enter: bool }
• ui:focus - { widgetId }
• ui:action - { action: "game:start" } (depuis onClick du JSON)

JSON exemple:

{
  "type": "button",
  "id": "btn_play",
  "text": "Jouer",
  "onClick": "game:start",
  "style": {
    "normal": { "bgColor": "0x444444FF" },
    "hover": { "bgColor": "0x666666FF" },
    "pressed": { "bgColor": "0x333333FF" }
  }
}

---

Phase 4: More Widgets

Objectif: Widgets interactifs avancés

Widgets:

• UIImage.cpp/h - Affiche une texture par ID ou path
• UISlider.cpp/h - Valeur numérique avec drag
• UICheckbox.cpp/h - Toggle boolean
• UIProgressBar.cpp/h - Affichage read-only d'une valeur

Events IIO:

• ui:value_changed - { widgetId, value, oldValue }

JSON exemple:

{
  "type": "slider",
  "id": "volume",
  "min": 0,
  "max": 100,
  "value": 80,
  "onChange": "settings:volume"
}

---

Phase 5: Styling & Themes

Objectif: Système de thèmes réutilisables

Composants:

• UIStyle.cpp/h - Définition des styles par widget type
• Héritage de styles (widget → parent → theme → default)
• Fichier de thème JSON séparé

Theme JSON:

{
  "name": "dark",
  "colors": {
    "primary": "0x3498dbFF",
    "secondary": "0x2ecc71FF",
    "background": "0x2c3e50FF",
    "text": "0xecf0f1FF"
  },
  "button": {
    "padding": [10, 20],
    "borderRadius": 4,
    "fontSize": 14,
    "normal": { "bgColor": "$primary" },
    "hover": { "bgColor": "$secondary" }
  },
  "panel": {
    "bgColor": "$background",
    "padding": 15
  }
}

---

Phase 6: Text Input

Objectif: Saisie de texte

Composants:

• UITextInput.cpp/h - Champ de saisie
• Cursor position, selection
• Clipboard (copy/paste basique)
• Input filtering (numbers only, max length, etc.)

Events IIO:

• ui:text_changed - { widgetId, text }
• ui:text_submit - { widgetId, text } (Enter pressed)

---

Phase 7: Advanced Features

Objectif: Fonctionnalités avancées

Features:

• Scrollable panels (UIScrollPanel)
• Drag & drop
• Tooltips
• Animations (fade, slide)
• Data binding (widget ↔ IDataNode automatique)
• Hot-reload des layouts JSON

---

Format JSON complet

{
  "id": "main_menu",
  "type": "panel",
  "style": {
    "bgColor": "0x2c3e50FF",
    "padding": 30
  },
  "layout": {
    "type": "vertical",
    "spacing": 15,
    "align": "center"
  },
  "children": [
    {
      "type": "label",
      "text": "Mon Super Jeu",
      "style": { "fontSize": 32, "color": "0xFFFFFFFF" }
    },
    {
      "type": "image",
      "textureId": 1,
      "width": 200,
      "height": 100
    },
    {
      "type": "panel",
      "layout": { "type": "vertical", "spacing": 10 },
      "children": [
        {
          "type": "button",
          "id": "btn_play",
          "text": "Nouvelle Partie",
          "onClick": "game:new"
        },
        {
          "type": "button",
          "id": "btn_load",
          "text": "Charger",
          "onClick": "game:load"
        },
        {
          "type": "button",
          "id": "btn_options",
          "text": "Options",
          "onClick": "ui:show_options"
        },
        {
          "type": "button",
          "id": "btn_quit",
          "text": "Quitter",
          "onClick": "app:quit"
        }
      ]
    },
    {
      "type": "panel",
      "id": "options_panel",
      "visible": false,
      "layout": { "type": "vertical", "spacing": 8 },
      "children": [
        {
          "type": "label",
          "text": "Volume"
        },
        {
          "type": "slider",
          "id": "volume_slider",
          "min": 0,
          "max": 100,
          "value": 80,
          "onChange": "settings:volume"
        },
        {
          "type": "checkbox",
          "id": "fullscreen_check",
          "text": "Plein écran",
          "checked": false,
          "onChange": "settings:fullscreen"
        }
      ]
    }
  ]
}

---

Intégration IIO

Topics consommés (subscribe)

Topic	Description
input:mouse:move	Position souris pour hover
input:mouse:button	Clicks pour interaction
input:keyboard	Saisie texte, navigation
ui:load	Charger un layout JSON
ui:set_value	Modifier valeur d'un widget
ui:set_visible	Afficher/masquer un widget

Topics publiés (publish)

Topic	Description
render:sprite	Background des panels/buttons
render:text	Labels, textes des boutons
ui:click	Widget cliqué
ui:value_changed	Valeur slider/checkbox modifiée
ui:action	Action custom (onClick)

---

Dépendances

• grove_impl - IModule, IDataNode, IIO
• BgfxRenderer - Pour le rendu (via IIO, pas de dépendance directe)
• nlohmann/json ou JsonDataNode existant pour parsing

---

Tests

Test Phase 1

// test_24_ui_basic.cpp
// Affiche un panel avec label
JsonDataNode config;
config.setString("layoutFile", "test_ui_basic.json");
uiModule->setConfiguration(config, io, nullptr);
// Loop: process() → vérifie render:sprite et render:text publiés

Test Phase 3

// test_25_ui_button.cpp
// Simule des clicks, vérifie les events ui:action
io->publish("input:mouse:button", mouseData);
// Vérifie que ui:action avec "game:start" est publié

---

Estimation

Phase	Complexité	Description
1	Moyenne	Core + Panel + Label + Renderer
2	Moyenne	Layout system
3	Moyenne	Button + Events + Hit testing
4	Facile	Widgets supplémentaires
5	Facile	Theming
6	Moyenne	Text input
7	Complexe	Features avancées

Ordre recommandé: 1 → 2 → 3 → 4 → 5 → 6 → 7

On commence par la Phase 1 ?