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 #

// Local variables
long ll_total = 4820

// Window open event : the readout, and the scale of the job
uo_progress.ib_show_value = true     // shows the percentage next to the bar
uo_progress.id_maximum = ll_total    // the scale of the job : nothing to compute

// Local variables
long ll_i, ll_total = 4820

// 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), or on every value when `is_format` writes it
`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`; the bar stands up with `is_orientation`
`is_orientation`	string	`"horizontal"`	Direction of the linear bar, in the words of the linear gauge: `horizontal` (default) or `vertical` — constants `ORIENTATION_HORIZONTAL`, `ORIENTATION_VERTICAL`. Vertical, the bar fills from the bottom up (a level, a tank, a queue), its readout under it: it fits where a `VProgressBar` stood. The ring ignores it. An unknown value falls back to `horizontal`
`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. With `ib_show_value`, the readout writes `is_unit` alone: the text of the wait ("Connecting..."). Paused or failed (`is_state`), the wait stops: a full bar (a full ring) at the color of the state, as the Windows taskbar shows it
`ib_show_value`	boolean	`false`	Displays the readout next to the bar or at the center of the ring: the percentage in the display language ("50%" in English, "50 %" in French), or the value written by `is_format`, followed by `is_unit`. A long readout is cut with "…" rather than crush the bar (the track keeps 40 % of the control); in the ring, the unit goes on a second line and the whole shrinks until it fits, the unit dropped when room is lacking. While busy (`ib_indeterminate`), only `is_unit` is written
`is_format`	string	`""`	Display format of the value in the readout (`ib_show_value`), in the syntax of a DataWindow format, as the gauges write it (`#,##0`, `#,##0.00`, `$#,##0`). The separators are those of the display language. A mask that holds `%` writes the share done, not the value: `0.0%` gives "35.0%" for 1,687 rows out of 4,820, on any scale, rounded down like the percentage (100 % = finished). Empty = the percentage. Once it is set, every value is sent to the bar, since the readout writes it. The screen reader says the same text
`is_unit`	string	`""`	Written after the readout, separated by a space: after the value, or after the percentage when `is_format` is empty (`of 500 rows`, `done`). Plain text, never markup. While busy, it is the only text of the readout (`Connecting...`); in the ring, it has a line of its own
`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_value_color`. A busy bar (`ib_indeterminate`) that is paused or failed stops and turns full at the color of the state, as the Windows taskbar shows it. The screen reader says the state before the value ("Error, 64%"). An unknown value counts as `STATE_NORMAL`
`il_value_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. `RGB()` only: a PowerBuilder system color (Highlight, ButtonFace…) has no color of its own, it is ignored (the bar keeps the accent, the property reads back `-1`)
`is_accessible_name`	string	`""`	What the screen reader calls this bar, like the `AccessibleName` of an `HProgressBar`. Empty = "Progress" in the display language: two bars in one window (a download, an import) are told apart only by their name. Plain text, never markup
`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. of_set_property("tooltip", …) (and super_tooltip_*) returns -5: the door by name is closed too.

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_show_value = 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_show_value = true
uo_progress.id_value = 40

Custom scale #

// Local variables
long ll_row_count = 4820, ll_current_row = 1687

// 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_show_value is still computed against that scale.

Custom color and driving the value #

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

// The fill color accepts a standard PowerBuilder RGB()
uo_progress.il_value_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

Formatted value, unit and failed state #

// The readout counts rows instead of a bare percentage
uo_progress.ib_show_value = true
uo_progress.id_maximum = 4820
uo_progress.id_value = 3120

// The value with a PowerBuilder mask, then what it counts
uo_progress.is_format = "#,##0"
uo_progress.is_unit = "of 4,820 rows"

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

A percentage with decimals #

// The readout says the share done with one decimal : a mask in % writes the percentage
uo_progress.ib_show_value = true
uo_progress.id_maximum = 4820
uo_progress.id_value = 1687
uo_progress.is_format = "0.0%"     // 35.0%

A wait that fails #

// A job of unknown length : a busy bar, with the text of the wait
uo_progress.ib_indeterminate = true
uo_progress.ib_show_value = true
uo_progress.is_unit = "Connecting to the server..."

// The connection failed : the busy bar stops, full and red, and says why
uo_progress.is_state = u_pbt_progressbar.STATE_ERROR
uo_progress.is_unit = "Connection lost"

A vertical bar with a name of its own #

// A level that fills from the bottom up, where a VProgressBar stood
uo_progress.is_orientation = u_pbt_progressbar.ORIENTATION_VERTICAL
uo_progress.ib_show_value = true
uo_progress.id_value = 35

// Two bars in one window : the screen reader tells them apart by their name
uo_progress.is_accessible_name = "Tank level"

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_value_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. At least one value every 50 ms of the clock waits until the bar has drawn it: the bar moves during the loop, even when the loop waits for a database or a network, with no code of yours.
Two bars in one window: give each its is_accessible_name, so that the screen reader tells them apart.
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
`is_accessible_name` · `is_accessible_description`	The name and description a screen reader says	3.4 Optional properties and events

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.