# 7. FAQ e risoluzione dei problemi #

← Funzioni trasversali · Sommario · Licenza →

## Installazione e avvio #

### Il componente resta grigio o vuoto #

Causa | Come riconoscerla | Soluzione
--- | --- | ---
Runtime WebView2 assente | L'event `ue_runtime_missing` viene attivato, `of_is_created()` restituisce `false` | Installare il runtime — vedere Installazione
DLL non trovata | Errore PowerBuilder di external function fin dalla prima chiamata | `pbtoolboxai.dll` (copia x86 o x64) accanto all'eseguibile — e accanto a `pbXXX.exe` per l'esecuzione dall'IDE
Architettura errata | Stesso errore, ma solo a 32 o solo a 64 bit | La DLL deve corrispondere al bitness di PowerBuilder
Thread UI bloccato | Il componente si disegna non appena la Sua elaborazione termina | Vedere qui sotto

### « Thread UI bloccato »: la trappola più comune #

L'inizializzazione della webview è asincrona: ha bisogno che il ciclo di messaggi di Windows sia in esecuzione. Un lungo ciclo PowerScript eseguito nell'`open` della finestra, prima di restituire il controllo, impedisce al componente di completare il caricamento.

    // DA EVITARE : il componente resta grigio per tutta l'elaborazione
    uo_grid.of_add_column("nom", "Nome", 200)
    of_charger_50000_lignes()      // 8 secondi senza restituire il controllo

    // PREFERIRE : lasciare che la finestra si visualizzi, POI caricare
    this.PostEvent("ue_charger")

### Il componente perde il tema / torna chiaro dopo un po' #

Probabilmente ha riutilizzato un'istanza senza azzerarla, oppure ha impostato un tema locale che non è mai stato annullato. Chiami `of_reset()` prima di visualizzare un contenuto diverso e imposti il tema globalmente con `PBT_SetDefaultTheme` anziché componente per componente (Temi).

## Comportamento durante l'esecuzione #

### Le proprietà impostate nel `constructor` sembrano ignorate #

Non lo sono: i comandi emessi prima di `ue_ready` vengono messi in coda e riprodotti nell'ordine. Se la visualizzazione non corrisponde, quasi sempre è un comando successivo che sovrascrive il primo — oppure il componente non è mai stato azzerato tra due utilizzi.

### Persiste un « residuo » della visualizzazione precedente #

Causa numero uno delle anomalie visive: `of_reset()` non è stato chiamato. Riutilizzare un'istanza per visualizzare altro conserva tutto ciò che è stato impostato (colori, modalità, altezza automatica, item). Verifichi che `of_reset()` sia davvero chiamato prima di concludere che sia difettoso.

### Rileggere una proprietà non riflette ciò che fa l'utente #

Verificate innanzitutto se un event annuncia questo cambiamento: quando esiste, aggiorna la proprietà per strada e la rilettura restituisce lo stato reale (`is_address` segue il collegamento che l'utente apre, `is_text` la sua digitazione). Altrimenti la lettura restituisce l'ultimo valore impostato da PowerBuilder (cache PB) — e allora l'event, con il suo valore come parametro, resta l'unico canale (Base comune).

### Un event non si attiva mai #

- Event del mouse ambientali (`ue_mouse_enter`, `ue_mouse_leave`, `ue_rclicked`): sono opt-in, imposti `ib_track_mouse = true`. Del resto sono pubblicati solo dai componenti in cui hanno senso.
- `ue_auto_height` / `ue_auto_width`: anch'essi opt-in (`ib_auto_height`, `ib_auto_width`), pubblicati da un elenco preciso di componenti. Eccezione: su `ribbon` e `toolbar`, `ue_auto_height` è sempre attivo (altezza intrinseca, nessuna proprietà da impostare).
- Event scritto nel posto sbagliato: lo scriva sul controllo posato nella finestra, oppure su un userobject ereditato dal componente — non su `u_pbt_base`.

### Un menu o un tooltip resta visualizzato #

I menu e i tooltip sono vere finestre di sistema: si chiudono al clic altrove, con Esc, alla perdita del primo piano, e il tooltip scompare al più tardi dopo 10 secondi. Un caso residuo: distruggere il componente mentre uno dei suoi menu è aperto — lo chiuda prima.

### Non appare alcun tooltip #

È voluto: i tooltip non si attivano se la Sua applicazione non ha il focus. Clicchi prima nella finestra.

## Immagini e icone #

### Un'immagine non appare #

- Il percorso deve essere raggiungibile sulla macchina di esecuzione (di preferenza un percorso assoluto, oppure relativo alla cartella di lavoro).
- Formati: PNG, JPG, GIF, BMP, ICO, SVG, WEBP. Un'immagine non trovata viene semplicemente nascosta, senza bloccare il componente.
- Risorsa di DLL: la sintassi è `percorso_completo.dll:NOME_RISORSA` (un nome di risorsa, non un nome di file).

### Un'icona `mono:` appare vuota o deformata #

Un'icona `mono:` è una maschera: non ha una dimensione naturale. Se il componente non la dimensiona (caso raro, al di fuori dei componenti standard), le assegni esplicitamente una dimensione — per esempio `[picture=mono:img\ok.svg,16,16]` nel testo formattato con tag.

### Ho sostituito un'immagine su disco, viene ancora visualizzata quella vecchia #

Le immagini sono memorizzate nella cache per 5 minuti per evitare lo sfarfallio al nuovo rendering. Per un'immagine modificata a caldo, aggiunga un suffisso variabile al percorso (`img\logo.png?v=2`).

## Prestazioni #

### Il primo componente è lento a comparire #

È l'avvio del processo Edge, pagato una sola volta. Chiami `PBT_Warmup()` all'avvio dell'applicazione: il costo viene assorbito durante il caricamento del resto (Installazione).

### La visualizzazione sfarfalla mentre costruisco il contenuto #

Racchiuda la costruzione:

    uo_grid.of_set_redraw(false)
    … aggiunte e assegnazioni …
    uo_grid.of_set_redraw(true)

### Alimentare un componente da un DataStore è lento #

Il trasferimento in sé è lineare e rapido. Il costo dominante è a monte: il Suo `Retrieve()` o la Sua generazione di dati in PowerScript. Su grandi volumi generati nel codice, alimenti il DataStore a blocchi — la concatenazione di una stringa di diversi megabyte è quadratica in PowerScript.

## Convivenza con PowerBuilder #

### Un controllo PowerBuilder ospitato passa sopra a tutto #

È il comportamento previsto: un controllo ospitato (pagina di scheda, pannello ancorabile) è una finestra nativa, disegnata sopra il livello web. In compenso, le Sue DataWindow restano nitide e rapide. Nessun effetto web può passarvi sopra.

### Il componente diventa bianco quando sono fermo nel debugger #

Comportamento strutturale di WebView2: il thread UI è congelato dal debugger, la webview non può più presentarsi. L'applicazione compilata non è interessata. Riprenda l'esecuzione e la visualizzazione ritorna.

### Ci sono processi `msedgewebview2` che rimangono attivi? #

No: ogni componente rilascia la propria webview alla distruzione, gestita dal `destructor` dell'userobject nel normale flusso di chiusura della finestra.

### Gli accenti vengono visualizzati male #

Passi le Sue etichette in chiaro da PowerBuilder (stringhe PB standard). Per i caratteri fuori tastiera, usi `Char()` — per esempio `Char(8364)` per il simbolo dell'euro — anziché un byte di code page.

## Varie #

### Un'esportazione di file non riesce #

L'event di ritorno (`ue_file_saved`, `ue_xlsx_saved`…) porta `ab_ok = false` e un messaggio. Cause frequenti: cartella non scrivibile (`Program Files`), file già aperto in un'altra applicazione. Scriva in una cartella utente (`%TEMP%`, `%LOCALAPPDATA%`).

### Appare il badge « DEMO » #

La licenza non è attiva in questo contesto — vedere Licenza e modalità demo.

### Codici di ritorno dei metodi `of_*` #

Ritorno | Significato
--- | ---
`≥ 0` | OK (applicato, oppure messo in coda)
`-2` | Componente non creato (runtime assente, host non valido) — verifichi `of_is_created()`
`-4` | Operazione non riuscita (schermata, scrittura di file…)
`-5` | Argomento non valido (identificatore vuoto, valore fuori dai limiti)

Dettaglio dell'ultimo errore: `of_get_last_error()`.

## Chiedere aiuto #

Alleghi alla Sua richiesta:

- la versione di PowerBuilder e il bitness (32 / 64);
- la versione di Windows;
- la versione della libreria (`PBT_GetVersion`) e del runtime WebView2 (`PBT_CheckRuntime`);
- lo stato della licenza (`PBT_LicenseStatus`);
- un estratto di codice minimo che riproduce il caso.

← Funzioni trasversali · Sommario · Licenza →