# 7. FAQ y resolución de problemas #

← Funciones transversales · Índice · Licencia →

## Instalación y arranque #

### El componente permanece gris o vacío #

Causa | Cómo reconocerla | Solución
--- | --- | ---
Runtime WebView2 ausente | El evento `ue_runtime_missing` se activa, `of_is_created()` devuelve `false` | Instalar el runtime — véase Instalación
DLL no encontrada | Error de PowerBuilder de external function desde la primera llamada | `pbtoolboxai.dll` (copia x86 o x64) junto al ejecutable — y junto a `pbXXX.exe` para la ejecución desde el IDE
Arquitectura incorrecta | El mismo error, pero solo en 32 o solo en 64 bits | La DLL debe corresponder al bitness de PowerBuilder
Hilo de interfaz bloqueado | El componente se dibuja en cuanto termina su procesamiento | Véase más abajo

### «Hilo de interfaz bloqueado»: la trampa más frecuente #

La inicialización de la webview es asíncrona: necesita que el bucle de mensajes de Windows esté en ejecución. Un bucle largo de PowerScript ejecutado en el `open` de la ventana, antes de devolver el control, impide que el componente termine su carga.

    // A EVITAR : el componente permanece gris durante todo el procesamiento
    uo_grid.of_add_column("nom", "Nombre", 200)
    of_charger_50000_lignes()      // 8 segundos sin devolver el control

    // PREFERIR : dejar que la ventana se muestre y DESPUES cargar
    this.PostEvent("ue_charger")

### El componente pierde el tema / vuelve a ser claro al cabo de un rato #

Lo más probable es que haya reutilizado una instancia sin ponerla a cero, o que haya asignado un tema local que nunca se anuló. Llame a `of_reset()` antes de mostrar un contenido distinto, y asigne el tema de forma global mediante `PBT_SetDefaultTheme` en lugar de componente por componente (Temas).

## Comportamiento en ejecución #

### Las propiedades que asigno en el `constructor` parecen ignorarse #

No lo son: los comandos emitidos antes de `ue_ready` se ponen en cola y se reproducen en orden. Si la visualización no coincide, casi siempre se debe a que un comando posterior sobrescribe al primero — o a que el componente nunca se puso a cero entre dos usos.

### Persiste un «resto» de la visualización anterior #

Causa número uno de las anomalías visuales: no se ha llamado a `of_reset()`. Reutilizar una instancia para mostrar otra cosa conserva todo lo que se había asignado (colores, modo, altura automática, items). Compruebe que `of_reset()` se llama realmente antes de concluir que está defectuoso.

### Releer una propiedad no refleja lo que hace el usuario #

Compruebe primero si un evento anuncia ese cambio: cuando existe, actualiza la propiedad de paso y la relectura devuelve el estado real (`is_address` sigue el enlace que abre el usuario, `is_text` sigue lo que escribe). Si no, la lectura devuelve el último valor asignado desde PowerBuilder (caché PB), y entonces el evento, con su valor como parámetro, es el único canal (Base común).

### Un evento no se activa nunca #

- Eventos de ratón ambientales (`ue_mouse_enter`, `ue_mouse_leave`, `ue_rclicked`): son opt-in, asigne `ib_track_mouse = true`. Además, solo los publican los componentes en los que tienen sentido.
- `ue_auto_height` / `ue_auto_width`: también opt-in (`ib_auto_height`, `ib_auto_width`), publicados por una lista concreta de componentes. Excepción: en `ribbon` y `toolbar`, `ue_auto_height` está siempre activo (altura intrínseca, ninguna propiedad que asignar).
- Evento programado en el lugar equivocado: prográmelo en el control colocado en la ventana, o en un userobject heredado del componente — no en `u_pbt_base`.

### Un menú o un tooltip permanece visible #

Los menús y los tooltips son verdaderas ventanas del sistema: se cierran al hacer clic en otro sitio, con Esc, al perder el primer plano, y el tooltip desaparece como muy tarde al cabo de 10 segundos. Un caso residual: destruir el componente mientras uno de sus menús está abierto — ciérrelo primero.

### No aparece ningún tooltip #

Es intencionado: los tooltips no se activan si su aplicación no tiene el foco. Haga clic primero en la ventana.

## Imágenes e iconos #

### Una imagen no se muestra #

- La ruta debe ser accesible en el equipo de ejecución (preferiblemente una ruta absoluta, o relativa a la carpeta de trabajo).
- Formatos: PNG, JPG, GIF, BMP, ICO, SVG, WEBP. Una imagen que no se encuentra simplemente se oculta, sin bloquear el componente.
- Recurso de DLL: la sintaxis es `ruta_completa.dll:NOMBRE_DE_RECURSO` (un nombre de recurso, no un nombre de archivo).

### Un icono `mono:` aparece vacío o deformado #

Un icono `mono:` es una máscara: no tiene tamaño natural. Si el componente no lo dimensiona (caso raro, fuera de los componentes estándar), asígnele explícitamente un tamaño — por ejemplo `[picture=mono:img\ok.svg,16,16]` en texto enriquecido con etiquetas.

### He sustituido una imagen en disco y sigue mostrándose la antigua #

Las imágenes se almacenan en caché durante 5 minutos para evitar el parpadeo al volver a representar. Para una imagen modificada en caliente, añada un sufijo variable a la ruta (`img\logo.png?v=2`).

## Rendimiento #

### El primer componente tarda en aparecer #

Es el arranque del proceso Edge, que se paga una sola vez. Llame a `PBT_Warmup()` al arrancar la aplicación: el coste se absorbe mientras se carga el resto (Instalación).

### La visualización parpadea mientras construyo mi contenido #

Enmarque la construcción:

    uo_grid.of_set_redraw(false)
    … adiciones y asignaciones …
    uo_grid.of_set_redraw(true)

### Alimentar un componente desde un DataStore es lento #

La transferencia en sí es lineal y rápida. El coste dominante está antes: su `Retrieve()` o su generación de datos en PowerScript. Con grandes volúmenes generados en código, alimente el DataStore por bloques — la concatenación de una cadena de varios megabytes es cuadrática en PowerScript.

## Convivencia con PowerBuilder #

### Un control de PowerBuilder alojado se dibuja por encima de todo #

Es el comportamiento previsto: un control alojado (página de pestaña, panel acoplable) es una ventana nativa, dibujada por encima de la capa web. A cambio, sus DataWindows se mantienen nítidas y rápidas. Ningún efecto web puede pasar por encima.

### El componente se vuelve blanco cuando estoy detenido en el depurador #

Comportamiento estructural de WebView2: el depurador congela el hilo de interfaz, por lo que la webview ya no puede presentarse. La aplicación compilada no se ve afectada. Reanude la ejecución y la visualización vuelve.

### ¿Hay procesos `msedgewebview2` que se queden colgados? #

No: cada componente libera su webview al destruirse, gestionado por el `destructor` del userobject en el flujo normal de cierre de la ventana.

### Los acentos se muestran mal #

Pase sus etiquetas en claro desde PowerBuilder (cadenas PB estándar). Para los caracteres fuera del teclado, utilice `Char()` — por ejemplo `Char(8364)` para el símbolo del euro — en lugar de un byte de página de códigos.

## Varios #

### Una exportación de archivo falla #

El evento de retorno (`ue_file_saved`, `ue_xlsx_saved`…) lleva `ab_ok = false` y un mensaje. Causas frecuentes: carpeta no grabable (`Program Files`), archivo ya abierto en otra aplicación. Escriba en una carpeta de usuario (`%TEMP%`, `%LOCALAPPDATA%`).

### Aparece el distintivo «DEMO» #

La licencia no está activa en este contexto — véase Licencia y modo demo.

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

Retorno | Significado
--- | ---
`≥ 0` | OK (aplicado, o puesto en cola)
`-2` | Componente no creado (runtime ausente, host no válido) — compruebe `of_is_created()`
`-4` | Operación fallida (captura, escritura de archivo…)
`-5` | Argumento no válido (identificador vacío, valor fuera de límites)

Detalle del último fallo: `of_get_last_error()`.

## Pedir ayuda #

Adjunte a su solicitud:

- la versión de PowerBuilder y el bitness (32 / 64);
- la versión de Windows;
- la versión de la biblioteca (`PBT_GetVersion`) y del runtime WebView2 (`PBT_CheckRuntime`);
- el estado de la licencia (`PBT_LicenseStatus`);
- un extracto de código mínimo que reproduzca el caso.

← Funciones transversales · Índice · Licencia →