progressbar — u_pbt_progressbar #

← Komponentenreferenz · Inhalt des Handbuchs

Fortschrittsbalken im Design: waagerechter Balken oder Ring, Zahlenwert oder Warteanimation, angezeigter Prozentsatz, frei wählbare Farbe.

▶ Live ansehen — Demoanwendung, Kachel Progress: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

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

Eigenschaften #

Diese Komponente veröffentlicht keinen Tooltip (is_tooltip, is_super_tooltip_*): Ein Fortschrittsbalken spricht für sich selbst, und eine Beschriftung beim Überfahren erschiene genau in dem Moment unter dem Zeiger, in dem der Anwender woanders hinsieht. Setzen Sie den Kommentar zum Fortschritt in einen statictext oder eine statusbar neben den Balken. of_set_property("tooltip", …) (und super_tooltip_*) liefert -5: Auch der Weg über den Namen ist geschlossen.

Methoden #

Events #

Beispiele #

Bestimmter Fortschritt mit Prozentsatz #

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

Unbestimmter Fortschritt (unbekannte Dauer) #

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

Kreisförmiger 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

Eigene Skala #

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

Der von ib_show_value angezeigte Prozentsatz wird weiterhin anhand dieser Skala berechnet.

Eigene Farbe und Steuerung des Werts #

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

Formatierter Wert, Einheit und Fehlerzustand #

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

Ein Prozentsatz mit Nachkommastellen #

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

Ein Warten, das fehlschlägt #

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

Ein senkrechter Balken mit eigenem Namen #

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

• Wählen Sie den Modus danach, was Sie wissen: unbestimmt, solange die Menge unbekannt ist, bestimmt, sobald sie feststeht.
• Ziehen Sie id_minimum / id_maximum dem manuellen Berechnen eines Prozentsatzes vor: Beschriftung und Anzeige folgen von selbst.
• Lassen Sie il_value_color auf -1, damit der Balken sowohl dem hellen als auch dem dunklen Design folgt; legen Sie eine Farbe nur fest, wenn sie eine Bedeutung trägt (Grün = Erfolg). Ein pausierter oder fehlgeschlagener Vorgang wird mit is_state angezeigt.
• Setzen Sie id_value ohne Bedenken: der Balken wird nur neu gezeichnet, wenn sich ändert, was er zeigt. Mindestens ein Wert alle 50 ms der Uhr wartet, bis der Balken ihn gezeichnet hat: der Balken bewegt sich während der Schleife, auch wenn diese auf eine Datenbank oder ein Netzwerk wartet, ohne Code Ihrerseits.
• Zwei Balken in einem Fenster: Geben Sie jedem seinen is_accessible_name, damit der Bildschirmleser sie unterscheidet.
• Rufen Sie of_reset() auf, bevor Sie denselben Balken für einen anderen Vorgang wiederverwenden.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs