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 #

Démarrage rapide #

// 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

Propriétés #

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 #

Événements #

Exemples #

Progression déterminée avec pourcentage #

// Show the percentage, then move the bar
uo_progress.ib_label = true
uo_progress.id_value = 75     // the bar fills up to three quarters

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

// 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

Anneau circulaire #

// 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

Échelle personnalisée #

// 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

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

Couleur personnalisée et pilotage de la valeur #

// 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

Libellé personnalisé et état d'échec #

// 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

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 id_minimum / id_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). Un traitement en pause ou en échec se dit par is_state.
• Affectez id_value sans compter : la barre n'est redessinée que quand ce qu'elle montre change. Chaque dessin laisse l'écran se rafraîchir : la barre avance pendant la boucle, sans code de votre part.
• Appelez of_reset() avant de réutiliser la même barre pour un autre traitement.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

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