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 #

Schnellstart #

// open-Event des Fensters
uo_browser.ib_address_bar = true    // Adressleiste + Navigationsschaltflaechen
uo_browser.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://. Ein Dateipfad (C:\ordner\seite.html, \\server\freigabe\seite.html) wird zu einer file:///-Adresse. Wörter, die keine Adresse sind ("Rechnung 2026"), gehen an die Suchmaschine von is_search_url; ohne Suchmaschine werden sie abgelehnt, und ue_error meldet es. Ein Servername aus einem Wort, gefolgt von /, ? oder # (office/, intranet/start), ist eine Adresse, ebenso eine IPv6-Adresse in eckigen Klammern ([::1]/x); das Wort allein (intranet) bleibt freier Text. Ein Server ohne HTTPS wird mit ausdrücklichem http:// geschrieben.

Eigenschaften #

Methoden #

Events #

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.

// Die Adressleiste, dann die zu oeffnende Seite
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Die Schaltflächen grauen sich von selbst aus, wenn es nirgendwohin zu gehen gibt. Im Adressfeld lädt F5 (oder Strg+R) neu, Alt+← / Alt+→ gehen zurück und vorwärts (bei Schreibrichtung von rechts nach links vertauscht), Esc stellt nach einer abgebrochenen Eingabe die aktuelle Adresse wieder her, und der erste Klick markiert die ganze Adresse.

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_browser.of_go_back()
uo_browser.of_go_forward()

// ue_load_completed-Event von uo_browser : (string as_url)
// Den Zustand Ihrer Schaltflaechen nach jeder Seite aktualisieren
uo_toolbar.of_item(/*keys*/ "main/back").ib_enabled = uo_browser.of_can_go_back()
uo_toolbar.of_item(/*keys*/ "main/forward").ib_enabled   = uo_browser.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 richtet sich nach dem, was unter der Maus liegt: Kopieren auf markiertem Text, Link öffnen und Linkadresse kopieren auf einem Link, Bild kopieren auf einem Bild. Per Tastatur geöffnet (Umschalt+F10, Menütaste) erscheint es am Element. Es teilt sich denselben Verlauf wie die Adressleiste: Beide bleiben also stets konsistent.

// A small menu on a right click : back, forward, refresh
uo_browser.ib_context_menu = true

Einen Ladevorgang abbrechen #

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

Wörter statt einer Adresse #

Standardmäßig wird ein Text, der keine Adresse ist, abgelehnt (ue_error), ohne etwas zu blockieren: Die nächste Adresse lädt normal. Um daraus eine Suche zu machen, wählen Sie die Suchmaschine:

// Words typed in the address bar go to this engine (%s = the text)
uo_browser.is_search_url = "https://www.bing.com/search?q=%s"
uo_browser.is_address = "PowerBuilder WebView2"

Neue Fenster und Downloads #

Ein Link „in neuem Tab öffnen“ oder ein nach einem Klick geöffnetes Anmeldefenster wird in der Ansicht angezeigt, und ue_new_window teilt es Ihnen mit. Ein Download läuft wie in Edge weiter, und ue_download_starting nennt Ihnen Adresse und Datei. Beide werden zu einer Rückfrage, wenn Sie es verlangen:

// Ask before each download
uo_browser.ib_veto_downloads = true

// ue_download_starting event of uo_browser : (string as_url, string as_path)
// Only PDF files may be downloaded
return Lower(Right(as_path, 4)) = ".pdf"

Auf den eigenen Servern bleiben #

ue_navigating wird jedes Mal ausgelöst, wenn die Website zu einer anderen Seite wechselt — ein Link, ein Formular, ein Skript —, nie für eine von Ihrem Code gesetzte Adresse. Mit ib_veto_navigation wird es zur Rückfrage: false behält die aktuelle Seite. Eine erlaubte Seite wird unter der von der Website angeforderten Adresse neu geöffnet; ein per POST gesendetes Formular verliert dabei seine Daten.

// Ask before the site leaves for another page
uo_browser.ib_veto_navigation = true

// ue_navigating event of uo_browser : (string as_url)
// Only the company servers may be opened
return Pos(Lower(as_url), "://intranet.example.com/") > 0

Kamera, Mikrofon, Standort #

Wenn eine Website Kamera, Mikrofon, Standort, Benachrichtigungen oder das Lesen der Zwischenablage verlangt, entscheidet ue_permission_requested, und die Standardantwort ist nein: Eine Website schaltet keine Kamera über eine Rückfrage ein, die der Benutzer nicht versteht. Es ist die einzige Frage der Bibliothek, bei der Schweigen Ablehnung bedeutet. Nichts wird gespeichert: Die Frage kommt bei jeder Anforderung wieder.

// ue_permission_requested event of uo_browser : (string as_url, string as_kind)
// The video-call page of the company may use the camera and the microphone
if Pos(Lower(as_url), "://visio.example.com/") = 0 then return false
return as_kind = uo_browser.PERMISSION_CAMERA or as_kind = uo_browser.PERMISSION_MICROPHONE

Werte von as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (mehrere Downloads hintereinander), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Warum eine Seite nicht geladen wurde #

al_status von ue_load_failed wird mit den LOADSTATUS_*-Konstanten der Komponente verglichen:

// ue_load_failed event of uo_browser : (string as_url, long al_status)
if al_status = uo_browser.LOADSTATUS_HOST_NOT_RESOLVED then
	st_message.text = "Unknown address : " + as_url
end if

Ein Skript in der Seite ausführen #

of_execute_javascript liest oder ändert die angezeigte Seite (ihren Titel, ein Feld, einen Zähler). Es ist durch die Lizenz nicht eingeschränkt, auch nicht auf einer about:blank- oder data:-Seite: Ein Skript in der Seite auszuführen ist die Aufgabe eines Browsers, und die Komponente ist kostenlos.

// ue_load_completed event of uo_browser : (string as_url)
// The page title, as JSON : "PowerBuilder - Wikipedia" (quotes included)
sle_title.text = uo_browser.of_execute_javascript(/*script*/ "document.title")

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_browser.ib_address_bar = true
uo_browser.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 #

of_show_html zeigt eine von Ihrer Anwendung erzeugte HTML-Seite an: die Vorschau eines Schreibens, eines Tickets, einer Rechnung oder eines Berichts, ganz ohne Netzwerkaufruf und ohne temporäre Datei. Die Seite wird für Sie kodiert: Eine Farbe #c00, ein Anker, ein % oder ein Akzent erscheinen wie geschrieben (höchstens 2 MB).

// Local variables
string ls_html

// An order summary built by the application : the colour and the "%" come out as written
ls_html = "<html><body>" &
        + "<h1 style='color:#1f6feb'>Order #4152</h1>" &
        + "<p>Discount : 10%</p>" &
        + "</body></html>"
uo_browser.of_show_html(/*html*/ ls_html)

Direkt in is_address gesetzt, wird eine data:text/html,-Adresse nicht kodiert: Ein # schneidet die Seite dort ab (alles Folgende gilt als Anker), und ein % verfälscht sie. Verwenden Sie lieber of_show_html, oder kodieren Sie selbst (# → %23, % → %25).

Eine lokale Datei öffnet sich genauso mit file:///C:/temp/bericht.html oder einfach über ihren Pfad C:\temp\bericht.html.

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. Was die Websites gespeichert haben, bleibt davon unberührt: Cookies, angemeldete Sitzungen, lokaler Speicher, Berechtigungen. An einem gemeinsam genutzten Arbeitsplatz wäre der nächste Benutzer als der vorherige angemeldet — of_clear_browsing_data() löscht das. Die Websites leben in einem eigenen Browserprofil, getrennt von den Komponenten der Anwendung.

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

// Dann der Vorgang, mit seiner Adressleiste
uo_browser.ib_address_bar = true
uo_browser.is_address = ls_folder_url

// The user of the workstation changes : no page, no history, no signed-in session left
uo_browser.of_reset()
uo_browser.of_clear_browsing_data()

Damit nie etwas auf die Festplatte geschrieben wird, setzen Sie ib_private = true vor der ersten Adresse: Cookies und Speicher verschwinden mit der Ansicht.

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_browser.of_reset()                  // sauber neu beginnen (Verlauf inbegriffen)

// Die Navigationswerkzeuge, dann die Startseite
uo_browser.ib_address_bar  = true      // URL-Feld + Zurueck / Vorwaerts / Neu laden
uo_browser.ib_context_menu = true      // dieselbe Navigation beim Rechtsklick
uo_browser.is_address = "https://intranet.example.com/home"

// ue_load_completed-Event von uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "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. Wechselt der Benutzer des Arbeitsplatzes, ergänzen Sie of_clear_browsing_data(): Ohne diesen Aufruf bleiben Cookies und Sitzungen der Websites erhalten.
• Die Komponente benötigt die auf dem Rechner installierte Web-Runtime: Behandeln Sie ue_runtime_missing wie bei jeder anderen Komponente (Installation).
• Eine Website darf ohne Geste des Benutzers Ton abspielen: die automatische Wiedergabe mit Ton ist in der gesamten WebView2-Umgebung der Anwendung erlaubt (Video- und Tonplayer brauchen sie, eine verborgene Seite hat keine Geste). Eine Seite, die beim Öffnen ein Video mit Ton startet, spielt es ab; stört das, öffnen Sie Adressen, die Sie kennen.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs