# webbrowser — `u_pbt_webbrowser` #

← Riferimento dei componenti · Sommario della guida

> Browser web integrato nella Sua finestra: visualizzazione di una pagina, barra degli indirizzi, cronologia Indietro / Avanti, menu contestuale di navigazione.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Web browser: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_webbrowser`
Classe degli item | — (componente senza item)
Serve per | Mostrare una pagina web, un portale interno, una documentazione online o un contenuto HTML generato, senza uscire dall'applicazione
Due modalità di visualizzazione | integrata (predefinita) o pagina intera, a seconda della tolleranza del sito visitato

## Avvio rapido #

    // event open della finestra
    uo_navigateur.ib_address_bar = true    // barra degli indirizzi + pulsanti di navigazione
    uo_navigateur.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Impostare `is_address` è l'atto di navigazione: ogni assegnazione apre la pagina richiesta. Un indirizzo privo di protocollo (`"esempio.it"`) riceve automaticamente `https://`.

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_address` | string | `""` | Indirizzo visualizzato. Assegnare questa proprietà attiva la navigazione. Rileggendola si ottiene la pagina realmente visualizzata: se l'utente segue un collegamento, la segue anche lei (`ue_load_completed` avvisa). Sono accettati tutti gli schemi, compresi `data:` e `file:`
`ib_address_bar` | boolean | `false` | Mostra la barra degli indirizzi integrata: campo URL, pulsanti Indietro / Avanti / Ricarica
`ib_context_menu` | boolean | `false` | Attiva il menu contestuale di navigazione con il clic destro: Indietro, Avanti, Ricarica
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)

## Metodi #

Metodo | Ruolo
--- | ---
`of_refresh ( )` | Ricarica la pagina corrente
`of_go_back ( )` | Torna alla pagina precedente
`of_go_forward ( )` | Avanza alla pagina successiva
`of_can_go_back ( )` → boolean | `true` se esiste una pagina precedente — per attivare o disattivare il Suo pulsante Indietro
`of_can_go_forward ( )` → boolean | `true` se esiste una pagina successiva
`of_stop ( )` | Interrompe il caricamento in corso
`of_execute_javascript (string as_script)` | Esegue uno script nella pagina visualizzata e ne restituisce il valore come stringa (JSON: un testo torna fra virgolette, un numero no). Una sola condizione, ed è strutturale: la pagina deve aver finito di caricarsi, quindi la chiami da `ue_load_completed`, mai subito dopo aver impostato `is_address`. Restituisce una stringa vuota se lo script fallisce o se non c'è alcuna pagina
`of_reset ( )` | Riporta il componente allo stato iniziale: pagina svuotata, cronologia di navigazione cancellata, barra degli indirizzi nascosta, menu contestuale disattivato, ritorno alla modalità integrata
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Esporta il rendering come immagine

## Event #

Event | Attivato quando
--- | ---
`ue_load_completed (string as_url)` | Una pagina ha terminato il caricamento; `as_url` è l'indirizzo effettivamente visualizzato
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Navigare #

### La barra degli indirizzi integrata #

È la soluzione più rapida: una proprietà, e l'utente dispone di un campo URL e dei pulsanti Indietro / Avanti / Ricarica, a tema come il resto dell'applicazione.

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

I pulsanti si disattivano da soli quando non c'è alcun posto dove andare.

### I Suoi pulsanti personali #

Se preferisce pilotare la navigazione dalla Sua barra degli strumenti, nasconda la barra integrata e utilizzi i metodi:

    // Pulsanti Indietro / Avanti della Sua finestra
    uo_navigateur.of_go_back()
    uo_navigateur.of_go_forward()

    // event ue_load_completed di uo_navigateur : (string as_url)
    // Aggiornare lo stato dei Suoi pulsanti dopo ogni 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()

    // E rispecchiare l'indirizzo reale (redirezioni comprese)
    sle_url.text = as_url

### Il menu contestuale di navigazione #

`ib_context_menu` aggiunge al clic destro un piccolo menu Indietro / Avanti / Ricarica, a tema e disegnato dall'applicazione. Condivide esattamente la stessa cronologia della barra degli indirizzi: i due restano quindi sempre coerenti.

    uo_navigateur.ib_context_menu = true

### Interrompere un caricamento #

    // Pulsante Stop : interrompe una pagina che tarda
    uo_navigateur.of_stop()

## Siti che rifiutano la visualizzazione integrata #

Alcuni siti — Google, la maggior parte delle banche, molte applicazioni SaaS — inviano intestazioni di sicurezza che vietano la visualizzazione all'interno di un'altra pagina. Il componente non è interessato: non mostra mai un sito in un riquadro. La pagina viene aperta come documento principale, esattamente come fa il Suo browser, e quelle intestazioni non si applicano più.

Non c'è quindi nulla da impostare, né alcun caso particolare da gestire nel Suo codice.

    // Un sito che rifiuta di essere integrato in una pagina : niente di speciale da fare
    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://www.google.com"

In cambio, la pagina occupa tutta la superficie del componente sotto la barra degli indirizzi: ciò che disegnasse sopra di essa (fasce, sovrapposizioni a tema) non è visibile durante la navigazione.

## Contenuto HTML senza rete #

Ogni indirizzo è accettato, compresa una pagina HTML fornita direttamente. Comodo per l'anteprima di una lettera, di un ticket, di una fattura o di un report generato dalla Sua applicazione, senza alcuna chiamata di rete né file temporaneo:

    string ls_html

    ls_html = "<html><head><meta charset='utf-8'></head><body>" &
            + "<h1>Riepilogo dell'ordine</h1>" &
            + "<p>Grazie per la fiducia accordataci.</p>" &
            + "</body></html>"

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

Un file locale si apre allo stesso modo con `file:///C:/temp/rapport.html`.

## Ripartire da zero #

`of_reset()` non si limita a svuotare la pagina: cancella anche la cronologia di navigazione. Un utente non può quindi tornare, con il pulsante Indietro, su una pagina consultata dall'utente precedente o in un'altra pratica.

    // Cambio di pratica : si riparte da un browser vergine, senza cronologia
    uo_navigateur.of_reset()

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = ls_url_du_dossier

È il riflesso da avere ogni volta che uno stesso componente serve a mostrare contenuti di contesti differenti.

## Esempio completo #

    // event open della finestra : pagina iniziale del portale interno
    uo_navigateur.of_reset()                  // ripartire puliti (cronologia compresa)

    uo_navigateur.ib_address_bar  = true      // campo URL + Indietro / Avanti / Ricarica
    uo_navigateur.ib_context_menu = true      // stessa navigazione con il clic destro
    uo_navigateur.is_address = "https://intranet.societe.fr/accueil"

    // event ue_load_completed di uo_navigateur : (string as_url)
    uo_statut.of_item("main").is_text = "Pagina caricata: " + as_url

## Buone pratiche #

- Assegni `is_address`, non chiami un metodo di navigazione: è la proprietà che attiva l'apertura della pagina.
- Attivi `ib_address_bar` non appena l'utente può navigare liberamente; riservi il pilotaggio tramite i Suoi pulsanti ai percorsi vincolati.
- Si affidi a `of_can_go_back()` / `of_can_go_forward()` per lo stato dei Suoi pulsanti anziché contare le pagine da sé: le redirezioni falserebbero il Suo conteggio.
- Nulla da prevedere per i siti che rifiutano la visualizzazione integrata: la pagina viene sempre aperta come documento principale, quelle intestazioni non si applicano.
- Chiami `of_reset()` cambiando contesto: è l'unico modo per garantire che nessuna pagina precedente sia raggiungibile con il pulsante Indietro.
- Il componente ha bisogno del runtime web installato sulla postazione: tratti `ue_runtime_missing` come per qualsiasi altro componente (Installazione).

← Riferimento dei componenti · Sommario della guida