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_editor)

// The explorer, docked at the start of the document, 260 pixels wide
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorer", /*content*/ uo_tree)

// The properties, docked at the end of the document, 300 pixels wide
uo_dock.of_add_panel(/*key*/ "properties", /*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_panel(key).

Methods #

Events #

Mouse #

Beyond dragging tabs and splitters, three gestures act on a panel — never on the main panel:

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(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Document", /*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*/ "Properties", /*content*/ uo_props)
uo_dock.of_add_panel(/*key*/ "output", /*position*/ uo_dock.POSITION_BOTTOM, /*relative_to*/ "document", /*size*/ 200, /*title*/ "Output", /*content*/ uo_console)

// A second panel stacked as a tab onto "properties"
uo_dock.of_add_panel(/*key*/ "help", /*position*/ uo_dock.POSITION_STACK, /*relative_to*/ "properties", /*size*/ 0, /*title*/ "Help", /*content*/ uo_help)

// The document is the central area
uo_dock.is_main = "document"

Remembering and restoring the user's layout #

// window close event : save what the user has arranged
string ls_layout
ls_layout = uo_dock.of_get_layout()
of_save_setting(/*name*/ "main_dock", /*value*/ ls_layout)

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

// First the panels : the of_add_panel calls above
of_create_panels()

// Then the layout saved at the last closing, if there is one
ls_layout = of_read_setting(/*name*/ "main_dock")
if ls_layout <> "" then uo_dock.of_set_layout(/*json*/ ls_layout)

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_save_setting(/*name*/ "main_dock", /*value*/ as_json)

Driving a panel through its handle #

// Local variables
n_pbt_dock_panel lnv_panel

// The properties panel : a title that counts the changes, folded onto its edge
lnv_panel = uo_dock.of_panel(/*key*/ "properties")
lnv_panel.is_title  = "Properties (3 changed)"
lnv_panel.ib_pinned = false        // collapses to a strip on the edge

// Hide a panel reserved for administrators
uo_dock.of_panel(/*key*/ "audit").ib_visible = gb_administrator

Drawing attention to a background panel #

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

Rearranging from code #

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

// Stack it as a tab onto another panel
uo_dock.of_move_panel(/*key*/ "help", /*target*/ "properties", /*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(/*key*/ "properties")

// ue_panel_docked event of uo_dock : (string as_key)
// The user closed the floating window : the panel is back.
of_log(/*msg*/ "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(/*key*/ as_key)

Refusing to close a panel that holds unsaved work #

// window open event : ask before a panel closes (off by default)
uo_dock.ib_veto_close = true

// ue_panel_closing event of uo_dock : (string as_key) returns boolean
// The editor still holds unsaved changes : its panel stays open.
if as_key = "editor" then
    if ib_editor_modified then return false
end if
return true

// Your code asks the same question : -4 when it is refused
if uo_dock.of_close_panel(/*key*/ "editor") = -4 then
    st_status.Text = "Save the document before closing the editor."
end if

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.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents