# webbrowser — `u_pbt_webbrowser` #

← Referencia de componentes · Índice de la guía

> Navegador web integrado en su ventana: visualización de una página, barra de direcciones, historial Atrás / Adelante, menú contextual de navegación.

> ▶ Verlo en vivo — Aplicación de demostración, mosaico Web browser: la vista previa, el código que lo genera y esta página, uno al lado del otro.

## De un vistazo #

Userobject | `u_pbt_webbrowser`
Clase de items | — (componente sin items)
Sirve para | Mostrar una página web, un portal interno, una documentación en línea o un contenido HTML generado, sin salir de la aplicación
Dos modos de visualización | integrado (predeterminado) o página completa, según la tolerancia del sitio visitado

## Inicio rápido #

    // event open de la ventana
    uo_navigateur.ib_address_bar = true    // barra de direcciones + botones de navegacion
    uo_navigateur.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Asignar `is_address` es el acto de navegación: cada asignación abre la página solicitada. Una dirección sin protocolo (`"ejemplo.com"`) recibe automáticamente `https://`.

## Propiedades #

Propiedad | Tipo | Predeterminado | Función
--- | --- | --- | ---
`is_address` | string | `""` | Dirección mostrada. Asignar esta propiedad desencadena la navegación. Al releerla se obtiene la página realmente mostrada: si el usuario sigue un enlace, ella también lo sigue (`ue_load_completed` avisa). Se admiten todos los esquemas, incluidos `data:` y `file:`
`ib_address_bar` | boolean | `false` | Muestra la barra de direcciones integrada: campo URL, botones Atrás / Adelante / Recargar
`ib_context_menu` | boolean | `false` | Activa el menú contextual de navegación con el clic derecho: Atrás, Adelante, Recargar
`is_theme_style` | string | `fluent` | Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Color de acento de este componente (`-1` = acento del tema)

## Métodos #

Método | Función
--- | ---
`of_refresh ( )` | Recarga la página actual
`of_go_back ( )` | Vuelve a la página anterior
`of_go_forward ( )` | Avanza a la página siguiente
`of_can_go_back ( )` → boolean | `true` si existe una página anterior — para activar o atenuar su botón Atrás
`of_can_go_forward ( )` → boolean | `true` si existe una página siguiente
`of_stop ( )` | Interrumpe la carga en curso
`of_execute_javascript (string as_script)` | Ejecuta un script en la página mostrada y devuelve su valor como cadena (JSON: un texto vuelve entre comillas, un número no). Una sola condición, y es estructural: la página debe haber terminado de cargarse, así que llámela desde `ue_load_completed`, nunca justo después de asignar `is_address`. Devuelve una cadena vacía si el script falla o si no hay página
`of_reset ( )` | Devuelve el componente a su estado inicial: página vaciada, historial de navegación borrado, barra de direcciones oculta, menú contextual desactivado, vuelta al modo integrado
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta la representación como imagen

## Eventos #

Evento | Se activa cuando
--- | ---
`ue_load_completed (string as_url)` | Una página ha terminado de cargarse; `as_url` es la dirección realmente mostrada
`ue_ready ( )` | El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )` | El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)` | El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

## Navegar #

### La barra de direcciones integrada #

Es la solución más rápida: una propiedad, y el usuario dispone de un campo URL y de los botones Atrás / Adelante / Recargar, con el mismo tema que el resto de la aplicación.

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Los botones se atenúan solos cuando no hay ningún sitio al que ir.

### Sus propios botones #

Si prefiere controlar la navegación desde su propia barra de herramientas, oculte la barra integrada y utilice los métodos:

    // Botones Atras / Adelante de su ventana
    uo_navigateur.of_go_back()
    uo_navigateur.of_go_forward()

    // event ue_load_completed de uo_navigateur : (string as_url)
    // Actualizar el estado de sus botones despues de cada pagina
    uo_barre.of_bar("main").of_item("precedent").ib_enabled = uo_navigateur.of_can_go_back()
    uo_barre.of_bar("main").of_item("suivant").ib_enabled   = uo_navigateur.of_can_go_forward()

    // Y reflejar la direccion real (redirecciones incluidas)
    sle_url.text = as_url

### El menú contextual de navegación #

`ib_context_menu` añade con el clic derecho un pequeño menú Atrás / Adelante / Recargar, con tema y representado por la aplicación. Comparte exactamente el mismo historial que la barra de direcciones: los dos permanecen, por tanto, siempre coherentes.

    uo_navigateur.ib_context_menu = true

### Detener una carga #

    // Boton Detener : interrumpe una pagina que tarda demasiado
    uo_navigateur.of_stop()

## Sitios que rechazan la visualización integrada #

Algunos sitios — Google, la mayoría de los bancos, muchas aplicaciones SaaS — envían encabezados de seguridad que prohíben su visualización dentro de otra página. El componente no se ve afectado: nunca muestra un sitio en un marco. La página se abre como documento principal, exactamente como lo hace su propio navegador, y esos encabezados dejan de aplicarse.

Así pues, no hay nada que configurar ni ningún caso particular que tratar en su código.

    // Un sitio que rechaza ser integrado en una pagina : nada especial que hacer
    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://www.google.com"

A cambio, la página ocupa toda la superficie del componente bajo la barra de direcciones: lo que dibujara por encima (bandas, superposiciones con tema) no se ve durante la navegación.

## Contenido HTML sin red #

Se admite cualquier dirección, incluida una página HTML suministrada directamente. Práctico para una vista previa de una carta, un ticket, una factura o un informe generado por su aplicación, sin ninguna llamada de red ni archivo temporal:

    string ls_html

    ls_html = "<html><head><meta charset='utf-8'></head><body>" &
            + "<h1>Resumen del pedido</h1>" &
            + "<p>Gracias por su confianza.</p>" &
            + "</body></html>"

    uo_navigateur.is_address = "data:text/html," + ls_html

Un archivo local se abre de la misma manera con `file:///C:/temp/rapport.html`.

## Volver a empezar de cero #

`of_reset()` no se limita a vaciar la página: también borra el historial de navegación. Un usuario no puede, por tanto, volver con el botón Atrás a una página consultada por el usuario anterior o en otro expediente.

    // Cambio de expediente : se parte de un navegador virgen, sin historial
    uo_navigateur.of_reset()

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = ls_url_du_dossier

Es el reflejo que conviene tener cada vez que un mismo componente sirve para mostrar contenidos de contextos diferentes.

## Ejemplo completo #

    // event open de la ventana : pagina de inicio del portal interno
    uo_navigateur.of_reset()                  // partir de cero (historial incluido)

    uo_navigateur.ib_address_bar  = true      // campo URL + Atras / Adelante / Recargar
    uo_navigateur.ib_context_menu = true      // la misma navegacion con el clic derecho
    uo_navigateur.is_address = "https://intranet.societe.fr/accueil"

    // event ue_load_completed de uo_navigateur : (string as_url)
    uo_statut.of_item("main").is_text = "Página cargada: " + as_url

## Buenas prácticas #

- Asigne `is_address`, no llame a ningún método de navegación: es la propiedad la que desencadena la apertura de la página.
- Active `ib_address_bar` en cuanto el usuario pueda navegar libremente; reserve el control mediante sus propios botones para los recorridos restringidos.
- Fíese de `of_can_go_back()` / `of_can_go_forward()` para el estado de sus botones en lugar de contar las páginas usted mismo: las redirecciones falsearían su cuenta.
- Nada que prever para los sitios que rechazan la visualización integrada: la página siempre se abre como documento principal, esos encabezados no se aplican.
- Llame a `of_reset()` al cambiar de contexto: es la única manera de garantizar que ninguna página anterior sea accesible mediante el botón Atrás.
- El componente necesita el runtime web instalado en el equipo: trate `ue_runtime_missing` igual que en cualquier otro componente (Instalación).

← Referencia de componentes · Índice de la guía