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_progress.ib_label = true          // shows the percentage next to the bar
uo_progress.id_maximum = ll_total    // the scale of the job : nothing to compute

// During the operation : give the raw value, row by row. It costs almost
// nothing : the bar is redrawn only when what it shows changes.
for ll_i = 1 to ll_total
    of_process_row(ll_i)
    uo_progress.id_value = ll_i
next

Properties #

Property	Type	Default	Purpose
`id_value`	double	`0`	Current progress, a RAW value on the `id_minimum` … `id_maximum` scale, read back as you last set it (not bounded). The label rounds down: 99.6 shows 99 %, 100 % means finished. Setting it on every row of a loop costs almost nothing: the bar is redrawn only when what it shows changes (a tenth of a percent)
`id_minimum`	double	`0`	Lower bound of the scale. A `double`: a 0..1 fraction is a valid scale
`id_maximum`	double	`100`	Upper bound of the scale. A `double`: a byte count over 2 GB is a valid scale. Empty or inverted range (min ≥ max): 100 % once the value reaches the maximum, 0 % before — an empty batch (`id_maximum = 0`, `id_value = 0`) shows as finished
`is_mode`	string	`"linear"`	Shape of the component: `linear` (a horizontal bar that takes the whole width of the control and follows its height: it fits where an `HProgressBar` stood) or `circular` (ring) — constants `MODE_LINEAR`, `MODE_CIRCULAR`. An unknown value falls back to `linear`
`ib_indeterminate`	boolean	`false`	Waiting mode: a sliding bar, or a fixed arc spinning in circular mode; `id_value` is ignored but kept. When Windows asks for fewer animations, the waiting state pulses instead of moving
`ib_label`	boolean	`false`	Displays the percentage next to the bar or at the center of the ring, in the display language ("50%" in English, "50 %" in French). `is_label_format` changes what it says
`is_label_format`	string	`""`	What the label says (`ib_label`). Empty = the percentage. Otherwise a text in which `{percent}`, `{value}`, `{min}` and `{max}` are replaced, numbers written in the display language; the rest is written as it stands, as plain text. The screen reader says the same text
`is_state`	string	`"normal"`	The meaning of the bar, like the Windows progress bar: `STATE_NORMAL` (accent color), `STATE_PAUSED` (yellow, the job waits) or `STATE_ERROR` (red, the job failed). Paused and error take the status colors of the theme, light or dark, and win over `il_color`; a busy bar stops moving. An unknown value counts as `STATE_NORMAL`
`il_color`	long	`-1`	Fill color, in PowerBuilder `RGB()` format. `-1` = accent color of the theme. When paused or in error (`is_state`), the state color wins
`is_theme_style`	string	`""`	Visual style of the component (`THEME_STYLE_*` constants); empty = the application's, followed at every change
`is_theme_mode`	string	`""`	Light or dark variant (`THEME_MODE_*` constants); empty = the application's, followed at every change
`il_theme_accent`	long	`-1`	Accent colour of this component (`-1` = the application accent, or the theme's)

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 #

// Show the percentage, then move the bar
uo_progress.ib_label = true
uo_progress.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_progress.ib_indeterminate = true

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

Circular ring #

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

Custom scale #

// Progress is not always a percentage : give the real scale
uo_progress.id_minimum = 0
uo_progress.id_maximum = ll_row_count    // e.g. 4820 rows to import

// Then report the row being processed
uo_progress.id_value = ll_current_row // raw value, not a percentage

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

Custom color and driving the value #

// Show the percentage next to the bar
uo_progress.ib_label = true

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

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

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

Custom label and failed state #

// The label counts rows instead of a bare percentage
uo_progress.ib_label = true
uo_progress.id_maximum = 4820
uo_progress.id_value = 3120
uo_progress.is_label_format = "{value} of {max} rows ({percent})"

// The import failed at this row : the bar turns red where it stands
uo_progress.is_state = u_pbt_progressbar.STATE_ERROR

Best practices #

Pick the mode according to what you know: indeterminate while the volume is unknown, determinate as soon as it is.
Prefer id_minimum / id_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). A paused or failed job is told with is_state.
Set id_value freely: the bar is redrawn only when what it shows changes. Each redraw lets the screen refresh: the bar moves during the loop, with no code of yours.
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
`of_set_property` · `of_get_property` · `of_component_name`	Driving a property by its name	3.1 The property engine

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.