# 2. Primi passi #

← Installazione · Sommario · Base comune →

Obiettivo: visualizzare un primo componente in cinque minuti, poi comprendere lo schema identico per tutti i componenti.

## 2.1 Aprire l'applicazione dimostrativa #

L'applicazione dimostrativa (`pbtoolboxai_demo`) e la libreria `pbtoolboxai.pbl` sono fornite nel formato PowerBuilder 10, il formato più vecchio che tutte le versioni supportate sanno ancora leggere.

1. Aprire il workspace `pbtoolboxai_demo.pbw` nella propria versione di PowerBuilder.
2. PowerBuilder propone di migrare le librerie: accettare. La migrazione converte `pbtoolboxai_demo.pbl` e `pbtoolboxai.pbl` nel formato della propria versione.
3. Eseguire un Full Build del target, poi avviarlo: la vetrina si apre sulle mattonelle dei componenti.

È questa migrazione a fornire un `pbtoolboxai.pbl` nel formato del proprio PowerBuilder: è questo file migrato che verrà poi aggiunto alla library list delle proprie applicazioni.

> ⚠️ La migrazione è a senso unico: una libreria migrata a PowerBuilder 2025 non si riapre più in PowerBuilder 10. Migrare una copia della cartella fornita e conservare l'originale.

## 2.2 Posizionare il componente #

1. Aprire una finestra (nuova o esistente).
2. Insert → Control → User Object → scegliere `u_pbt_statictext` in `pbtoolboxai.pbl`.
3. Chiamarlo `uo_texte` e ridimensionarlo.

Nel painter, il controllo mostra una cornice grigia «PBToolboxAI component (rendered at runtime)»: il rendering reale avviene soltanto in esecuzione.

> 💡 Per intercettare gli event del componente, conviene creare un userobject ereditato (`u_pbt_statictext` → `uo_mon_texte`) e scrivere gli script degli event su di esso. È possibile anche scriverli direttamente sul controllo posizionato nella finestra.

## 2.3 Pilotarlo #

Nell'event `open` della finestra:

    // Contenuto (il testo accetta la formattazione con tag: [b], [color=...], [br]...)
    uo_texte.is_text = "Benvenuto in [b]PBToolboxAI[/b]!"

    // Formattazione: tutto e una PROPRIETA, non 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)

Tutto qui: il componente si rende, applica il tema e reagisce alle interazioni.

### Le costanti anziché le stringhe #

Ogni proprietà con valori predefiniti espone costanti sul componente. Vengono completate automaticamente dall'IDE ed evitano gli errori di digitazione:

    uo_texte.is_align = uo_texte.ALIGN_CENTER      // invece di "center"
    uo_texte.is_theme_style = uo_texte.THEME_STYLE_OFFICE2007
    uo_texte.is_theme_mode  = uo_texte.THEME_MODE_DARK

## 2.4 Ricevere gli eventi #

I componenti restituiscono event PB tipizzati. Scriverne gli script sul proprio controllo (o sul proprio userobject ereditato):

    // event ue_clicked di uo_texte
    MessageBox("PBToolboxAI", "Testo cliccato")

    // event ue_hyperlink di uo_texte -- attivato da [hyperlink=...]
    // as_url = l'indirizzo cliccato
    Run("explorer.exe " + as_url)

## 2.5 Lo schema, identico per tutti i componenti #

Passaggio | Voi fate | Il componente fa
--- | --- | ---
Creazione | Posizionare l'userobject | Si crea, mette i comandi in coda
Configurazione | Assegnare proprietà / richiamare gli `of_add_*` | Le applica, anche prima di essere pronto
Pronto | (niente) | Attiva `ue_ready`
Interazione | (niente) | Attiva event `ue_*` tipizzati
Ridimensionamento | (niente) | Segue la dimensione dell'userobject
Azzeramento | `of_reset()` | Torna allo stato iniziale
Chiusura | Chiudere la finestra | Si distrugge in modo pulito

Non si deve mai gestire l'HTML, il JSON né lo stato «pronto / non pronto».

## 2.6 Un esempio completo #

    // ---- event open della finestra ---------------------------------------
    // Raggruppa le modifiche in UN solo repaint (nessuno sfarfallio)
    uo_texte.of_set_redraw(false)

    uo_texte.is_text        = "Fatturato: [b][color=#2e7d32]1 240 500 €[/color][/b]" &
                              + "[br][size-=15]Aggiornato il " + 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     = "Totale dal 1° gennaio"

    uo_texte.of_set_redraw(true)

## 2.7 Codici di ritorno #

Tutti i metodi `of_*` restituiscono un `long`:

    long ll_rc

    ll_rc = uo_texte.of_reset()
    if ll_rc < 0 then
        // -2 = componente non creato (runtime assente) ; -5 = argomento non valido
        f_log(uo_texte.of_get_last_error())
    end if

In pratica il valore restituito viene spesso ignorato (gli errori di configurazione sono rari) e ci si basa su `ue_ready` / `ue_runtime_missing`.

L'assegnazione di una proprietà non restituisce nulla (è un'assegnazione PowerScript): un valore non valido viene ignorato dal componente, senza eccezioni.

## 2.8 E poi #

- Base comune: motore delle proprietà, item, ciclo di vita dettagliato.
- Temi e aspetto: applicare un'identità visiva a tutta l'applicazione.
- Riferimento dei componenti: una pagina per ogni componente della v1.

← Installazione · Sommario · Base comune →