# 7. FAQ e resolução de problemas #

← Funcionalidades transversais · Índice · Licença →

## Instalação e arranque #

### O componente permanece cinzento ou vazio #

Causa | Como reconhecê-la | Solução
--- | --- | ---
Runtime WebView2 ausente | O event `ue_runtime_missing` é acionado, `of_is_created()` devolve `false` | Instalar o runtime — ver Instalação
DLL não encontrada | Erro de external function do PowerBuilder logo na primeira chamada | `pbtoolboxai.dll` (cópia x86 ou x64) junto ao executável — e junto a `pbXXX.exe` para a execução a partir do IDE
Arquitetura incorreta | Idem, apenas em 32 ou apenas em 64 bits | A DLL tem de corresponder à arquitetura do PowerBuilder
Thread de interface bloqueado | O componente é desenhado assim que o processamento termina | Ver abaixo

### «Thread de interface bloqueado»: a armadilha mais comum #

A inicialização do webview é assíncrona: necessita que o ciclo de mensagens do Windows esteja a decorrer. Um ciclo PowerScript demorado executado no `open` da window, antes de devolver o controlo, impede o componente de concluir o carregamento.

    // A EVITAR : o componente permanece cinzento durante todo o processamento
    uo_grid.of_add_column("nom", "Nome", 200)
    of_charger_50000_lignes()      // 8 segundos sem devolver o controlo

    // PREFERIR : deixar a window aparecer e SO DEPOIS carregar
    this.PostEvent("ue_charger")

### O componente perde o tema / volta a ficar claro passado algum tempo #

É provável que uma instância tenha sido reutilizada sem ser reposta, ou que tenha sido atribuído um tema local que não foi anulado. Deve chamar-se `of_reset()` antes de apresentar outro conteúdo, e o tema global deve ser definido através de `PBT_SetDefaultTheme` em vez de componente a componente (Temas).

## Comportamento em execução #

### As propriedades atribuídas no `constructor` parecem ser ignoradas #

Não são: os comandos emitidos antes de `ue_ready` são colocados em fila e reexecutados pela mesma ordem. Se a apresentação não corresponder ao esperado, quase sempre é porque um comando posterior sobrepõe o primeiro — ou porque o componente nunca foi reposto entre duas utilizações.

### Persiste um «resto» da apresentação anterior #

Causa n.º 1 das anomalias visuais: `of_reset()` não foi chamado. Reutilizar uma instância para apresentar outro conteúdo mantém tudo o que foi atribuído (cores, modo, altura automática, items). Deve confirmar-se que `of_reset()` é efetivamente chamado antes de se concluir que está defeituoso.

### A releitura de uma propriedade não reflete o que o utilizador faz #

Verifique primeiro se um event anuncia essa alteração: quando existe, atualiza a propriedade de passagem e a releitura devolve o estado real (`is_address` segue a ligação que o utilizador abre, `is_text` segue o que escreve). Caso contrário, a leitura devolve o último valor atribuído a partir do PowerBuilder (cache PB) — e então o event, com o seu valor como parâmetro, é o único canal (Base comum).

### Um event nunca é acionado #

- Eventos de rato ambientais (`ue_mouse_enter`, `ue_mouse_leave`, `ue_rclicked`): são opt-in, é necessário definir `ib_track_mouse = true`. Além disso, só são publicados pelos componentes onde fazem sentido.
- `ue_auto_height` / `ue_auto_width`: igualmente opt-in (`ib_auto_height`, `ib_auto_width`), publicados por uma lista precisa de componentes. Exceção: no `ribbon` e na `toolbar`, `ue_auto_height` está sempre ativo (altura intrínseca, nenhuma propriedade a definir).
- Event programado no sítio errado: deve ser programado no controlo colocado na window, ou num userobject herdado do componente — nunca em `u_pbt_base`.

### Um menu ou um tooltip permanece visível #

Os menus e os tooltips são verdadeiras janelas do sistema: fecham-se ao clicar noutro sítio, com Esc, ao perder o primeiro plano, e o tooltip desaparece no máximo ao fim de 10 segundos. Existe um caso residual: destruir o componente enquanto um dos seus menus está aberto — deve fechar-se primeiro.

### Não aparece nenhum tooltip #

É intencional: os tooltips não são acionados se a aplicação não tiver o foco. Deve clicar-se primeiro na window.

## Imagens e ícones #

### Uma imagem não aparece #

- O caminho tem de estar acessível no posto de execução (de preferência caminho absoluto, ou relativo à pasta de trabalho).
- Formatos: PNG, JPG, GIF, BMP, ICO, SVG, WEBP. Uma imagem não encontrada é simplesmente ocultada, sem bloquear o componente.
- Recurso de DLL: a sintaxe é `caminho_completo.dll:NOME_DO_RECURSO` (nome de recurso, não um nome de ficheiro).

### Um ícone `mono:` aparece vazio ou deformado #

Um ícone `mono:` é uma máscara: não tem tamanho natural. Se o componente não o dimensionar (caso raro, fora dos componentes padrão), deve atribuir-se-lhe explicitamente um tamanho — por exemplo `[picture=mono:img\ok.svg,16,16]` em texto formatado.

### Substituí uma imagem no disco, mas continua a aparecer a anterior #

As imagens são colocadas em cache durante 5 minutos para evitar a cintilação ao voltar a desenhar. Para uma imagem alterada a quente, deve acrescentar-se um sufixo variável ao caminho (`img\logo.png?v=2`).

## Desempenho #

### O primeiro componente demora a aparecer #

Trata-se do arranque do processo Edge, pago uma única vez. Deve chamar-se `PBT_Warmup()` no arranque da aplicação: o custo é absorvido durante o carregamento do restante (Instalação).

### A apresentação cintila enquanto o conteúdo é construído #

A construção deve ser enquadrada:

    uo_grid.of_set_redraw(false)
    … adicoes e atribuicoes …
    uo_grid.of_set_redraw(true)

### Alimentar um componente a partir de um DataStore é lento #

A transferência em si é linear e rápida. O custo dominante está a montante: o `Retrieve()` ou a geração de dados em PowerScript. Em grandes volumes gerados por código, o DataStore deve ser alimentado por blocos — a concatenação de uma cadeia de vários megabytes é quadrática em PowerScript.

## Coexistência com o PowerBuilder #

### Um controlo PowerBuilder alojado fica por cima de tudo #

É o comportamento esperado: um controlo alojado (página de separador, painel acoplável) é uma janela nativa, desenhada por cima da camada web. Em contrapartida, as DataWindows mantêm-se nítidas e rápidas. Nenhum efeito web pode passar por cima.

### O componente fica branco quando estou parado no depurador #

Comportamento estrutural do WebView2: o thread de interface está congelado pelo depurador, o webview deixa de poder apresentar-se. A aplicação compilada não é afetada. Ao retomar a execução, a apresentação regressa.

### Existem processos `msedgewebview2` que ficam pendentes? #

Não: cada componente liberta o seu webview ao ser destruído, tarefa assegurada pelo `destructor` do userobject no fluxo normal de fecho da window.

### Os acentos aparecem incorretamente #

As etiquetas devem ser passadas em texto simples a partir do PowerBuilder (cadeias PB padrão). Para os caracteres fora do teclado, deve utilizar-se `Char()` — por exemplo `Char(8364)` para o símbolo do euro — em vez de um byte de página de código.

## Diversos #

### Uma exportação de ficheiro falha #

O event de retorno (`ue_file_saved`, `ue_xlsx_saved`…) traz `ab_ok = false` e uma mensagem. Causas frequentes: pasta sem permissão de escrita (`Program Files`), ficheiro já aberto noutra aplicação. Deve escrever-se numa pasta do utilizador (`%TEMP%`, `%LOCALAPPDATA%`).

### Aparece o emblema «DEMO» #

A licença não está ativa neste contexto — ver Licença e modo de demonstração.

### Códigos de retorno dos métodos `of_*` #

Retorno | Significado
--- | ---
`≥ 0` | OK (aplicado, ou colocado em fila)
`-2` | Componente não criado (runtime ausente, host inválido) — verificar `of_is_created()`
`-4` | Operação falhada (captura, escrita de ficheiro…)
`-5` | Argumento inválido (identificador vazio, valor fora dos limites)

Detalhe da última falha: `of_get_last_error()`.

## Pedir ajuda #

Ao pedido devem juntar-se:

- versão do PowerBuilder e arquitetura (32 / 64);
- versão do Windows;
- versão da biblioteca (`PBT_GetVersion`) e do runtime WebView2 (`PBT_CheckRuntime`);
- o estado da licença (`PBT_LicenseStatus`);
- um excerto de código mínimo que reproduza o caso.

← Funcionalidades transversais · Índice · Licença →