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.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.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_x, ghost_y, ghost_w, ghost_h)

Resolve a tab drop target from the ghost tab rectangle.

Parameters:

  • ghost_x (int) – Ghost tab X position.

  • ghost_y (int) – Ghost tab Y position.

  • ghost_w (int) – Ghost tab width.

  • ghost_h (int) – Ghost tab height.

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) – Position and size for the new floating frame.

Returns:

The new floating desktop item, or None on failure.

Return type:

DesktopItemFloatingFrame | None