dockcontainer — u_pbt_dockcontainer #

← Komponentenreferenz · Inhalt des Handbuchs

Andockbare Panels im Stil von Visual Studio: Andocken per Drag & Drop, Stapeln als Registerkarten, verstellbare Trennlinien, schwebende Fenster, automatisches Ausblenden — und Speichern bzw. Wiederherstellen der Anordnung.

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

Auf einen Blick #

Wie bei tab beherbergt jedes Panel ein echtes PowerBuilder-Steuerelement (dragobject): ein Userobject, eine DataWindow oder eine weitere PBToolboxAI-Komponente. Siehe Echte PowerBuilder-Steuerelemente hosten.

Schnellstart #

// open-Event des Fensters : die Panel-Steuerelemente liegen bereits darauf
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Dokument", /*content*/ uo_editor)

// Der Explorer, am Anfang des Dokuments angedockt, 260 Pixel breit
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorer", /*content*/ uo_tree)

// Die Eigenschaften, am Ende des Dokuments angedockt, 300 Pixel breit
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Eigenschaften", /*content*/ uo_props)

// Der zentrale Bereich : vom Docking weder schliessbar noch schwebend noch ausblendbar
uo_dock.is_main = "document"

Eigenschaften #

Docking-Positionen #

Die Konstanten der Komponente speisen as_position in of_add_panel und of_move_panel:

Eigenschaften eines Panels — n_pbt_dock_panel #

Über of_panel(schluessel) zu erhalten.

Methoden #

Events #

Mit der Maus #

Über das Ziehen von Registerkarten und Splittern hinaus wirken drei Gesten auf ein Panel — nie auf das Haupt-Panel:

Über die Tastatur #

Der Inhalt eines Panels ist ein echtes PowerBuilder-Steuerelement: die Tastatur gehört dort Ihrem Code, wie in jedem Fenster. Was die Komponente übernimmt, ist ihr eigener Rahmen — Kopfzeilen, Registerkarten, Splitter:

Ein Splitter ist ein fokussierbarer separator, der seine Position ansagt; die Schaltflächen der Kopfzeile (abdocken, ausblenden, schließen) tragen einen Namen, und das aktive Panel einer Gruppe ist mit aria-selected markiert. Eine Verschiebung über die Tastatur wird genau wie ein Ziehen mit der Maus über ue_layout_changed gemeldet.

Beispiele #

Ein Fenster im IDE-Stil #

// open-Event : jeder Inhalt ist ein echtes PB-Steuerelement auf dem Fenster
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Dokument", /*content*/ uo_editor)
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorer", /*content*/ uo_tree)
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Eigenschaften", /*content*/ uo_props)
uo_dock.of_add_panel(/*key*/ "output", /*position*/ uo_dock.POSITION_BOTTOM, /*relative_to*/ "document", /*size*/ 200, /*title*/ "Ausgabe", /*content*/ uo_console)

// Ein zweites Panel als Registerkarte auf "properties" gestapelt
uo_dock.of_add_panel(/*key*/ "help", /*position*/ uo_dock.POSITION_STACK, /*relative_to*/ "properties", /*size*/ 0, /*title*/ "Hilfe", /*content*/ uo_help)

// Das Dokument ist der zentrale Bereich
uo_dock.is_main = "document"

Die Anordnung des Benutzers merken und wiederherstellen #

// close-Event des Fensters : speichern, was der Benutzer angeordnet hat
// Local variables
string ls_layout

// Die aktuelle Anordnung, bereit zum Ablegen
ls_layout = uo_dock.of_get_layout()
of_save_setting(/*name*/ "main_dock", /*value*/ ls_layout)

// open-Event : die gespeicherte Anordnung LESEN, DANN die Panels erstellen
// Local variables
string ls_layout

// Zuerst die Einstellung : der Aufbau des Docks loest ue_layout_changed aus, das sie ueberschreiben koennte
ls_layout = of_read_setting(/*name*/ "main_dock")

// Dann die Panels und die Anordnung, in EINER Folge : ein einziges ue_layout_changed, bei der Wiederaufnahme
uo_dock.of_set_redraw(/*on*/ false)
of_create_panels()

// Und die Anordnung des letzten Schliessens, falls vorhanden
if ls_layout <> "" then uo_dock.of_set_layout(/*json*/ ls_layout)

// Ende der Folge
uo_dock.of_set_redraw(/*on*/ true)

Die Reihenfolge ist zwingend: of_set_layout erzeugt kein Panel, es ordnet nur die bereits vorhandenen neu an. Und die Einstellung wird vor dem Aufbau gelesen: jedes of_add_panel ändert die Anordnung, und ein ue_layout_changed, das sie speichert, würde eine halb aufgebaute Anordnung über die schreiben, die Sie wiederherstellen wollten.

Änderungen fortlaufend verfolgen #

// ue_layout_changed-Event von uo_dock : (string as_json)
// Einmal pro Folge von Aenderungen ausgeloest (Aufbau, wiederhergestellte Anordnung) : unveraendert gespeichert.
of_save_setting(/*name*/ "main_dock", /*value*/ as_json)

Ein Panel über sein Handle steuern #

// Local variables
n_pbt_dock_panel lnv_panel

// Der Eigenschaftenbereich : ein Titel, der die Aenderungen zaehlt, an seinem Rand eingeklappt
lnv_panel = uo_dock.of_panel(/*key*/ "properties")
lnv_panel.is_title  = "Eigenschaften (3 geändert)"
lnv_panel.ib_pinned = false        // klappt zu einer Lasche am Rand zusammen

// Ein Panel ausblenden, das Administratoren vorbehalten ist
uo_dock.of_panel(/*key*/ "audit").ib_visible = gb_administrator

Aufmerksamkeit auf ein Panel im Hintergrund lenken #

// Ein Hintergrundvorgang hat in die Konsole geschrieben : melden, ohne den Fokus zu stehlen
uo_dock.of_notify_panel(/*key*/ "output")

Aus dem Code neu anordnen #

// Ein Panel verschieben, als haette der Benutzer seine Registerkarte gezogen
uo_dock.of_move_panel(/*key*/ "output", /*target*/ "document", /*position*/ "bottom")

// Es als Registerkarte auf ein anderes Panel stapeln
uo_dock.of_move_panel(/*key*/ "help", /*target*/ "properties", /*position*/ "stack")

Ein Panel auf einen zweiten Bildschirm ablösen #

// Natives schwebendes Fenster : der Benutzer kann es auf einen anderen Bildschirm legen
uo_dock.of_float_panel(/*key*/ "properties")

// ue_panel_docked-Event von uo_dock : (string as_key)
// Der Benutzer hat das schwebende Fenster geschlossen : das Panel ist zurueck.
of_log(/*msg*/ "Panel wieder angedockt : " + as_key)

Ein Panel schließen und wieder öffnen #

// ue_panel_closed-Event von uo_dock : (string as_key)
// Das Panel ist nur ausgeblendet : sein Steuerelement bleibt im Dock, nichts taucht auf dem Fenster auf.
st_status.Text = "Panel geschlossen: " + as_key

// Menue Ansicht, Eigenschaften : das Panel wieder oeffnen, vorn in seinem Stapel
uo_dock.of_panel(/*key*/ "properties").ib_visible = true

Ein Panel schließen heißt es ausblenden: sein Steuerelement bleibt gehostet, und ib_visible = true öffnet es wieder vorn in seinem Stapel. of_remove_panel gibt das Steuerelement an das Fenster zurück, an seinen Platz und sichtbar, wenn es das war: reservieren Sie es für ein Steuerelement, das Sie danach zerstören.

Das Schließen eines Panels mit nicht gespeicherter Arbeit ablehnen #

// open-Event des Fensters : nachfragen, bevor sich ein Panel schliesst (standardmaessig aus)
uo_dock.ib_veto_close = true

// ue_panel_closing event of uo_dock : (string as_key) returns boolean
// Der Editor enthaelt noch ungespeicherte Aenderungen : sein Panel bleibt offen.
if as_key = "editor" then
    if ib_editor_modified then return false
end if
return true

// Ihr Code stellt dieselbe Frage : -4, wenn sie abgelehnt wird
if uo_dock.of_close_panel(/*key*/ "editor") = -4 then
    st_status.Text = "Speichern Sie das Dokument, bevor Sie den Editor schliessen."
end if

Best Practices #

• Legen Sie immer ein Haupt-Panel mit is_main fest: Ohne zentralen Bereich können die Benutzer alles ausblenden und stehen vor einem leeren Fenster.
• Lesen Sie die gespeicherte Anordnung vor dem Erstellen der Panels und speichern Sie sie dann bei ue_layout_changed statt nur beim Schließen: So geht bei einem unsauberen Beenden nichts verloren, und der Aufbau des Docks überschreibt nicht mehr, was Sie wiederherstellen wollten.
• of_set_layout kommt nach den of_add_panel-Aufrufen, niemals davor.
• Verwenden Sie of_notify_panel für Hintergrundvorgänge: Das ist weniger aufdringlich als ein Dialogfeld, und die Information bleibt sichtbar.
• Ein gehostetes Steuerelement ist ein natives Fenster: Es zeichnet sich über der Web-Ebene, kein visueller Effekt der Komponente kann darüber liegen.
• Ein Steuerelement wird nur von einem Container gehostet: es einem zweiten Dock (oder einem tab) zu geben, nimmt es dem ersten weg. Ein Steuerelement, das das Dock selbst enthält, wird abgelehnt (-5).
• Ein Panel schließen heißt es ausblenden (ib_visible = true öffnet es wieder); of_remove_panel gibt das Steuerelement an das Fenster zurück, sichtbar, wenn es das war.
• Rufen Sie of_reset() vor jedem Neuaufbau auf: Ohne diesen Aufruf bleiben die zuvor gehosteten Steuerelemente in den geleerten Container umgehängt, und die Wiederverwendung eines Schlüssels schlägt fehl.
• Für einfache, sich gegenseitig ausschließende Seiten, ohne Andocken und ohne Schweben, ist tab leichtgewichtiger.

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