# progressbar — `u_pbt_progressbar` #

← Référence des composants · Sommaire du guide

> Barre de progression thémée : barre horizontale ou anneau, valeur chiffrée ou animation d'attente, pourcentage affiché, couleur libre.

> ▶ Le voir en vrai — Application de démonstration, tuile Progress : l'aperçu, le code qui le produit et cette page, côte à côte.

## En bref #

Userobject | `u_pbt_progressbar`
Classe d'items | — (composant sans items)
Sert à | Montrer l'avancement d'un traitement long : import, export, impression, appel serveur
Deux usages | déterminé (on connaît l'avancement) ou indéterminé (on sait seulement que ça travaille)

## Démarrage rapide #

    // event open de la fenetre
    uo_progression.ib_label = true      // affiche le pourcentage sur la barre
    uo_progression.id_value = 0         // point de depart

    // Pendant le traitement : une simple affectation deplace la barre
    for ll_i = 1 to ll_total
        of_traiter_ligne(ll_i)
        uo_progression.id_value = (ll_i / ll_total) * 100
    next

## Propriétés #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`id_value` | double | `0` | Avancement courant, exprimé dans l'échelle `il_minimum` … `il_maximum`
`il_minimum` | long | `0` | Borne basse de l'échelle
`il_maximum` | long | `100` | Borne haute de l'échelle
`is_mode` | string | `"linear"` | Forme du composant : `linear` (barre horizontale) ou `circular` (anneau) — constantes `MODE_LINEAR`, `MODE_CIRCULAR`
`ib_indeterminate` | boolean | `false` | Mode attente : animation continue, `id_value` est ignorée
`ib_label` | boolean | `false` | Affiche le pourcentage sur la barre ou au centre de l'anneau
`il_color` | long | `-1` | Couleur de remplissage, au format `RGB()` PowerBuilder. `-1` = couleur du thème
`is_theme_style` | string | `fluent` | Style visuel du composant (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante claire ou sombre (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Couleur d'accent de ce composant (`-1` = accent du thème)

> Ce composant ne publie pas d'info-bulle (`is_tooltip`, `is_super_tooltip_*`) : une barre de progression se lit d'elle-même, et un libellé au survol arriverait sous le pointeur au moment précis où l'utilisateur regarde ailleurs. Mettez le commentaire d'avancement dans un statictext ou une statusbar à côté de la barre.

## Méthodes #

Méthode | Rôle
--- | ---
`of_reset ( )` | Remet toutes les propriétés à leur défaut (barre linéaire, échelle 0–100, valeur 0, pourcentage masqué, couleur du thème)
`of_set_redraw (boolean)` | Regroupe une rafale de modifications en un seul rendu
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporte le rendu en image

## Événements #

Événement | Déclenché quand
--- | ---
`ue_ready ( )` | Le composant a fini de charger ; tout ce qui a été envoyé avant a été rejoué
`ue_runtime_missing ( )` | Le runtime WebView2 est absent : le composant reste vide
`ue_bg_color (long al_color)` | Le composant a calculé sa couleur de fond de thème ; l'userobject l'a déjà adoptée (`backcolor`)

## Exemples #

### Progression déterminée avec pourcentage #

    uo_progression.ib_label = true
    uo_progression.id_value = 75      // la barre se remplit aux trois quarts

### Progression indéterminée (durée inconnue) #

    // Quand la duree est inconnue : la barre s'anime en continu
    // et ignore id_value
    uo_progression.ib_indeterminate = true

    // Une fois la duree connue, on revient au mode determine
    uo_progression.ib_indeterminate = false
    uo_progression.id_value = 20

### Anneau circulaire #

    // Mode d'affichage : linear (barre) ou circular (anneau)
    uo_progression.is_mode  = uo_progression.MODE_CIRCULAR
    uo_progression.ib_label = true
    uo_progression.id_value = 40

### Échelle personnalisée #

    // L'avancement n'est pas toujours un pourcentage : on donne l'echelle reelle
    uo_progression.il_minimum = 0
    uo_progression.il_maximum = ll_nb_lignes    // ex : 4820 lignes a importer

    uo_progression.id_value = ll_ligne_courante // valeur brute, pas un pourcentage

Le pourcentage affiché par `ib_label` reste calculé par rapport à cette échelle.

### Couleur personnalisée et pilotage de la valeur #

    uo_progression.ib_label = true

    // La couleur de remplissage accepte un RGB() PowerBuilder standard
    uo_progression.il_color = RGB(/*red*/ 16, /*green*/ 137, /*blue*/ 62)

    // La barre affiche une valeur, elle ne la calcule pas : c'est votre code qui l'avance
    uo_progression.id_value = 0

    // event timer de la fenetre, une fois par seconde
    if uo_progression.id_value >= 100 then
    	Timer(0)   // termine : votre code le sait, c'est lui qui l'a decide
    	uo_statut.of_item("main").is_text = "Import termine"
    else
    	uo_progression.id_value = uo_progression.id_value + 10
    end if

## Bonnes pratiques #

- Choisissez le mode selon ce que vous savez : indéterminé tant que le volume est inconnu, déterminé dès qu'il l'est.
- Préférez `il_minimum` / `il_maximum` au calcul manuel d'un pourcentage : le libellé et l'affichage suivent tout seuls.
- Laissez `il_color` à `-1` pour que la barre suive le thème clair comme sombre ; ne fixez une couleur que pour porter un sens (vert = succès, rouge = alerte).
- Une longue boucle PowerScript sans rendre la main gèle l'affichage : laissez respirer la boucle de messages entre deux lots (voir FAQ).
- Appelez `of_reset()` avant de réutiliser la même barre pour un autre traitement.

← Référence des composants · Sommaire du guide