# 1. Installation und Verteilung #

← Inhalt · Erste Schritte →

## 1.1 Voraussetzungen #

Element | Detail
--- | ---
PowerBuilder | 10.2 → 2025 (32 Bit oder 64 Bit)
Windows | 10 / 11, Server 2016 und höher
WebView2-Evergreen-Runtime | Auf aktuellen Windows 10/11 vorinstalliert. Unter Windows Server oder LTSC einmalig mit dem Bootstrapper `MicrosoftEdgeWebview2Setup.exe` installieren (~2 MB, unbeaufsichtigt: `/silent /install`)

Es gibt nichts weiter zu installieren: kein .NET, kein ActiveX, kein PBNI, keine COM-Registrierung und keine Administratorrechte für die Bibliothek selbst.

## 1.2 Auszuliefernde Dateien #

Verteilung per xcopy, neben Ihre ausführbare Datei:

    mon_appli.exe
    pbtoolboxai.dll        <- x86- oder x64-Exemplar, passend zur Anwendung

Die DLL ist eigenständig: Die HTML/CSS/JS-Bundles, die Designs und die Sprachwörterbücher sind als Ressourcen eingebettet. Keine Webdateien auf der Festplatte, kein zusätzlicher Ordner zum Kopieren.

Auf PowerBuilder-Seite wird `pbtoolboxai.pbl` wie jede andere Bibliothek in Ihre Anwendung eingebunden (als `.pbl` in der Entwicklung, als `.pbd` oder in die ausführbare Datei kompiliert in der Produktion).

### Ein einziger DLL-Name für 32 und 64 Bit #

Die Bibliothek wird als zwei Dateien mit demselben Namen ausgeliefert, in zwei getrennten Ordnern:

Ausgelieferter Ordner | Datei | Auszuliefern mit
--- | --- | ---
`x86\` | `pbtoolboxai.dll` | der PowerBuilder-IDE (immer 32 Bit) und 32-Bit-Anwendungen
`x64\` | `pbtoolboxai.dll` | 64-Bit-Anwendungen

Praktische Folge: Ihre External-Function-Deklarationen nennen einen einzigen Namen, `pbtoolboxai.dll`. Sie entwickeln und debuggen in der 32-Bit-IDE und kompilieren anschließend eine 64-Bit-Anwendung, ohne eine Zeile PowerScript zu ändern — nur die ausgelieferte Datei ist eine andere.

> Sanduhr während eines langen Vorgangs. `SetPointer(HourGlass!)` deckt nur die PowerBuilder-Bereiche ab: eine Komponente ist ein WebView2, läuft in einem anderen Prozess und zeigt weiterhin ihren normalen Cursor — der Bildschirm sagt „klick mich“, während niemand zuhört. `PBT_SetBusy(1)` weist alle Komponenten an, die Sanduhr zu zeigen, auch die während der Wartezeit entstehenden; `PBT_SetBusy(0)` hebt sie auf. Klammern Sie damit Ihre langen Vorgänge ein, wie Sie es mit `SetPointer` bereits tun.

> ⚠️ Da beide Dateien denselben Namen tragen, dürfen sie niemals im selben Ordner liegen.

> ℹ️ Für 64 Bit ist sonst nichts zu ändern. Fensterhandles überqueren die API der Bibliothek mit 32 Bit — Windows garantiert, dass Fensterhandles 32 signifikante Bits tragen, genau für diesen Übergang. Die von `u_pbt_base` gehaltene `long`-Deklaration ist daher auf beiden Zielen exakt: Sie ändern weder den Namen der Bibliothek noch eine einzige Zeile PowerScript. Kein `longptr` erforderlich, und die Untergrenze bleibt PowerBuilder 10.2.

## 1.3 Integration in die PowerBuilder-IDE #

1. Kopieren Sie `pbtoolboxai.pbl` in den Ordner Ihrer Anwendung.
2. Library list des Ziels → `pbtoolboxai.pbl` hinzufügen.
3. Kopieren Sie `pbtoolboxai.dll` — das x86-Exemplar, da die PowerBuilder-IDE 32 Bit ist — neben `pbXXX.exe` oder in den Arbeitsordner des Ziels, damit die IDE sie beim Ausführen aus der IDE findet.
4. Die External-Function-Deklarationen liegen bereits auf `u_pbt_base`: nichts neu zu deklarieren, um eine Komponente zu verwenden.

### Globale Deklarationen (optional) #

Einige Funktionen gelten prozessweit (Standarddesign, Sprache, Leserichtung, Lizenz). Sie hängen von keiner Komponente ab: Deklarieren Sie sie im Anwendungsobjekt (`Local External Functions` des Objekts `application`) und rufen Sie sie dann im Event `open` auf.

    // Deklarationen - Anwendungsobjekt, Registerkarte "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 des Anwendungsobjekts
    PBT_SetLicense(gs_titulaire, gs_cle_licence)      // schaltet die Bibliothek frei
    PBT_SetDefaultTheme("fluent-dark")  // Design wird VOR der ersten Darstellung angewendet
    PBT_SetLanguage("fr")               // Sprache der Benutzeroberflaeche der Komponenten
    PBT_Warmup()                        // waermt die WebView2-Engine vor

    Open(w_principale)

> ⚠️ Der Name der Bibliothek ist unter 32 und 64 Bit derselbe: Diese Deklarationen bleiben unabhängig vom kompilierten Ziel identisch.

## 1.4 Die Runtime beim Start prüfen (empfohlen) #

Zwei sich ergänzende Wege:

    // 1. Auf der Komponente: das Event ue_runtime_missing wird ausgeloest, wenn WebView2 fehlt
    event ue_runtime_missing   // auf Ihrer Komponente
    MessageBox("PBToolboxAI", "Die Komponente Microsoft WebView2 ist erforderlich.")

    // 2. Kalt, ohne Komponente: PBT_CheckRuntime liefert die installierte 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 fehlt: Installieren Sie sie, bevor Sie fortfahren.")
    end if

## 1.5 Vorwärmen (Startleistung) #

Die erste erstellte Komponente zahlt den Start des Edge-Prozesses (einige Hundert Millisekunden). `PBT_Warmup()` stößt diesen Start an, während Ihre Anwendung den Rest lädt:

    // Event open des Anwendungsobjekts, VOR dem Oeffnen des ersten Fensters
    PBT_Warmup()

Ohne Vorwärmen funktioniert alles: Das erste Fenster erscheint lediglich etwas langsamer.

## 1.6 WebView2-Datenordner #

Jede Anwendung erhält ihren eigenen Cache-Ordner unter `%LOCALAPPDATA%\PBToolboxAI\WebView2\<nom_exe>` — niemals neben der ausführbaren Datei (unter `Program Files` oft nicht beschreibbar). Er wird automatisch angelegt; keine Aktion erforderlich, keine besonderen Rechte.

## 1.7 Deinstallation #

Entfernen Sie die DLL und die PBL aus Ihrer Auslieferung. Der Cache kann unter `%LOCALAPPDATA%\PBToolboxAI` gelöscht werden. Die WebView2-Runtime wird mit Windows und anderen Anwendungen geteilt und bleibt bestehen.

## 1.8 Checkliste für die Inbetriebnahme #

- [ ] `pbtoolboxai.dll` (x86 / x64) neben der ausführbaren Datei (und neben `pbXXX.exe` für die IDE)
- [ ] `pbtoolboxai.pbl` in der Library list
- [ ] `PBT_SetLicense` im Event `open` der Anwendung aufgerufen (Lizenz)
- [ ] `PBT_SetDefaultTheme` vor dem Öffnen des ersten Fensters aufgerufen (Designs)
- [ ] `PBT_Warmup` einmal beim Start aufgerufen
- [ ] WebView2-Runtime auf dem Zielrechner geprüft

← Inhalt · Erste Schritte →