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 #

Início 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

Propriedades #

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 #

Eventos #

Exemplos #

Progresso determinado com percentagem #

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

Progresso indeterminado (duração desconhecida) #

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

Anel 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

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

Cor personalizada e controlo do 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 e estado de erro #

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

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 id_minimum / id_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). Um processamento em pausa ou falhado indica-se com is_state.
• Atribuir id_value sem receio: a barra só é redesenhada quando muda o que mostra. Cada desenho deixa o ecrã atualizar-se: a barra avança durante o ciclo, sem código da sua parte.
• Chamar of_reset() antes de reutilizar a mesma barra para outro processamento.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia