toaster — n_pbt_toaster #

← Riferimento dei componenti · Sommario della guida

Notifiche « toast » in un angolo dello schermo: un messaggio che appare, informa e scompare senza bloccare l'utente né interrompere la sua digitazione.

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

In breve #

Il toast è una finestra staccata: fluttua sopra la Sua applicazione (o sopra tutto lo schermo) e si chiude da solo.

// Variabili locali
n_pbt_toaster lnv_toast

// Creare il notificatore
lnv_toast = create n_pbt_toaster

// ... configurazione ...

// Distruggerlo alla fine
destroy lnv_toast

Avvio rapido #

// Variabili locali
n_pbt_toaster lnv_toast

// Creare il notificatore
lnv_toast = create n_pbt_toaster

// Configurare, poi mostrare
lnv_toast.ipo_owner = this                       // finestra a cui il toast si aggancia
lnv_toast.is_kind   = lnv_toast.KIND_SUCCESS     // icona verde + bordino di successo
lnv_toast.is_text   = "Le Sue modifiche sono state [b]salvate[/b]."
lnv_toast.of_show()

// Distruggerlo alla fine
destroy lnv_toast

Tutto si configura tramite proprietà, poi of_show() — che non accetta alcun argomento — fa apparire la notifica. Il toaster qui sopra viene distrutto subito: non torna nulla, ed è quanto basta per una semplice conferma. Per ricevere i ritorni di un toast, vedere « Dove scrivere gli event ».

Proprietà #

Da impostare prima di of_show.

Costanti #

Perché LEFT/RIGHT qui, e START/END altrove? Il toast è una finestra di sistema posizionata in pixel dello schermo, non un contenuto che segue un senso di lettura: un angolo dello schermo non ha un « inizio ». Queste costanti restano quindi volutamente fisiche e non cambiano lato quando l'applicazione passa alla scrittura da destra a sinistra. Vedere Lingua e RTL.

Metodi #

Più toast visualizzati nello stesso angolo si impilano automaticamente. Ciascuno porta una croce di chiusura; l'identificatore restituito da of_show permette di distinguerli negli event e di chiuderli dal Suo codice.

Il conto alla rovescia si sospende finché il puntatore è sul toast: una notifica non deve svanire sotto gli occhi di chi la legge. Una sottile barra in basso mostra il tempo restante — e quindi spiega la sua sparizione. Un clic sul corpo risponde e chiude.

Una notifica impostata con il_timeout = 0 resta a schermo finché nessuno la chiude: conservi il suo identificatore per poterla rimuovere quando l'attività che annuncia è terminata.

// Variabili locali
long ll_toast

// Notifica persistente : restera visualizzata fino a of_close.
inv_toaster.is_text = "Esportazione in corso..."
inv_toaster.il_timeout = /*ms, 0 = nessuna chiusura automatica*/ 0
ll_toast = inv_toaster.of_show()

// ... elaborazione lunga ...

// Chiudere il toast a lavoro finito
inv_toaster.of_close(/*id*/ ll_toast)

Event — il toast Le risponde #

Una notifica non è un semplice « visualizza e dimentica »: può dirLe che è stata cliccata, che è stato scelto un pulsante d'azione, o che si è chiusa.

Non devi collegare nulla: imposta ipo_owner (la finestra a cui il toast è ancorato) e gestisci gli eventi. Il componente li preleva da solo finché un toast è a schermo e li solleva sull'oggetto — nessun ricevitore, nessun timer.

Dove scrivere gli event #

PowerBuilder offre gli event di un oggetto non visuale solo in due posti: un discendente di n_pbt_toaster (i suoi event portano i Suoi script), oppure un toaster collocato sulla finestra come ogni oggetto non visuale (nel painter della finestra, Insert > Object, poi n_pbt_toaster: i suoi event si scrivono nella finestra). Una variabile n_pbt_toaster creata con create non ha alcuno script: i suoi toast si mostrano, ma i loro ritorni non arrivano a nessuno. E un toaster distrutto non riferisce più nulla: i suoi toast persistenti e quelli con pulsanti si chiudono con lui, gli altri finiscono da soli, muti. Con un discendente n_my_toaster, la finestra ne tiene uno in una variabile di istanza inv_toaster:

// event open della finestra : creare il toaster una volta e ancorarlo
inv_toaster = create n_my_toaster
inv_toaster.ipo_owner = this

1. Impostare ipo_owner sulla finestra a cui il toast è ancorato:

// Ancorare i toast a questa finestra
inv_toaster.ipo_owner = this      // la finestra a cui il toast e ancorato

2. Trattare gli event attivati sul toaster:

Se non ti aspetti alcun ritorno — nessun pulsante d'azione, nessun clic sul corpo — non hai nessuno di questi eventi da gestire: la notifica appare e scompare da sola. È la modalità più semplice, perfetta per una semplice conferma.

Esempi #

I quattro livelli #

// Info : un messaggio neutro
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_INFO
inv_toaster.is_text = "Operazione terminata."
inv_toaster.of_show()

// Successo : e andato a buon fine
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
inv_toaster.is_text = "Le Sue modifiche sono state [b]salvate[/b]."
inv_toaster.of_show()

// Avviso : da guardare
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_WARNING
inv_toaster.il_timeout = 5000                        // un po' piu lungo
inv_toaster.is_text    = "Spazio su disco insufficiente sull'unità C:."
inv_toaster.of_show()

// Errore : non e riuscito ; resta fino al clic
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_ERROR
inv_toaster.is_text    = "Impossibile contattare il server."
inv_toaster.of_show()

Scegliere l'angolo, nella finestra o sullo schermo #

// Ancorato all'angolo in alto a destra della FINESTRA (predefinito : segue l'applicazione)
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = false
inv_toaster.is_text     = "Ancorato all'angolo della finestra."
inv_toaster.of_show()

// Staccato : ancorato all'angolo dello SCHERMO, visibile anche se la finestra e ridotta a icona
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = true
inv_toaster.is_text     = "Elaborazione notturna terminata."
inv_toaster.of_show()

Toast avanzato: titolo, immagine e durata #

// Ripartire dalle impostazioni predefinite
inv_toaster.of_reset()

// Un titolo, un testo e un'immagine
inv_toaster.is_title    = "Backup completato"
inv_toaster.is_text     = "1 240 file copiati in [b]\\server\backup[/b]."
inv_toaster.is_image    = "mono:img\backup.svg"
inv_toaster.il_timeout  = 8000                    // resta 8 secondi
inv_toaster.of_show()

Notifica con pulsanti d'azione #

// event open : ancorare il toaster una volta per tutte ; i ritorni arrivano da soli
inv_toaster.ipo_owner = this

// Proporre due azioni ; timeout 0 = il toast attende la decisione dell'utente
inv_toaster.of_reset()

// Titolo, testo e due pulsanti, poi mostrare
inv_toaster.is_title   = "Aggiornamento disponibile"
inv_toaster.is_text    = "La versione 2.0 è pronta per essere installata."
inv_toaster.il_timeout = 0
inv_toaster.of_add_button(/*key*/ "install", /*label*/ "Installa")
inv_toaster.of_add_button(/*key*/ "later", /*label*/ "Piu tardi")
inv_toaster.of_show()

// event ue_toast_action di inv_toaster : (long al_id, string as_key, string as_action)
choose case as_action
    case "install" ; of_start_update()
    case "later" ; of_remind_later()
end choose

Reagire al clic sul messaggio #

// event ue_toast_clicked di inv_toaster : (long al_id, string as_key)
// L'utente ha cliccato il corpo del toast : aprire la schermata interessata
Open(w_import_log)

Sapere perché un toast si è chiuso, chiuderli tutti #

// event ue_toast_dismissed di inv_toaster : (long al_id, string as_key, string as_reason)
// Solo un toast chiuso dall'utente vuol dire non ora : ricordarlo piu tardi
if as_reason = n_pbt_toaster.REASON_USER then of_remind_later()

// Inizia una nuova importazione : le notifiche della precedente se ne vanno
inv_toaster.of_close_all()

Notificare da un'elaborazione lunga #

// Variabili locali
long ll_rows, ll_errors

// Righe caricate ed errori incontrati dall'importazione
ll_rows = of_rows_loaded()
ll_errors = of_errors_met()

// Fine di un'importazione : informare senza bloccare la schermata di digitazione
inv_toaster.of_reset()

// Tipo e testo seguono l'esito
if ll_errors = 0 then
    inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
    inv_toaster.is_text = "Importazione terminata : [b]" + String(ll_rows) + " righe[/b] integrate."
else
    inv_toaster.is_kind    = inv_toaster.KIND_ERROR
    inv_toaster.il_timeout = 0                    // un errore deve essere letto
    inv_toaster.is_text    = "Importazione interrotta : " + String(ll_errors) + " errori."
end if

// Mostrare il toast
inv_toaster.of_show()

Buone pratiche #

• Un toaster per finestra, collocato sulla finestra o tenuto da una variabile di istanza di un discendente (vedere « Dove scrivere gli event »), invece di una creazione/distruzione a ogni messaggio: l'ancoraggio ipo_owner resta in essere e i ritorni arrivano. Un toaster distrutto non riceve più nulla: i suoi toast persistenti e quelli con pulsanti si chiudono con lui, gli altri finiscono da soli, muti.
• Chiami of_reset() prima di ogni notifica: senza di esso il titolo, l'immagine o i pulsanti della precedente restano impostati.
• Riservi il_timeout = 0 ai messaggi che esigono una decisione (errore bloccante, azione proposta): un toast che non se ne va da solo finisce per infastidire.
• Usi ib_screen = true soltanto per ciò che deve restare visibile quando l'applicazione è in secondo piano (fine di un'elaborazione lunga, attività notturna).
• Un toast è un messaggio transitorio: se serve assolutamente una risposta prima di continuare, usi messagebox, che blocca e restituisce la scelta.
• Per uno stato permanente invece di una notifica, preferisca statusbar.

← Riferimento dei componenti · Sommario della guida