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

    // event open de la ventana
    uo_progression.ib_label = true      // muestra el porcentaje en la barra
    uo_progression.id_value = 0         // punto de partida

    // Durante el procesamiento : una simple asignacion mueve la barra
    for ll_i = 1 to ll_total
        of_traiter_ligne(ll_i)
        uo_progression.id_value = (ll_i / ll_total) * 100
    next

## Propiedades #

Propiedad | Tipo | Predeterminado | Función
--- | --- | --- | ---
`id_value` | double | `0` | Avance actual, expresado en la escala `il_minimum` … `il_maximum`
`il_minimum` | long | `0` | Límite inferior de la escala
`il_maximum` | long | `100` | Límite superior de la escala
`is_mode` | string | `"linear"` | Forma del componente: `linear` (barra horizontal) o `circular` (anillo) — constantes `MODE_LINEAR`, `MODE_CIRCULAR`
`ib_indeterminate` | boolean | `false` | Modo espera: animación continua, `id_value` se ignora
`ib_label` | boolean | `false` | Muestra el porcentaje en la barra o en el centro del anillo
`il_color` | long | `-1` | Color de relleno, con el formato `RGB()` de PowerBuilder. `-1` = color del tema
`is_theme_style` | string | `fluent` | Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Color de acento de este componente (`-1` = acento 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.

## 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)
`of_set_redraw (boolean)` | Agrupa una ráfaga de modificaciones en una sola representación
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta la representación como imagen

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

    uo_progression.ib_label = true
    uo_progression.id_value = 75      // la barra se rellena en tres cuartos

### Progreso indeterminado (duración desconocida) #

    // Cuando se desconoce la duracion : la barra se anima de forma continua
    // e ignora id_value
    uo_progression.ib_indeterminate = true

    // Una vez conocida la duracion, se vuelve al modo determinado
    uo_progression.ib_indeterminate = false
    uo_progression.id_value = 20

### Anillo circular #

    // Modo de visualizacion : linear (barra) o circular (anillo)
    uo_progression.is_mode  = uo_progression.MODE_CIRCULAR
    uo_progression.ib_label = true
    uo_progression.id_value = 40

### Escala personalizada #

    // El avance no siempre es un porcentaje : se indica la escala real
    uo_progression.il_minimum = 0
    uo_progression.il_maximum = ll_nb_lignes    // ej : 4820 lineas que importar

    uo_progression.id_value = ll_ligne_courante // valor bruto, no un porcentaje

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

### Color personalizado y control del valor #

    uo_progression.ib_label = true

    // El color de relleno acepta un RGB() estandar de PowerBuilder
    uo_progression.il_color = RGB(/*rojo*/ 16, /*verde*/ 137, /*azul*/ 62)

    // La barra muestra un valor, no lo calcula : es su codigo el que lo hace avanzar
    uo_progression.id_value = 0

    // evento timer de la ventana, una vez por segundo
    if uo_progression.id_value >= 100 then
    	Timer(0)   // terminado : su codigo lo sabe, es el que lo ha decidido
    	uo_statut.of_item("main").is_text = "Importación finalizada"
    else
    	uo_progression.id_value = uo_progression.id_value + 10
    end if

## 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 `il_minimum` / `il_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, rojo = alerta).
- Un bucle PowerScript largo que no cede el control congela la visualización: deje respirar el bucle de mensajes entre dos lotes (consulte las FAQ).
- Llame a `of_reset()` antes de reutilizar la misma barra para otro procesamiento.

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