3. Shared foundation u_pbt_base #

← Getting started · Contents · Themes →

Every visual component inherits from u_pbt_base, which provides the life cycle, the property engine, the transport to the web component and error handling. The properties themselves — theme and tooltips included — are published by each component: its own page lists them all. You never use u_pbt_base directly — you drop a concrete component onto your window — but everything described below is available everywhere.

3.1 The property engine #

Assigning #

Every value you can drive is a public instance variable, assigned directly:

uo_progress.id_value   = 42.5
uo_progress.is_label   = "Import in progress…"
uo_progress.ib_animated = true

The Hungarian prefix tells you the type: is_ string, ib_ boolean, ii_ integer, il_ long (often an RGB() color), id_ double.

There is no scalar of_set_xxx: a property is set by assignment. What remains methods are additions, removals and actions (of_add_*, of_remove_*, of_select_*, of_reset, of_set_layout…).

Reading back #

Reading returns the current value (a cache on the PowerBuilder side):

if uo_progress.id_value >= 100 then …

A web component cannot be queried synchronously, so that cache is refreshed by the events. Whenever the component moves a property by itself — the user follows a link, zooms with the wheel, folds the ribbon, types — the event that tells you about it updates the property on the way. Reading it back then gives the real state, and the new value is already in place when your event code runs.

The same holds for items: after a user click, of_item(...) reads back what is on screen — the selected entry, the folded section, the checked button.

A property that no event accompanies stays on the last value you set.

Batching changes #

A burst of assignments triggers just as many renders. of_set_redraw merges them into a single one:

uo_grid.of_set_redraw(false)
… vingt affectations et of_add_* …
uo_grid.of_set_redraw(true)     // ONE single repaint

Always call both (the closing true is not optional).

3.2 Items #

A component with content (tabs, buttons, panels, tiles, sections…) exposes its elements through typed handles, obtained from the component itself or from their parent.

Adding #

Adding returns the handle of the element that was created:

n_pbt_tab_page lnv_page

uo_tab.of_add_page("clients", "Customers", uo_page_clients)
lnv_page = uo_tab.of_item("clients")
lnv_page.is_icon = "img\clients.png"

Retrieving and modifying #

of_item(id) — or the factory for the level concerned — returns the handle of an existing element; its properties are set exactly like a component's:

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false
uo_tab.of_item("clients").is_title = "Customers (128)"

Hierarchies: an identifier is only unique within its parent #

A multi-level component provides no shortcut down to the leaf: the full path is required, which guarantees that no identifier is ambiguous.

// Ribbon: tab > group > control > menu entry
uo_ribbon.of_tab("home").of_group("clipboard").of_item("paste").ib_enabled = false

The events carry the full path as well:

// ue_clicked event of uo_toolbar: (string as_bar, string as_id)
choose case as_bar + "/" + as_id
    case "main/save" ; of_enregistrer()
end choose

Item events #

There are no generic item events on the ancestor: a leaf identifier alone would be ambiguous as soon as items are nested (a toolbar has several bars, a tilesbox several groups…). Each component therefore declares its own item events, carrying the full path: ue_item_selected (as_section, as_id) for the listbar, ue_tile_clicked (as_group, as_id) for the tilesbox, ue_clicked (as_bar, as_id) for the toolbar…

See the component page: that is where the exact list lives.

3.3 Events common to every component #

Commands sent before ue_ready are not lost: they are queued and replayed in order. You can therefore configure everything as early as the constructor or the open.

// ue_bg_color event: match the window to the component background
parent.backcolor = al_color

3.4 Optional properties and events (opt-in) #

Some features are not enabled by default: they are only published by the components where they make sense, and you have to ask for them.

Automatic height — ib_auto_height #

The component measures its ideal height and resizes the userobject; the ue_auto_height(al_height) event lets you reposition the neighboring controls.

uo_entete.ib_auto_height = true

// ue_auto_height event of uo_entete
il_hauteur_entete = al_height
of_relayout()          // reposition the content below

Published by: picture and statictext.

Bands do not publish this property — their height is intrinsic. ribbon and toolbar do not scroll vertically: a fixed height can only produce empty space under the band or truncated content (a collapsed ribbon, a toolbar wrapped onto two rows, and so on). They therefore adjust at all times, with nothing to enable, and still publish ue_auto_height so that you can reposition whatever sits below.

Automatic width — ib_auto_width #

Same principle for the width. Published only by listbar, the one component whose natural width means something.

A collapsed listbar shrinks to the rail on its own and gives the width back when it expands: ib_auto_width is only useful if you also want to follow the expanded width (the bar then sizes itself to the longest label).

Ambient mouse events — ib_track_mouse #

High-frequency mouse events are cut off at the source: without a subscription, the component does not emit them at all (nothing crosses the bridge to PowerBuilder).

uo_bouton.ib_track_mouse = true    // enables ue_mouse_enter / ue_mouse_leave / ue_rclicked

Published by: button, picture, statictext.

Discrete events (click, selection, menu, drop…) are always emitted, with no subscription needed.

3.5 Keyboard shortcuts #

A shortcut triggers a component wherever the focus sits in the window — the user does not have to go back to the button to fire it. Every visual component accepts them, with nothing to enable.

uo_enregistrer.of_register_shortcut("Ctrl+S")
uo_actualiser.of_register_shortcut("F5")

Writing a key chord #

The chord is a free-form string, normalized by the library: case, spaces and modifier order are irrelevant. "Ctrl+Shift+S", "ctrl + shift + s" and "SHIFT+CTRL+S" all mean the same shortcut — you cannot register two variants of it by mistake.

This list is exhaustive: a key that is not in it (Tab, Space, a numeric keypad key, a punctuation character) fires no shortcut.

A single key is a valid chord ("F5"). An empty string removes the shortcut from the component.

"Enter" and "Escape" on their own cannot be registered as shortcuts: those two keys stay reserved for the default button and the cancel button (ib_default / ib_cancel of the button). Combined with a modifier, they become ordinary chords again ("Ctrl+Enter").

Who wins in case of conflict #

Two components may ask for the same chord — a common situation when a window hosts several areas that each have their own "Save". The arbitration goes like this:

1. the component that holds the keyboard focus wins over all the others: the shortcut of an active area is never eclipsed by a neighbour;
2. failing that, the first one registered wins.

Only the visible and enabled components of the foreground window take part. Re-registering a chord on a component that already had one replaces it without changing its rank: reconfiguring a window does not reshuffle the priorities.

Item shortcuts #

The two-argument overload attaches the chord to an item of the component rather than to the whole component — the second argument is the item identifier:

uo_barre.of_register_shortcut(/*chord*/ "Ctrl+N", /*item*/ "nouveau")
uo_barre.of_register_shortcut(/*chord*/ "Ctrl+P", /*item*/ "imprimer")

Removing shortcuts #

uo_barre.of_clear_shortcuts()      // component AND items

of_reset() and destroying the component call of_clear_shortcuts() for you: a component that is gone never keeps a chord reserved.

The Alt key #

Alt on its own is not captured: it gives the focus to the ribbon, which raises its keytips (see ribbon). The library therefore does not intercept the keystrokes that follow — the ribbon reads them, as if the user had clicked it. Escape or a second Alt return the focus to the control that was left. If no ribbon in the window declares a keytip, Alt keeps its usual Windows behaviour.

3.6 Resetting a component: of_reset() #

of_reset() returns the component to its as-new state, as if it had just been loaded:

• the content is cleared (items, pages, panels…);
• every property goes back to its default (formatting, colors, mode, labels);
• the style overrides and tooltips set on the instance are cancelled;
• the property cache on the PowerBuilder side is emptied (read-backs start again from the defaults);
• the native state is flattened as well (context menu, display mode…).

uo_grid.of_reset()          // start again from an empty grid
// ... then rebuild

⚠️ Reusing an instance to display something else without calling of_reset() keeps the previous state (a color, a mode, an automatic height). This is the single most common cause of an unexplained "leftover" on screen.

3.7 Diagnostics #

Return codes of the of_* methods:

3.8 Exporting the rendering as an image #

Every component can export itself as an image, exactly as displayed:

uo_pivot.of_save_as_png("C:\temp\tableau.png")
uo_pivot.of_save_as_jpg("C:\temp\tableau.jpg")

To print it rather than export it, see Printing.

Handy for a report, an e-mail attachment or an incident trace. The component must be created and its content loaded.

3.9 Life cycle #

1. Construction: the webview is created as soon as the userobject is constructed — essential for hosting (tabs, dockable panels): a webview created after its HWND has been reparented does not display.
2. Queue: your commands are queued for as long as ue_ready has not been raised.
3. Ready: ue_ready; the queue is replayed in order.
4. Resizing: automatic, the component follows the size of the userobject.
5. Destruction: when the window closes; the webview is released, with no orphan process left behind.

Call PBT_Warmup() once when the application starts so that this cycle goes unnoticed (Installation).

3.10 Best practices #

• Set the default theme and the language in the application object, before the first window opens: the components then show no style flash.
• Wrap any bulk build in of_set_redraw(false) / of_set_redraw(true).
• Call of_reset() before reusing an instance for different content.
• Do not block the UI thread with a long PowerScript loop between creation and display: initializing the webview needs the message loop (see FAQ).

← Getting started · Contents · Themes →