# 1. Instalação e implementação #

← Índice · Primeiros passos →

## 1.1 Pré-requisitos #

Elemento | Detalhe
--- | ---
PowerBuilder | 10.2 → 2025 (32 bits ou 64 bits)
Windows | 10 / 11, Server 2016 e superior
Runtime WebView2 Evergreen | Pré-instalado no Windows 10/11 atualizado. No Windows Server ou LTSC, instalá-lo uma vez com o bootstrapper `MicrosoftEdgeWebview2Setup.exe` (~2 MB, silencioso: `/silent /install`)

Não há mais nada a instalar: sem .NET, sem ActiveX, sem PBNI, sem registo COM, sem direitos de administrador para a própria biblioteca.

## 1.2 Ficheiros a implementar #

Implementação xcopy, junto ao executável:

    mon_appli.exe
    pbtoolboxai.dll        <- copia x86 ou x64, conforme a aplicacao

A DLL é autónoma: os bundles HTML/CSS/JS, os temas e os dicionários de idioma estão incorporados como recursos. Nenhum ficheiro web em disco, nenhuma pasta anexa a copiar.

Do lado do PowerBuilder, `pbtoolboxai.pbl` é integrada na aplicação como qualquer outra biblioteca (em `.pbl` em desenvolvimento, em `.pbd` ou compilada no executável em produção).

### Um único nome de DLL para 32 e 64 bits #

A biblioteca é fornecida em dois ficheiros com o mesmo nome, em duas pastas separadas:

Pasta fornecida | Ficheiro | A implementar com
--- | --- | ---
`x86\` | `pbtoolboxai.dll` | o IDE PowerBuilder (sempre de 32 bits) e os executáveis de 32 bits
`x64\` | `pbtoolboxai.dll` | os executáveis de 64 bits

Consequência prática: as declarações external functions citam um único nome, `pbtoolboxai.dll`. Desenvolve-se e depura-se no IDE de 32 bits e depois compila-se um executável de 64 bits sem alterar uma linha de PowerScript: muda apenas o ficheiro implementado.

> Ampulheta durante uma operação longa. `SetPointer(HourGlass!)` só cobre as zonas PowerBuilder: um componente é um WebView2, corre noutro processo e continua a mostrar o seu cursor normal — o ecrã diz «clica-me» enquanto ninguém escuta. `PBT_SetBusy(1)` pede a todos os componentes que mostrem a ampulheta, incluindo os que nascem durante a espera; `PBT_SetBusy(0)` retira-a. Envolva assim as suas operações longas, como já faz com `SetPointer`.

> ⚠️ Como os dois ficheiros têm o mesmo nome, nunca devem coexistir na mesma pasta.

> ℹ️ Não há mais nada a alterar para 64 bits. Os handles de janela atravessam a API da biblioteca em 32 bits — o Windows garante que os handles de janela cabem em 32 bits significativos, precisamente para esta passagem. A declaração `long` mantida por `u_pbt_base` é portanto exata em ambos os targets: não mexe no nome da biblioteca nem numa única linha de PowerScript. Nenhum `longptr` é necessário, e o mínimo continua a ser o PowerBuilder 10.2.

## 1.3 Integração no IDE PowerBuilder #

1. Copiar `pbtoolboxai.pbl` para a pasta da aplicação.
2. Library list do target → adicionar `pbtoolboxai.pbl`.
3. Copiar `pbtoolboxai.dll` — a cópia x86, uma vez que o IDE PowerBuilder é de 32 bits — junto a `pbXXX.exe` ou para a pasta de trabalho do target, para que o IDE a encontre ao executar a partir do IDE.
4. As declarações external functions já são fornecidas por `u_pbt_base`: nada a redeclarar para utilizar um componente.

### Declarações globais (opcional) #

Algumas funções são globais ao processo (tema predefinido, idioma, sentido de leitura, licença). Não dependem de nenhum componente: devem ser declaradas no objeto application (`Local External Functions` do objeto `application`) e depois chamadas no event `open`.

    // Declarations - objeto application, separador "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 do objeto application
    PBT_SetLicense(gs_titulaire, gs_cle_licence)      // desbloqueia a biblioteca
    PBT_SetDefaultTheme("fluent-dark")  // tema aplicado ANTES da primeira apresentacao
    PBT_SetLanguage("fr")               // idioma da interface dos componentes
    PBT_Warmup()                        // pre-aquece o motor WebView2

    Open(w_principale)

> ⚠️ O nome da biblioteca é o mesmo em 32 e em 64 bits: estas declarações mantêm-se idênticas qualquer que seja o target compilado.

## 1.4 Verificar o runtime no arranque (recomendado) #

Dois meios complementares:

    // 1. No componente: o event ue_runtime_missing e levantado se o WebView2 estiver ausente
    event ue_runtime_missing   // no seu componente
    MessageBox("PBToolboxAI", "O componente Microsoft WebView2 é necessário.")

    // 2. A frio, sem componente: PBT_CheckRuntime devolve a versao 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: instale-o antes de continuar.")
    end if

## 1.5 Pré-aquecimento (desempenho de arranque) #

O primeiro componente criado paga o arranque do processo Edge (algumas centenas de milissegundos). `PBT_Warmup()` desencadeia esse arranque enquanto a aplicação carrega o resto:

    // Event open do objeto application, ANTES da abertura da primeira window
    PBT_Warmup()

Sem pré-aquecimento tudo funciona: a primeira window limita-se a aparecer um pouco mais lentamente.

## 1.6 Pasta de dados do WebView2 #

Cada aplicação obtém a sua própria pasta de cache em `%LOCALAPPDATA%\PBToolboxAI\WebView2\<nom_exe>` — nunca junto ao executável (muitas vezes não gravável em `Program Files`). É criada automaticamente; nenhuma ação é necessária, nenhum direito especial.

## 1.7 Desinstalação #

Basta remover a DLL e a PBL da entrega. A cache pode ser eliminada em `%LOCALAPPDATA%\PBToolboxAI`. O runtime WebView2, partilhado com o Windows e outras aplicações, deve ser deixado no lugar.

## 1.8 Lista de verificação de entrada em serviço #

- [ ] `pbtoolboxai.dll` (x86 / x64) junto ao executável (e a `pbXXX.exe` para o IDE)
- [ ] `pbtoolboxai.pbl` na library list
- [ ] `PBT_SetLicense` chamado no event `open` da aplicação (Licença)
- [ ] `PBT_SetDefaultTheme` chamado antes da abertura da primeira window (Temas)
- [ ] `PBT_Warmup` chamado uma vez no arranque
- [ ] Runtime WebView2 verificado no posto de destino

← Índice · Primeiros passos →