dockcontainer — u_pbt_dockcontainer #

← Component reference · Guide contents

Visual Studio style dockable panels: drag-and-drop docking, tab stacking, resizable splitters, floating windows, auto-hide — plus saving and restoring the layout.

▶ See it live — Demo application, Dock container tile: the preview, the code behind it and this page, side by side.

At a glance #

Just like tab, every panel hosts a real PowerBuilder control (dragobject): a userobject, a DataWindow, or another PBToolboxAI component. See Hosting real PowerBuilder controls.

Quick start #

// window open event : the panel controls are already placed on it
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", &
                     /*size*/ 0, /*title*/ "Document", /*content*/ uo_editeur)

uo_dock.of_add_panel(/*key*/ "explorateur", /*position*/ uo_dock.POSITION_START, &
                     /*relative_to*/ "document", /*size*/ 260, &
                     /*title*/ "Explorer", /*content*/ uo_arbre)

uo_dock.of_add_panel(/*key*/ "proprietes", /*position*/ uo_dock.POSITION_END, &
                     /*relative_to*/ "document", /*size*/ 300, &
                     /*title*/ "Properties", /*content*/ uo_props)

// The central area : the docking cannot close, float or hide it
uo_dock.is_main = "document"

Properties #

Docking positions #

The component constants feed as_position in of_add_panel and of_move_panel:

Properties of a panel — n_pbt_dock_panel #

Obtained through of_item(key).

Methods #

Events #

Keyboard #

A panel's content is a real PowerBuilder control: the keyboard there belongs to your code, as in any window. What the component takes care of is its own chrome — headers, tabs, splitters:

A splitter is a focusable separator that announces its position; the header buttons (float, hide, close) carry a name, and the active panel of a group is marked aria-selected. A keyboard move is reported through ue_layout_changed exactly like a mouse drag.

Examples #

An IDE-style window #

// open event : every content is a real PB control placed on the window
uo_dock.of_add_panel("document", "", "", 0, "Document", uo_editeur)
uo_dock.of_add_panel("explorateur", uo_dock.POSITION_START,   "document", 260, "Explorer", uo_arbre)
uo_dock.of_add_panel("proprietes",  uo_dock.POSITION_END,  "document", 300, "Properties",  uo_props)
uo_dock.of_add_panel("sortie",      uo_dock.POSITION_BOTTOM, "document", 200, "Output",      uo_console)

// A second panel stacked as a tab onto "proprietes"
uo_dock.of_add_panel("aide", uo_dock.POSITION_STACK, "proprietes", 0, "Help", uo_aide)

uo_dock.is_main = "document"

Remembering and restoring the user's layout #

// window close event : save what the user has arranged
string ls_disposition
ls_disposition = uo_dock.of_get_layout()
of_enregistrer_preference("dock_principal", ls_disposition)

// open event : RE-CREATE the panels first, restore afterwards
string ls_disposition

of_creer_les_panneaux()          // the of_add_panel calls above

ls_disposition = of_lire_preference("dock_principal")
if ls_disposition <> "" then uo_dock.of_set_layout(ls_disposition)

The order matters: of_set_layout creates no panel, it only rearranges the ones that already exist.

Tracking changes continuously #

// ue_layout_changed event of uo_dock : (string as_json)
// Saved right away, without waiting for the window to close.
of_enregistrer_preference("dock_principal", as_json)

Driving a panel through its handle #

n_pbt_dock_panel lnv_panneau

lnv_panneau = uo_dock.of_item("proprietes")
lnv_panneau.is_title  = "Properties (3 changed)"
lnv_panneau.ib_pinned = false        // collapses to a strip on the edge

// Hide a panel reserved for administrators
uo_dock.of_item("audit").ib_visible = gb_administrateur

Drawing attention to a background panel #

// A background task wrote to the console : signal it without stealing the focus
uo_dock.of_notify_panel("sortie")

Rearranging from code #

// Move a panel as if the user had dragged its tab
uo_dock.of_move_panel(/*key*/ "sortie", /*target*/ "document", /*position*/ "bottom")

// Stack it as a tab onto another panel
uo_dock.of_move_panel(/*key*/ "aide", /*target*/ "proprietes", /*position*/ "stack")

Floating a panel onto a second monitor #

// Native floating window : the user can drop it on another monitor
uo_dock.of_float_panel("proprietes")

// ue_panel_docked event of uo_dock : (string as_key)
// The user closed the floating window : the panel is back.
of_journaliser("Panel docked back : " + as_key)

Closing a panel cleanly #

// ue_panel_closed event of uo_dock : (string as_key)
// Also remove the panel from the container to release the hosted control.
uo_dock.of_remove_panel(as_key)

Best practices #

• Always designate a main panel with is_main: without a central area, users can hide everything and end up staring at an empty window.
• Save the layout on ue_layout_changed rather than only on close: an abnormal shutdown then loses nothing.
• of_set_layout comes after the of_add_panel calls, never before.
• Use of_notify_panel for background tasks: it is less intrusive than a dialog box and the information stays visible.
• A hosted control is a native window: it draws above the web layer, so no visual effect of the component can appear over it.
• Call of_reset() before any rebuild: without it, the previously hosted controls stay reparented into the emptied container and reusing a key fails.
• For simple exclusive pages, with no docking and no floating, tab is lighter.

← Component reference · Guide contents