LayoutEngine API Reference

Full API reference for the LayoutEngine class, accessible via engine.layout. The LayoutEngine shares the component objects dictionary with ComponentAPI and computes pixel-level positions from proportional modifiers.

set_dimensions(*, id, width_modifier=None, height_modifier=None, margin_top=None, margin_left=None)

Sets one or more layout dimension modifiers on an existing component. All modifier values must be floats between 0.0 and 1.0 inclusive.

Parameter	Type	Description
id	str	ID of the target component
width_modifier	float \| None	Proportion of terminal width (0.0–1.0)
height_modifier	float \| None	Proportion of terminal height (0.0–1.0)
margin_top	float \| None	Top margin as proportion of terminal height
margin_left	float \| None	Left margin as proportion of terminal width

Raises ValueError if: (1) component id doesn't exist, (2) no parameters provided, (3) value is outside 0.0–1.0, or (4) margin is set when the corresponding margin mode is 'centered'.

engine.layout.set_dimensions(
    id='menu_1',
    width_modifier=0.6,
    height_modifier=0.4
)

# Set custom margins
engine.layout.set_dimensions(
    id='menu_1',
    margin_top=0.1,
    margin_left=0.2
)

margin_mode(*, id, param, mode)

Sets the margin calculation mode for one or both axes.

Parameter	Type	Description
id	str	ID of the target component
param	str \| list	'margin_top', 'margin_left', or a list of both
mode	str	'centered' (auto-center) or 'custom' (manual margin values)

# Center both axes
engine.layout.margin_mode(
    id='menu_1',
    param=['margin_top', 'margin_left'],
    mode='centered'
)

# Custom top margin, centered horizontally
engine.layout.margin_mode(id='menu_1', param='margin_top', mode='custom')
engine.layout.margin_mode(id='menu_1', param='margin_left', mode='centered')

Centered Mode RestrictionWhen a margin axis is set to 'centered', you cannot manually set that margin via set_dimensions(). Attempting to do so will raise a ValueError. Switch to 'custom' mode first if you need manual control.

Layout Computation Details

Layout is computed by the internal _compute_all() method (called automatically by RenderEngine.draw()). For each component, it resolves:

x = int(width_modifier * terminal_cols)
y = int(height_modifier * terminal_rows)
margin_top: int(margin_modifier * rows) if custom, or (rows - y) // 2 if centered
margin_left: int(margin_modifier * cols) if custom, or (cols - x) // 2 if centered
corners.top_left and corners.bottom_right tuples

Terminal dimensions are read fresh on every call via shutil.get_terminal_size(), so the layout automatically adapts if the terminal is resized between renders.