# 7. FAQ and troubleshooting #

← Cross-cutting features · Contents · License →

## Installation and startup #

### The component stays gray or empty #

Cause | How to recognize it | Fix
--- | --- | ---
WebView2 runtime missing | The `ue_runtime_missing` event is raised, `of_is_created()` returns `false` | Install the runtime — see Installation
DLL not found | A PowerBuilder external function error on the very first call | Put `pbtoolboxai.dll` (x86 or x64 copy) next to the executable — and next to `pbXXX.exe` to run from the IDE
Wrong architecture | Same error, but only in 32-bit or only in 64-bit | The DLL must match the bitness of PowerBuilder
UI thread blocked | The component paints as soon as your processing ends | See below

### "UI thread blocked": the most common pitfall #

Webview initialization is asynchronous: it needs the Windows message loop to run. A long PowerScript loop executed in the window `open`, before giving control back, prevents the component from finishing its load.

    // AVOID: the component stays gray for the whole processing
    uo_grid.of_add_column("nom", "Name", 200)
    of_charger_50000_lignes()      // 8 seconds without giving control back

    // PREFER: let the window display itself, THEN load
    this.PostEvent("ue_charger")

### The component loses its theme / turns light again after a while #

You have most likely reused an instance without resetting it, or set a local theme that was never cleared. Call `of_reset()` before displaying different content, and set the theme globally with `PBT_SetDefaultTheme` rather than component by component (Themes).

## Runtime behavior #

### The properties I set in the `constructor` seem to be ignored #

They are not: commands issued before `ue_ready` are queued and replayed in order. If the display does not match, it is almost always because a later command overwrites the first one — or because the component was never reset between two uses.

### A "leftover" from the previous display remains #

Cause number one of visual glitches: `of_reset()` was not called. Reusing an instance to display something else keeps everything that was set before (colors, mode, automatic height, items). Make sure `of_reset()` really is called before concluding that it is broken.

### Reading a property back does not reflect what the user is doing #

First check whether an event announces that change: when one exists, it refreshes the property on the way and reading back gives the real state (`is_address` follows the link the user clicks, `is_text` follows their typing). Otherwise, reading returns the last value set from PowerBuilder (the PB cache) — and the event, with its value as a parameter, is then the only channel (Shared foundation).

### An event never fires #

- Ambient mouse events (`ue_mouse_enter`, `ue_mouse_leave`, `ue_rclicked`): they are opt-in, set `ib_track_mouse = true`. They are also only published by the components where they make sense.
- `ue_auto_height` / `ue_auto_width`: opt-in as well (`ib_auto_height`, `ib_auto_width`), published by a specific list of components. Exception: on `ribbon` and `toolbar`, `ue_auto_height` is always active (intrinsic height, no property to set).
- Event scripted in the wrong place: script it on the control placed in the window, or on a userobject inherited from the component — not on `u_pbt_base`.

### A menu or a tooltip stays on screen #

Menus and tooltips are real system windows: they close when you click elsewhere, on Esc, and when the application loses the foreground, and a tooltip fades away after 10 seconds at the latest. One remaining case: destroying the component while one of its menus is open — close it first.

### No tooltip appears at all #

This is intentional: tooltips do not appear when your application does not have the focus. Click inside the window first.

## Images and icons #

### An image does not appear #

- The path must be reachable on the machine running the application (preferably an absolute path, or one relative to the working folder).
- Formats: PNG, JPG, GIF, BMP, ICO, SVG, WEBP. An image that cannot be found is simply hidden, without blocking the component.
- DLL resource: the syntax is `full_path.dll:RESOURCE_NAME` (a resource name, not a file name).

### A `mono:` icon appears empty or distorted #

A `mono:` icon is a mask: it has no natural size. If the component does not size it (a rare case, outside the standard components), give it an explicit size — for example `[picture=mono:img\ok.svg,16,16]` in rich text.

### I replaced an image on disk and the old one is still displayed #

Images are cached for 5 minutes to avoid flicker when re-rendering. For an image changed on the fly, add a varying suffix to the path (`img\logo.png?v=2`).

## Performance #

### The first component is slow to appear #

That is the Edge process starting up, paid only once. Call `PBT_Warmup()` when the application starts: the cost is absorbed while the rest loads (Installation).

### The display flickers while I build my content #

Wrap the construction:

    uo_grid.of_set_redraw(false)
    … additions and assignments …
    uo_grid.of_set_redraw(true)

### Feeding a component from a DataStore is slow #

The transfer itself is linear and fast. The dominant cost lies upstream: your `Retrieve()` or your data generation in PowerScript. For large volumes generated in code, fill the DataStore in blocks — concatenating a string of several megabytes is quadratic in PowerScript.

## Living alongside PowerBuilder #

### A hosted PowerBuilder control is drawn over everything #

That is the expected behavior: a hosted control (tab page, dockable panel) is a native window, painted above the web layer. In return, your DataWindows stay crisp and fast. No web effect can be drawn over it.

### The component turns white when I am stopped in the debugger #

Structural WebView2 behavior: the UI thread is frozen by the debugger, so the webview can no longer present itself. The compiled application is not affected. Resume execution and the display comes back.

### Are there `msedgewebview2` processes leaking? #

No: each component releases its webview when it is destroyed, handled by the userobject `destructor` in the normal window closing flow.

### Accented characters display incorrectly #

Pass your labels as plain text from PowerBuilder (standard PB strings). For characters not on the keyboard, use `Char()` — for example `Char(8364)` for the euro sign — rather than a code page byte.

## Miscellaneous #

### A file export fails #

The returning event (`ue_file_saved`, `ue_xlsx_saved`…) carries `ab_ok = false` and a message. Common causes: a folder that is not writable (`Program Files`), a file already open in another application. Write to a user folder (`%TEMP%`, `%LOCALAPPDATA%`).

### The "DEMO" badge appears #

The license is not active in this context — see License and demo mode.

### Return codes of the `of_*` methods #

Return | Meaning
--- | ---
`≥ 0` | OK (applied, or queued)
`-2` | Component not created (runtime missing, invalid host) — check `of_is_created()`
`-4` | Operation failed (screenshot, file write…)
`-5` | Invalid argument (empty identifier, value out of range)

Details of the last failure: `of_get_last_error()`.

## Asking for help #

Include in your request:

- your PowerBuilder version and bitness (32 / 64);
- your Windows version;
- the library version (`PBT_GetVersion`) and the WebView2 runtime version (`PBT_CheckRuntime`);
- the license state (`PBT_LicenseStatus`);
- a minimal code snippet that reproduces the case.

← Cross-cutting features · Contents · License →