Grouped Widgets

Grouped Widgets

MDW lets you combine several separate widgets into a single tabbed group, so they share one dock slot (or one floating frame) and only the active tab's content is shown. This is different from a Tabbed Widget: a group is formed from independent widgets you already have, each keeping its own content and update logic, whereas a Tabbed Widget is a single widget you create with multiple built-in channels.

Internally these groups are called "Stacks", and the public API lives under mdw.Stack.

The home group

Every widget always lives inside a group. By default that group holds just the one widget, so you see no tab bar and it behaves like a plain widget. The moment you combine two widgets, the group holds both and a tab bar appears across the top - one tab per member. When there are more tabs than the bar can hold, the tabs shrink to fit - spare padding first, then the labels truncate with .. - so they never spill past the bar.

Because the group is the real dock/float occupant, position, docking, visibility, and resizing operate on the whole group. The Widget Methods transparently delegate to the group, so you rarely need to think about this - widget:dock("left") docks the group the widget belongs to, widget:show() shows the group and selects that widget's tab, and so on.

Grouping widgets by dragging

To combine two widgets into a group:

1. Drag a widget's tab (or, for a lone widget, its title bar) and drop it onto the tab-bar band at the top of another widget.
2. A ghost tab shows where it will slot in. On release, the two become one tabbed group.

If you drop onto the left/right edge of a widget instead of its tab bar, the widgets are placed side-by-side rather than grouped. See Drag and Drop for all the drop targets.

A group can contain a Tabbed Widget as one of its members, in which case that member's tab shows its own inner tab bar. Groups cannot be nested inside other groups.

Ungrouping

There are two ways to remove a widget from a group:

• Drag its tab out of the tab bar. Pulling a tab away tears it out into its own group, which you can then float, dock, or drop into a different group.
• Click the close "x" shown on the active tab. This detaches that widget and hides it. Re-checking it in the Widgets menu brings it back as a floating widget in the centre; mdw.showWidget(name) (Scripted Control) puts it back into the group it was closed from instead.

When a group is left with a single member it simply behaves like a normal widget again.

Programmatic API

-- Get a group by name (returns nil if the name is not a group)
local grp = mdw.Stack.get("Group1")

-- List all group names (sorted)
local names = mdw.Stack.list()

-- Switch a group's active tab to one of its member widgets
mdw.Stack.select("Group1", "Comm")

Building groups from a script

You can also form groups without dragging. These lower-level module functions operate on widget names:

-- Group existing widgets into a new tabbed group at the first widget's slot.
-- Groups are auto-named "Group1", "Group2", ... unless you pass a name.
mdw.groupWidgetsIntoStack({"Comm", "Log", "Debug"})
mdw.groupWidgetsIntoStack({"Comm", "Log"}, { name = "Chat", dock = "right" })

-- Add a widget to an existing group (optionally at a specific tab index). A widget
-- grouped elsewhere - including its own home group - is moved here, and an
-- emptied source group is destroyed.
mdw.addToStack("Group1", "Log")
mdw.addToStack("Group1", "Log", 1)

-- Remove a widget from a group, restoring it as a standalone widget
mdw.removeFromStack("Group1", "Log")

The named, set-semantics counterparts - mdw.groupWidget(name, targetName), mdw.ungroupWidget(name), mdw.floatWidget(name, opts), mdw.dockWidget(name, side, position) - return ok, code and re-lay and save like a drag does; they are the right layer for commands and hotkeys. See Scripted Control.

Groups and the class APIs

Groups are internal containers, so they are deliberately excluded from the widget class helpers:

• mdw.Widget.get() / mdw.Widget.list() return only plain widgets, never groups.
• mdw.TabbedWidget.get() / mdw.TabbedWidget.list() return only tabbed widgets, never groups.
• The Widgets header menu lists the individual member widgets, not the group containers.

Use mdw.Stack.get() / mdw.Stack.list() when you specifically need the group.