Scripted Control

Scripted Control

Everything the header menus and the mouse can do, a script can do by name - so a game package can offer keyboard commands (ui show quests), hotkeys, or an accessible text interface over the same layout.

These functions are plain set-semantics: each applies a change and returns ok, code[, detail], never echoing anything itself, so your package owns every word the player sees. The header menus and the drag paths call the same functions, so a scripted change leaves exactly the state a mouse action would (docks re-laid, layout saved, Widgets menu refreshed).

code is one of "ok", "already", "unknown_widget", "sidebar_hidden" (detail = the side), "fill", "alone", "same", "target_hidden", "unsupported", "invalid".

Resolving what the player typed

Function	Does
mdw.findWidget(query)	Resolve a typed name: exact name, exact title, then unique prefix of either (case, spaces, and underscores ignored). Returns widget, or nil, candidates - the sorted candidate names when a prefix was ambiguous, an empty table when nothing matched. Groups are never returned
mdw.widgetConsole(name)	The live MiniConsole behind a name: a group resolves to its active member, a tabbed widget to its active tab; nil for an embedded mapper

Visibility and placement

Function	Does
mdw.showWidget(name)	Reveal a widget and front its tab. Puts it BACK where it was: into the group it was closed from, else at the end of the dock it came from; returns "sidebar_hidden" instead of forcing a group into a hidden sidebar
mdw.hideWidget(name)	Close its tab when it has siblings, else hide its (lone) group
mdw.focusWidget(name)	showWidget, then raise its group above other floating groups
mdw.floatWidget(name)	Give it a group of its own, floating centred (cascaded past other floats)
mdw.dockWidget(name, side, position)	Its own group docked "left"/"right", at the "top" or (default) bottom of that dock
mdw.groupWidget(name, targetName)	Add it to targetName's group as a tab, fronted (migrating out of its old group)
mdw.ungroupWidget(name)	Pull it out of its group into one of its own, directly below the old group (or floating, when the old group floats)
mdw.setSidebarVisible(side, on)	Show or hide a sidebar by value
mdw.setPromptBarVisible(on)	Show or hide the prompt bar by value

One deliberate divergence from the mouse: the Widgets menu reveals a hidden widget floating in the centre, because the player can drag it from there. showWidget puts it back where it was instead - a keyboard user cannot drag a float back into a dock.

Sizes and fonts

Function	Does
mdw.setDockWidth(side, px)	Dock width by value, clamped like the splitter drag (minDockWidth..maxDockWidth); returns the applied width as the third value
mdw.setWidgetHeight(name, px)	Height of the widget's dock occupant (its group), clamped like the drag handle; "fill" when the occupant is the auto-filled bottom of a column
mdw.setMainFontSize(size), mdw.setMenuFontSize(size), mdw.setWidgetHeaderFontSize(size), mdw.setPromptFontSize(size), mdw.setWidgetFontSize(name, size)	Absolute font sizes (the prompt and per-widget sizes are stored as offsets from the content size, so they follow a later content-size change). Each clamps, applies, saves, and returns the applied size
mdw.setFontFamily(name)	The font family every MDW surface renders in (widget consoles, tab bars, the prompt bar, chrome bars, menus). Validated against the fonts Mudlet has loaded: a name it does not know is refused with "invalid" (detail = the name) rather than applied, because Qt would substitute silently while MDW's column arithmetic kept measuring the requested font. Applies in place and is persisted in the layout. No menu offers this - Mudlet cannot tell a monospace family from a proportional one, and MDW's layout math is meaningless in the latter, so a game package exposes it in its own command
mdw.getFontFamily()	preferred, effective - the same name twice, unless the preferred font is not loaded and MDW is rendering in the fallback for this session
mdw.getFontSizes()	{ main, menu, header, prompt, widgets = { [name] = effectiveSize } }

The Font Size menu's +/- rows are thin wrappers over these setters; a setter never opens a menu.

Reading and scrolling

Function	Does
mdw.scrollWidget(name, action, lines)	"up"/"down" by lines (default 10), "top", "bottom". Per-window scrolling needs Mudlet 4.17+, else "unsupported"
mdw.widgetText(name)	The widget's current console text as an array of plain lines (colours dropped, trailing blank lines removed) - for reading a widget aloud or echoing it elsewhere. Returns nil, code on failure

The whole layout

Function	Does
mdw.describeLayout()	The layout as plain data: { sidebars = { left/right = { visible, width } }, promptBar = { visible, height }, theme, fonts, docks = { left/right = { rows = { { occupants } } } }, floating = { occupant... }, hidden = { { name, title, reason } } }. An occupant is { group, members = { { name, title } }, active, height, fill, visible, docked }; side-by-side columns are flattened into the row's occupant list in column order. reason is closed, group_hidden, or sidebar_hidden
mdw.resetLayout(opts)	Delete the saved layout, restore the factory value of every persisted key (mdw.layoutDefaults), and rebuild the UI now. opts.keepGameSettings (default true) preserves mdw.gameSettings; originalMainFontSize and originalMainFont always survive, since they are the uninstall restore values

Example

-- "show quests" from your own alias, in your own words
local widget, candidates = mdw.findWidget("que")
if not widget then
  echo(#candidates > 0 and ("Did you mean: " .. table.concat(candidates, ", ") .. "\n")
    or "No such widget.\n")
  return
end
local ok, code, detail = mdw.showWidget(widget.name)
if not ok and code == "sidebar_hidden" then
  echo("The " .. detail .. " sidebar is off.\n")
end