# webbrowser — `u_pbt_webbrowser` #

← Komponentenreferenz · Inhalt des Handbuchs

> Ein in Ihr Fenster integrierter Webbrowser: Anzeige einer Seite, Adressleiste, Verlauf Zurück / Vorwärts, Kontextmenü für die Navigation.

> ▶ Live ansehen — Demoanwendung, Kachel Web browser: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

## Auf einen Blick #

Userobject | `u_pbt_webbrowser`
Item-Klasse | — (Komponente ohne Items)
Wofür | Eine Webseite, ein internes Portal, eine Online-Dokumentation oder erzeugte HTML-Inhalte anzeigen, ohne die Anwendung zu verlassen
Zwei Anzeigemodi | eingebettet (Standard) oder ganzseitig, je nachdem, wie tolerant die besuchte Website ist

## Schnellstart #

    // open-Event des Fensters
    uo_navigateur.ib_address_bar = true    // Adressleiste + Navigationsschaltflaechen
    uo_navigateur.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Das Setzen von `is_address` ist der Navigationsvorgang: Jede Zuweisung öffnet die angeforderte Seite. Eine Adresse ohne Protokoll (`"beispiel.de"`) erhält automatisch `https://`.

## Eigenschaften #

Eigenschaft | Typ | Standard | Zweck
--- | --- | --- | ---
`is_address` | string | `""` | Angezeigte Adresse. Das Zuweisen dieser Eigenschaft löst die Navigation aus. Zurückgelesen liefert sie die tatsächlich angezeigte Seite: Folgt der Benutzer einem Link, folgt sie mit (`ue_load_completed` meldet es). Alle Schemata werden akzeptiert, auch `data:` und `file:`
`ib_address_bar` | boolean | `false` | Zeigt die integrierte Adressleiste an: URL-Feld, Schaltflächen Zurück / Vorwärts / Neu laden
`ib_context_menu` | boolean | `false` | Aktiviert das Kontextmenü für die Navigation beim Rechtsklick: Zurück, Vorwärts, Neu laden
`is_theme_style` | string | `fluent` | Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Akzentfarbe dieser Komponente (`-1` = Akzent des Designs)

## Methoden #

Methode | Zweck
--- | ---
`of_refresh ( )` | Lädt die aktuelle Seite neu
`of_go_back ( )` | Kehrt zur vorherigen Seite zurück
`of_go_forward ( )` | Geht zur nächsten Seite weiter
`of_can_go_back ( )` → boolean | `true`, wenn eine vorherige Seite vorhanden ist — um Ihre eigene Zurück-Schaltfläche zu aktivieren oder auszugrauen
`of_can_go_forward ( )` → boolean | `true`, wenn eine nächste Seite vorhanden ist
`of_stop ( )` | Bricht den laufenden Ladevorgang ab
`of_execute_javascript (string as_script)` | Führt ein Skript in der angezeigten Seite aus und liefert dessen Wert als Zeichenkette (JSON: ein Text kommt in Anführungszeichen zurück, eine Zahl nicht). Eine einzige Bedingung, und sie ist struktureller Art: Die Seite muss geladen sein, rufen Sie die Methode also aus `ue_load_completed` auf, nie direkt nach dem Setzen von `is_address`. Liefert eine leere Zeichenkette, wenn das Skript fehlschlägt oder keine Seite angezeigt wird
`of_reset ( )` | Versetzt die Komponente in den Ausgangszustand: Seite geleert, Navigationsverlauf gelöscht, Adressleiste ausgeblendet, Kontextmenü deaktiviert, zurück zum eingebetteten Modus
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exportiert die Darstellung als Bild

## Events #

Event | Ausgelöst wenn
--- | ---
`ue_load_completed (string as_url)` | Eine Seite ist fertig geladen; `as_url` ist die tatsächlich angezeigte Adresse
`ue_ready ( )` | Die Komponente ist fertig geladen; alles zuvor Gesendete wurde nachgespielt
`ue_runtime_missing ( )` | Die WebView2-Runtime fehlt: die Komponente bleibt leer
`ue_bg_color (long al_color)` | Die Komponente hat ihre Design-Hintergrundfarbe berechnet; das Userobject hat sie bereits übernommen (`backcolor`)

## Navigieren #

### Die integrierte Adressleiste #

Das ist die schnellste Lösung: eine Eigenschaft, und der Benutzer verfügt über ein URL-Feld sowie die Schaltflächen Zurück / Vorwärts / Neu laden, im Design der übrigen Anwendung.

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

Die Schaltflächen grauen sich von selbst aus, wenn es nirgendwohin zu gehen gibt.

### Ihre eigenen Schaltflächen #

Wenn Sie die Navigation lieber über Ihre eigene Symbolleiste steuern möchten, blenden Sie die integrierte Leiste aus und verwenden Sie die Methoden:

    // Schaltflaechen Zurueck / Vorwaerts Ihres Fensters
    uo_navigateur.of_go_back()
    uo_navigateur.of_go_forward()

    // ue_load_completed-Event von uo_navigateur : (string as_url)
    // Den Zustand Ihrer Schaltflaechen nach jeder Seite aktualisieren
    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()

    // Und die tatsaechliche Adresse widerspiegeln (Weiterleitungen inbegriffen)
    sle_url.text = as_url

### Das Kontextmenü für die Navigation #

`ib_context_menu` fügt beim Rechtsklick ein kleines Menü Zurück / Vorwärts / Neu laden hinzu, im Design und von der Anwendung gezeichnet. Es teilt sich denselben Verlauf wie die Adressleiste: Beide bleiben also stets konsistent.

    uo_navigateur.ib_context_menu = true

### Einen Ladevorgang abbrechen #

    // Schaltflaeche Stopp : bricht eine Seite ab, die zu lange braucht
    uo_navigateur.of_stop()

## Websites, die die eingebettete Anzeige verweigern #

Manche Websites — Google, die meisten Banken, viele SaaS-Anwendungen — senden Sicherheits-Header, die die Anzeige innerhalb einer anderen Seite verbieten. Die Komponente ist davon nicht betroffen: Sie zeigt eine Website nie in einem Rahmen. Die Seite wird als Hauptdokument geöffnet, genau wie in Ihrem eigenen Browser, und diese Header greifen dann nicht mehr.

Es gibt also nichts einzustellen und keinen Sonderfall, den Sie in Ihrem Code behandeln müssten.

    // Eine Website, die die Einbettung verweigert : nichts Besonderes zu tun
    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://www.google.com"

Im Gegenzug füllt die Seite die gesamte Komponente unterhalb der Adressleiste: Was Sie darüber zeichnen würden (Banner, gestaltete Überlagerungen), ist während des Surfens nicht sichtbar.

## HTML-Inhalt ohne Netzwerk #

Jede Adresse wird akzeptiert, auch eine direkt gelieferte HTML-Seite. Praktisch für die Vorschau eines Schreibens, eines Tickets, einer Rechnung oder eines von Ihrer Anwendung erzeugten Berichts, ganz ohne Netzwerkaufruf und ohne temporäre Datei:

    string ls_html

    ls_html = "<html><head><meta charset='utf-8'></head><body>" &
            + "<h1>Bestellübersicht</h1>" &
            + "<p>Vielen Dank für Ihr Vertrauen.</p>" &
            + "</body></html>"

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

Eine lokale Datei wird auf dieselbe Weise mit `file:///C:/temp/rapport.html` geöffnet.

## Wieder bei null anfangen #

`of_reset()` leert nicht nur die Seite: Es löscht auch den Navigationsverlauf. Ein Benutzer kann also nicht über die Zurück-Schaltfläche zu einer Seite gelangen, die vom vorherigen Benutzer oder in einem anderen Vorgang aufgerufen wurde.

    // Wechsel des Vorgangs : mit einem leeren Browser ohne Verlauf neu beginnen
    uo_navigateur.of_reset()

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = ls_url_du_dossier

Das ist der Reflex, den man haben sollte, sobald ein und dieselbe Komponente Inhalte aus unterschiedlichen Kontexten anzeigt.

## Vollständiges Beispiel #

    // open-Event des Fensters : Startseite des internen Portals
    uo_navigateur.of_reset()                  // sauber neu beginnen (Verlauf inbegriffen)

    uo_navigateur.ib_address_bar  = true      // URL-Feld + Zurueck / Vorwaerts / Neu laden
    uo_navigateur.ib_context_menu = true      // dieselbe Navigation beim Rechtsklick
    uo_navigateur.is_address = "https://intranet.societe.fr/accueil"

    // ue_load_completed-Event von uo_navigateur : (string as_url)
    uo_statut.of_item("main").is_text = "Seite geladen: " + as_url

## Best Practices #

- Weisen Sie `is_address` zu, rufen Sie keine Navigationsmethode auf: Es ist die Eigenschaft, die das Öffnen der Seite auslöst.
- Aktivieren Sie `ib_address_bar`, sobald der Benutzer frei navigieren darf; die Steuerung über Ihre eigenen Schaltflächen bleibt eingeschränkten Abläufen vorbehalten.
- Verlassen Sie sich für den Zustand Ihrer Schaltflächen auf `of_can_go_back()` / `of_can_go_forward()`, statt die Seiten selbst zu zählen: Weiterleitungen würden Ihre Zählung verfälschen.
- Für Websites, die die eingebettete Anzeige verweigern, ist nichts vorzusehen: Die Seite wird stets als Hauptdokument geöffnet, diese Header greifen nicht.
- Rufen Sie `of_reset()` beim Kontextwechsel auf: Nur so ist gewährleistet, dass keine vorherige Seite über die Zurück-Schaltfläche erreichbar ist.
- Die Komponente benötigt die auf dem Rechner installierte Web-Runtime: Behandeln Sie `ue_runtime_missing` wie bei jeder anderen Komponente (Installation).

← Komponentenreferenz · Inhalt des Handbuchs