progressbar — `u_pbt_progressbar` #

← Component reference · Guide contents

Themed progress bar: horizontal bar or ring, numeric value or waiting animation, percentage display, free choice of color.

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

At a glance #

Userobject	`u_pbt_progressbar`
Item class	— (component without items)
Used for	Showing how far a long operation has gone: import, export, printing, server call
Two use cases	determinate (you know the progress) or indeterminate (you only know that work is in progress)

Quick start #

// window open event
uo_progression.ib_label = true      // shows the percentage on the bar
uo_progression.id_value = 0         // starting point

// During the operation : a simple assignment moves the bar
for ll_i = 1 to ll_total
    of_traiter_ligne(ll_i)
    uo_progression.id_value = (ll_i / ll_total) * 100
next

Properties #

Property	Type	Default	Purpose
`id_value`	double	`0`	Current progress, expressed on the `il_minimum` … `il_maximum` scale
`il_minimum`	long	`0`	Lower bound of the scale
`il_maximum`	long	`100`	Upper bound of the scale
`is_mode`	string	`"linear"`	Shape of the component: `linear` (horizontal bar) or `circular` (ring) — constants `MODE_LINEAR`, `MODE_CIRCULAR`
`ib_indeterminate`	boolean	`false`	Waiting mode: continuous animation, `id_value` is ignored
`ib_label`	boolean	`false`	Displays the percentage on the bar or at the center of the ring
`il_color`	long	`-1`	Fill color, in PowerBuilder `RGB()` format. `-1` = color from the theme
`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)

This component publishes no tooltip (is_tooltip, is_super_tooltip_*): a progress bar reads by itself, and a caption on hover would appear under the pointer at the very moment the user is looking elsewhere. Put the progress commentary in a statictext or a statusbar next to the bar.

Methods #

Method	Purpose
`of_reset ( )`	Resets every property to its default (linear bar, 0–100 scale, value 0, percentage hidden, theme color). Returns `0` once applied, `-2` when the component is not created
`of_set_redraw (boolean)`	Groups a burst of changes into a single render. Returns `0` once applied, `-2` when the component is not created
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exports the rendering as an image. Returns `0` once the image is written, `-4` when writing fails, `-2` when the component is not created

Events #

Event	Raised when
`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`)

Examples #

Determinate progress with a percentage #

uo_progression.ib_label = true
uo_progression.id_value = 75      // the bar fills up to three quarters

Indeterminate progress (unknown duration) #

// When the duration is unknown : the bar animates continuously
// and ignores id_value
uo_progression.ib_indeterminate = true

// Once the duration is known, switch back to determinate mode
uo_progression.ib_indeterminate = false
uo_progression.id_value = 20

Circular ring #

// Display mode : linear (bar) or circular (ring)
uo_progression.is_mode  = uo_progression.MODE_CIRCULAR
uo_progression.ib_label = true
uo_progression.id_value = 40

Custom scale #

// Progress is not always a percentage : give the real scale
uo_progression.il_minimum = 0
uo_progression.il_maximum = ll_nb_lignes    // e.g. 4820 rows to import

uo_progression.id_value = ll_ligne_courante // raw value, not a percentage

The percentage displayed by ib_label is still computed against that scale.

Custom color and driving the value #

uo_progression.ib_label = true

// The fill color accepts a standard PowerBuilder RGB()
uo_progression.il_color = RGB(/*red*/ 16, /*green*/ 137, /*blue*/ 62)

// The bar displays a value, it never computes one : your code moves it
uo_progression.id_value = 0

// timer event of the window, once a second
if uo_progression.id_value >= 100 then
	Timer(0)   // done : your code knows, it is the one that decided
	uo_statut.of_item("main").is_text = "Import complete"
else
	uo_progression.id_value = uo_progression.id_value + 10
end if

Best practices #

Pick the mode according to what you know: indeterminate while the volume is unknown, determinate as soon as it is.
Prefer il_minimum / il_maximum over computing a percentage by hand: the label and the display follow on their own.
Leave il_color at -1 so the bar follows both the light and the dark theme; set a color only when it carries meaning (green = success, red = warning).
A long PowerScript loop that never yields freezes the display: let the message loop breathe between batches (see FAQ).
Call of_reset() before reusing the same bar for another operation.

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.

Members	Role	Detailed in
`of_reset`	Put the component back to zero	3.6 Resetting a component: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	The component's keyboard chords	3.5 Keyboard shortcuts
`of_is_created` · `of_is_ready` · `of_get_last_error`	Whether it was born, whether it is ready, what failed	3.7 Diagnostics
`of_save_as_png` · `of_save_as_jpg`	Export the rendering as an image	3.8 Exporting the rendering as an image
`of_set_redraw`	Group changes into a single repaint	3.10 Best practices
`of_preload_icons`	Icons shown with no delay	Instant display: `of_icon`
`of_set_translation`	Translate one of the component's labels	5.2 Adapting a label: `of_set_translation`
`of_focus_webview`	Give the component the focus	6.4 Keyboard and focus
`of_print` · `of_print_to_pdf`	Print, or write a PDF	6.9 Printing

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.