# progressbar — `u_pbt_progressbar` #

← Riferimento dei componenti · Sommario della guida

> Barra di avanzamento a tema: barra orizzontale o anello, valore numerico o animazione di attesa, percentuale visualizzata, colore a scelta.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Progress: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_progressbar`
Classe degli item | — (componente senza item)
Serve per | Mostrare l'avanzamento di un'elaborazione lunga: importazione, esportazione, stampa, chiamata al server
Due utilizzi | determinato (l'avanzamento è noto) o indeterminato (si sa soltanto che il lavoro è in corso)

## Avvio rapido #

    // event open della finestra
    uo_progression.ib_label = true      // mostra la percentuale sulla barra
    uo_progression.id_value = 0         // punto di partenza

    // Durante l'elaborazione : una semplice assegnazione sposta la barra
    for ll_i = 1 to ll_total
        of_traiter_ligne(ll_i)
        uo_progression.id_value = (ll_i / ll_total) * 100
    next

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`id_value` | double | `0` | Avanzamento corrente, espresso nella scala `il_minimum` … `il_maximum`
`il_minimum` | long | `0` | Limite inferiore della scala
`il_maximum` | long | `100` | Limite superiore della scala
`is_mode` | string | `"linear"` | Forma del componente: `linear` (barra orizzontale) o `circular` (anello) — costanti `MODE_LINEAR`, `MODE_CIRCULAR`
`ib_indeterminate` | boolean | `false` | Modalità attesa: animazione continua, `id_value` viene ignorata
`ib_label` | boolean | `false` | Mostra la percentuale sulla barra o al centro dell'anello
`il_color` | long | `-1` | Colore di riempimento, nel formato `RGB()` di PowerBuilder. `-1` = colore del tema
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)

> Questo componente non espone tooltip (`is_tooltip`, `is_super_tooltip_*`): una barra di avanzamento si legge da sé, e un'etichetta al passaggio del mouse arriverebbe sotto il puntatore proprio nel momento in cui l'utente guarda altrove. Metta il commento sullo stato di avanzamento in uno statictext o in una statusbar accanto alla barra.

## Metodi #

Metodo | Ruolo
--- | ---
`of_reset ( )` | Riporta tutte le proprietà ai valori predefiniti (barra lineare, scala 0–100, valore 0, percentuale nascosta, colore del tema)
`of_set_redraw (boolean)` | Raggruppa una serie di modifiche in un unico rendering
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Esporta il rendering come immagine

## Event #

Event | Attivato quando
--- | ---
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Esempi #

### Avanzamento determinato con percentuale #

    uo_progression.ib_label = true
    uo_progression.id_value = 75      // la barra si riempie per tre quarti

### Avanzamento indeterminato (durata sconosciuta) #

    // Quando la durata e sconosciuta : la barra si anima in continuo
    // e ignora id_value
    uo_progression.ib_indeterminate = true

    // Una volta nota la durata, si torna alla modalita determinata
    uo_progression.ib_indeterminate = false
    uo_progression.id_value = 20

### Anello circolare #

    // Modalita di visualizzazione : linear (barra) o circular (anello)
    uo_progression.is_mode  = uo_progression.MODE_CIRCULAR
    uo_progression.ib_label = true
    uo_progression.id_value = 40

### Scala personalizzata #

    // L'avanzamento non e sempre una percentuale : si indica la scala reale
    uo_progression.il_minimum = 0
    uo_progression.il_maximum = ll_nb_lignes    // es : 4820 righe da importare

    uo_progression.id_value = ll_ligne_courante // valore grezzo, non una percentuale

La percentuale mostrata da `ib_label` resta calcolata rispetto a questa scala.

### Colore personalizzato e pilotaggio del valore #

    uo_progression.ib_label = true

    // Il colore di riempimento accetta un RGB() standard di PowerBuilder
    uo_progression.il_color = RGB(/*rosso*/ 16, /*verde*/ 137, /*blu*/ 62)

    // La barra mostra un valore, non lo calcola : e il vostro codice a farlo avanzare
    uo_progression.id_value = 0

    // event timer della finestra, una volta al secondo
    if uo_progression.id_value >= 100 then
    	Timer(0)   // finito : il vostro codice lo sa, e lui che lo ha deciso
    	uo_statut.of_item("main").is_text = "Importazione completata"
    else
    	uo_progression.id_value = uo_progression.id_value + 10
    end if

## Buone pratiche #

- Scelga la modalità in base a ciò che sa: indeterminata finché il volume è sconosciuto, determinata non appena lo conosce.
- Preferisca `il_minimum` / `il_maximum` al calcolo manuale di una percentuale: l'etichetta e la visualizzazione seguono da sole.
- Lasci `il_color` a `-1` affinché la barra segua sia il tema chiaro sia quello scuro; imposti un colore solo per veicolare un significato (verde = riuscita, rosso = allerta).
- Un ciclo PowerScript lungo che non restituisce il controllo blocca la visualizzazione: lasci respirare il ciclo dei messaggi tra un lotto e l'altro (vedere FAQ).
- Chiami `of_reset()` prima di riutilizzare la stessa barra per un'altra elaborazione.

← Riferimento dei componenti · Sommario della guida