MDIPane

Wire name mdipane

A pane that hosts child windows inside itself — the classic multiple-document interface. The windows are ordinary Window objects; the pane arranges them, tracks which is active, and reports what the user does to them.

p=new mdipane fill="." children={
	a=new window title="Report.txt"
	b=new window title="Notes.txt"
}
sub p active

---

Properties

Property	Type	Default	Meaning
cascade	flag	—	Cascade the hosted windows
fill	string	—	Background fill character
minimize	int	—	Minimize a hosted window by id
next	flag	—	Activate the next window
pattern	flag	false	Draw a pattern background
prior	flag	—	Activate the prior window
remove	int	—	Close a hosted window by id
restore	int	—	Restore a hosted window by id
tile	flag	—	Tile the hosted windows

Plus the common properties.

Events

active — The active child window changed, including to none.

Field	Type	Meaning
trinket	uint	The pane's object ID.
window	uint	The newly active window, or 0 when none is.
title	string	The active window's title; absent when none is active.

minimize — A child window was minimized to the dock.

Field	Type	Meaning
trinket	uint	The pane's object ID.
window	uint	The minimized window.
title	string	The window's title.

remove — A child window left the pane.

Field	Type	Meaning
trinket	uint	The pane's object ID.
window	uint	The window that left.
title	string	The window's title.

restore — A minimized child window was restored.

Field	Type	Meaning
trinket	uint	The pane's object ID.
window	uint	The restored window.
title	string	The window's title.

Some of those properties are verbs

Most of this table is not state. tile, cascade, next, prior, restore, minimize and remove are actions: writing one makes something happen, and there is nothing to read back afterwards.

They come in two shapes.

Flag actions — tile cascade next prior — act on the pane as a whole and are written bare:

set p tile
set p cascade
set p next

They take the flag spelling and only the flag spelling. A value is an error, even the obvious one:

set p tile=1
  ->  tile: expected a flag

!tile parses and does nothing at all — negating an action asks for the action not to happen, which is the same as not writing it. It is never useful, but it is not an error either.

Id-directed actions — restore minimize remove — name a window. The number is one the reply gave you; see below for getting it:

set p minimize=1042
set p restore=1042
set p remove=1042

A window that is not in this pane is rejected rather than ignored:

set p restore=9999
  ->  restore: no window 9999 in this pane

And these take an integer only — the bare flag spelling is an error, which is the mirror of the rule above:

set p restore
  ->  restore: expected an integer

Getting the window ids

The ids those actions need are not in the build reply. A correlation key written inside children={…} does not come back:

p=new mdipane children={
	a=new window title="One"
	b=new window title="Two"
}
  ->  the reply carries p, and neither a nor b

Surface them with bare reference statements, the same way TreeView reaches a nested item:

aid=p.a
bid=p.b

Those reply with the numbers, and the actions go out against them in a later batch.

Children

A pane takes two different kinds of child, told apart by what they are.

Windows become hosted windows. Appending later is how a pane spawns one:

set p children={ new window title="Third" }

One non-window trinket becomes the pane's background content — what is seen behind the windows, in place of the fill character. Only one:

new mdipane children={
	new label caption="No documents open"
	new window title="One"
}

A second is refused rather than replacing the first:

new mdipane children={ new label caption="a"  new label caption="b" }
  ->  mdipane: background content already set

Order does not matter — the pane sorts them by type, not by position.

Background

fill is the character painted behind the windows, and it is exactly one character:

new mdipane fill="."
new mdipane fill=".."     ->  fill: expected exactly one character
new mdipane fill=""       ->  fill: expected exactly one character

pattern draws a patterned background instead. A background content trinket covers both.

What the events report

active fires whenever the active window changes, including to none — window=0 and no title is how an empty pane reports itself. It is the one to subscribe to for a title bar or a Window menu that tracks the front document.

The others say what became of a particular window, and all carry window and title.

A single user action often produces more than one event, in a meaningful order:

The user does	Events, in order
minimizes a window	minimize
restores it	active, then restore
steps to the next window	active
closes a window	remove, then active for whatever surfaced

So a client watching active alone still learns the front document changed when a window closes.

remove supersedes a hosted window's own close event. The pane owns the close-complete hook of the windows it holds, so a child window inside a pane does not report its own closing — the pane does.

Your own actions do not come back

Driving the pane from the wire raises nothing:

set p minimize=1042
  ->  the window minimizes, and no minimize event arrives

The client that sent it already knows. Events report what the user did, and this is the same rule that holds across the toolkit — a wire-side change is not echoed to the client that made it.

That is worth noticing here in particular, because tile, next and the rest look like the sort of thing you might drive from a Window menu and then expect to hear about. Update your own state when you send the action.

See also

Window — what a pane hosts · Dock — where minimized windows go · Desktop · Common Properties