:orphan:

ion._internal
=============

.. module:: ion._internal

Internal APIs - not part of the public interface.

Functions
---------

.. function:: divider_at_pointer()

   Query the split divider under the pointer.

   :return: ``(split_node, axis, cursor_offset)`` or ``None``.
   :rtype: tuple[:class:`~ion.types.SplitNodeContainer`, int, int] | None

.. function:: 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.

   :param item: The floating item to focus.
   :type item: :class:`~ion.types.DesktopItemFloating`
   :rtype: None

.. function:: 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.

   :param frame: The frame being resized.
   :type frame: :class:`~ion.types.Frame`
   :param edge: Resize edge (0 = top-left, 1 = top-right,
      2 = bottom-left, 3 = bottom-right, 4 = top, 5 = bottom,
      6 = left, 7 = right).
   :type edge: int
   :return: ``(size_min, size_max)`` where ``size_max`` is ``None``
      when unconstrained.
   :rtype: tuple[:class:`~ion.types.Size`, :class:`~ion.types.Size` | None]

.. function:: floating_frame_resize_end()

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

   :rtype: None

.. function:: 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.

   :return: The floating item, or ``None``.
   :rtype: :class:`~ion.types.DesktopItemFloating` | None

.. function:: 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.

   :rtype: None

.. function:: 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.

   :rtype: None

.. function:: 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.

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

.. function:: tab_at_pointer()

   Query the tab under the pointer.

   :return: ``(window, frame, tab_rect, grab_offset)`` or ``None``.
   :rtype: tuple[:class:`~ion.types.Window`, :class:`~ion.types.Frame`, :class:`~ion.types.Rect`, :class:`~ion.types.Point`] | None

.. function:: tab_drop_resolve(ghost_x, ghost_y, ghost_w, ghost_h)

   Resolve a tab drop target from the ghost tab rectangle.

   :param ghost_x: Ghost tab X position.
   :type ghost_x: int
   :param ghost_y: Ghost tab Y position.
   :type ghost_y: int
   :param ghost_w: Ghost tab width.
   :type ghost_w: int
   :param ghost_h: Ghost tab height.
   :type ghost_h: int
   :return: ``(frame, index)`` where frame is ``None`` for empty space
      and index is ``None`` when dropped on frame body.
   :rtype: tuple[:class:`~ion.types.Frame` | None, int | None]

.. function:: 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.

   :param frame: Target frame, as returned by :func:`tab_drop_resolve`.
   :type frame: :class:`~ion.types.Frame`
   :param drop_index: Insertion index within the tab bar.
   :type drop_index: int
   :param window: The window being dragged.
   :type window: :class:`~ion.types.Window`
   :return: The slot rectangle, or ``None`` when tabs are hidden or the
      frame is empty.
   :rtype: :class:`~ion.types.Rect` | None

.. function:: 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.

   :param window: The window to detach.
   :type window: :class:`~ion.types.Window`
   :param source_frame: The floating frame containing the window.
   :type source_frame: :class:`~ion.types.Frame`
   :param rect: Position and size for the new floating frame.
   :type rect: :class:`~ion.types.Rect`
   :return: The new floating desktop item, or ``None`` on failure.
   :rtype: :class:`~ion.types.DesktopItemFloatingFrame` | None