ion._internal¶

Internal APIs - not part of the public interface.

Functions¶

ion._internal.divider_at_pointer()¶

Query the split divider under the pointer.

Returns:: (split_node, axis, cursor_offset) or None.
Return type:: tuple[SplitNodeContainer, int, int] | None

ion._internal.edge_direction_at(position, margin)¶

The outer screen edge within margin of position, for a drag resting against it. A seam between two outputs is not an edge, and a corner is the diagonal between its two edges.

Parameters:

position (Point | tuple[int, int]) – The point to classify.
margin (int) – Distance from the edge that counts as resting against it (logical pixels). 0 is never an edge.

Returns:

The edge’s direction, or None when position is not within margin of one.

Return type:

Literal[‘LEFT’, ‘RIGHT’, ‘UP’, ‘DOWN’, ‘UP_LEFT’, ‘UP_RIGHT’, ‘DOWN_LEFT’, ‘DOWN_RIGHT’] | None

ion._internal.floating_focus_raise(item)¶

Focus the frame contained in a floating item and optionally raise it according to the pointer_click_to_raise preference. Call this before starting a floating move or resize drag to match the old grab behavior.

Parameters:: item (DesktopItemFloating) – The floating item to focus.
Return type:: None

ion._internal.floating_frame_resize_begin(frame, edge)¶

Begin an interactive floating resize. Sets Resizing toplevel state on all windows, stores edge tracking for the commit-time position fixup, and returns the frame’s effective size constraints.

Parameters:

frame (Frame) – The frame being resized.
edge (int) – Resize edge (0 = top-left, 1 = top-right, 2 = bottom-left, 3 = bottom-right, 4 = top, 5 = bottom, 6 = left, 7 = right).

Returns:

(size_min, size_max) where size_max is None when unconstrained.

Return type:

tuple[Size, Size | None]

ion._internal.floating_frame_resize_end()¶

End an interactive floating resize. Unsets Resizing toplevel state, sends final configure, and clears edge tracking.

Return type:: None

ion._internal.floating_item_at_pointer()¶

Query the topmost floating item under the pointer.

The hit test includes the item’s input footprint - the outer border zone and, for a floating frame, the drawn tab span of the titlebar above it - so a pointer on a frame’s border or a tab finds the correct item. The undrawn remainder of the titlebar past the tabs passes through.

Returns:: The floating item, or None.
Return type:: DesktopItemFloating | None

ion._internal.floating_lower_at_pointer()¶

Lower the floating item under the pointer to the bottom of the z-order. A no-op if the pointer is not over a floating item.

Return type:: None

ion._internal.floating_raise_at_pointer()¶

Raise the floating item under the pointer to the top of the z-order. A no-op if the pointer is not over a floating item.

Return type:: None

ion._internal.floating_resize_edge_at_pointer()¶

The resize edge under the pointer, matching the resize cursor ionwl shows for a floating item’s border. Reading it lets a resize drag use the same edge the cursor indicates, so the two cannot disagree.

Returns None when the pointer is not over a resize border (for example a drag started inside the item, or just past the rendered border), so the caller can fall back to its own edge detection.

Returns:: edge index (0 = top-left, 1 = top-right, 2 = bottom-left, 3 = bottom-right, 4 = top, 5 = bottom, 6 = left, 7 = right), or None.
Return type:: int | None

ion._internal.getset_writable(descr)¶

Whether a getset descriptor has a setter, which Python does not expose.

Parameters:: descr (Any) – A getset descriptor, e.g. Window.__dict__["app_id"].
Return type:: bool
Raises:: TypeError – If descr is not a getset descriptor.

ion._internal.hook_running()¶

Whether a hook callback is running, including anything it calls.

Return type:: bool

ion._internal.sloppy_focus_update()¶

Focus whatever the pointer is over, as a pointer motion would.

For an operator that moves a window out from under the pointer without warping: nothing else re-runs focus-follows-mouse until the user moves the pointer again. A no-op when the pointer is over no frame, and where a pointer motion would leave focus alone: over a panel or a client’s popup, with a menu open, while a layer surface such as a launcher holds keyboard focus, or during a client’s popup or drag-and-drop grab.

Focus moves once the calling operator or callback returns, not during this call. While a mouse button is held it moves when the button is released.

Return type:: None

ion._internal.tab_at_pointer()¶

Query the tab under the pointer.

Returns:: (window, frame, tab_rect, grab_offset) or None.
Return type:: tuple[Window, Frame, Rect, Point] | None

ion._internal.tab_drop_resolve(ghost)¶

Resolve a tab drop target from the ghost tab rectangle.

Parameters:: ghost (Rect | tuple[tuple[int, int], tuple[int, int]]) – Ghost tab rectangle.
Returns:: (frame, index) where frame is None for empty space and index is None when dropped on frame body.
Return type:: tuple[Frame | None, int | None]

ion._internal.tab_drop_slot(frame, drop_index, window)¶

Query the rectangle the dragged window would occupy if dropped at drop_index in frame, as the bar appears after the drop.

When window is not already in frame the siblings resize to make room for it; when it is (a same-frame reorder) the current layout is used.

Parameters:

frame (Frame) – Target frame, as returned by tab_drop_resolve().
drop_index (int) – Insertion index within the tab bar.
window (Window) – The window being dragged.

Returns:

The slot rectangle, or None when tabs are hidden or the frame is empty.

Return type:

Rect | None

ion._internal.window_detach_to_floating(window, source_frame, rect)¶

Detach a window from a multi-tab floating frame into its own new floating frame at the given rect. The source frame must contain more than one window.

Parameters:

window (Window) – The window to detach.
source_frame (Frame) – The floating frame containing the window.
rect (Rect | tuple[tuple[int, int], tuple[int, int]]) – Position and size for the new floating frame.

Returns:

The new floating desktop item, or None on failure.

Return type:

DesktopItemFloatingFrame | None