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.

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, in beiden Hosting-Modi.

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.

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
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_ERROR
inv_toaster.il_timeout = 6000
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*/ "installer", /*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 "installer" ; of_start_update()
    case "later" ; of_reporter(1)
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_journal_import)

Aus einer langen Verarbeitung heraus benachrichtigen #

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

• Eine dauerhafte Instanz pro Fenster (eine beim Öffnen erzeugte Instanzvariable) 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 Toasts bleiben stumm auf dem Bildschirm.
• 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