# 1. Installazione e distribuzione #

← Sommario · Primi passi →

## 1.1 Prerequisiti #

Elemento | Dettaglio
--- | ---
PowerBuilder | 10.2 → 2025 (32 bit o 64 bit)
Windows | 10 / 11, Server 2016 e successivi
Runtime WebView2 Evergreen | Preinstallato su Windows 10/11 aggiornati. Su Windows Server o LTSC, installarlo una volta con il bootstrapper `MicrosoftEdgeWebview2Setup.exe` (~2 MB, silenzioso: `/silent /install`)

Non c'è nient'altro da installare: niente .NET, niente ActiveX, niente PBNI, nessuna registrazione COM, nessun diritto di amministratore per la libreria stessa.

## 1.2 File da distribuire #

Distribuzione xcopy, accanto al proprio eseguibile:

    mon_appli.exe
    pbtoolboxai.dll        <- copia x86 o x64, secondo la propria applicazione

La DLL è autonoma: i bundle HTML/CSS/JS, i temi e i dizionari di lingua sono incorporati come risorse. Nessun file web su disco, nessuna cartella aggiuntiva da copiare.

Sul lato PowerBuilder, `pbtoolboxai.pbl` viene integrata nella propria applicazione come qualsiasi altra libreria (come `.pbl` in sviluppo, come `.pbd` o compilata nell'eseguibile in produzione).

### Un solo nome di DLL per 32 e 64 bit #

La libreria viene fornita in due file con lo stesso nome, in due cartelle separate:

Cartella fornita | File | Da distribuire con
--- | --- | ---
`x86\` | `pbtoolboxai.dll` | l'IDE PowerBuilder (sempre a 32 bit) e gli eseguibili a 32 bit
`x64\` | `pbtoolboxai.dll` | gli eseguibili a 64 bit

Conseguenza pratica: le dichiarazioni external functions citano un solo nome, `pbtoolboxai.dll`. Si sviluppa e si esegue il debug nell'IDE a 32 bit, poi si compila un eseguibile a 64 bit senza modificare una riga di PowerScript: cambia solo il file distribuito.

> Clessidra durante un'operazione lunga. `SetPointer(HourGlass!)` copre solo le zone PowerBuilder: un componente è un WebView2, gira in un altro processo e continua a mostrare il cursore normale — lo schermo dice «cliccami» mentre nessuno ascolta. `PBT_SetBusy(1)` chiede a tutti i componenti di mostrare la clessidra, compresi quelli che nascono durante l'attesa; `PBT_SetBusy(0)` la toglie. Racchiudete così le vostre operazioni lunghe, come già fate con `SetPointer`.

> ⚠️ Poiché i due file hanno lo stesso nome, non devono mai trovarsi nella stessa cartella.

> ℹ️ Per i 64 bit non c'è altro da cambiare. Gli handle di finestra attraversano l'API della libreria su 32 bit: Windows garantisce che gli handle di finestra stiano in 32 bit significativi, proprio per questo passaggio. La dichiarazione `long` portata da `u_pbt_base` è quindi esatta su entrambi i target: non si tocca né il nome della libreria né una sola riga di PowerScript. Nessun `longptr` è richiesto e la soglia resta PowerBuilder 10.2.

## 1.3 Integrazione nell'IDE PowerBuilder #

1. Copiare `pbtoolboxai.pbl` nella cartella della propria applicazione.
2. Library list del target → aggiungere `pbtoolboxai.pbl`.
3. Copiare `pbtoolboxai.dll` — la copia x86, poiché l'IDE PowerBuilder è a 32 bit — accanto a `pbXXX.exe` oppure nella cartella di lavoro del target, affinché l'IDE la trovi durante l'esecuzione dall'IDE.
4. Le dichiarazioni external functions si trovano già su `u_pbt_base`: niente da ridichiarare per utilizzare un componente.

### Dichiarazioni globali (facoltativo) #

Alcune funzioni sono globali al processo (tema predefinito, lingua, senso di lettura, licenza). Non dipendono da alcun componente: dichiararle nell'oggetto applicazione (`Local External Functions` dell'oggetto `application`), quindi richiamarle nell'event `open`.

    // Dichiarazioni - oggetto applicazione, scheda "Local External Functions"
    Function long PBT_SetLicense (string as_client, string as_key) Library "pbtoolboxai.dll"
    Function long PBT_SetDefaultTheme (string as_name) Library "pbtoolboxai.dll"
    Function long PBT_SetDefaultThemeAccent (long al_accent) Library "pbtoolboxai.dll"
    Function long PBT_SetLanguage (string as_lang) Library "pbtoolboxai.dll"
    Function long PBT_SetFlowDirection (string as_dir) Library "pbtoolboxai.dll"
    Function long PBT_SetBusy (long al_on) Library "pbtoolboxai.dll"
    Function long PBT_Warmup () Library "pbtoolboxai.dll"

    // Event open dell'oggetto applicazione
    PBT_SetLicense(gs_titulaire, gs_cle_licence)      // sblocca la libreria
    PBT_SetDefaultTheme("fluent-dark")  // tema applicato PRIMA del primo rendering
    PBT_SetLanguage("fr")               // lingua dell'interfaccia dei componenti
    PBT_Warmup()                        // preriscalda il motore WebView2

    Open(w_principale)

> ⚠️ Il nome della libreria è lo stesso a 32 e a 64 bit: queste dichiarazioni restano identiche qualunque sia il target compilato.

## 1.4 Verificare il runtime all'avvio (consigliato) #

Due modi complementari:

    // 1. Sul componente: l'event ue_runtime_missing viene attivato se WebView2 manca
    event ue_runtime_missing   // sul proprio componente
    MessageBox("PBToolboxAI", "Il componente Microsoft WebView2 è obbligatorio.")

    // 2. A freddo, senza componente: PBT_CheckRuntime restituisce la versione installata
    string ls_version
    long ll_rc

    ls_version = Space(64)
    ll_rc = PBT_CheckRuntime(ls_version, 64)
    if ll_rc <= 0 then
        MessageBox("PBToolboxAI", "Runtime WebView2 assente: installarlo prima di continuare.")
    end if

## 1.5 Preriscaldamento (prestazioni di avvio) #

Il primo componente creato paga l'avvio del processo Edge (qualche centinaio di millisecondi). `PBT_Warmup()` avvia questo processo mentre l'applicazione carica il resto:

    // Event open dell'oggetto applicazione, PRIMA dell'apertura della prima finestra
    PBT_Warmup()

Senza preriscaldamento tutto funziona: la prima finestra compare semplicemente un po' più lentamente.

## 1.6 Cartella dati di WebView2 #

Ogni applicazione ottiene la propria cartella di cache in `%LOCALAPPDATA%\PBToolboxAI\WebView2\<nom_exe>` — mai accanto all'eseguibile (spesso non scrivibile in `Program Files`). Viene creata automaticamente; nessuna azione richiesta, nessun diritto particolare.

## 1.7 Disinstallazione #

Rimuovere la DLL e la PBL dalla propria distribuzione. La cache può essere eliminata in `%LOCALAPPDATA%\PBToolboxAI`. Il runtime WebView2, condiviso con Windows e con altre applicazioni, si lascia al suo posto.

## 1.8 Elenco di controllo per la messa in servizio #

- [ ] `pbtoolboxai.dll` (x86 / x64) accanto all'eseguibile (e a `pbXXX.exe` per l'IDE)
- [ ] `pbtoolboxai.pbl` nella library list
- [ ] `PBT_SetLicense` richiamata nell'event `open` dell'applicazione (Licenza)
- [ ] `PBT_SetDefaultTheme` richiamata prima dell'apertura della prima finestra (Temi)
- [ ] `PBT_Warmup` richiamata una volta all'avvio
- [ ] Runtime WebView2 verificato sulla postazione di destinazione

← Sommario · Primi passi →