# 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)
`of_set_redraw (boolean)` | Groups a burst of changes into a single render
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exports the rendering as an image

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

← Component reference · Guide contents