statusbar — u_pbt_statusbar #

← Komponentenreferenz · Inhalt des Handbuchs

Statusleiste aus Bereichen: Rich-Text, Symbole, feste oder automatische Breiten, Ausrichtung nach links oder rechts, anklickbare Bereiche, ein Mini-Fortschrittsbalken und farbige Zustände.

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

Auf einen Blick #

Schnellstart #

// open-Event des Fensters
// of_add_panel(Schluessel, Text, Symbol, Ausrichtung, Breite)
// ueber den Schluessel findet man den Bereich wieder ; Breite 0 = an den Text angepasst, -1 = nimmt den freien Platz
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Line 12, Col 4", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_END,   /*width*/ 140)

// Einen Bereich jederzeit ueber seinen Bezeichner aktualisieren
uo_status.of_panel(/*key*/ "state").is_text = "Wird gespeichert..."

Das Modell: Bereiche mit Schlüssel #

Die Leiste ist eine Folge von Bereichen, die der Reihe nach hinzugefügt werden. Ein Bereich erhält bei der Erstellung einen Bezeichner: Über ihn finden Sie ihn später wieder, um seinen Text, sein Symbol oder seinen Zustand zu ändern.

Der Bezeichner ist ein Adressierungsschlüssel, kein Schalter für Interaktivität:

• Bezeichner angegeben: das Panel ist wiederauffindbar — man ändert seinen Inhalt, man gibt ihm einen Tooltip. Es bleibt reglos: eine Statusleiste zeigt vor allem an, und ein Panel wie Zeile 12, Sp. 4 darf nicht drückbar wirken. Den Rechtsklick erhält es dennoch (ue_panel_rclicked) : ein Kontextmenü « Kopieren » ist keine Aktivierung.
• Leerer Bezeichner: das Panel ist rein dekorativ. Es ist weder auffindbar noch anklickbar, und es lässt sich kein Tooltip daran hängen. Geben Sie jedem Panel einen Bezeichner: das kostet nichts und hält die Tür offen. Er zählt dennoch in of_count und in den Positionen, und of_keys_at liefert für ihn einen leeren Schlüssel.
• Um ein Panel anklickbar zu machen, verlangen Sie es: of_panel(/*key*/ "id").ib_clickable = true. Ein Panel mit einer Auswahlliste (of_add_menu_item) ist es bereits.

// Der Bereich zeigt einen neuen Text
uo_status.of_panel(/*key*/ "state").is_text = "3 Datensaetze geaendert"

Siehe Gemeinsame Basis · Die Items.

Eigenschaften #

Methoden #

Die Argumente von of_add_panel #

Auf einem Bereich — n_pbt_statusbar_panel #

Auf einem Listeneintrag — n_pbt_statusbar_menu_item #

Erhalten über of_menu_item(/*keys*/ "enc/utf8"): die Adresse hat zwei Ebenen, das Panel und dann den Eintrag. Die Liste ist ein natives Menü: eine Eigenschaft, die geändert wird, während es offen ist, zeigt sich beim nächsten Öffnen.

Die Eigenschaften, die jedes Item-Handle erbt — is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image, il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover — sind auf einem Eintrag wirkungslos: die Liste ist ein natives Menü, das weder einen Tooltip noch die Farben eines Eintrags zeigt. Sie werden ignoriert und lesen sich leer (-1 für eine Farbe). Eine Position in einer Liste zählt Einträge: ein Trenner ist keiner, und of_count("enc"), of_keys_at("enc", n), of_has("enc/utf8") durchlaufen die Einträge eines Bereichs. Ein Schlüssel, der mit __ beginnt, ist der Komponente vorbehalten.

// The menu of the encoding panel, entry by entry
uo_status.of_add_menu_item(/*keys*/ "enc/utf8", /*label*/ "UTF-8")
uo_status.of_add_menu_item(/*keys*/ "enc/ansi", /*label*/ "ANSI")
uo_status.of_menu_item(/*keys*/ "enc/utf8").ib_checked = true     // the current value
uo_status.of_menu_item(/*keys*/ "enc/ansi").ib_enabled = false    // not available here

Zustandskonstanten #

Wie bei jeder Eigenschaft mit vordefinierten Werten sollten Sie die Konstante statt der Zeichenkette verwenden:

// The panel takes the colors of a warning
uo_status.of_panel(/*key*/ "state").is_state = n_pbt_statusbar_panel.STATE_WARNING

Events #

Über die Tastatur #

Die Leiste ist ein einziger Tabulatorstopp: nur die zum Anklicken gedachten Felder gehören dazu, und die Pfeile durchlaufen sie.

Ein Feld, das nur anzeigt, ist kein Steuerelement: es ist weder fokussierbar noch wird es als solches angesagt. Ein anklickbares, aber deaktiviertes Feld bleibt dagegen als nicht verfügbar angesagt, statt für Text gehalten zu werden. Ein Fortschrittsbalken sagt seinen Wert an, ein unbestimmter keinen — dieses Fehlen ist die Bedeutung des Wortes. Ein ausgegrauter anklickbarer Bereich zeigt weiterhin seinen Tooltip — den, der sagt, warum er ausgegraut ist — und ein Bereich mit Liste sagt, ob seine Liste offen ist.

Ein Bildschirmleser hört die Meldungen von of_flash_panel, ohne dass sich der Fokus bewegt: dafür ist eine Statusleiste da (ein höflicher Live-Bereich). Die anderen Änderungen — ein neuer Text, ein neuer Zustand — werden nur mit ib_announce = true vorgelesen; sonst würde eine sekündlich tickende Uhr den ganzen Tag reden.

Der Fokus übersteht den Neuaufbau der Leiste: ein hinzugefügter, entfernter, ausgeblendeter oder ausgegrauter Bereich baut sie neu auf, und der Fokus kehrt zum selben Bereich zurück (zum nächsten, wenn er ihn nicht mehr nehmen kann). Ein Text, ein Zustand oder ein Fortschritt ändert sich an Ort und Stelle, ohne Neuaufbau — eine sekündlich tickende Uhr stiehlt nie den Fokus.

Beispiele #

Feste und automatische Breiten #

// Breite 0 : der Bereich nimmt genau den Platz seines Textes ein
uo_status.of_add_panel(/*key*/ "", /*text*/ "An den Inhalt angepasster Bereich", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Feste Breite in Pixeln : nuetzlich, wenn sich der Text haeufig aendert,
// damit die benachbarten Bereiche nicht bei jeder Aktualisierung springen
uo_status.of_add_panel(/*key*/ "pos", /*text*/ "Zeile 1, Sp. 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

// Ein Bereich, der ans entgegengesetzte Ende geschoben wird
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

Symbole und anklickbare Bereiche #

// Ein Schluessel macht den Bereich adressierbar ; ib_clickable macht ihn anklickbar
uo_status.of_add_panel(/*key*/ "save", /*text*/ "Gespeichert", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_sep()   // Trennlinie zwischen zwei Gruppen von Bereichen
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Verbunden",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "user", /*text*/ "Alex Martin",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_status.ALIGN_END, /*width*/ 160)

// Nur diese beiden reagieren auf einen Klick (ue_panel_clicked)
uo_status.of_panel(/*key*/ "conn").ib_clickable = true
uo_status.of_panel(/*key*/ "user").ib_clickable = true

// Event ue_panel_clicked von uo_status
choose case as_key
    case "conn" ; open(w_connection_settings)
    case "user" ; open(w_profile)
end choose

Rich-Text in einem Bereich #

Die Bereiche akzeptieren die Rich-Text-Auszeichnung: Stile, Farben und kleine Bilder direkt im Text.

// Eine Begruessung links
uo_status.of_add_panel(/*key*/ "", /*text*/ "Willkommen [b]bei[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Der Verbindungsstatus rechts
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]Online[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// Lokale Variablen
long ll_changed

// Rich-Text gilt auch fuer Aktualisierungen
ll_changed = dw_list.ModifiedCount()
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] records changed"

Einen langen Vorgang verfolgen #

// Local variables
n_pbt_statusbar_panel lnv_import

// Der Import-Bereich, dann sein Handle, um ihm zu folgen
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Import", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// Lokale Variablen
long ll_percent

// In der Verarbeitungsschleife : der Mini-Balken folgt dem Fortschritt
for ll_percent = 0 to 100 step 25
    lnv_import.ii_progress = ll_percent
    lnv_import.is_text     = "Import " + String(ll_percent) + " %"
next

// Am Ende : den Mini-Balken ausblenden und das Ergebnis melden
lnv_import.ii_progress = -1                       // negativer Wert = Balken ausgeblendet
lnv_import.is_text     = "Import abgeschlossen"
lnv_import.is_state    = lnv_import.STATE_SUCCESS

Einen dezenten Hinweis melden #

// Local variables
n_pbt_statusbar_panel lnv_panel

// Der Bereich der Verbindung
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Offline : der Bereich zeigt einen Fehler ; verbunden : er sieht wieder normal aus
if not ib_connected then
    lnv_panel.is_text  = "Offline"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Verbunden"
    lnv_panel.is_state = lnv_panel.STATE_NONE   // zurueck zum normalen Erscheinungsbild
end if

Die Leiste an den Kontext anpassen #

// Einen Bereich ausblenden, ohne ihn zu loeschen : er findet seinen Platz spaeter wieder
uo_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Ihn ausgrauen, wenn die zugehoerige Aktion keinen Sinn ergibt
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

// Neu anordnen : den Zustandsbereich an den Anfang stellen (Positionen ab 1 gezaehlt)
uo_status.of_move_panel(/*key*/ "state", /*index*/ 1)

// Einen ueberfluessig gewordenen Bereich entfernen
uo_status.of_remove_panel(/*key*/ "import")

Der Größenänderungsgriff #

// Am Eckgriff ziehen aendert die Groesse des Fensters, das die Leiste traegt (ausgeblendet, solange es maximiert ist)
uo_status.ib_show_resize_grip = true

Ein Bereich, der den freien Platz nimmt #

Wie der Bereich « Bereit » jeder Windows-Statusleiste: er wächst mit dem Fenster, schiebt die Endbereiche ans Ende, und sein Text wird als erster gekürzt, wenn der Platz knapp wird.

// Eine Breite von -1 : der Bereich nimmt den ganzen freien Platz
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// Dasselbe auf einem schon vorhandenen Bereich
uo_status.of_panel(/*key*/ "state").ib_spring = true

Die Leiste an den unteren Fensterrand setzen #

of_dock_bottom setzt sie über die ganze Breite an den unteren Rand dessen, was sie trägt: ein Aufruf im resize-Event genügt. In einem MDI-Rahmen teilen sich die Blätter, was darüber bleibt.

// resize-Event des Fensters : die Leiste folgt dem unteren Rand
uo_status.of_dock_bottom()

// resize-Event eines MDI-Rahmens : die Leiste unten, die Blaetter darueber
uo_status.of_dock_bottom()
mdi_1.Resize(WorkSpaceWidth(), WorkSpaceHeight() - uo_status.Height)

Die MicroHelp übernehmen #

In einem MDI-Rahmen mit MicroHelp schreibt PowerBuilder die Hilfe des Menüeintrags unter dem Zeiger, und SetMicroHelp schreibt Ihre. Die Leiste übernimmt diese Rolle: nennen Sie einmal den Bereich, der die Hilfe zeigt (is_help_panel), und schreiben Sie dann is_help dort, wo Sie SetMicroHelp aufriefen. Die Hilfe steht über dem Text des Bereichs, und "" gibt ihm den Text zurück.

// Einmal : der Bereich, der die Hilfe zeigt (meist der erste)
uo_status.is_help_panel = "state"

// Wo Sie SetMicroHelp aufriefen : die Hilfe steht ueber Ready
uo_status.is_help = "Saving the order..."

// "" gibt dem Bereich seinen eigenen Text zurueck
uo_status.is_help = ""

// ue_item_hover-Event einer Menueleiste (uo_menu) : die Hilfe des Eintrags unter dem Zeiger
uo_status.is_help = this.of_item(/*keys*/ as_keys).is_tooltip

// getfocus-Event eines Feldes (sle_name) : sein Tag ist seine Hilfe
uo_status.is_help = sle_name.Tag

Best Practices #

• Geben Sie Bereichen, deren Text sich häufig ändert (Cursorposition, Zähler), eine feste Breite: Die benachbarten Bereiche springen dann nicht mehr bei jeder Aktualisierung.
• Machen Sie den ersten Bereich zu einer Feder (ib_spring oder eine Breite von -1): er nimmt den freien Platz, und sein Text wird als erster gekürzt.
• Ein Bereich ist standardmäßig reglos: verlangen Sie den Klick mit ib_clickable und lassen Sie Bereiche, die nur anzeigen, ohne Reaktion.
• Reservieren Sie das Ende der Leiste (ALIGN_END) für stabile Informationen (Uhrzeit, Benutzer, Verbindung) und den Anfang (ALIGN_START) für den aktuellen Kontext; bei Leserichtung von rechts nach links tauschen beide Seiten von selbst.
• Verwenden Sie is_state statt Farben im Text: Der Zustand folgt sowohl dem hellen als auch dem dunklen Design.
• Denken Sie daran, is_state wieder auf STATE_NONE und ii_progress wieder auf einen negativen Wert zu setzen, sobald der Hinweis oder der Vorgang beendet ist.
• Eine Statusleiste ist kein Protokoll: Ab fünf oder sechs Bereichen ist eine toaster-Benachrichtigung vorzuziehen.
• Wenn der Fortschritt mehr verdient als einen Mini-Balken in einem Bereich, wechseln Sie zur progressbar.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs