1. Installazione e distribuzione #

← Sommario · Primi passi →

1.1 Prerequisiti #

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:

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 →