toaster — n_pbt_toaster #

← Référence des composants · Sommaire du guide

Notifications « toast » en coin d'écran : un message qui apparaît, informe et disparaît sans bloquer l'utilisateur ni interrompre sa saisie.

▶ Le voir en vrai — Application de démonstration, tuile Toaster : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Le toast est une fenêtre détachée : il flotte au-dessus de votre application (ou de tout l'écran) et se referme tout seul.

// Variables locales
n_pbt_toaster lnv_toast

// Creer le notificateur
lnv_toast = create n_pbt_toaster

// ... configuration ...

// Le detruire une fois termine
destroy lnv_toast

Démarrage rapide #

// Variables locales
n_pbt_toaster lnv_toast

// Creer le notificateur
lnv_toast = create n_pbt_toaster

// Configurer puis afficher
lnv_toast.ipo_owner = this                       // fenetre a laquelle le toast s'accroche
lnv_toast.is_kind   = lnv_toast.KIND_SUCCESS     // icone verte + lisere de succes
lnv_toast.is_text   = "Vos modifications ont ete [b]enregistrees[/b]."
lnv_toast.of_show()

// Le detruire une fois termine
destroy lnv_toast

Tout se configure par propriétés, puis of_show() — qui ne prend aucun argument — fait apparaître la notification. Le toaster ci-dessus est détruit tout de suite : rien ne revient, et c'est voulu pour une simple confirmation. Pour recevoir les retours d'un toast, voir « Où écrire les événements ».

Propriétés #

À poser avant of_show.

Constantes #

Pourquoi LEFT/RIGHT ici, et START/END ailleurs ? Le toast est une fenêtre système posée en pixels écran, pas un contenu qui suit un sens de lecture : un coin d'écran n'a pas de « début ». Ces constantes restent donc volontairement physiques, et ne changent pas de côté quand l'application passe en écriture de droite à gauche. Voir Langue et RTL.

Méthodes #

Plusieurs toasts affichés au même coin s'empilent automatiquement. Chacun porte une croix de fermeture ; l'identifiant renvoyé par of_show permet de les distinguer dans les événements et de les fermer depuis votre code.

Le compte à rebours se met en pause tant que le pointeur est sur le toast : une notification ne doit pas s'évanouir sous les yeux de qui la lit. Une fine barre en bas du toast montre le temps restant — et explique donc sa disparition. Un clic sur le corps répond et ferme.

Une notification posée avec il_timeout = 0 reste à l'écran tant que personne ne la ferme : gardez son identifiant pour pouvoir la retirer quand la tâche qu'elle annonce est terminée.

// Variables locales
long ll_toast

// Notification persistante : elle restera affichee jusqu'a of_close.
inv_toaster.is_text = "Export en cours..."
inv_toaster.il_timeout = /*ms, 0 = pas de fermeture auto*/ 0
ll_toast = inv_toaster.of_show()

// ... traitement long ...

// Fermer le toast une fois le travail fini
inv_toaster.of_close(/*id*/ ll_toast)

Événements — le toast vous répond #

Une notification n'est pas un simple « affiche et oublie » : elle peut vous dire qu'elle a été cliquée, qu'un bouton d'action a été choisi, ou qu'elle s'est fermée.

Vous n'avez rien à câbler pour cela : réglez ipo_owner (la fenêtre à laquelle le toast est ancré) et traitez les événements. Le composant les draine lui-même tant qu'un toast est à l'écran et les lève sur l'objet — ni receveur, ni timer.

Où écrire les événements #

PowerBuilder n'offre les événements d'un objet non visuel qu'à deux endroits : un descendant de n_pbt_toaster (ses événements portent vos scripts), ou un toaster posé sur la fenêtre comme tout objet non visuel (dans le peintre de fenêtre, Insert > Object, puis n_pbt_toaster : ses événements se scriptent dans la fenêtre). Une variable n_pbt_toaster créée par create n'a aucun script : ses toasts s'affichent, mais leurs retours n'arrivent à personne. Et un toaster détruit ne rapporte plus rien : ses toasts persistants et ceux qui portent des boutons se ferment avec lui, les autres finissent seuls, muets. Avec un descendant n_my_toaster, la fenêtre en garde un dans une variable d'instance inv_toaster :

// Event open de la fenetre : creer le toaster une fois et l'ancrer
inv_toaster = create n_my_toaster
inv_toaster.ipo_owner = this

1. Régler ipo_owner sur la fenêtre à laquelle le toast est ancré :

// Ancrer les toasts a cette fenetre
inv_toaster.ipo_owner = this      // la fenetre a laquelle le toast est ancre

2. Traiter les événements levés sur le toaster :

Si vous n'attendez aucun retour — ni bouton d'action, ni clic sur le corps — vous n'avez aucun de ces événements à traiter : la notification s'affiche et disparaît toute seule. C'est le mode le plus simple, parfait pour une simple confirmation.

Exemples #

Les quatre niveaux #

// Info : un message neutre
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_INFO
inv_toaster.is_text = "Operation terminee."
inv_toaster.of_show()

// Succes : c'est fait
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
inv_toaster.is_text = "Vos modifications ont ete [b]enregistrees[/b]."
inv_toaster.of_show()

// Avertissement : a regarder
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_WARNING
inv_toaster.il_timeout = 5000                        // un peu plus long
inv_toaster.is_text    = "Espace disque faible sur le lecteur C:."
inv_toaster.of_show()

// Erreur : c'est un echec ; elle reste jusqu'au clic
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_ERROR
inv_toaster.is_text    = "Impossible de joindre le serveur."
inv_toaster.of_show()

Choisir le coin, dans la fenêtre ou sur l'écran #

// Ancre au coin haut droit de la FENETRE (defaut : suit l'application)
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = false
inv_toaster.is_text     = "Ancre au coin de la fenetre."
inv_toaster.of_show()

// Detache : ancre au coin de l'ECRAN, visible meme si la fenetre est reduite
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = true
inv_toaster.is_text     = "Traitement de nuit termine."
inv_toaster.of_show()

Toast enrichi : titre, image et durée #

// Repartir des reglages par defaut
inv_toaster.of_reset()

// Un titre, un texte et une image
inv_toaster.is_title    = "Sauvegarde terminee"
inv_toaster.is_text     = "1 240 fichiers copies vers [b]\\serveur\backup[/b]."
inv_toaster.is_image    = "mono:img\backup.svg"
inv_toaster.il_timeout  = 8000                    // reste 8 secondes
inv_toaster.of_show()

Notification avec boutons d'action #

// event open : ancrer le toaster une fois pour toutes ; les retours arrivent seuls
inv_toaster.ipo_owner = this

// Proposer deux actions ; timeout 0 = le toast attend la decision de l'utilisateur
inv_toaster.of_reset()

// Titre, texte et deux boutons, puis afficher
inv_toaster.is_title   = "Mise a jour disponible"
inv_toaster.is_text    = "La version 2.0 est prete a etre installee."
inv_toaster.il_timeout = 0
inv_toaster.of_add_button(/*key*/ "install", /*label*/ "Installer")
inv_toaster.of_add_button(/*key*/ "later", /*label*/ "Plus tard")
inv_toaster.of_show()

// event ue_toast_action de 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

Réagir au clic sur le message #

// event ue_toast_clicked de inv_toaster : (long al_id, string as_key)
// L'utilisateur a clique le corps du toast : ouvrir l'ecran concerne
Open(w_import_log)

Savoir pourquoi un toast s'est fermé, tout fermer #

// event ue_toast_dismissed de inv_toaster : (long al_id, string as_key, string as_reason)
// Seul un toast ferme par l'utilisateur veut dire pas maintenant : le rappeler plus tard
if as_reason = n_pbt_toaster.REASON_USER then of_remind_later()

// Un nouvel import commence : les notifications du precedent s'en vont
inv_toaster.of_close_all()

Notifier depuis un traitement long #

// Variables locales
long ll_rows, ll_errors

// Lignes chargees et erreurs rencontrees par l'import
ll_rows = of_rows_loaded()
ll_errors = of_errors_met()

// Fin d'un import : informer sans bloquer l'ecran de saisie
inv_toaster.of_reset()

// Le type et le texte suivent le resultat
if ll_errors = 0 then
    inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
    inv_toaster.is_text = "Import termine : [b]" + String(ll_rows) + " lignes[/b] integrees."
else
    inv_toaster.is_kind    = inv_toaster.KIND_ERROR
    inv_toaster.il_timeout = 0                    // une erreur doit etre lue
    inv_toaster.is_text    = "Import interrompu : " + String(ll_errors) + " erreurs."
end if

// Afficher le toast
inv_toaster.of_show()

Bonnes pratiques #

• Un toaster par fenêtre, posé sur la fenêtre ou tenu par une variable d'instance d'un descendant (voir « Où écrire les événements »), plutôt qu'une création/destruction à chaque message : l'ancrage ipo_owner reste en place et les retours arrivent. Un toaster détruit ne reçoit plus rien : ses toasts persistants et ceux à boutons se ferment avec lui, les autres finissent seuls, muets.
• Appelez of_reset() avant chaque notification : sans cela le titre, l'image ou les boutons de la précédente restent posés.
• Réservez il_timeout = 0 aux messages qui exigent une décision (erreur bloquante, action proposée) : un toast qui ne part pas tout seul finit par agacer.
• Utilisez ib_screen = true uniquement pour ce qui doit rester visible quand l'application est en arrière-plan (fin de traitement long, tâche de nuit).
• Un toast est un message transitoire : s'il faut absolument une réponse avant de continuer, utilisez messagebox, qui bloque et renvoie le choix.
• Pour un statut permanent plutôt qu'une notification, préférez statusbar.

← Référence des composants · Sommaire du guide