wijjit.core.overlay.OverlayManager

class wijjit.core.overlay.OverlayManager(app)[source]

Manages overlay rendering, z-indexing, and event routing.

The OverlayManager maintains a stack of overlays and handles: - Automatic z-index assignment - Event routing (highest z-index first) - Focus management and trapping - Rendering order - Background dimming

Examples

Basic modal usage:

modal = Modal(title="Confirm", content="Delete file?")
overlay = app.overlay_manager.push(
    modal,
    LayerType.MODAL,
    trap_focus=True,
    dimmed_background=True
)

Context menu usage:

menu = ContextMenu(items=[...])
overlay = app.overlay_manager.push(
    menu,
    LayerType.DROPDOWN,
    close_on_click_outside=True
)

Tooltip usage:

tooltip = Tooltip(text="Help text")
overlay = app.overlay_manager.push(
    tooltip,
    LayerType.TOOLTIP,
    close_on_click_outside=False,
    close_on_escape=False
)

Parameters:: app (Wijjit)

__init__(app)[source]

Initialize the overlay manager.

Parameters:: app (Wijjit) – Reference to the main app for focus/event management
Return type:: None

Methods

`__init__`(app)	Initialize the overlay manager.
`center_element`(element)	Center a `centered` overlay element on the current terminal.
`clear`()	Remove all overlays.
`get_at_position`(x, y)	Get the topmost overlay at the given position.
`get_focus_trap_elements`()	Get focusable elements in the focus-trapping overlay.
`get_overlay_elements`()	Get all overlay elements in z-order.
`get_top_overlay`()	Get the overlay with highest z-index.
`handle_click_outside`(x, y)	Handle a click outside any overlay.
`handle_escape`()	Handle ESC key press.
`has_dimmed_overlay`()	Check if any overlay requests background dimming.
`pop`([overlay])	Remove an overlay from the stack.
`pop_layer`(layer_type)	Remove all overlays in a specific layer.
`push`(element[, layer_type, ...])	Add an overlay to the stack.
`recalculate_centered_overlays`(term_width, ...)	Alias for recalculate_overlay_positions for backwards compatibility.
`recalculate_overlay_positions`(term_width, ...)	Recalculate positions for all overlays after terminal resize.
`should_trap_focus`()	Check if focus should be trapped in an overlay.

push(element, layer_type=LayerType.MODAL, close_on_click_outside=True, close_on_escape=True, trap_focus=False, dimmed_background=False, on_close=None)[source]

Add an overlay to the stack.

Parameters:

element (Element) – The element to display as an overlay
layer_type (LayerType) – Which layer to place this overlay in (default: MODAL)
close_on_click_outside (bool) – Close when clicking outside the overlay (default: True)
close_on_escape (bool) – Close when pressing ESC (default: True)
trap_focus (bool) – Trap focus within this overlay (default: False)
dimmed_background (bool) – Dim the background behind this overlay (default: False)
on_close (Callable or None) – Callback to invoke when overlay closes

Returns:

The created overlay object

Return type:

Overlay

center_element(element)[source]

Center a centered overlay element on the current terminal.

Computes bounds from the element’s width/height attributes and the live terminal size and assigns them to element.bounds.

Parameters:: element (Element) – The overlay element to place.
Returns:: True if the element opts into centering (element.centered) and was placed, False otherwise (bounds left untouched).
Return type:: bool

Notes

Shared by add_overlay() (initial placement) and the per-render template-overlay sync in Wijjit._process_template_overlays. A template rebuilds each overlay element on every render with bounds=None; without re-centering on the update path a centered modal loses its bounds on the first re-render and silently drops out of compositing (review item 2.13).

pop(overlay=None)[source]

Remove an overlay from the stack.

Parameters:: overlay (Overlay or None) – Specific overlay to remove, or None to remove the topmost
Returns:: The removed overlay, or None if stack was empty
Return type:: Overlay or None

pop_layer(layer_type)[source]

Remove all overlays in a specific layer.

Useful for closing all dropdowns or all tooltips at once.

Parameters:: layer_type (LayerType) – Layer to clear
Returns:: List of removed overlays
Return type:: List[Overlay]

clear()[source]

Remove all overlays.

Returns:: List of all removed overlays
Return type:: List[Overlay]

get_at_position(x, y)[source]

Get the topmost overlay at the given position.

Used for event routing - returns the highest z-index overlay that contains the specified point.

Parameters:

x (int) – X coordinate
y (int) – Y coordinate

Returns:

Topmost overlay at position, or None

Return type:

Overlay or None

get_top_overlay()[source]

Get the overlay with highest z-index.

Returns:: Topmost overlay, or None if stack is empty
Return type:: Overlay or None

handle_click_outside(x, y)[source]

Handle a click outside any overlay.

Closes overlays that have close_on_click_outside=True, starting from the topmost overlay.

Parameters:

x (int) – Click X coordinate
y (int) – Click Y coordinate

Returns:

True if any overlay was closed

Return type:

bool

handle_escape()[source]

Handle ESC key press.

Closes the topmost overlay that has close_on_escape=True.

Returns:: True if an overlay was closed
Return type:: bool

should_trap_focus()[source]

Check if focus should be trapped in an overlay.

Returns:: True if the topmost overlay is trapping focus
Return type:: bool

get_focus_trap_elements()[source]

Get focusable elements in the focus-trapping overlay.

Returns:: Focusable elements in the topmost focus-trapping overlay, or empty list if no overlay is trapping focus
Return type:: List[Element]

get_overlay_elements()[source]

Get all overlay elements in z-order.

Returns:: All overlay elements sorted by z-index (lowest to highest)
Return type:: List[Element]

has_dimmed_overlay()[source]

Check if any overlay requests background dimming.

Returns:: True if at least one visible overlay has dimmed_background=True
Return type:: bool

recalculate_overlay_positions(term_width, term_height)[source]

Recalculate positions for all overlays after terminal resize.

This method: 1. Repositions centered overlays to remain centered 2. Clamps all overlays within terminal bounds to prevent off-screen positioning

Parameters:

term_width (int) – New terminal width in columns
term_height (int) – New terminal height in lines

Return type:

None

recalculate_centered_overlays(term_width, term_height)[source]

Alias for recalculate_overlay_positions for backwards compatibility.

Parameters:

term_width (int)
term_height (int)

Return type:

None