# progressbar — `u_pbt_progressbar` #

← Referência dos componentes · Índice do guia

> Barra de progresso com tema: barra horizontal ou anel, valor quantificado ou animação de espera, percentagem apresentada, cor livre.

> ▶ Ver ao vivo — Aplicação de demonstração, mosaico Progress: a pré-visualização, o código que o produz e esta página, lado a lado.

## Em resumo #

Userobject | `u_pbt_progressbar`
Classe de items | — (componente sem items)
Serve para | Mostrar o avanço de um processamento longo: importação, exportação, impressão, chamada ao servidor
Duas utilizações | determinada (o avanço é conhecido) ou indeterminada (apenas se sabe que está a trabalhar)

## Início rápido #

    // event open da janela
    uo_progression.ib_label = true      // apresenta a percentagem sobre a barra
    uo_progression.id_value = 0         // ponto de partida

    // Durante o processamento : uma simples atribuicao desloca a barra
    for ll_i = 1 to ll_total
        of_traiter_ligne(ll_i)
        uo_progression.id_value = (ll_i / ll_total) * 100
    next

## Propriedades #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`id_value` | double | `0` | Avanço atual, expresso na escala `il_minimum` … `il_maximum`
`il_minimum` | long | `0` | Limite inferior da escala
`il_maximum` | long | `100` | Limite superior da escala
`is_mode` | string | `"linear"` | Forma do componente: `linear` (barra horizontal) ou `circular` (anel) — constantes `MODE_LINEAR`, `MODE_CIRCULAR`
`ib_indeterminate` | boolean | `false` | Modo espera: animação contínua, `id_value` é ignorada
`ib_label` | boolean | `false` | Apresenta a percentagem sobre a barra ou no centro do anel
`il_color` | long | `-1` | Cor de preenchimento, no formato `RGB()` do PowerBuilder. `-1` = cor do tema
`is_theme_style` | string | `fluent` | Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Cor de destaque deste componente (`-1` = destaque do tema)

> Este componente não publica tooltip (`is_tooltip`, `is_super_tooltip_*`): uma barra de progresso lê-se por si própria, e uma etiqueta ao passar o rato surgiria por baixo do ponteiro no preciso momento em que o utilizador olha para outro lado. Coloque o comentário de progresso num statictext ou numa statusbar ao lado da barra.

## Métodos #

Método | Função
--- | ---
`of_reset ( )` | Repõe todas as propriedades nos respetivos valores por omissão (barra linear, escala 0–100, valor 0, percentagem oculta, cor do tema)
`of_set_redraw (boolean)` | Agrupa uma rajada de alterações numa única representação
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem

## Eventos #

Evento | Acionado quando
--- | ---
`ue_ready ( )` | O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )` | O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)` | O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

## Exemplos #

### Progresso determinado com percentagem #

    uo_progression.ib_label = true
    uo_progression.id_value = 75      // a barra enche-se ate tres quartos

### Progresso indeterminado (duração desconhecida) #

    // Quando a duracao e desconhecida : a barra anima-se continuamente
    // e ignora id_value
    uo_progression.ib_indeterminate = true

    // Assim que a duracao for conhecida, volta-se ao modo determinado
    uo_progression.ib_indeterminate = false
    uo_progression.id_value = 20

### Anel circular #

    // Modo de apresentacao : linear (barra) ou circular (anel)
    uo_progression.is_mode  = uo_progression.MODE_CIRCULAR
    uo_progression.ib_label = true
    uo_progression.id_value = 40

### Escala personalizada #

    // O avanco nem sempre e uma percentagem : indica-se a escala real
    uo_progression.il_minimum = 0
    uo_progression.il_maximum = ll_nb_lignes    // ex : 4820 linhas a importar

    uo_progression.id_value = ll_ligne_courante // valor bruto, nao uma percentagem

A percentagem apresentada por `ib_label` continua a ser calculada em relação a esta escala.

### Cor personalizada e controlo do valor #

    uo_progression.ib_label = true

    // A cor de preenchimento aceita um RGB() padrao do PowerBuilder
    uo_progression.il_color = RGB(/*vermelho*/ 16, /*verde*/ 137, /*azul*/ 62)

    // A barra mostra um valor, nao o calcula : e o seu codigo que o faz avancar
    uo_progression.id_value = 0

    // evento timer da janela, uma vez por segundo
    if uo_progression.id_value >= 100 then
    	Timer(0)   // terminado : o seu codigo sabe-o, foi ele que o decidiu
    	uo_statut.of_item("main").is_text = "Importação concluída"
    else
    	uo_progression.id_value = uo_progression.id_value + 10
    end if

## Boas práticas #

- Escolher o modo em função do que se sabe: indeterminado enquanto o volume for desconhecido, determinado assim que for conhecido.
- Preferir `il_minimum` / `il_maximum` ao cálculo manual de uma percentagem: a etiqueta e a apresentação acompanham automaticamente.
- Deixar `il_color` a `-1` para que a barra siga o tema, tanto claro como escuro; só fixar uma cor para transmitir um significado (verde = êxito, vermelho = alerta).
- Um ciclo PowerScript longo sem devolver o controlo bloqueia a apresentação: deixar respirar o ciclo de mensagens entre dois lotes (ver FAQ).
- Chamar `of_reset()` antes de reutilizar a mesma barra para outro processamento.

← Referência dos componentes · Índice do guia