toaster — n_pbt_toaster #

← Komponentenreferenz · Inhalt des Handbuchs

„Toast“-Benachrichtigungen in einer Bildschirmecke: eine Meldung, die erscheint, informiert und wieder verschwindet, ohne den Benutzer zu blockieren oder seine Eingabe zu unterbrechen.

▶ Live ansehen — Demoanwendung, Kachel Toaster: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Der Toast ist ein losgelöstes Fenster: Er schwebt über Ihrer Anwendung (oder über dem gesamten Bildschirm) und schließt sich von selbst.

// Lokale Variablen
n_pbt_toaster lnv_toast

// Den Notifier erzeugen
lnv_toast = create n_pbt_toaster

// ... Konfiguration ...

// Am Ende zerstoeren
destroy lnv_toast

Schnellstart #

// Lokale Variablen
n_pbt_toaster lnv_toast

// Den Notifier erzeugen
lnv_toast = create n_pbt_toaster

// Konfigurieren, dann anzeigen
lnv_toast.ipo_owner = this                       // Fenster, an dem sich der Toast festmacht
lnv_toast.is_kind   = lnv_toast.KIND_SUCCESS     // gruenes Symbol + Erfolgsstreifen
lnv_toast.is_text   = "Ihre Änderungen wurden [b]gespeichert[/b]."
lnv_toast.of_show()

// Am Ende zerstoeren
destroy lnv_toast

Alles wird über Eigenschaften konfiguriert, danach lässt of_show() — das kein Argument entgegennimmt — die Benachrichtigung erscheinen. Der obige Toaster wird sofort zerstört: Nichts kommt zurück, was für eine schlichte Bestätigung passt. Um die Rückmeldungen eines Toasts zu empfangen, siehe „Wo die Events geschrieben werden“.

Eigenschaften #

Vor of_show zu setzen.

Konstanten #

Warum hier LEFT/RIGHT und anderswo START/END? Der Toast ist ein Systemfenster, das in Bildschirmpixeln platziert wird, kein Inhalt, der einer Leserichtung folgt: Eine Bildschirmecke hat keinen „Anfang“. Diese Konstanten bleiben daher bewusst physisch und wechseln nicht die Seite, wenn die Anwendung auf Schreibrichtung von rechts nach links umschaltet. Siehe Sprache und RTL.

Methoden #

Mehrere in derselben Ecke angezeigte Toasts stapeln sich automatisch. Jeder trägt ein Schließkreuz; der von of_show gelieferte Bezeichner erlaubt es, sie in den Events zu unterscheiden und sie aus Ihrem Code heraus zu schließen.

Der Countdown pausiert, solange der Zeiger über dem Toast steht: eine Meldung darf nicht unter den Augen dessen verschwinden, der sie liest. Ein schmaler Balken am unteren Rand zeigt die verbleibende Zeit — und erklärt damit ihr Verschwinden. Ein Klick auf den Rumpf antwortet und schließt.

Eine mit il_timeout = 0 gesetzte Benachrichtigung bleibt auf dem Bildschirm, solange niemand sie schließt: Bewahren Sie ihren Bezeichner auf, um sie entfernen zu können, sobald die angekündigte Aufgabe beendet ist.

// Lokale Variablen
long ll_toast

// Dauerhafte Benachrichtigung : sie bleibt bis of_close sichtbar.
inv_toaster.is_text = "Export läuft..."
inv_toaster.il_timeout = /*ms, 0 = kein automatisches Schliessen*/ 0
ll_toast = inv_toaster.of_show()

// ... lange Verarbeitung ...

// Den Toast nach getaner Arbeit schliessen
inv_toaster.of_close(/*id*/ ll_toast)

Events — der Toast antwortet Ihnen #

Eine Benachrichtigung ist kein bloßes „anzeigen und vergessen“: Sie kann Ihnen mitteilen, dass sie angeklickt wurde, dass eine Aktionsschaltfläche gewählt wurde oder dass sie sich geschlossen hat.

Sie müssen dafür nichts verdrahten: Setzen Sie ipo_owner (das Fenster, an dem der Toast verankert ist) und behandeln Sie die Events. Die Komponente holt sie selbst, solange ein Toast sichtbar ist, und löst sie am Objekt aus — kein Empfänger, kein Timer.

Wo die Events geschrieben werden #

PowerBuilder bietet die Events eines nicht visuellen Objekts nur an zwei Stellen: ein Nachfahre von n_pbt_toaster (seine Events tragen Ihre Skripte) oder ein im Fenster platzierter Toaster wie jedes nicht visuelle Objekt (im Fenstermaler Insert > Object, dann n_pbt_toaster: seine Events werden im Fenster geskriptet). Eine mit create erzeugte n_pbt_toaster-Variable hat kein Skript: Ihre Toasts erscheinen, aber ihre Rückmeldungen erreichen niemanden. Und ein zerstörter Toaster meldet nichts mehr: Seine dauerhaften Toasts und die mit Schaltflächen schließen sich mit ihm, die anderen enden von selbst, stumm. Mit einem Nachfahren n_my_toaster hält das Fenster einen in einer Instanzvariablen inv_toaster:

// open-Event des Fensters : den Toaster einmal erzeugen und verankern
inv_toaster = create n_my_toaster
inv_toaster.ipo_owner = this

1. ipo_owner auf das Fenster setzen, an dem der Toast verankert ist:

// Die Toasts an diesem Fenster verankern
inv_toaster.ipo_owner = this      // das Fenster, an dem der Toast verankert ist

2. Die auf dem Toaster ausgelösten Events behandeln:

Wenn Sie keine Rückmeldung erwarten — keine Aktionsschaltfläche, kein Klick auf den Rumpf — müssen Sie keines dieser Events behandeln: Die Benachrichtigung erscheint und verschwindet von selbst. Das ist der einfachste Modus, ideal für eine schlichte Bestätigung.

Beispiele #

Die vier Stufen #

// Info : eine neutrale Meldung
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_INFO
inv_toaster.is_text = "Vorgang abgeschlossen."
inv_toaster.of_show()

// Erfolg : es hat geklappt
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
inv_toaster.is_text = "Ihre Änderungen wurden [b]gespeichert[/b]."
inv_toaster.of_show()

// Warnung : einen Blick wert
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_WARNING
inv_toaster.il_timeout = 5000                        // etwas laenger
inv_toaster.is_text    = "Wenig Speicherplatz auf Laufwerk C:."
inv_toaster.of_show()

// Fehler : es ist fehlgeschlagen ; er bleibt bis zum Klick
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_ERROR
inv_toaster.is_text    = "Der Server ist nicht erreichbar."
inv_toaster.of_show()

Die Ecke wählen, im Fenster oder auf dem Bildschirm #

// Verankert an der oberen rechten Ecke des FENSTERS (Standard : folgt der Anwendung)
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = false
inv_toaster.is_text     = "An der Fensterecke verankert."
inv_toaster.of_show()

// Losgeloest : an der BILDSCHIRM-Ecke verankert, sichtbar auch wenn das Fenster minimiert ist
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = true
inv_toaster.is_text     = "Nachtverarbeitung abgeschlossen."
inv_toaster.of_show()

Erweiterter Toast: Titel, Bild und Dauer #

// Von den Standardeinstellungen ausgehen
inv_toaster.of_reset()

// Ein Titel, ein Text und ein Bild
inv_toaster.is_title    = "Sicherung abgeschlossen"
inv_toaster.is_text     = "1 240 Dateien kopiert nach [b]\\server\backup[/b]."
inv_toaster.is_image    = "mono:img\backup.svg"
inv_toaster.il_timeout  = 8000                    // bleibt 8 Sekunden
inv_toaster.of_show()

Benachrichtigung mit Aktionsschaltflächen #

// open-Event : den Toaster ein fuer alle Mal verankern ; die Rueckmeldung kommt von selbst
inv_toaster.ipo_owner = this

// Zwei Aktionen anbieten ; timeout 0 = der Toast wartet auf die Entscheidung des Benutzers
inv_toaster.of_reset()

// Titel, Text und zwei Schaltflaechen, dann anzeigen
inv_toaster.is_title   = "Update verfügbar"
inv_toaster.is_text    = "Version 2.0 ist zur Installation bereit."
inv_toaster.il_timeout = 0
inv_toaster.of_add_button(/*key*/ "install", /*label*/ "Installieren")
inv_toaster.of_add_button(/*key*/ "later", /*label*/ "Spaeter")
inv_toaster.of_show()

// Event ue_toast_action von 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

Auf den Klick auf die Meldung reagieren #

// Event ue_toast_clicked von inv_toaster : (long al_id, string as_key)
// Der Benutzer hat den Rumpf des Toasts angeklickt : die betreffende Maske oeffnen
Open(w_import_log)

Wissen, warum ein Toast geschlossen wurde, alle schließen #

// Event ue_toast_dismissed von inv_toaster : (long al_id, string as_key, string as_reason)
// Nur ein vom Benutzer geschlossener Toast heisst nicht jetzt : spaeter erinnern
if as_reason = n_pbt_toaster.REASON_USER then of_remind_later()

// Ein neuer Import beginnt : die Benachrichtigungen des vorigen verschwinden
inv_toaster.of_close_all()

Aus einer langen Verarbeitung heraus benachrichtigen #

// Lokale Variablen
long ll_rows, ll_errors

// Geladene Zeilen und beim Import aufgetretene Fehler
ll_rows = of_rows_loaded()
ll_errors = of_errors_met()

// Ende eines Imports : informieren, ohne die Eingabemaske zu blockieren
inv_toaster.of_reset()

// Art und Text folgen dem Ergebnis
if ll_errors = 0 then
    inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
    inv_toaster.is_text = "Import abgeschlossen : [b]" + String(ll_rows) + " Zeilen[/b] übernommen."
else
    inv_toaster.is_kind    = inv_toaster.KIND_ERROR
    inv_toaster.il_timeout = 0                    // ein Fehler muss gelesen werden
    inv_toaster.is_text    = "Import abgebrochen : " + String(ll_errors) + " Fehler."
end if

// Den Toast anzeigen
inv_toaster.of_show()

Best Practices #

• Ein Toaster pro Fenster, im Fenster platziert oder von einer Instanzvariablen eines Nachfahren gehalten (siehe „Wo die Events geschrieben werden“), statt einer Erzeugung und Zerstörung bei jeder Meldung: Die ipo_owner-Verankerung bleibt bestehen und die Rückmeldungen kommen an. Ein zerstörter Toaster empfängt nichts mehr: Seine dauerhaften Toasts und die mit Schaltflächen schließen sich mit ihm, die anderen enden von selbst, stumm.
• Rufen Sie of_reset() vor jeder Benachrichtigung auf: Andernfalls bleiben Titel, Bild oder Schaltflächen der vorherigen bestehen.
• Behalten Sie il_timeout = 0 den Meldungen vor, die eine Entscheidung verlangen (blockierender Fehler, angebotene Aktion): Ein Toast, der nicht von selbst verschwindet, wird auf Dauer lästig.
• Verwenden Sie ib_screen = true nur für das, was sichtbar bleiben muss, wenn die Anwendung im Hintergrund ist (Ende einer langen Verarbeitung, Nachtlauf).
• Ein Toast ist eine flüchtige Meldung: Wenn Sie unbedingt eine Antwort brauchen, bevor es weitergeht, verwenden Sie messagebox, das blockiert und die Auswahl zurückgibt.
• Für einen dauerhaften Status statt einer Benachrichtigung bevorzugen Sie statusbar.

← Komponentenreferenz · Inhalt des Handbuchs