gnome-asus-kbd-rgb/docs/UI_SCHEMA.md

Schéma de l'Interface Utilisateur

Vue d'ensemble

L'extension ajoute une icône dans la barre supérieure de GNOME Shell. Au clic, un popover s'affiche avec tous les contrôles.

Diagramme Mermaid - Architecture UI

graph TD
    A[Top Bar GNOME Shell] --> B[Panel Button avec icône clavier]
    B -->|Clic| C[Popover Menu]

    C --> D[Section Intensité]
    C --> E[Section Sliders RGB]
    C --> F[Section Info]
    C --> G[Section Presets]

    D --> D1[Bouton OFF]
    D --> D2[Bouton Faible]
    D --> D3[Bouton Moyen]
    D --> D4[Bouton Fort]

    E --> E1[Slider Rouge 0-255]
    E --> E2[Slider Vert 0-255]
    E --> E3[Slider Bleu 0-255]
    E --> E4[Slider Master 0-100%]

    F --> F1[Label RGB=r,g,b]
    F --> F2[Label HEX=#RRGGBB]
    F --> F3[Label Intensity=n/max]

    G --> G1[Preset 1: Orange]
    G --> G2[Preset 2: Rouge]
    G --> G3[Preset 3: Vert]
    G --> G4[Preset 4: Bleu]
    G --> G5[Preset 5: Blanc]
    G --> G6[Preset 6: Cyan]

    E1 -->|Change| H[Backend: Debounce]
    E2 -->|Change| H
    E3 -->|Change| H
    E4 -->|Change| H
    D1 -->|Click| H
    D2 -->|Click| H
    D3 -->|Click| H
    D4 -->|Click| H
    G1 -->|Click| H
    G2 -->|Click| H
    G3 -->|Click| H
    G4 -->|Click| H
    G5 -->|Click| H
    G6 -->|Click| H

    H --> I[Écriture sysfs]
    I --> J[/sys/class/leds/asus::kbd_backlight/]

    H --> K[Sauvegarde GSettings]

Layout ASCII du Popover

┌─────────────────────────────────────────────────────┐
│  Rétroéclairage Clavier ASUS                        │
├─────────────────────────────────────────────────────┤
│                                                      │
│  Intensité:                                          │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐                   │
│  │ OFF │ │  1  │ │  2  │ │  3  │                   │
│  └─────┘ └─────┘ └─────┘ └─────┘                   │
│                                                      │
│  ┌────────────────────────────────────────────┐     │
│  │ Rouge    ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Vert     ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Bleu     ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Master   ●─────────────────────○   100%    │     │
│  └────────────────────────────────────────────┘     │
│                                                      │
│  ┌────────────────────────────────────────────┐     │
│  │ RGB=(255,165,0)  #FFA500  Intensité=2/3    │     │
│  └────────────────────────────────────────────┘     │
│                                                      │
│  Couleurs prédéfinies:                               │
│  ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐              │
│  │ 🟠│ │🔴 │ │🟢 │ │🔵 │ │⚪ │ │🔵 │              │
│  └───┘ └───┘ └───┘ └───┘ └───┘ └───┘              │
│                                                      │
└─────────────────────────────────────────────────────┘

Flux de Données

Utilisateur → Slider/Bouton → Event Handler (ui.js)
                                     ↓
                            Debounce Timer (50-100ms)
                                     ↓
                            Backend.applyRGB() (backend.js)
                                     ↓
                         Clamping + Master Gain
                                     ↓
                    ┌────────────────┴────────────────┐
                    ↓                                 ↓
          Écriture sysfs                    Sauvegarde GSettings
        (kbd_rgb_mode, brightness)          (persistance)
                    ↓                                 ↓
            Mise à jour matérielle            Restauration au démarrage

Composants GNOME Shell Utilisés

• PanelMenu.Button : Bouton dans la top bar
• PopupMenu.PopupBaseMenuItem : Items personnalisés dans le menu
• St.BoxLayout : Layout vertical/horizontal
• St.Button : Boutons d'intensité
• Slider : Sliders RGB et Master (API GNOME Shell)
• St.Label : Labels et texte d'information
• St.Bin : Containers pour les presets couleur

Interactions Utilisateur

Actions Immédiates (sans confirmation)

• Déplacer un slider RGB → Application immédiate avec debounce
• Cliquer sur un bouton d'intensité → Application immédiate
• Cliquer sur une couleur preset → Application immédiate
• Déplacer le slider Master → Ajuste R/G/B proportionnellement

Feedback Visuel

• Slider actif → Curseur se déplace
• Bouton intensité actif → Surligné/highlighted
• Info line → Mise à jour en temps réel
• Preset cliqué → Feedback visuel temporaire

Gestion des Erreurs UI

Permission refusée

┌─────────────────────────────────────────────────────┐
│  ⚠️  Permissions insuffisantes                       │
│                                                      │
│  Impossible d'accéder au rétroéclairage.             │
│  Veuillez configurer les règles udev.                │
│                                                      │
│  Voir: docs/INSTALL.md                               │
└─────────────────────────────────────────────────────┘

Matériel non supporté

┌─────────────────────────────────────────────────────┐
│  ❌ Matériel non supporté                            │
│                                                      │
│  Aucun clavier ASUS RGB détecté sur ce système.     │
└─────────────────────────────────────────────────────┘

Notes d'Implémentation

1. Debouncing: Utiliser GLib.timeout_add() avec timeout de 75ms
2. Master Slider: Multiplier R/G/B par (master/100) avant écriture
3. Presets: Stocker dans GSettings, charger au démarrage
4. Info Line: Mettre à jour via callback après chaque changement
5. Style: Utiliser stylesheet.css pour personnalisation minimale