webbrowser — `u_pbt_webbrowser` #

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 #

Userobject	`u_pbt_webbrowser`
Item class	— (component without items)
Used for	Displaying a web page, an internal portal, online documentation or generated HTML content without leaving the application
Two display modes	embedded (default) or full page, depending on how tolerant the visited site is

Quick start #

// open event of the window
uo_navigateur.ib_address_bar = true    // address bar + navigation buttons
uo_navigateur.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://.

Properties #

Property	Type	Default	Purpose
`is_address`	string	`""`	Address being displayed. Assigning this property triggers navigation. Reading it back gives the page actually on screen: follow a link and it follows too (`ue_load_completed` tells you). Every scheme is accepted, including `data:` and `file:`
`ib_address_bar`	boolean	`false`	Shows the built-in address bar: URL field, Back / Forward / Refresh buttons
`ib_context_menu`	boolean	`false`	Enables the navigation context menu on right-click: Back, Forward, Refresh
`is_theme_style`	string	`fluent`	Visual style of the component (`THEME_STYLE_*` constants)
`is_theme_mode`	string	`light`	Light or dark variant (`THEME_MODE_*` constants)
`il_theme_accent`	long	`-1`	Accent color of this component (`-1` = the theme accent)

Methods #

Method	Purpose
`of_refresh ( )`	Reloads the current page
`of_go_back ( )`	Returns to the previous page
`of_go_forward ( )`	Moves on to the next page
`of_can_go_back ( )` → boolean	`true` if a previous page exists — to enable or gray out your own Back button
`of_can_go_forward ( )` → boolean	`true` if a next page exists
`of_stop ( )`	Interrupts the page currently loading
`of_execute_javascript (string as_script)`	Runs a script inside the browsed page and returns what it evaluates to, as a string (JSON: a text comes back quoted, a number does not). One condition, and it is structural: the page must have finished loading, so call it from `ue_load_completed`, never right after setting `is_address`. Returns an empty string when the script fails or there is no browsed page
`of_reset ( )`	Returns the component to a clean state: page cleared, navigation history erased, address bar hidden, context menu disabled, back to embedded mode
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exports the rendering as an image

Events #

Event	Raised when
`ue_load_completed (string as_url)`	A page has finished loading; `as_url` is the address actually displayed
`ue_ready ( )`	The component has finished loading; everything sent beforehand has been replayed
`ue_runtime_missing ( )`	The WebView2 runtime is missing: the component stays empty
`ue_bg_color (long al_color)`	The component has computed its theme background color; the userobject has already adopted it (`backcolor`)

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.

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

The buttons gray themselves out when there is nowhere to go.

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_navigateur.of_go_back()
uo_navigateur.of_go_forward()

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

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

ib_context_menu adds a small Back / Forward / Refresh menu on right-click, themed and rendered by the application. It shares exactly the same history as the address bar, so the two always stay consistent.

uo_navigateur.ib_context_menu = true

Stopping a load #

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

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_navigateur.ib_address_bar = true
uo_navigateur.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 #

Any address is accepted, including an HTML page supplied directly. Handy for previewing a letter, a ticket, an invoice or a report generated by your application, with no network call and no temporary file:

string ls_html

ls_html = "<html><head><meta charset='utf-8'></head><body>" &
        + "<h1>Order summary</h1>" &
        + "<p>Thank you for your business.</p>" &
        + "</body></html>"

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

A local file opens the same way with file:///C:/temp/rapport.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.

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

uo_navigateur.ib_address_bar = true
uo_navigateur.is_address = ls_url_du_dossier

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_navigateur.of_reset()                  // start clean (history included)

uo_navigateur.ib_address_bar  = true      // URL field + Back / Forward / Refresh
uo_navigateur.ib_context_menu = true      // same navigation on right-click
uo_navigateur.is_address = "https://intranet.societe.fr/accueil"

// ue_load_completed event of uo_navigateur : (string as_url)
uo_statut.of_item("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.
The component needs the web runtime installed on the machine: handle ue_runtime_missing as you would for any other component (Installation).

← Component reference · Guide contents

webbrowser — u_pbt_webbrowser #