progressbar — u_pbt_progressbar #

← Referencia de componentes · Índice de la guía

Barra de progreso con tema: barra horizontal o anillo, valor numérico o animación de espera, porcentaje mostrado, color libre.

▶ Verlo en vivo — Aplicación de demostración, mosaico Progress: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

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

Propiedades #

Este componente no publica tooltip (is_tooltip, is_super_tooltip_*): una barra de progreso se lee por sí sola, y una etiqueta al pasar el ratón aparecería bajo el puntero justo en el momento en que el usuario mira a otra parte. Ponga el comentario de avance en un statictext o una statusbar junto a la barra.

Métodos #

Eventos #

Ejemplos #

Progreso determinado con porcentaje #

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

Progreso indeterminado (duración desconocida) #

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

Anillo circular #

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

Escala personalizada #

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

El porcentaje mostrado por ib_label sigue calculándose con respecto a esta escala.

Color personalizado y control del valor #

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

Etiqueta personalizada y estado de error #

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

Buenas prácticas #

• Elija el modo en función de lo que sepa: indeterminado mientras se desconozca el volumen, determinado en cuanto se conozca.
• Prefiera id_minimum / id_maximum al cálculo manual de un porcentaje: la etiqueta y la visualización se adaptan solas.
• Deje il_color en -1 para que la barra siga tanto el tema claro como el oscuro; fije un color únicamente para transmitir un significado (verde = éxito). Un procesamiento en pausa o fallido se indica con is_state.
• Asigne id_value sin preocuparse: la barra solo se vuelve a dibujar cuando cambia lo que muestra. Cada dibujo deja que la pantalla se actualice: la barra avanza durante el bucle, sin código por su parte.
• Llame a of_reset() antes de reutilizar la misma barra para otro procesamiento.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía