# 1. Installation and deployment #

← Contents · Getting started →

## 1.1 Requirements #

Item | Details
--- | ---
PowerBuilder | 10.2 → 2025 (32-bit or 64-bit)
Windows | 10 / 11, Server 2016 and later
WebView2 Evergreen runtime | Preinstalled on up-to-date Windows 10/11. On Windows Server or LTSC, install it once with the `MicrosoftEdgeWebview2Setup.exe` bootstrapper (~2 MB, silent: `/silent /install`)

There is nothing else to install: no .NET, no ActiveX, no PBNI, no COM registration, and no administrator rights for the library itself.

## 1.2 Files to deploy #

An xcopy deployment, next to your executable:

    mon_appli.exe
    pbtoolboxai.dll        <- the x86 or x64 copy, matching your application

The DLL is self-contained: the HTML/CSS/JS bundles, the themes and the language dictionaries are embedded as resources. No web files on disk, no extra folder to copy.

On the PowerBuilder side, `pbtoolboxai.pbl` is added to your application like any other library (as a `.pbl` during development, as a `.pbd` or compiled into the executable in production).

### One DLL name for both 32-bit and 64-bit #

The library ships as two files with the same name, in two separate folders:

Folder shipped | File | Deploy with
--- | --- | ---
`x86\` | `pbtoolboxai.dll` | the PowerBuilder IDE (always 32-bit) and 32-bit executables
`x64\` | `pbtoolboxai.dll` | 64-bit executables

The practical consequence: your external function declarations name a single file, `pbtoolboxai.dll`. You develop and debug in the 32-bit IDE, then compile a 64-bit executable without changing a line of PowerScript — only the deployed file changes.

> Hourglass during a long operation. `SetPointer(HourGlass!)` only covers the PowerBuilder areas: a component is a WebView2, it runs in another process and keeps showing its normal cursor — the screen says "click me" while nothing is listening. `PBT_SetBusy(1)` asks every component to show the hourglass, including those born during the wait; `PBT_SetBusy(0)` clears it. Wrap your long operations in it, just as you already do with `SetPointer`.

> ⚠️ Since both files share the same name, they must never sit in the same folder.

> ℹ️ Nothing else to change for 64-bit. Window handles cross the library API on 32 bits — Windows guarantees that window handles carry 32 significant bits, precisely for this kind of crossing. The `long` declaration held by `u_pbt_base` is therefore exact on both targets: you change neither the library name nor a single line of PowerScript. No `longptr` is required, and the floor stays PowerBuilder 10.2.

## 1.3 Integrating with the PowerBuilder IDE #

1. Copy `pbtoolboxai.pbl` into your application folder.
2. Target Library list → add `pbtoolboxai.pbl`.
3. Copy `pbtoolboxai.dll` — the x86 copy, since the PowerBuilder IDE is 32-bit — next to `pbXXX.exe` or into the target's working folder, so that the IDE finds it when running from the IDE.
4. The external function declarations already live on `u_pbt_base`: nothing to redeclare in order to use a component.

### Global declarations (optional) #

A few functions are process-wide (default theme, language, reading direction, license). They do not depend on any component: declare them in the application object (`Local External Functions` of the `application` object), then call them from the `open` event.

    // Declarations - application object, "Local External Functions" tab
    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"

    // open event of the application object
    PBT_SetLicense(gs_titulaire, gs_cle_licence)      // unlocks the library
    PBT_SetDefaultTheme("fluent-dark")  // theme applied BEFORE the first rendering
    PBT_SetLanguage("fr")               // language of the component user interface
    PBT_Warmup()                        // warms up the WebView2 engine

    Open(w_principale)

> ⚠️ The library name is the same in 32-bit and 64-bit: these declarations stay identical whatever the compiled target.

## 1.4 Checking the runtime at startup (recommended) #

Two complementary ways:

    // 1. On the component: the ue_runtime_missing event is raised when WebView2 is missing
    event ue_runtime_missing   // on your component
    MessageBox("PBToolboxAI", "The Microsoft WebView2 component is required.")

    // 2. Cold, with no component: PBT_CheckRuntime returns the installed version
    string ls_version
    long ll_rc

    ls_version = Space(64)
    ll_rc = PBT_CheckRuntime(ls_version, 64)
    if ll_rc <= 0 then
        MessageBox("PBToolboxAI", "WebView2 runtime missing: install it before continuing.")
    end if

## 1.5 Warm-up (startup performance) #

The first component you create pays for starting the Edge process (a few hundred milliseconds). `PBT_Warmup()` triggers that startup while your application loads everything else:

    // open event of the application object, BEFORE opening the first window
    PBT_Warmup()

Everything works without the warm-up: the first window simply appears a little more slowly.

## 1.6 WebView2 data folder #

Each application gets its own cache folder under `%LOCALAPPDATA%\PBToolboxAI\WebView2\<nom_exe>` — never next to the executable (which is often not writable under `Program Files`). It is created automatically; no action required, no special rights.

## 1.7 Uninstalling #

Remove the DLL and the PBL from your delivery. The cache can be deleted under `%LOCALAPPDATA%\PBToolboxAI`. Leave the WebView2 runtime in place, as it is shared with Windows and other applications.

## 1.8 Go-live checklist #

- [ ] `pbtoolboxai.dll` (x86 / x64) next to the executable (and to `pbXXX.exe` for the IDE)
- [ ] `pbtoolboxai.pbl` in the library list
- [ ] `PBT_SetLicense` called from the application `open` event (License)
- [ ] `PBT_SetDefaultTheme` called before the first window opens (Themes)
- [ ] `PBT_Warmup` called once at startup
- [ ] WebView2 runtime checked on the target machine

← Contents · Getting started →