webbrowser — u_pbt_webbrowser #

← Component reference · Guide contents

A web browser built into your window: page display, address bar, Back / Forward history, navigation context menu.

▶ See it live — Demo application, Web browser tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

// open event of the window
uo_browser.ib_address_bar = true    // address bar + navigation buttons
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Setting is_address is the act of navigating: every assignment opens the requested page. An address without a protocol ("example.com") automatically receives https://. A disk path (C:\folder\page.html, \\server\share\page.html) becomes a file:/// address. Words that are not an address ("invoice 2026") go to the search engine of is_search_url; without one, they are refused and ue_error says so. A one-word server name followed by /, ? or # (office/, intranet/home) is an address, and so is an IPv6 address in brackets ([::1]/x); the word alone (intranet) stays free text. A server without HTTPS is written with an explicit http://.

Properties #

Methods #

Events #

Navigating #

The built-in address bar #

This is the fastest option: one property, and the user gets a URL field and Back / Forward / Refresh buttons, themed like the rest of the application.

// The address bar, then the page to open
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

The buttons gray themselves out when there is nowhere to go. In the address field, F5 (or Ctrl+R) reloads, Alt+← / Alt+→ go back and forward (swapped in right-to-left writing), Esc brings back the current address after an abandoned edit, and the first click selects the whole address. A text that is not an address is flagged: the field gets a red border, with a tooltip, until the next key. Enter on an empty field does nothing: the page stays.

Your own buttons #

If you would rather drive navigation from your own toolbar, hide the built-in bar and use the methods:

// Back / Forward buttons of your window
uo_browser.of_go_back()
uo_browser.of_go_forward()

// ue_load_completed event of uo_browser : (string as_url)
// Update the state of your buttons after each page
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()

// And reflect the real address (redirections included)
sle_url.text = as_url

The navigation context menu #

ib_context_menu adds a small Back / Forward / Refresh menu on right-click, themed and rendered by the application. It follows what is under the mouse: Copy on selected text, Open link and Copy link address on a link, Copy image on an image. Opened from the keyboard (Shift+F10, Menu key), it comes up on the element. It shares exactly the same history as the address bar, so the two always stay consistent.

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

Stopping a load #

// Stop button : interrupts a page that is taking too long
uo_browser.of_stop()

Words instead of an address #

By default, a text that is not an address is refused (ue_error), without holding anything: the next address loads normally. To turn it into a search, choose the engine:

// 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"

New windows and downloads #

An "open in a new tab" link or a sign-in window opened after a click is shown in the view, and ue_new_window tells you. A download goes on as in Edge, and ue_download_starting gives you the address and the file. Both turn into a question when you ask for it:

// 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"

A sign-in window that talks back to the page that opened it (an OAuth or Microsoft sign-in in a pop-up) loses that link once shown in the view, and the sign-in does not complete: open such a sign-in in the page itself (redirect mode).

Staying on your own servers #

To keep a business application on its own servers, list them in is_allowed_hosts: any page of another host is refused, whoever asks for it — your code, a link, an address typed in the bar, a redirection of the server —, and ue_navigation_blocked says so. The page on screen stays.

// Only the company servers : any other host is refused, redirections included
uo_browser.is_allowed_hosts = "intranet.example.com|*.example.com"

// ue_navigation_blocked event of uo_browser : (string as_url)
st_message.text = "This site is not allowed : " + as_url

ue_navigating is raised each time the page leaves for another one — a link, a form or a script of the site, an address typed by the user, Open link, a new window —, never for an address set by your code nor for a redirection. With ib_veto_navigation it is a question: returning false keeps the current page. An allowed page is opened again at the address asked for; a form sent by POST loses its data. Compare the host of the address, never a piece of the whole address: https://evil.test/?next=://intranet.example.com/ holds the name of your server.

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

// ue_navigating event of uo_browser : (string as_url)
// Local variables
string ls_host
long ll_cut

// The host of the address : after "://", up to the first "/", "?", "#" or ":"
ls_host = Lower(Mid(as_url, Pos(as_url, "://") + 3))
for ll_cut = 1 to Len(ls_host)
	if Pos("/?#:", Mid(ls_host, ll_cut, 1)) > 0 then exit
next
ls_host = Left(ls_host, ll_cut - 1)

// Only the company server may be opened : the host must be EXACTLY it
return ls_host = "intranet.example.com"

Camera, microphone, position #

When a site asks for the camera, the microphone, the position, notifications or reading the clipboard, ue_permission_requested decides, and the default answer is no: a site does not switch a camera on through a prompt the user does not understand. It is the one question of the library where silence means refusal. Nothing is remembered: the question comes back at each request.

// 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

Values of as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (several downloads in a row), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Why a page did not load #

al_status of ue_load_failed is compared with the LOADSTATUS_* constants of the component:

// 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

Running a script in the page #

of_execute_javascript reads or changes the displayed page (its title, a field, a counter). It is not restricted by the licence, including on an about:blank or data: page: running a script in the page is what a browser is for, and the component is free.

// 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")

A loading indicator #

ue_load_started is raised when a page starts loading — an address of your code, a link, a gesture of the user —, and of_is_loading() returns true until ue_load_completed or ue_load_failed: enough to show an hourglass or to enable your Stop button.

// ue_load_started event of uo_browser : (string as_url)
// The Stop button works while the page loads
cb_stop.enabled = true

// ue_load_completed event of uo_browser : (string as_url)
// Loaded : nothing left to stop
cb_stop.enabled = uo_browser.of_is_loading()

Zoom #

ii_zoom enlarges or shrinks the site (the address bar keeps its size), from 25 to 500 %. It reads back live: Ctrl+mouse wheel in the site changes it too, and your code sees it.

// A screen read from a distance : the site one and a half times larger
uo_browser.ii_zoom = 150

The certificate of an intranet #

A server whose certificate is not valid (an internal or expired certificate) is refused, and ue_load_failed gives a LOADSTATUS_CERT_* status. With ib_certificate_questions, ue_certificate_error decides — and its default answer is no, as for a permission: accepting a certificate is a decision of security. An answer is good for the current navigation only; nothing is remembered.

// Ask about certificates instead of refusing them at once
uo_browser.ib_certificate_questions = true

// ue_certificate_error event of uo_browser : (string as_url, long al_status)
// Only the test server of the company, whose certificate is internal
return Left(Lower(as_url), 34) = "https://test-intranet.example.com/"

Messages between the page and the application #

An internal portal can tell the application something ("file saved", "row chosen"): open the bridge with ib_web_messages, and list in is_message_origins the origins allowed to talk. With no origin listed, the bridge stays closed: no site of the Web can reach your application. The page sends a JSON value, ue_web_message receives it as it is; of_post_message answers the page.

// The company portal may talk with the application
uo_browser.ib_web_messages = true
uo_browser.is_message_origins = "https://portal.example.com"
uo_browser.is_address = "https://portal.example.com/orders"

// In a page of the portal : send a value to the application, and listen to its answers
chrome.webview.postMessage({ order: 4152, action: "open" });
chrome.webview.addEventListener("message", function (e) { console.log(e.data); });

// ue_web_message event of uo_browser : (string as_origin, string as_json)
// Local variables
n_pbt_json lnv_json

// Read the value the page sent, then answer it
lnv_json.of_load(/*json*/ as_json)
if lnv_json.of_get_string(/*path*/ "action") = "open" then
	st_message.text = "Order " + String(lnv_json.of_get_number(/*path*/ "order"))
	uo_browser.of_post_message(/*json*/ '{"opened":true}')
end if

An origin is written as a scheme, a host and a port when it is not the default one (https://portal.example.com:8443); a sub-domain is another origin, and file:/// stands for the pages of the workstation. A message larger than 64 KB is dropped. of_post_message to a page of another origin raises ue_error and sends nothing.

Sites that refuse embedded display #

Some sites — Google, most banks, many SaaS applications — send security headers that forbid being displayed inside another page. The component is not affected: it never shows a site in a frame. The page is opened as a top-level document, exactly as your own browser does, and those headers no longer apply.

So there is nothing to set, and no special case to handle in your code.

// A site that refuses to be embedded in a page : nothing special to do
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

In exchange, the page fills the whole component below the address bar: anything you would draw over it (banners, themed overlays) is not visible while browsing.

HTML content with no network #

of_show_html shows an HTML page built by your application: previewing a letter, a ticket, an invoice or a report, with no network call and no temporary file. The page is encoded for you: a colour #c00, an anchor, a % or an accent is shown as written (2 MB at most).

// 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)

Set straight into is_address, a data:text/html, address is not encoded: a # cuts the page there (everything after it is taken as an anchor) and a % garbles it. Prefer of_show_html, or encode it yourself (# → %23, % → %25).

Such a page has no address of its own: is_address reads empty, so does the address bar, and ue_load_completed receives an empty address. Without a <title>, its title is empty. An image of the disk (file:///) is not shown in it: the engine does not let a data: page read the files of the workstation; write the image into the page (<img src="data:image/png;base64,…">).

A local file opens the same way with file:///C:/temp/report.html, or simply its path C:\temp\report.html.

Starting over #

of_reset() does more than clear the page: it erases the navigation history too. A user therefore cannot use the Back button to return to a page viewed by the previous user or in another file. It does not touch what the sites stored: cookies, signed-in sessions, local storage, permissions. On a shared workstation, the next user would arrive signed in as the previous one — of_clear_browsing_data() is what clears it. The sites live in a browsing profile of their own, separate from the components of the application.

// Local variables
string ls_folder_url

// The address of the file the user has just opened
ls_folder_url = "https://intranet.example.com/files/4152"

// Switching to another file : start again from a clean browser, with no history
uo_browser.of_reset()

// Then the file, with its address bar
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()

For nothing to ever be written to the disk, set ib_private = true before the first address: cookies and storage vanish with the view.

This is the reflex to have whenever a single component is used to display content from different contexts.

Complete example #

// open event of the window : home page of the internal portal
uo_browser.of_reset()                  // start clean (history included)

// The navigation tools, then the home page
uo_browser.ib_address_bar  = true      // URL field + Back / Forward / Refresh
uo_browser.ib_context_menu = true      // same navigation on right-click
uo_browser.is_address = "https://intranet.example.com/home"

// ue_load_completed event of uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Page loaded: " + as_url

Best practices #

• Assign is_address, do not call a navigation method: it is the property that triggers the page opening.
• Turn ib_address_bar on as soon as the user is free to browse; keep driving with your own buttons for constrained workflows.
• Rely on of_can_go_back() / of_can_go_forward() for the state of your buttons rather than counting pages yourself: redirections would throw your count off.
• Nothing to plan for sites that refuse embedded display: the page is always opened as a top-level document, so those headers do not apply.
• Call of_reset() when switching context: it is the only way to guarantee that no previous page is reachable through the Back button. When the user of the workstation changes, add of_clear_browsing_data(): without it, cookies and sessions of the sites stay.
• The component needs the web runtime installed on the machine: handle ue_runtime_missing as you would for any other component (Installation).
• A site may play sound without a user gesture: autoplay with sound is allowed in the whole WebView2 environment of the application (the video and sound players need it, a hidden page has no gesture). A page that starts a video with sound on opening will play it; if that is a problem, open addresses you know.
• To keep the application on its own servers, list them in is_allowed_hosts: it also stops redirections, which ue_navigating does not see.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents