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 #

Userobject	`u_pbt_progressbar`
Clase de items	— (componente sin items)
Sirve para	Mostrar el avance de un procesamiento largo: importación, exportación, impresión, llamada al servidor
Dos usos	determinado (se conoce el avance) o indeterminado (solo se sabe que está trabajando)

Inicio rápido #

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

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`id_value`	double	`0`	Avance actual, valor BRUTO en la escala `id_minimum` … `id_maximum`, releído tal como lo asignó por última vez (sin acotar). La etiqueta redondea hacia abajo: 99,6 muestra 99 %, 100 % significa terminado. Asignarlo en cada fila de un bucle apenas cuesta nada: la barra solo se vuelve a dibujar cuando cambia lo que muestra (una décima de punto porcentual), o con cada valor cuando `is_format` lo escribe
`id_minimum`	double	`0`	Límite inferior de la escala. Un `double`: una fracción 0..1 es una escala válida
`id_maximum`	double	`100`	Límite superior de la escala. Un `double`: un número de bytes superior a 2 GB es una escala válida. Rango vacío o invertido (mín ≥ máx): 100 % en cuanto el valor alcanza el máximo, 0 % antes — un lote vacío (`id_maximum = 0`, `id_value = 0`) se muestra terminado
`is_mode`	string	`"linear"`	Forma del componente: `linear` (barra horizontal que ocupa todo el ancho del control y sigue su altura: cabe donde estaba una `HProgressBar`) o `circular` (anillo) — constantes `MODE_LINEAR`, `MODE_CIRCULAR`. Un valor desconocido vuelve a `linear`; la barra se pone de pie con `is_orientation`
`is_orientation`	string	`"horizontal"`	Dirección de la barra lineal, con las palabras del indicador lineal: `horizontal` (por defecto) o `vertical` — constantes `ORIENTATION_HORIZONTAL`, `ORIENTATION_VERTICAL`. Vertical, la barra se llena de abajo arriba (un nivel, un depósito, una cola), con la lectura debajo: cabe donde estaba una `VProgressBar`. El anillo la ignora. Un valor desconocido vuelve a `horizontal`
`ib_indeterminate`	boolean	`false`	Modo espera: una barra que se desliza, o un arco fijo que gira en modo circular; `id_value` se ignora pero se conserva. Si Windows pide menos animaciones, la espera pulsa en lugar de moverse. Con `ib_show_value`, la lectura escribe solo `is_unit`: el texto de la espera («Connecting...»). En pausa o en error (`is_state`), la espera se detiene: una barra (un anillo) llena del color del estado, como la barra de tareas de Windows
`ib_show_value`	boolean	`false`	Muestra la lectura junto a la barra o en el centro del anillo: el porcentaje en el idioma de visualización («50 %» en francés, «50%» en inglés), o el valor escrito por `is_format`, seguido de `is_unit`. Una lectura larga se corta con «…» en lugar de aplastar la barra (la pista conserva el 40 % del control); en el anillo, la unidad pasa a una segunda línea y el conjunto se reduce hasta caber, la unidad retirada cuando falta sitio. En espera (`ib_indeterminate`), solo se escribe `is_unit`
`is_format`	string	`""`	Formato de visualización del valor en la lectura (`ib_show_value`), con la sintaxis de un formato de DataWindow, como en los indicadores (`#,##0`, `#,##0.00`, `$#,##0`). Los separadores son los del idioma de visualización. Una máscara que contiene `%` escribe la parte realizada, no el valor: `0.0%` da «35.0%» para 1.687 filas de 4.820, en cualquier escala, redondeada hacia abajo como el porcentaje (100 % = terminado). Vacío = el porcentaje. Una vez asignado, cada valor se envía a la barra, puesto que la lectura lo escribe. El lector de pantalla dice el mismo texto
`is_unit`	string	`""`	Se escribe después de la lectura, separado por un espacio: después del valor, o después del porcentaje cuando `is_format` está vacío (`of 500 rows`, `done`). Texto sin formato, nunca marcado. En espera es el único texto de la lectura (`Connecting...`); en el anillo tiene su propia línea
`is_state`	string	`"normal"`	El significado de la barra, como la barra de progreso de Windows: `STATE_NORMAL` (color de acento), `STATE_PAUSED` (amarillo, el procesamiento espera) o `STATE_ERROR` (rojo, el procesamiento ha fallado). Pausa y error toman los colores de estado del tema, claro u oscuro, y prevalecen sobre `il_value_color`. Una barra de espera (`ib_indeterminate`) en pausa o en error se detiene y se vuelve llena del color del estado, como la barra de tareas de Windows. El lector de pantalla dice el estado antes del valor («Error, 64%»). Un valor desconocido equivale a `STATE_NORMAL`
`il_value_color`	long	`-1`	Color de relleno, con el formato `RGB()` de PowerBuilder. `-1` = color de acento del tema. En pausa o en error (`is_state`), prevalece el color de estado. Solo `RGB()`: un color del sistema de PowerBuilder (Highlight, ButtonFace…) no tiene color propio, se ignora (la barra conserva el acento, la propiedad se relee `-1`)
`is_accessible_name`	string	`""`	Cómo llama el lector de pantalla a esta barra, como el `AccessibleName` de una `HProgressBar`. Vacío = «Progress» en el idioma de visualización: dos barras de una misma ventana (una descarga, una importación) solo se distinguen por su nombre. Texto sin formato, nunca marcado
`is_theme_style`	string	`""`	Estilo visual del componente (constantes `THEME_STYLE_*`); vacío = el de la aplicación, seguido en cada cambio
`is_theme_mode`	string	`""`	Variante clara u oscura (constantes `THEME_MODE_*`); vacío = la de la aplicación, seguida en cada cambio
`il_theme_accent`	long	`-1`	Color de acento de este componente (`-1` = acento de la aplicación, o el del tema)

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. of_set_property("tooltip", …) (y super_tooltip_*) devuelve -5: la puerta por nombre también está cerrada.

Métodos #

Método	Función
`of_reset ( )`	Restablece todas las propiedades a sus valores predeterminados (barra lineal, escala 0–100, valor 0, porcentaje oculto, color del tema). Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_set_redraw (boolean)`	Agrupa una ráfaga de modificaciones en una sola representación. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta la representación como imagen. Devuelve `0` una vez escrita la imagen, `-4` si la escritura falla, `-2` si el componente no está creado

Eventos #

Evento	Se activa cuando
`ue_ready ( )`	El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )`	El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)`	El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

Ejemplos #

Progreso determinado con porcentaje #

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

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_show_value = true
uo_progress.id_value = 40

Escala personalizada #

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

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

Color personalizado y control del valor #

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

Valor con formato, unidad y estado de error #

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

Un porcentaje con decimales #

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

Una espera que falla #

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

Una barra vertical con nombre propio #

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

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_value_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. Al menos un valor cada 50 ms de reloj espera a que la barra lo haya dibujado: la barra avanza durante el bucle, incluso cuando el bucle espera una base de datos o una red, sin código por su parte.
Dos barras en una misma ventana: dé a cada una su is_accessible_name, para que el lector de pantalla las distinga.
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.

Miembros	Función	Detallado en
`of_reset`	Poner el componente a cero	3.6 Poner un componente a cero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atajos de teclado del componente	3.5 Los atajos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Si ha nacido, si está listo, qué ha fallado	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar el render como imagen	3.8 Exportar la representación como imagen
`of_set_redraw`	Agrupar los cambios en un solo repintado	3.10 Buenas prácticas
`of_preload_icons`	Iconos mostrados sin retardo	Visualización instantánea: `of_icon`
`of_set_translation`	Traducir una etiqueta del componente	5.2 Adaptar una etiqueta: `of_set_translation`
`of_focus_webview`	Dar el foco al componente	6.4 Teclado y foco
`of_print` · `of_print_to_pdf`	Imprimir, o escribir un PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar una propiedad por su nombre	3.1 El motor de propiedades
`is_accessible_name` · `is_accessible_description`	El nombre y la descripción que dice un lector de pantalla	3.4 Propiedades y eventos opcionales

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.