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

← Índice · Primeiros passos →

1.1 Pré-requisitos #

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:

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 →