# 1. Instalación e implementación #

← Índice · Primeros pasos →

## 1.1 Requisitos previos #

Elemento | Detalle
--- | ---
PowerBuilder | 10.2 → 2025 (32 bits o 64 bits)
Windows | 10 / 11, Server 2016 y posteriores
Runtime WebView2 Evergreen | Preinstalado en Windows 10/11 actualizados. En Windows Server o LTSC, instalarlo una vez con el bootstrapper `MicrosoftEdgeWebview2Setup.exe` (~2 MB, silencioso: `/silent /install`)

No hay nada más que instalar: ni .NET, ni ActiveX, ni PBNI, ningún registro COM, ningún derecho de administrador para la biblioteca en sí.

## 1.2 Archivos que implementar #

Implementación xcopy, junto a su ejecutable:

    mon_appli.exe
    pbtoolboxai.dll        <- copia x86 o x64, según su aplicación

La DLL es autónoma: los bundles HTML/CSS/JS, los temas y los diccionarios de idioma están incorporados como recursos. Ningún archivo web en disco, ninguna carpeta adicional que copiar.

Del lado de PowerBuilder, `pbtoolboxai.pbl` se integra en su aplicación como cualquier otra biblioteca (como `.pbl` en desarrollo, como `.pbd` o compilada en el ejecutable en producción).

### Un único nombre de DLL para 32 y 64 bits #

La biblioteca se entrega como dos archivos con el mismo nombre, en dos carpetas separadas:

Carpeta entregada | Archivo | Se implementa con
--- | --- | ---
`x86\` | `pbtoolboxai.dll` | el IDE de PowerBuilder (siempre de 32 bits) y los ejecutables de 32 bits
`x64\` | `pbtoolboxai.dll` | los ejecutables de 64 bits

Consecuencia práctica: sus declaraciones external functions citan un único nombre, `pbtoolboxai.dll`. Usted desarrolla y depura en el IDE de 32 bits y después compila un ejecutable de 64 bits sin cambiar una línea de PowerScript: solo cambia el archivo implementado.

> Reloj de arena durante una operación larga. `SetPointer(HourGlass!)` solo cubre las zonas PowerBuilder: un componente es un WebView2, se ejecuta en otro proceso y sigue mostrando su cursor normal — la pantalla dice «púlsame» mientras nadie escucha. `PBT_SetBusy(1)` pide a todos los componentes que muestren el reloj de arena, incluidos los que nacen durante la espera; `PBT_SetBusy(0)` lo retira. Encierre así sus operaciones largas, como ya hace con `SetPointer`.

> ⚠️ Como ambos archivos tienen el mismo nombre, nunca deben convivir en la misma carpeta.

> ℹ️ No hay nada más que cambiar para 64 bits. Los handles de ventana cruzan la API de la biblioteca en 32 bits: Windows garantiza que los handles de ventana caben en 32 bits significativos, precisamente para este paso. La declaración `long` que lleva `u_pbt_base` es por tanto exacta en ambos targets: no toca ni el nombre de la biblioteca ni una sola línea de PowerScript. No hace falta ningún `longptr`, y el mínimo sigue siendo PowerBuilder 10.2.

## 1.3 Integración en el IDE de PowerBuilder #

1. Copie `pbtoolboxai.pbl` en la carpeta de su aplicación.
2. Library list del target → añada `pbtoolboxai.pbl`.
3. Copie `pbtoolboxai.dll` — la copia x86, ya que el IDE de PowerBuilder es de 32 bits — junto a `pbXXX.exe` o en la carpeta de trabajo del target, para que el IDE la encuentre al ejecutar desde el IDE.
4. Las declaraciones external functions ya están en `u_pbt_base`: nada que volver a declarar para utilizar un componente.

### Declaraciones globales (opcional) #

Algunas funciones son globales al proceso (tema predeterminado, idioma, sentido de lectura, licencia). No dependen de ningún componente: declárelas en el objeto aplicación (`Local External Functions` del objeto `application`) y llámelas después en el evento `open`.

    // Declaraciones - objeto aplicacion, pestana "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"

    // Evento open del objeto aplicacion
    PBT_SetLicense(gs_titulaire, gs_cle_licence)      // desbloquea la biblioteca
    PBT_SetDefaultTheme("fluent-dark")  // tema aplicado ANTES de la primera representacion
    PBT_SetLanguage("fr")               // idioma de la interfaz de los componentes
    PBT_Warmup()                        // precalienta el motor WebView2

    Open(w_principale)

> ⚠️ El nombre de la biblioteca es el mismo en 32 y en 64 bits: estas declaraciones no cambian sea cual sea el target compilado.

## 1.4 Comprobar el runtime al arrancar (recomendado) #

Dos medios complementarios:

    // 1. En el componente: el evento ue_runtime_missing se activa si WebView2 falta
    event ue_runtime_missing   // en su componente
    MessageBox("PBToolboxAI", "El componente Microsoft WebView2 es obligatorio.")

    // 2. En frio, sin componente: PBT_CheckRuntime devuelve la version instalada
    string ls_version
    long ll_rc

    ls_version = Space(64)
    ll_rc = PBT_CheckRuntime(ls_version, 64)
    if ll_rc <= 0 then
        MessageBox("PBToolboxAI", "Runtime WebView2 ausente: instálelo antes de continuar.")
    end if

## 1.5 Precalentamiento (rendimiento de arranque) #

El primer componente creado paga el arranque del proceso Edge (unos cientos de milisegundos). `PBT_Warmup()` desencadena ese arranque mientras su aplicación carga el resto:

    // Evento open del objeto aplicacion, ANTES de abrir la primera ventana
    PBT_Warmup()

Sin precalentamiento todo funciona: la primera ventana simplemente aparece un poco más despacio.

## 1.6 Carpeta de datos de WebView2 #

Cada aplicación obtiene su propia carpeta de caché en `%LOCALAPPDATA%\PBToolboxAI\WebView2\<nom_exe>` — nunca junto al ejecutable (a menudo no grabable en `Program Files`). Se crea automáticamente; no requiere ninguna acción ni ningún derecho particular.

## 1.7 Desinstalación #

Elimine la DLL y la PBL de su entrega. La caché puede borrarse en `%LOCALAPPDATA%\PBToolboxAI`. El runtime WebView2, compartido con Windows y con otras aplicaciones, se deja en su sitio.

## 1.8 Lista de comprobación para la puesta en servicio #

- [ ] `pbtoolboxai.dll` (x86 / x64) junto al ejecutable (y a `pbXXX.exe` para el IDE)
- [ ] `pbtoolboxai.pbl` en la library list
- [ ] `PBT_SetLicense` llamada en el evento `open` de la aplicación (Licencia)
- [ ] `PBT_SetDefaultTheme` llamada antes de abrir la primera ventana (Temas)
- [ ] `PBT_Warmup` llamada una vez al arrancar
- [ ] Runtime WebView2 comprobado en el equipo de destino

← Índice · Primeros pasos →