Widget Options

Widget Options

Constructor Options

Option	Type	Default	Description
name	string	required	Unique identifier for the widget
title	string	name	Display title shown in title bar
dock	string	nil	"left", "right", or nil for floating
x	number	100	Initial X position (floating only)
y	number	100	Initial Y position (floating only)
height	number	200	Widget height in pixels
visible	boolean	true	Whether widget starts visible
row	number	auto	Row index in dock (auto-assigned if nil)
rowPosition	number	0	Position within a row for side-by-side placement
subRow	number	0	Sub-row within a column for vertical sub-stacking
overflow	string	"wrap"	Text overflow mode: "wrap", "ellipsis", or "hidden"
fill	boolean	false	Whether widget fills remaining dock column height (see note below)
fontAdjust	number	0	Font size offset from the global content font size
liveReflow	boolean	false	Re-run reflow() on every move of a live drag. Only for widgets whose reflow is a cheap repaint-from-state (a renderer bound as the instance reflow); echo-buffer replay is too heavy per move
onClose	function	nil	Callback when widget is hidden
onClick	function	nil	Callback when content area is clicked

Note: If a widget with the same name already exists, Widget:new() returns the existing widget instead of creating a duplicate. This allows scripts to be safely reloaded without errors.

Fill: Fill is normally automatic - the bottom widget of each dock column stretches to fill the remaining height. The fill option seeds this state at creation; you rarely need to set it by hand.

Overflow Modes

The overflow option controls how text behaves when it exceeds the widget width:

Mode	Behavior	On Resize
"wrap"	Lines wrap at the widget edge (default)	Text reflows to new width
"ellipsis"	Long lines are truncated with "..."	Text re-truncated to new width
"hidden"	Text clips at widget edge, no wrapping	No reflow

-- Default: text wraps and reflows on resize
local inv = mdw.Widget:new({
  name = "Inventory",
  overflow = "wrap",
})

-- Long lines show "..." instead of wrapping
local status = mdw.Widget:new({
  name = "Status",
  overflow = "ellipsis",
})

-- Text clips at the edge, no buffer or reflow
local log = mdw.Widget:new({
  name = "Log",
  overflow = "hidden",
})

Ellipsis mode works with all echo methods (echo, cecho, decho, hecho), preserving color codes up to the truncation point. Both "wrap" and "ellipsis" modes buffer recent echo calls (maxEchoBuffer, 200 by default) so text can be reflowed when the widget is resized.

Callbacks

local widget = mdw.Widget:new({
  name = "Clickable",
  title = "Click Me",
  dock = "right",
  onClick = function(self, event)
    self:cecho("<yellow>Clicked at " .. event.x .. ", " .. event.y .. "\n")
  end,
  onClose = function(self)
    echo("Widget was closed\n")
  end,
})