# 7. FAQ et dépannage #

← Fonctions transverses · Sommaire · Licence →

## Installation et démarrage #

### Le composant reste gris ou vide #

Cause | Comment la reconnaître | Solution
--- | --- | ---
Runtime WebView2 absent | L'event `ue_runtime_missing` est levé, `of_is_created()` renvoie `false` | Installer le runtime — voir Installation
DLL introuvable | Erreur PowerBuilder d'external function dès le premier appel | `pbtoolboxai.dll` (exemplaire x86 ou x64) à côté de l'exécutable — et à côté de `pbXXX.exe` pour l'exécution depuis l'IDE
Mauvaise architecture | Idem, seulement en 32 ou seulement en 64 bits | La DLL doit correspondre au bitness de PowerBuilder
Thread UI bloqué | Le composant se peint dès que votre traitement se termine | Voir ci-dessous

### « Thread UI bloqué » : le piège le plus courant #

L'initialisation du webview est asynchrone : elle a besoin que la boucle de messages Windows tourne. Une longue boucle PowerScript exécutée dans l'`open` de la fenêtre, avant de rendre la main, empêche le composant de terminer son chargement.

    // A EVITER : le composant reste gris pendant tout le traitement
    uo_grid.of_add_column("nom", "Nom", 200)
    of_charger_50000_lignes()      // 8 secondes sans rendre la main

    // PREFERER : laisser la fenetre s'afficher, PUIS charger
    this.PostEvent("ue_charger")

### Le composant se dé-thème / redevient clair après un moment #

Vous avez probablement réutilisé une instance sans la remettre à zéro, ou posé un thème local qui n'a pas été annulé. Appelez `of_reset()` avant de réafficher un autre contenu, et posez le thème global via `PBT_SetDefaultTheme` plutôt que composant par composant (Thèmes).

## Comportement à l'exécution #

### Mes propriétés posées dans le `constructor` semblent ignorées #

Elles ne le sont pas : les commandes émises avant `ue_ready` sont mises en file et rejouées dans l'ordre. Si l'affichage ne correspond pas, c'est presque toujours qu'une commande ultérieure écrase la première — ou que le composant n'a jamais été remis à zéro entre deux usages.

### Un « reste » de l'affichage précédent persiste #

Cause n°1 des anomalies visuelles : `of_reset()` n'a pas été appelé. Réutiliser une instance pour afficher autre chose conserve tout ce qui a été posé (couleurs, mode, hauteur automatique, items). Vérifiez que `of_reset()` est bien appelé avant de conclure qu'il est défaillant.

### Relire une propriété ne reflète pas ce que fait l'utilisateur #

Vérifiez d'abord qu'un event annonce ce changement : quand il en existe un, il rafraîchit la propriété au passage et la relecture donne l'état réel (`is_address` suit le lien que l'utilisateur clique, `is_text` suit sa frappe). Sinon, la lecture renvoie la dernière valeur posée depuis PowerBuilder (cache PB) — et c'est alors l'event, avec sa valeur en paramètre, qui reste le seul canal (Socle commun).

### Un event ne se déclenche jamais #

- Événements souris ambiants (`ue_mouse_enter`, `ue_mouse_leave`, `ue_rclicked`) : ils sont opt-in, posez `ib_track_mouse = true`. Ils ne sont d'ailleurs publiés que par les composants où ils ont un sens.
- `ue_auto_height` / `ue_auto_width` : opt-in également (`ib_auto_height`, `ib_auto_width`), publiés par une liste précise de composants. Exception : sur `ribbon` et `toolbar`, `ue_auto_height` est toujours actif (hauteur intrinsèque, aucune propriété à poser).
- Event scripté au mauvais endroit : scriptez-le sur le contrôle posé dans la fenêtre, ou sur un userobject hérité du composant — pas sur `u_pbt_base`.

### Un menu ou une info-bulle reste affiché #

Les menus et info-bulles sont de vraies fenêtres système : ils se ferment au clic ailleurs, sur Échap, sur perte du premier plan, et l'info-bulle s'efface au plus tard au bout de 10 secondes. Un cas résiduel : détruire le composant pendant qu'un de ses menus est ouvert — fermez d'abord.

### Aucune info-bulle ne s'affiche #

Volontaire : les info-bulles ne se déclenchent pas si votre application n'a pas le focus. Cliquez d'abord dans la fenêtre.

## Images et icônes #

### Une image ne s'affiche pas #

- Le chemin doit être accessible sur le poste d'exécution (chemin absolu de préférence, ou relatif au dossier de travail).
- Formats : PNG, JPG, GIF, BMP, ICO, SVG, WEBP. Une image introuvable est simplement masquée, sans bloquer le composant.
- Ressource de DLL : la syntaxe est `chemin_complet.dll:NOM_DE_RESSOURCE` (nom de ressource, pas un nom de fichier).

### Une icône `mono:` apparaît vide ou déformée #

Une icône `mono:` est un masque : elle n'a pas de taille naturelle. Si le composant ne la dimensionne pas (cas rare, hors des composants standard), donnez-lui explicitement une taille — par exemple `[picture=mono:img\ok.svg,16,16]` en texte riche.

### J'ai remplacé une image sur disque, l'ancienne s'affiche toujours #

Les images sont mises en cache 5 minutes pour éviter le scintillement au re-rendu. Pour une image modifiée à chaud, ajoutez un suffixe variable au chemin (`img\logo.png?v=2`).

## Performance #

### Le premier composant est lent à s'afficher #

C'est le démarrage du processus Edge, payé une seule fois. Appelez `PBT_Warmup()` au démarrage de l'application : le coût est absorbé pendant le chargement du reste (Installation).

### L'affichage scintille pendant que je construis mon contenu #

Encadrez la construction :

    uo_grid.of_set_redraw(false)
    … ajouts et affectations …
    uo_grid.of_set_redraw(true)

### Alimenter un composant depuis un DataStore est lent #

Le transfert lui-même est linéaire et rapide. Le coût dominant est en amont : votre `Retrieve()` ou votre génération de données en PowerScript. Sur de gros volumes générés en code, alimentez le DataStore par blocs — la concaténation d'une chaîne de plusieurs mégaoctets est quadratique en PowerScript.

## Cohabitation avec PowerBuilder #

### Un contrôle PowerBuilder hébergé passe au-dessus de tout #

C'est le comportement attendu : un contrôle hébergé (page d'onglet, panneau dockable) est une fenêtre native, dessinée au-dessus de la couche web. En contrepartie, vos DataWindows restent nettes et rapides. Aucun effet web ne peut passer par-dessus.

### Le composant devient blanc quand je suis à l'arrêt dans le débogueur #

Comportement structurel de WebView2 : le thread UI est gelé par le débogueur, le webview ne peut plus se présenter. L'application compilée n'est pas concernée. Reprenez l'exécution, l'affichage revient.

### Y a-t-il des processus `msedgewebview2` qui fuient ? #

Non : chaque composant libère son webview à sa destruction, prise en charge par le `destructor` de l'userobject dans le flux normal de fermeture de fenêtre.

### Les accents s'affichent mal #

Passez vos libellés en clair depuis PowerBuilder (chaînes PB standard). Pour les caractères hors clavier, utilisez `Char()` — par exemple `Char(8364)` pour le symbole euro — plutôt qu'un octet de page de code.

## Divers #

### Un export de fichier échoue #

L'event de retour (`ue_file_saved`, `ue_xlsx_saved`…) porte `ab_ok = false` et un message. Causes fréquentes : dossier non inscriptible (`Program Files`), fichier déjà ouvert dans une autre application. Écrivez dans un dossier utilisateur (`%TEMP%`, `%LOCALAPPDATA%`).

### Le badge « DEMO » apparaît #

La licence n'est pas active dans ce contexte — voir Licence et mode démo.

### Codes de retour des méthodes `of_*` #

Retour | Signification
--- | ---
`≥ 0` | OK (appliqué, ou mis en file)
`-2` | Composant non créé (runtime absent, hôte invalide) — vérifiez `of_is_created()`
`-4` | Opération échouée (capture, écriture de fichier…)
`-5` | Argument invalide (identifiant vide, valeur hors bornes)

Détail du dernier échec : `of_get_last_error()`.

## Demander de l'aide #

Joignez à votre demande :

- version de PowerBuilder et bitness (32 / 64) ;
- version de Windows ;
- version de la bibliothèque (`PBT_GetVersion`) et du runtime WebView2 (`PBT_CheckRuntime`) ;
- l'état de la licence (`PBT_LicenseStatus`) ;
- un extrait de code minimal reproduisant le cas.

← Fonctions transverses · Sommaire · Licence →