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

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

### The navigation context menu #

`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