# 2. Prise en main #

← Installation · Sommaire · Socle commun →

Objectif : afficher un premier composant en cinq minutes, puis comprendre le schéma identique pour tous les composants.

## 2.1 Ouvrir l'application de démonstration #

L'application de démonstration (`pbtoolboxai_demo`) et la bibliothèque `pbtoolboxai.pbl` sont livrées au format PowerBuilder 10 — le format le plus ancien que toutes les versions supportées savent relire.

1. Ouvrez le workspace `pbtoolboxai_demo.pbw` dans votre version de PowerBuilder.
2. PowerBuilder propose de migrer les bibliothèques : acceptez. La migration convertit `pbtoolboxai_demo.pbl` et `pbtoolboxai.pbl` au format de votre version.
3. Lancez un Full Build de la cible, puis exécutez : la vitrine s'ouvre sur les tuiles de composants.

C'est cette migration qui vous donne un `pbtoolboxai.pbl` au format de votre PowerBuilder : c'est ce fichier migré que vous ajouterez ensuite à la library list de vos propres applications.

> ⚠️ La migration est à sens unique : une bibliothèque migrée en PowerBuilder 2025 ne se rouvre plus en PowerBuilder 10. Migrez une copie du dossier livré et conservez l'original.

## 2.2 Poser le composant #

1. Ouvrez une fenêtre (nouvelle ou existante).
2. Insert → Control → User Object → choisissez `u_pbt_statictext` dans `pbtoolboxai.pbl`.
3. Nommez-le `uo_texte` et dimensionnez-le.

Dans le peintre, le contrôle affiche un cadre gris « PBToolboxAI component (rendered at runtime) » : le rendu réel n'a lieu qu'à l'exécution.

> 💡 Pour intercepter les events du composant, créez plutôt un userobject hérité (`u_pbt_statictext` → `uo_mon_texte`) et scriptez les events dessus. Vous pouvez aussi les scripter directement sur le contrôle posé dans la fenêtre.

## 2.3 Le piloter #

Dans l'event `open` de la fenêtre :

    // Contenu (le texte accepte le balisage riche : [b], [color=...], [br]...)
    uo_texte.is_text = "Bienvenue dans [b]PBToolboxAI[/b] !"

    // Mise en forme : tout est une PROPRIETE, pas un setter
    uo_texte.is_align    = uo_texte.ALIGN_CENTER
    uo_texte.is_valign   = uo_texte.VALIGN_CENTER
    uo_texte.ii_font_size = 14
    uo_texte.il_text_color = RGB(0, 103, 192)

C'est tout : le composant se rend, se thème, et réagit aux interactions.

### Les constantes plutôt que les chaînes #

Chaque propriété à valeurs prédéfinies expose des constantes sur le composant. Elles sont auto-complétées par l'IDE et vous évitent les fautes de frappe :

    uo_texte.is_align = uo_texte.ALIGN_CENTER      // au lieu de "center"
    uo_texte.is_theme_style = uo_texte.THEME_STYLE_OFFICE2007
    uo_texte.is_theme_mode  = uo_texte.THEME_MODE_DARK

## 2.4 Recevoir les événements #

Les composants remontent des events PB typés. Scriptez-les sur votre contrôle (ou votre userobject hérité) :

    // event ue_clicked de uo_texte
    MessageBox("PBToolboxAI", "Texte cliqué")

    // event ue_hyperlink de uo_texte -- declenche par [hyperlink=...]
    // as_url = l'adresse cliquee
    Run("explorer.exe " + as_url)

## 2.5 Le schéma, identique pour tous les composants #

Étape | Vous faites | Le composant fait
--- | --- | ---
Création | Poser l'userobject | Se crée, met vos commandes en file
Configuration | Affecter des propriétés / appeler des `of_add_*` | Applique, même avant d'être prêt
Prêt | (rien) | Lève `ue_ready`
Interaction | (rien) | Lève des events `ue_*` typés
Redimensionnement | (rien) | Suit la taille de l'userobject
Remise à zéro | `of_reset()` | Revient à l'état neuf
Fermeture | Fermer la fenêtre | Se détruit proprement

Vous n'avez jamais à gérer le HTML, le JSON, ni l'état « prêt / pas prêt ».

## 2.6 Un exemple complet #

    // ---- event open de la fenetre ----------------------------------------
    // Regroupe les modifications en UN seul repaint (pas de scintillement)
    uo_texte.of_set_redraw(false)

    uo_texte.is_text        = "Chiffre d'affaires : [b][color=#2e7d32]1 240 500 €[/color][/b]" &
                              + "[br][size-=15]Mise à jour " + String(Today(), "dd/mm/yyyy") + "[/size-=15]"
    uo_texte.is_align       = uo_texte.ALIGN_CENTER
    uo_texte.is_valign      = uo_texte.VALIGN_CENTER
    uo_texte.ii_padding     = 12
    uo_texte.ii_corner_radius = 6
    uo_texte.is_tooltip     = "Cumul depuis le 1er janvier"

    uo_texte.of_set_redraw(true)

## 2.7 Codes de retour #

Toutes les méthodes `of_*` renvoient un `long` :

    long ll_rc

    ll_rc = uo_texte.of_reset()
    if ll_rc < 0 then
        // -2 = composant non cree (runtime absent) ; -5 = argument invalide
        f_log(uo_texte.of_get_last_error())
    end if

En pratique on ignore souvent le retour (les erreurs de configuration sont rares) et on s'appuie sur `ue_ready` / `ue_runtime_missing`.

L'affectation d'une propriété ne renvoie rien (c'est une affectation PowerScript) : une valeur invalide est ignorée par le composant, sans exception.

## 2.8 Et ensuite #

- Socle commun : moteur de propriétés, items, cycle de vie détaillé.
- Thèmes et apparence : appliquer une identité visuelle à toute l'application.
- Référence des composants : une page par composant de la v1.

← Installation · Sommaire · Socle commun →