ion.types
=========

.. module:: ion.types

.. include:: ../rst/ion.types.rst

All type definitions for the ion API.

Classes
-------

.. class:: AnimatePreferences

   Animation preferences.


   .. attribute:: desktop_axis

      Desktop layout axis: 0 = horizontal (side by side), 1 = vertical (stacked).
      Default: 0.
      
      :type: int

   .. attribute:: desktop_axis_rows

      Number of rows (horizontal axis) or columns (vertical axis) in the
      overview grid. 1 = single row/column, 2+ = wrap into a grid.
      Default: 1.
      
      :type: int

   .. attribute:: desktop_slide_duration

      Desktop slide animation duration in milliseconds.
      Default: 300.
      
      :type: int

   .. attribute:: desktop_zoom_duration

      Desktop zoom phase duration in milliseconds (each of zoom-out and zoom-in).
      Default: 500.
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: ColorRGB

   RGB color with components in 0.0-1.0 range, accessed via [0]..[2].

   .. method:: __init__(self, rgb)

      :param rgb: RGB components in 0.0-1.0 range.
      :type rgb: tuple[float, float, float]
      :rtype: None

   .. method:: __getitem__(self, index)

      Get an item by index.

      :param index: ``0`` for red, ``1`` for green, ``2`` for blue.
      :type index: int
      :rtype: float

   .. method:: __getitem__(self, index)
      :noindex:

      :param index: A slice over the three components.
      :type index: slice
      :rtype: tuple[float, ...]

   .. method:: __len__(self)

      Return the number of components (always 3).

      :rtype: int

   .. method:: __iter__(self)

      Iterate over components (r, g, b).

      :rtype: Iterator[float]

   .. classmethod:: from_rgb_hex(hex)
   
      Create a ColorRGB from an RGB hex value.
      Accepts a string (``"#rrggbb"``) or integer (``0xRRGGBB``).
   
      :param hex: Hex color as string or integer.
      :type hex: str | int
      :rtype: :class:`ion.types.ColorRGB`

   .. method:: copy(self)
   
      Return a mutable (unfrozen) copy.
   
      :rtype: :class:`ColorRGB`

   .. method:: freeze(self)
   
      Freeze this value, making it read-only and hashable.
      Returns self for convenience (e.g. ``d[p.freeze()] = v``).
   
      :rtype: Self

   .. method:: lerp(self, other, factor)
   
      Linearly interpolate between this color and ``other``.
   
      :param other: Target color.
      :type other: :class:`ColorRGB`
      :param factor: Blend factor (0.0-1.0).
      :type factor: float
      :rtype: :class:`ion.types.ColorRGB`

   .. method:: offset(self, value)
   
      Add a uniform value to all channels (clamped to 0.0-1.0).
   
      :param value: Value to add to each channel.
      :type value: float
      :rtype: :class:`ion.types.ColorRGB`

   .. method:: to_hex(self)
   
      Convert to hex string (``"#rrggbb"``).
   
      :rtype: str

   .. method:: to_rgba(self, alpha=1.0)
   
      Convert to RGBA with the given alpha.
   
      :param alpha: Alpha component (default 1.0).
      :type alpha: float
      :rtype: :class:`ion.types.ColorRGBA`

   .. method:: to_tuple(self)
   
      Convert to tuple ``(r, g, b)``.
   
      :return: Tuple ``(r, g, b)``.
      :rtype: tuple[float, float, float]

   .. attribute:: is_frozen

      Whether this value is frozen (read-only).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __copy__(self)

         :rtype: :class:`ColorRGB`

      .. method:: __deepcopy__(self, memo)

         :param memo: Memoization dict for shared subobjects.
         :type memo: dict
         :rtype: :class:`ColorRGB`

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __format__(self, format_spec)

         :param format_spec: Format spec applied per component (empty spec returns ``repr(self)``).
         :type format_spec: str
         :rtype: str

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str

      .. method:: __setitem__(self, key, value)

         Set self[key] to value.

         :param key: Index or key.
         :type key: int
         :param value: Value to assign.
         :type value: object



.. class:: ColorRGBA

   RGBA color with components in 0.0-1.0 range, accessed via [0]..[3].

   .. method:: __init__(self, rgba)

      :param rgba: RGBA components in 0.0-1.0 range.
      :type rgba: tuple[float, float, float, float]
      :rtype: None

   .. method:: __getitem__(self, index)

      Get an item by index.

      :param index: ``0`` for red, ``1`` for green, ``2`` for blue, ``3`` for alpha.
      :type index: int
      :rtype: float

   .. method:: __getitem__(self, index)
      :noindex:

      :param index: A slice over the four components.
      :type index: slice
      :rtype: tuple[float, ...]

   .. method:: __len__(self)

      Return the number of components (always 4).

      :rtype: int

   .. method:: __iter__(self)

      Iterate over components (r, g, b, a).

      :rtype: Iterator[float]

   .. classmethod:: from_rgb_hex(hex)
   
      Create a ColorRGBA from an RGB hex value. Alpha defaults to 1.0.
      Accepts a string (``"#rrggbb"``) or integer (``0xRRGGBB``).
   
      :param hex: Hex color as string or integer.
      :type hex: str | int
      :rtype: :class:`ion.types.ColorRGBA`

   .. classmethod:: from_rgba_hex(hex)
   
      Create a ColorRGBA from an RGBA hex value.
      Accepts a string (``"#rrggbbaa"``) or integer (``0xRRGGBBAA``).
   
      :param hex: Hex color as string or integer.
      :type hex: str | int
      :rtype: :class:`ion.types.ColorRGBA`

   .. method:: copy(self)
   
      Return a mutable (unfrozen) copy.
   
      :rtype: :class:`ColorRGBA`

   .. method:: freeze(self)
   
      Freeze this value, making it read-only and hashable.
      Returns self for convenience (e.g. ``d[p.freeze()] = v``).
   
      :rtype: Self

   .. method:: lerp(self, other, factor)
   
      Linearly interpolate between this color and ``other``.
      A factor of 0.0 returns this color; 1.0 returns ``other``.
      All four components (including alpha) are interpolated.
   
      :param other: Target color.
      :type other: :class:`ColorRGBA`
      :param factor: Blend factor (0.0-1.0).
      :type factor: float
      :rtype: :class:`ion.types.ColorRGBA`

   .. method:: offset(self, value)
   
      Add a uniform value to the R, G, B channels (clamped to 0.0-1.0).
      Alpha is preserved. Use positive values to brighten, negative to dim,
      without affecting saturation.
   
      :param value: Value to add to each RGB channel.
      :type value: float
      :rtype: :class:`ion.types.ColorRGBA`

   .. method:: to_hex(self)
   
      Convert to hex string (``"#rrggbb"`` or ``"#rrggbbaa"`` if alpha != 1.0).
   
      :return: Hex string (``"#rrggbb"`` or ``"#rrggbbaa"``).
      :rtype: str

   .. method:: to_rgb(self)
   
      Convert to RGB, dropping the alpha channel.
   
      :rtype: :class:`ion.types.ColorRGB`

   .. method:: to_tuple(self)
   
      Convert to tuple ``(r, g, b, a)``.
   
      :return: Tuple ``(r, g, b, a)``.
      :rtype: tuple[float, float, float, float]

   .. attribute:: is_frozen

      Whether this value is frozen (read-only).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __copy__(self)

         :rtype: :class:`ColorRGBA`

      .. method:: __deepcopy__(self, memo)

         :param memo: Memoization dict for shared subobjects.
         :type memo: dict
         :rtype: :class:`ColorRGBA`

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __format__(self, format_spec)

         :param format_spec: Format spec applied per component (empty spec returns ``repr(self)``).
         :type format_spec: str
         :rtype: str

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str

      .. method:: __setitem__(self, key, value)

         Set self[key] to value.

         :param key: Index or key.
         :type key: int
         :param value: Value to assign.
         :type value: object



.. class:: ContextAccessor

   Accessor object exposed as ``ion.wm.context``.
   
   Exposes the elements the current keymap or menu action targets. Each
   attribute is a lookup of the current focus - so a keyboard binding and a
   menu opened on the focused frame see the same thing - unless the action's
   region overrode it for the click (e.g. the root menu's pointer output, or
   the divider's split). Attributes are ``None`` only when nothing of that
   kind is in use.


   .. method:: capture(self)
   
      Capture the current action context as an opaque snapshot, for
      replaying later. A region installs this context for the click (e.g.
      the divider's split), so capturing it pins a menu operator to the
      same elements it was drawn against, even after the menu has closed.
   
      :return: A snapshot of the active context, or ``None`` when none is
         set.
      :rtype: :class:`ion.types.ContextSnapshot` | None

   .. attribute:: button

      The pointer button that triggered this action, or ``None`` when the
      action was not invoked by a pointer event.
      
      Live only for the duration of a pointer-only operator's dispatch and
      cleared afterwards, so reading it outside a live pointer event yields
      ``None``. Codes match :mod:`ion.constants.pointer_buttons`.
      
      :type: int | None

   .. attribute:: desktop

      The active desktop for this context: the overriding desktop if a region
      set one, else the active desktop, or ``None``.
      
      :type: :class:`ion.types.Desktop` | None

   .. attribute:: frame

      The frame this context targets: the overriding frame if a region set
      one, else the focused frame, or ``None``.
      
      :type: :class:`ion.types.Frame` | None

   .. attribute:: output

      The output this context targets: the overriding output if a region set
      one (the pointer's output for a click), else the focused output, or
      ``None``. For the output of a specific frame or split, use that
      object's own accessors instead.
      
      :type: :class:`ion.types.Output` | None

   .. attribute:: split

      The split whose divider is under the pointer, or ``None`` when not over
      a divider. A divider is the boundary of a split, so this is the split.
      Override-only: a split has no focus to look up.
      
      :type: :class:`ion.types.SplitNodeContainer` | None

   .. attribute:: window

      The window this context targets: the overriding tab if a region set one
      (a clicked tab), else the focused window, or ``None``.
      
      :type: :class:`ion.types.Window` | None

   .. attribute:: workspace

      The workspace this context targets: the overriding workspace if a region
      set one, else the focused workspace, or ``None``.
      
      :type: :class:`ion.types.Workspace` | None



.. class:: ContextSnapshot

   Opaque snapshot of action-context values, replayed as the action context
   when a menu item is activated.
   
   Built by :meth:`ContextAccessor.capture` (the region's live context) and by
   :meth:`ContextSnapshot.build` (explicit values a layout stores for an
   operator). The stored values become the context the operator runs against.
   
   .. class:: ContextSnapshot
   
   .. staticmethod:: build(base=None, *, window=None, frame=None, split=None, output=None, workspace=None, desktop=None)
   
      Build a snapshot from explicit context values merged over an optional
      ``base`` snapshot: each value given replaces that attribute, and the
      rest fall back to ``base``. Returns ``None`` when the result is empty.
   
      This is how :class:`ion.types.UILayout` stores per-operator overrides
      (e.g. the divider a menu item should act on) without touching the live
      context.
   
      :param base: Snapshot whose values fill attributes left unset, or ``None``.
      :type base: :class:`ion.types.ContextSnapshot` | None
      :param window: The window the operator should target.
      :type window: :class:`ion.types.Window` | None
      :param frame: The frame the operator should target.
      :type frame: :class:`ion.types.Frame` | None
      :param split: The split whose divider the operator should target.
      :type split: :class:`ion.types.SplitNodeContainer` | None
      :param output: The output the operator should target.
      :type output: :class:`ion.types.Output` | None
      :param workspace: The workspace the operator should target.
      :type workspace: :class:`ion.types.Workspace` | None
      :param desktop: The desktop the operator should target.
      :type desktop: :class:`ion.types.Desktop` | None
      :return: The merged snapshot, or ``None`` when no value is set.
      :rtype: :class:`ion.types.ContextSnapshot` | None


   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: CursorPreferences

   Cursor appearance preferences.


   .. attribute:: size

      Cursor size in pixels (default: 24).
      
      :type: int

   .. attribute:: theme

      Cursor theme name (default: "default").
      
      :type: str

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: CursorToken

   Opaque cursor stack token.
   
   Returned by :func:`ion.wm.cursor_push`. Pass to
   :func:`ion.wm.cursor_pop` to pop this entry and any later ones.
   
   .. class:: CursorToken


   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Decor()

   Decoration configuration (geometry and visual properties).


   .. attribute:: geom

      Decoration geometry, values that impact the layout.
      
      :type: DecorGeom

   .. attribute:: look

      Visual decoration properties (colors, bevel settings).
      
      :type: DecorLook

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: DecorGeom()

   Decoration geometry (divider width, window pad, titlebar height).


   .. attribute:: divider_width

      Width of frame dividers in pixels.
      
      :type: int

   .. attribute:: tab_pad

      Padding of the border drawn around each tab, in pixels (0 disables it).
      
      Painted over the ``window_pad`` border rather than added to it, so a
      ``tab_pad`` of 3 with a ``window_pad`` of 5 shows 3px in the
      :data:`ion.app.decor.look.tab_pad` color and 2px in the
      :data:`ion.app.decor.look.window_pad` color. The color defaults to
      black, matching ``window_pad``; set a contrasting color to visualize
      tab padding (a dragged tab shows the full border, as it has no
      ``window_pad`` border behind it).
      
      :type: int

   .. attribute:: titlebar_height

      Height of window titlebars in pixels.
      
      :type: int

   .. attribute:: titlebar_icon_size

      Size of titlebar tab icons in logical pixels (square).
      
      :type: int

   .. attribute:: window_pad

      Padding of the border between a tiled window and an adjacent divider,
      in pixels (0 disables it).
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: DecorLook()

   Visual decoration properties (colors, bevel width).


   .. attribute:: bevel_highlight

      Default bevel highlight.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: bevel_shadow

      Default bevel shadow.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: bevel_width

      Bevel line width in pixels.
      
      :type: int

   .. attribute:: border

      Border color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: divider

      Divider fill color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: floating_border

      Floating border color (outline around floating window/workspace borders).
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: focused_active_bevel_highlight

      Bevel highlight for focused active tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: focused_active_bevel_shadow

      Bevel shadow for focused active tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: menu_bevel_highlight

      Menu bevel highlight color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: menu_bevel_shadow

      Menu bevel shadow color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: menu_bg

      Menu background color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: menu_text_color

      Menu text color (hovered items).
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: menu_text_color_inactive

      Menu text color for inactive (non-hovered) items.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: outline

      Outline color. Currently unused by the renderer (the tab-bar outline it
      drove was replaced by :data:`ion.app.decor.geom.tab_pad`); retained for
      configuration compatibility.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_focused_active

      Active tab in focused frame.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_focused_inactive

      Inactive tab in focused frame.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_pad

      Color of the tab padding border (drawn around each tab).
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_unfocused_active

      Active tab in unfocused frame.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_unfocused_inactive

      Inactive tab in unfocused frame.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_urgent

      Urgent tab (wants attention).
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_urgent_bevel_highlight

      Bevel highlight for urgent tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: tab_urgent_bevel_shadow

      Bevel shadow for urgent tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: text_disabled

      Text color for disabled items.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: text_focused_active

      Text color for focused active tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: text_inactive

      Text color for inactive tabs.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: text_urgent

      Text color for urgent tabs.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: unfocused_active_bevel_highlight

      Bevel highlight for unfocused active tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: unfocused_active_bevel_shadow

      Bevel shadow for unfocused active tab.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: window_pad

      Color of the window padding border (between a tiled window and an
      adjacent divider).
      
      :type: :class:`ion.types.ColorRGB`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Desktop

   A desktop groups floating windows and per-output workspace assignments (see :ref:`proxy-objects`).


   .. method:: focus(self)
   
      Switch to this desktop.
   
      :return: None.
      :rtype: None

   .. attribute:: data

      Per-desktop dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the desktop.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: id

      Unique numeric identifier for this desktop (read-only).
      
      Stable for the lifetime of the desktop regardless of ordering
      or other desktops being added or removed.
      Not reused after the desktop is removed.
      
      :type: int

   .. attribute:: is_empty

      Whether this desktop contains no windows (read-only).
      A desktop must be empty before it can be removed via
      :meth:`~ion.types.DesktopCollection.remove`.
      
      :type: bool

   .. attribute:: is_valid

      Whether this desktop still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: items_floating

      Floating layer entries on this desktop (read-only).
      
      :type: :class:`ion.types.DesktopFloatingCollection`

   .. attribute:: items_tiling

      Tiling layer entries on this desktop (read-only).
      
      :type: :class:`ion.types.DesktopTilingCollection`

   .. attribute:: name

      Desktop name.
      
      :type: str

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopCollection

   Collection accessor for desktops (:data:`ion.wm.desktops`).
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The desktop to check for membership.
      :type value: :class:`Desktop`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Desktop`]
   
   .. method:: __getitem__(self, key)
   
      Get a desktop by name or index.
   
      :param key: Desktop name, or zero-based index.
      :type key: str | int
      :rtype: :class:`Desktop`


   .. method:: find_adjacent(self, layout, desktop, direction, wrap=True)
   
      Find the adjacent desktop in a spatial layout.
   
      Returns the desktop in the neighboring grid cell, or ``None``.
      When *wrap* is true, wraps to the opposite end of the same
      row or column.
   
      :param layout: Layout from :meth:`layout_calc`.
      :type layout: list[tuple[tuple[int, int], Desktop]]
      :param desktop: The reference desktop.
      :type desktop: :class:`Desktop`
      :param direction: ``'LEFT'``, ``'RIGHT'``, ``'UP'``, or ``'DOWN'``.
      :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN']
      :param wrap: Wrap to the opposite end of the same row or column.
         Defaults to ``True``.
      :type wrap: bool
      :return: The adjacent desktop, or ``None``.
      :rtype: :class:`Desktop` | None

   .. method:: find_by_frame(self, frame)
   
      Find the desktop containing the given frame.
   
      :param frame: The frame to search for.
      :type frame: :class:`ion.types.Frame`
   
      :return: The desktop containing the frame, or ``None`` if not found.
      :rtype: :class:`ion.types.Desktop` | None

   .. method:: find_by_id(self, id)
   
      Look up a desktop by its unique numeric :attr:`~ion.types.Desktop.id`.
   
      :param id: The desktop ID to look up.
      :type id: int
      :return: The desktop, or None if no matching desktop exists.
      :rtype: :class:`~ion.types.Desktop` | None

   .. method:: find_by_item(self, item)
   
      Find the desktop containing the given floating or tiling item.
   
      :param item: A floating or tiling desktop item.
      :type item: :class:`ion.types.DesktopItemFloating` | :class:`ion.types.DesktopItemTiling`
   
      :return: The desktop containing the item, or ``None`` if not found.
      :rtype: :class:`ion.types.Desktop` | None

   .. method:: find_by_window(self, window)
   
      Find the desktop containing the given window.
   
      :param window: The window to search for.
      :type window: :class:`ion.types.Window`
   
      :return: The desktop containing the window, or ``None`` if not found.
      :rtype: :class:`ion.types.Desktop` | None

   .. method:: find_by_workspace(self, workspace)
   
      Find the desktop containing the given workspace.
   
      :param workspace: The workspace to search for.
      :type workspace: :class:`ion.types.Workspace`
   
      :return: The desktop containing the workspace, or ``None`` if not found.
      :rtype: :class:`ion.types.Desktop` | None

   .. method:: get(self, name)
   
      Get a desktop by name.
   
      :param name: The desktop name.
      :type name: str
   
      :return: The desktop, or ``None`` if not found.
      :rtype: :class:`ion.types.Desktop` | None

   .. method:: index(self, desktop)
   
      Return the index of a desktop in the collection.
   
      :param desktop: The desktop to find.
      :type desktop: :class:`ion.types.Desktop`
      :rtype: int
      :raises ValueError: If the desktop is not in the collection.

   .. method:: items(self)
   
      All (name, desktop) pairs.
   
      :return: List of (name, desktop) tuples.
      :rtype: list[tuple[str, :class:`ion.types.Desktop`]]

   .. method:: keys(self)
   
      All desktop names.
   
      :return: List of desktop name strings.
      :rtype: list[str]

   .. method:: layout_calc(self, desktops=None)
   
      Query desktop layout providers, falling back to a grid.
   
      Iterates :attr:`ion.types.Preferences.desktop_layout_providers` in order. The first
      provider that returns a non-``None`` result wins. If no provider
      returns a result, a grid layout is used. Providers that raise
      exceptions are logged and skipped.
   
      An empty list is a valid result (desktop operations become no-ops).
   
      :param desktops: Optional subset of desktops. When ``None``, all
         desktops are used.
      :type desktops: list[Desktop] | None
      :return: List of ``((x_index, y_index), desktop)`` pairs.
      :rtype: list[tuple[tuple[int, int], Desktop]]

   .. method:: new(self, name="")
   
      Create a new desktop with the given name.
   
      If a desktop with that name already exists, a unique name is generated
      by appending a number (e.g., "work.1", "work.2").
      When *name* is empty, a numbered name is generated automatically.
   
      :param name: Base name for the new desktop.
      :type name: str
   
      :return: The newly created desktop.
      :rtype: :class:`ion.types.Desktop`

   .. method:: remove(self, desktop)
   
      Remove a desktop (must be empty, cannot be the last).
   
      :param desktop: The desktop to remove.
      :type desktop: :class:`ion.types.Desktop`
   
      :raises RuntimeError: If the desktop is not empty or is the last desktop.
      :rtype: None

   .. method:: sort(self, key)
   
      Sort desktops by a key function, similar to ``list.sort(key=...)``.
   
      :param key: Callable taking a :class:`Desktop` and returning a comparable value.
      :type key: Callable[[Desktop], Any]
      :rtype: None

   .. attribute:: active

      Currently active desktop (read-only). Use :meth:`Desktop.focus` to
      queue a desktop to become active.
      
      :type: :class:`ion.types.Desktop`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopFloatingCollection

   Floating item collection for a desktop (see :ref:`proxy-objects`).
   
   Access via :attr:`Desktop.items_floating`.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __iter__(self)
   
      Iterate over all floating entries (bottom to top).
   
      :rtype: Iterator[:class:`DesktopItemFloating`]
   
   .. method:: __getitem__(self, index)
   
      Get a floating entry by depth index.
   
      :param index: Zero-based depth index (``0`` is the bottom).
      :type index: int
      :rtype: :class:`DesktopItemFloating`


   .. method:: add(self, workspace)
   
      Add a workspace as a floating overlay on this desktop.
   
      A workspace already floating on another desktop is moved here
      (the previous floating entry is removed - floating ownership is
      exclusive across desktops). A workspace tiled on any desktop is
      orphaned from tiling first; the ``workspace_unmap_tiling_post``
      hook fires before the floating overlay is shown, and
      :attr:`Workspace.floating_rect` is overwritten with the tile rect
      so the overlay appears at the same visible position. Orphan
      workspaces (created via :meth:`WorkspaceCollection.new` with a
      caller-supplied rect, or via :meth:`WorkspaceCollection.new_from_split_node`
      which seeds the rect from the extracted node) are placed using
      their existing :attr:`Workspace.floating_rect`.
   
      :param workspace: The workspace to add.
      :type workspace: :class:`~ion.types.Workspace`
      :return: The floating entry, or ``None`` if the workspace is
         already on this desktop's floating layer.
      :rtype: :class:`~ion.types.DesktopItemFloatingWorkspace` | None
      :raises ValueError: If the workspace's ``floating_rect`` is empty
         (zero or inverted).

   .. method:: depth_sort(self, key)
   
      Sort floating entries by a key function, similar to
      ``list.sort(key=...)``. Depth 0 gets the item with the
      smallest key value (back), highest depth gets the largest
      (front).
   
      :param key: Callable taking a :class:`DesktopItemFloating` and returning a comparable value.
      :type key: Callable[[DesktopItemFloating], Any]
      :rtype: None

   .. method:: depth_swap(self, a, b)
   
      Swap the depth positions of two floating entries.
   
      :param a: First entry (must belong to this desktop).
      :type a: :class:`DesktopItemFloating`
      :param b: Second entry (must belong to this desktop).
      :type b: :class:`DesktopItemFloating`
      :rtype: None

   .. method:: depth_to_back(self, items)
   
      Move the given entries to the back of the floating layer,
      preserving their relative order. Entries not in the sequence
      keep their original order at the front.
   
      :param items: Entries to lower (must be unique, must belong to this desktop).
      :type items: Sequence[:class:`DesktopItemFloating`]
      :rtype: None

   .. method:: depth_to_front(self, items)
   
      Move the given entries to the front of the floating layer,
      preserving their relative order. Entries not in the sequence
      keep their original order at the back.
   
      :param items: Entries to raise (must be unique, must belong to this desktop).
      :type items: Sequence[:class:`DesktopItemFloating`]
      :rtype: None

   .. method:: find_by_frame(self, frame)
   
      Find a floating entry by frame.
   
      :param frame: The frame to search for.
      :type frame: :class:`Frame`
      :return: The floating entry, or ``None`` if the frame is not in the floating layer.
      :rtype: :class:`DesktopItemFloatingFrame` | None

   .. method:: find_by_workspace(self, workspace)
   
      Find a floating entry by workspace.
   
      :param workspace: The workspace to search for.
      :type workspace: :class:`Workspace`
      :return: The floating entry, or ``None`` if the workspace is not in the floating layer.
      :rtype: :class:`DesktopItemFloatingWorkspace` | None

   .. method:: remove(self, item)
   
      Remove a floating workspace overlay from this desktop.
   
      :param item: The floating workspace entry to remove.
      :type item: :class:`DesktopItemFloatingWorkspace`
      :rtype: None
      :raises ValueError: If the workspace overlay is not on this desktop.

   .. attribute:: active

      The focused floating entry, or ``None`` when focus is on
      the tiling layer.
      
      :type: :class:`DesktopItemFloating` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopItemFloating

   A floating layer entry (see :ref:`proxy-objects`).
   
   Base class for :class:`DesktopItemFloatingFrame` and :class:`DesktopItemFloatingWorkspace`.


   .. method:: depth_to_back(self)
   
      Lower this floating item to the back of the z-order.
   
      :return: None.
      :rtype: None

   .. method:: depth_to_front(self)
   
      Raise this floating item to the front of the z-order.
   
      :return: None.
      :rtype: None

   .. method:: move_to_output(self, output, pointer_warp=True)
   
      Move this floating item to a different output, remapping its
      position proportionally.
   
      :param output: The target output.
      :type output: :class:`ion.types.Output`
      :param pointer_warp: Whether the pointer will be warped to follow
         the item. When false and focus-follows-pointer is enabled,
         focus updates to whatever is under the pointer.
      :type pointer_warp: bool
      :return: None.
      :rtype: None

   .. attribute:: depth

      Depth index (0 = back, higher = closer to front).
      
      :type: int

   .. attribute:: rect

      Bounding rectangle in logical pixels.
      
      :type: :class:`ion.types.Rect`

   .. attribute:: visible

      Whether this entry is visible.
      
      :type: bool

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopItemFloatingFrame(DesktopItemFloating)

   A floating frame entry (see :ref:`proxy-objects`).

   .. attribute:: frame

      The frame contained in this floating entry.
      
      :type: :class:`ion.types.Frame`



.. class:: DesktopItemFloatingWorkspace(DesktopItemFloating)

   A floating workspace overlay entry (see :ref:`proxy-objects`).

   .. attribute:: workspace

      The workspace contained in this floating entry.
      
      :type: :class:`ion.types.Workspace`



.. class:: DesktopItemTiling

   A tiling layer entry on a desktop (see :ref:`proxy-objects`).


   .. attribute:: output

      Output this tiling entry is assigned to, or ``None`` for unified
      (spanning all outputs).
      
      :type: :class:`ion.types.Output` | None

   .. attribute:: rect

      Bounding rectangle in logical pixels (read-only). For per-output entries
      this is the output's usable area; for unified entries it spans all outputs.
      
      :type: :class:`ion.types.Rect`

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopItemTilingFrame

   A tiling frame reference for use with :class:`OverlayDesktopItem`.

   .. method:: __init__(self, frame)

      :param frame: The tiled frame.
      :type frame: :class:`Frame`
      :rtype: None

   .. attribute:: frame

      The frame contained in this tiling entry.
      
      :type: :class:`ion.types.Frame`

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: DesktopItemTilingWorkspace(DesktopItemTiling)

   A tiling workspace entry (see :ref:`proxy-objects`).

   .. attribute:: workspace

      The workspace contained in this tiling entry.
      
      :type: :class:`ion.types.Workspace`



.. class:: DesktopTilingCollection

   Tiling item collection for a desktop (see :ref:`proxy-objects`).
   
   Access via :attr:`Desktop.items_tiling`.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __iter__(self)
   
      Iterate over all tiling entries.
   
      :rtype: Iterator[:class:`DesktopItemTiling`]
   
   .. method:: __getitem__(self, index)
   
      Get a tiling entry by index.
   
      :param index: Zero-based index of the tiling entry to retrieve.
      :type index: int
      :rtype: :class:`DesktopItemTiling`


   .. method:: add(self, workspace, output=None)
   
      Add a workspace to this desktop's tiling layer.
   
      A workspace currently shown as a floating overlay on any desktop
      is auto-removed from the floating layer first. Orphan workspaces
      (created via :meth:`WorkspaceCollection.new` or
      :meth:`WorkspaceCollection.new_from_split_node`) are also
      accepted.
   
      When *output* is ``None`` the workspace spans all outputs.
      When an :class:`~ion.types.Output` is given the workspace is
      confined to that output.
   
      :param workspace: The workspace to tile.
      :type workspace: :class:`Workspace`
      :param output: The target output, or ``None`` for all outputs.
      :type output: :class:`~ion.types.Output` | None
      :return: The tiling entry, or ``None`` if the workspace is
         already tiled on any desktop.
      :rtype: :class:`~ion.types.DesktopItemTilingWorkspace` | None

   .. method:: find_by_output(self, output)
   
      Find the tiling entry assigned to a specific output.
   
      For unified desktops this returns the first entry (since all
      workspaces span every output). For per-output desktops it returns
      the entry confined to that output.
   
      :param output: The output to look up.
      :type output: :class:`Output`
      :return: The tiling entry, or ``None`` if no workspace is assigned.
      :rtype: :class:`DesktopItemTiling` | None

   .. method:: find_by_workspace(self, workspace)
   
      Find a tiling entry by workspace.
   
      :param workspace: The workspace to search for.
      :type workspace: :class:`Workspace`
      :return: The tiling entry, or ``None`` if the workspace is not in the tiling layer.
      :rtype: :class:`DesktopItemTilingWorkspace` | None

   .. method:: remove(self, item)
   
      Remove a tiling entry from this desktop.
   
      The workspace's :attr:`Workspace.floating_rect` is left unchanged.
      To surface the workspace as a floating overlay afterwards, assign
      :attr:`DesktopItemTiling.rect` first:
   
      .. code-block:: python
   
         workspace.floating_rect = item.rect
         desktop.items_tiling.remove(item)
         desktop.items_floating.add(workspace)
   
      :param item: The tiling entry to remove.
      :type item: :class:`DesktopItemTiling`
      :rtype: None
      :raises ValueError: If the entry is not on this desktop.

   .. attribute:: active

      The focused tiling entry, or ``None`` when focus is on
      the floating layer.
      
      :type: :class:`DesktopItemTiling` | None

   .. attribute:: has_all_output

      Whether this desktop has any all-output (spanning) workspaces (read-only).
      
      :type: bool

   .. attribute:: has_per_output

      Whether this desktop has any per-output (confined) workspaces (read-only).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Direction

   Direction enum.


   .. attribute:: DOWN

      :type: str
      :value: 'DOWN'

   .. attribute:: LEFT

      :type: str
      :value: 'LEFT'

   .. attribute:: RIGHT

      :type: str
      :value: 'RIGHT'

   .. attribute:: UP

      :type: str
      :value: 'UP'



.. class:: Event

   Base type for input events.

   Every event carries the held modifier flags and cursor position
   at the time it was created.

   .. method:: __init__(self, *, modifiers, position)

      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :param position: Pointer position.
      :type position: :class:`Point`
      :rtype: None

   .. attribute:: modifiers

      Held modifier flags (bitmask of ``ion.constants.modifiers`` constants).
      
      :type: int

   .. attribute:: position

      Cursor position in logical coordinates.
      
      :type: :class:`~ion.types.Point`

   .. attribute:: time_stamp

      Monotonic timestamp in milliseconds.
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventCancel()

   Sent to a generator when it is cancelled (e.g. compositor shutdown).

   :rtype: :class:`~ion.types.EventCancel`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventCommand(Event)

   Sent to an operator when it is invoked by an IPC command or test harness.

   .. method:: __init__(self, *, modifiers=None, position=None)

      :param modifiers: Modifier bitmask, or ``None`` for current keyboard state.
      :type modifiers: int | None
      :param position: Pointer position, or ``None`` for current pointer location.
      :type position: :class:`Point` | None
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventKey(Event)

   Keyboard event.

   .. method:: __init__(self, key, press, *, modifiers, position)

      :param key: Key code (see :mod:`ion.constants.keys`).
      :type key: int
      :param press: ``True`` for press, ``False`` for release.
      :type press: bool
      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :param position: Pointer position.
      :type position: :class:`Point`
      :rtype: None

   .. attribute:: key

      The keysym code.
      
      :type: int

   .. attribute:: press

      ``True`` for key press, ``False`` for key release.
      
      :type: bool

   .. attribute:: text

      The printable character for this key, or empty string for non-printable keys.
      
      :type: str

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventMenu(Event)

   Sent to an operator when it is invoked from a menu.

   .. method:: __init__(self, *, modifiers, position)

      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :param position: Pointer position.
      :type position: :class:`Point`
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventMotion(Event)

   Pointer motion event sent to a generator.

   The cursor position is available via the inherited
   :attr:`~ion.types.Event.position` attribute.

   .. method:: __init__(self, position, *, modifiers)

      :param position: Pointer position.
      :type position: :class:`Point`
      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventPointer(Event)

   Pointer button event.

   .. method:: __init__(self, button, press, *, modifiers, position)

      :param button: Pointer button code (see :mod:`ion.constants.pointer_buttons`).
      :type button: int
      :param press: ``True`` for press, ``False`` for release.
      :type press: bool
      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :param position: Pointer position.
      :type position: :class:`Point`
      :rtype: None

   .. attribute:: button

      The mouse button code.
      
      :type: int

   .. attribute:: press

      ``True`` for button press, ``False`` for button release.
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventScroll(Event)

   Scroll (axis) event sent to a generator.

   .. method:: __init__(self, delta_x, delta_y, *, modifiers, position)

      :param delta_x: Horizontal scroll delta.
      :type delta_x: float
      :param delta_y: Vertical scroll delta.
      :type delta_y: float
      :param modifiers: Modifier bitmask (see :mod:`ion.constants.modifiers`).
      :type modifiers: int
      :param position: Pointer position.
      :type position: :class:`Point`
      :rtype: None

   .. attribute:: delta_x

      Horizontal scroll amount (positive = right).
      
      :type: float

   .. attribute:: delta_y

      Vertical scroll amount (positive = down).
      
      :type: float

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: EventTimer()

   Sent to a generator when its ``GeneratorStep(time=<ms>)`` delay elapses.

   :rtype: :class:`~ion.types.EventTimer`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: FloatingPreferences

   Floating window placement preferences.


   .. attribute:: auto_float_dialog

      Automatically float dialog windows (those with a parent) (default: True).
      
      :type: bool

   .. attribute:: auto_float_fixed_size

      Automatically float fixed-size windows where min and max size are equal (default: True).
      
      :type: bool

   .. attribute:: corner_resize_size

      Size of the corner grab zone in logical pixels (default: 12).
      
      Controls how far along each edge the corner resize zones extend.
      Larger values make corners easier to grab; smaller values give
      more room for straight-edge resizing.
      
      :type: int

   .. attribute:: size_min

      Minimum size for floating windows during interactive resize (default: 100).
      
      This is the smallest width or height (in logical pixels) that a
      floating window can be resized to. Changing this at run-time only
      affects future resize operations; existing windows are not resized.
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: FocusPreferences

   Window focus behavior preferences.


   .. attribute:: double_click_time

      Maximum interval in milliseconds between two clicks for
      double-click detection (default: 400).
      
      :type: int

   .. attribute:: drag_threshold

      Pointer motion threshold in logical pixels for drag detection (default: 3).
      
      :type: int

   .. attribute:: on_activation

      Window activation behavior (default: ``"SMART"``).
      
      :type: Literal["SMART", "FOCUS", "URGENT", "NONE"]

   .. attribute:: pointer_click_to_raise

      Clicking a floating window raises it to the top (default: True).
      
      :type: bool

   .. attribute:: pointer_follow

      Focus follows mouse pointer (default: False).
      
      :type: bool

   .. attribute:: pointer_warp

      Warp mouse to focused frame on directional focus change (default: True).
      
      :type: bool

   .. attribute:: pointer_warp_factor

      Position factor (x, y) within frame for pointer warp.
      Each value is 0.0-1.0 where (0.0, 0.0)=top-left, (0.5, 0.5)=center, (1.0, 1.0)=bottom-right.
      
      :type: tuple[float, float]

   .. attribute:: pointer_warp_margin

      Margin in pixels to inset from frame edges when warping (default: 5).
      
      :type: int

   .. attribute:: switch_to_new

      Focus newly created windows (default: True).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: FontParams

   Per-font rendering parameters (face pattern + vertical offset).


   .. attribute:: face

      Font pattern in fontconfig format (e.g. ``"monospace:size=10"``).
      
      :type: str

   .. attribute:: offset_y

      Vertical text offset as a fraction of the font's full height.
      
      Positive values shift text down, negative values up. The effective
      range is ``-1.0`` to ``1.0``; either extreme moves the text fully
      outside the visible area. Default: ``0.0``.
      
      :type: float

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: FontPreferences

   Font rendering preferences.


   .. attribute:: message_font

      Popup/message font (face pattern and vertical offset).
      
      :type: :class:`ion.types.FontParams`

   .. attribute:: titlebar_font

      Titlebar font (face pattern and vertical offset).
      
      :type: :class:`ion.types.FontParams`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Frame

   A tiling frame that holds one or more tabbed windows (see :ref:`proxy-objects`).


   .. method:: attach_tagged(self)
   
      Attach all tagged windows to this frame as tabs.
   
      :return: Whether any tagged windows were attached.
      :rtype: bool

   .. method:: focus(self)
   
      Focus this frame.
   
      :return: None.
      :rtype: None

   .. method:: pointer_warp(self)
   
      Warp the pointer to this frame unconditionally.
   
      :return: None.
      :rtype: None

   .. method:: pointer_warp_if_needed(self)
   
      Warp the pointer to this frame only if the pointer is not already inside it.
   
      :return: ``True`` if the pointer was warped, ``False`` otherwise.
      :rtype: bool

   .. method:: tab_move_cycle(self, direction)
   
      Move the current tab to the next/previous position in this frame.
   
      :param direction: Positive for next, negative for previous.
      :type direction: int
      :return: None.
      :rtype: None

   .. method:: tile(self)
   
      Tile this floating workspace frame back into the tiling workspace on the active output.
   
      :return: The target frame's split node, or ``None`` if tiling failed.
      :rtype: :class:`~ion.types.SplitNodeLeaf` | None

   .. method:: window_reorder(self, window, index)
   
      Move a window to a different position within this frame's tab bar.
   
      :param window: The window to reorder.
      :type window: :class:`Window`
      :param index: New tab position.
      :type index: int
      :rtype: None

   .. attribute:: active_index

      Index of the active tab (0-based) (read-only).
      
      :type: int

   .. attribute:: content_rect

      Frame content rectangle, excluding the tab bar and border, or ``None``
      if the frame is not currently placed (read-only).
      
      Derived from frame geometry, so it is defined even for an empty frame
      with no window. For a floating frame this equals the frame rect, since
      its tab bar and border are drawn outside the frame rect.
      
      :type: :class:`ion.types.Rect` | None

   .. attribute:: data

      Per-frame dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the frame.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: id

      Unique numeric identifier for this frame (read-only).
      
      Stable for the lifetime of the frame regardless of
      workspace, output, or desktop changes.
      Not reused after the frame is removed.
      
      :type: int

   .. attribute:: is_floating

      Whether this frame is floating (read-only).
      
      :type: bool

   .. attribute:: is_focused

      Whether this frame is focused (read-only).
      
      :type: bool

   .. attribute:: is_valid

      Whether this frame still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: split_node

      Split tree leaf node for this frame, or ``None`` if not in a workspace (read-only).
      
      :type: :class:`ion.types.SplitNodeLeaf` | None

   .. attribute:: windows

      All windows in this frame (read-only).
      
      :type: :class:`ion.types.FrameWindowCollection`

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: FrameCollection

   Collection accessor for frames.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The frame to check for membership.
      :type value: :class:`Frame`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Frame`]
   
   .. method:: __getitem__(self, index)
   
      Get a frame by index. Supports negative indices.
   
      :param index: Zero-based index of the frame.
      :type index: int
      :rtype: :class:`Frame`
   
   .. method:: __getitem__(self, index)
      :noindex:
   
      :param index: A slice over the frames.
      :type index: slice
      :rtype: tuple[:class:`Frame`, ...]


   .. method:: find_by_id(self, id)
   
      Look up a frame by its unique numeric :attr:`~ion.types.Frame.id`.
   
      :param id: The frame ID to look up.
      :type id: int
      :return: The frame, or None if no frame with that ID exists.
      :rtype: :class:`~ion.types.Frame` | None

   .. method:: find_by_window(self, window)
   
      Find the frame containing the given window.
   
      :param window: The window to search for.
      :type window: :class:`ion.types.Window`
   
      :return: The frame, or ``None`` if the window is floating or not found.
      :rtype: :class:`ion.types.Frame` | None

   .. method:: find_isect_all_point(self, point)
   
      Find all frames containing the given point.
   
      :param point: The position to look up.
      :type point: :class:`ion.types.Point`
   
      :return: Frames containing the point, most interior first.
      :rtype: list[:class:`ion.types.Frame`]

   .. method:: find_isect_all_rect(self, rect)
   
      Find all frames intersecting the given rectangle.
   
      :param rect: The area to check.
      :type rect: :class:`ion.types.Rect`
   
      :return: Frames intersecting the rectangle, ordered by intersection area (largest first).
      :rtype: list[:class:`ion.types.Frame`]

   .. method:: index(self, frame)
   
      Return the index of a frame in the collection.
   
      :param frame: The frame to find.
      :type frame: :class:`ion.types.Frame`
      :rtype: int
      :raises ValueError: If the frame is not in the collection.

   .. attribute:: active

      Currently focused frame (read-only).
      
      :type: :class:`ion.types.Frame` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: FrameWindowCollection

   Collection accessor for windows within a specific frame.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The window to check for membership.
      :type value: :class:`Window`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Window`]
   
   .. method:: __getitem__(self, index)
   
      Get a window by index.
   
      :param index: Zero-based index of the window to retrieve.
      :type index: int
      :rtype: :class:`Window`


   .. method:: find_by_id(self, id)
   
      Look up a window by its unique numeric :attr:`~ion.types.Window.id`,
      only if it belongs to this frame.
   
      :param id: The window ID to look up.
      :type id: int
      :return: The window, or None if no matching window exists in this frame.
      :rtype: :class:`~ion.types.Window` | None

   .. method:: index(self, window)
   
      Return the index of a window in this frame.
   
      :param window: The window to find.
      :type window: :class:`ion.types.Window`
      :rtype: int
      :raises ValueError: If the window is not in this frame.

   .. method:: sort(self, key)
   
      Sort windows by a key function, similar to ``list.sort(key=...)``.
   
      :param key: Callable taking a :class:`Window` and returning a comparable value.
      :type key: Callable[[Window], Any]
      :rtype: None

   .. attribute:: active

      Active window (visible tab) in this frame.
      
      :type: :class:`ion.types.Window` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: GeneratorStep

   Yield value for generators scheduled with :func:`ion.utils.exec_generator`.

   Controls when the generator is next triggered and whether it
   receives input events.

   .. method:: __init__(self, *, time=0, consume_event=False)

      :param time: Delay in milliseconds before re-triggering with an
         :class:`EventTimer`. ``0`` schedules no timer.
      :type time: int
      :param consume_event: When ``True``, the next input event is
         delivered to this generator.
      :type consume_event: bool
      :rtype: None

   .. code-block:: python

      def _overview():
          yield GeneratorStep(time=500)                        # Animate.
          while True:
              event = yield GeneratorStep(consume_event=True)  # Wait for input.
              if isinstance(event, EventPointer) and event.press:
                  break
          yield GeneratorStep(time=500)                        # Animate.

   .. attribute:: consume_event

      When ``True``, input events are delivered to this generator.
      
      :type: bool

   .. attribute:: time

      Time in milliseconds before the generator is triggered again.
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Hook

   .. method:: append(self, callback)
   
      Append a callback to the end of this hook's callback list.
   
      The callback is returned so this method can be used as a decorator::
   
          @ion.app.hooks.window_new_post.append
          def on_window_new(window):
              ...
   
      :param callback: A callable to register.
      :type callback: ``T``
   
      :return: The callback (for use as a decorator).
      :rtype: ``T``

   .. method:: clear(self)
   
      Remove all callbacks from this hook.
   
      :rtype: None

   .. method:: insert(self, index, callback)
   
      Insert a callback at the given position in the callback list.
   
      Follows :meth:`list.insert` semantics: negative indices count from
      the end, and out-of-range indices are clamped to the bounds of the
      list (no :exc:`IndexError` is raised).
   
      :param index: Position at which to insert.
      :type index: int
      :param callback: A callable to register.
      :type callback: ``T``
      :rtype: None

   .. method:: pop(self, index=-1)
   
      Remove and return the callback at the given position. Defaults to
      the last callback, matching :meth:`list.pop` semantics. Negative
      indices count from the end.
   
      :param index: Position of the callback to remove.
      :type index: int
      :return: The removed callback.
      :rtype: ``T``
      :raises IndexError: If the hook is empty or the index is out of range.

   .. method:: remove(self, callback)
   
      Remove the first occurrence of a callback from this hook.
      Callbacks are compared by identity (``is``), matching the way
      they were registered.
   
      :param callback: The callback to unregister.
      :type callback: ``T``
      :rtype: None
      :raises ValueError: If the callback is not registered.

   .. details:: Special Methods

      .. classmethod:: __class_getitem__(cls, item)

         Subscript support so ``Hook[Callable[[Window], None]]`` evaluates at
         runtime (as required by ``typing.get_type_hints`` and the stubs that
         declare ``Hook(Generic[T])``).

         :param item: Type parameter; ignored at runtime.
         :type item: Any
         :rtype: Any

      .. method:: __contains__(self, item)

         Return bool(key in self).

         :param item: Item to test for membership.
         :type item: object
         :rtype: bool

      .. method:: __iter__(self)

         Implement iter(self).

         :rtype: Iterator[T]

      .. method:: __len__(self)

         :rtype: int

      .. method:: __repr__(self)

         :rtype: str



.. class:: HooksRegistry

   Namespace exposing all hooks as attributes, e.g. ``ion.app.hooks.window_new_post``.
   
   The set of hooks is fixed at compile time. Users attach callbacks to a
   :class:`ion.types.Hook` via :meth:`ion.types.Hook.append`; they do not
   add or remove hooks themselves.


   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str

   .. attribute:: compositor_reload_post

      Fired after the config script has been re-executed.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: compositor_reload_pre

      Fired before the config script is re-executed.
      All keybindings, menus, and hook callbacks are cleared before reload.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: compositor_session_pause_post

      Fired after the session has been paused.
      
      This occurs on TTY switch away or system suspend.
      Rendering and input have already been suspended.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: compositor_session_pause_pre

      Fired before the session is paused.
      
      This occurs on TTY switch away or system suspend.
      Rendering and input are suspended after this hook returns.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: compositor_shutdown_pre

      Fired before the compositor begins shutting down.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: compositor_startup_post

      Fired once after the compositor finishes startup.
      All outputs are configured and the config has been loaded.
      
      Use this hook to create initial desktops, workspaces, and
      any other setup that requires live compositor state.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: desktop_new_post

      Fired after a new desktop is created.
      
      Callbacks receive a :class:`~ion.types.Desktop` argument.
      
      :type: Hook[Callable[[Desktop], None]]

   .. attribute:: desktop_remove_post

      Fired after a desktop is removed.
      
      Callbacks receive a :class:`~ion.types.Desktop` argument.
      
      :type: Hook[Callable[[Desktop], None]]

   .. attribute:: desktop_remove_pre

      Fired before a desktop is removed.
      The desktop is still accessible and its workspaces have not yet been relocated.
      
      Callbacks receive a :class:`~ion.types.Desktop` argument.
      
      :type: Hook[Callable[[Desktop], None]]

   .. attribute:: desktop_rename_post

      Fired after a desktop is renamed.
      
      Callbacks receive a :class:`~ion.types.Desktop` argument.
      
      :type: Hook[Callable[[Desktop], None]]

   .. attribute:: desktop_rename_pre

      Fired before a desktop is renamed.
      
      Callbacks receive a :class:`~ion.types.Desktop` argument.
      
      :type: Hook[Callable[[Desktop], None]]

   .. attribute:: desktop_switch_post

      Fired after the active desktop switches.
      Callbacks receive the old and new :class:`~ion.types.Desktop` as arguments.
      
      :type: Hook[Callable[[Desktop, Desktop], None]]

   .. attribute:: desktop_switch_pre

      Fired before the active desktop switches.
      Callbacks receive the old and new :class:`~ion.types.Desktop` as arguments.
      
      :type: Hook[Callable[[Desktop, Desktop], None]]

   .. attribute:: idle_lock

      Fired when the idle timeout triggers a screen lock.
      This hook is responsible for spawning the lock command
      (e.g. ``utils.exec(('swaylock',))``).
      Without a registered callback, no locking occurs.
      
      Callbacks receive no arguments.
      
      :type: Hook[Callable[[], None]]

   .. attribute:: keyboard_add_post

      Fired after a keyboard device is connected.
      
      Also fires for devices already present at startup. Callbacks
      registered in the init script are in place before the initial
      device discovery runs.
      
      Callbacks receive a :class:`~ion.types.KeyboardDevice` argument.
      
      :type: Hook[Callable[[KeyboardDevice], None]]

   .. attribute:: keyboard_remove_pre

      Fired before a keyboard device is disconnected (not on exit).
      The device is still accessible.
      
      Callbacks receive a :class:`~ion.types.KeyboardDevice` argument.
      
      :type: Hook[Callable[[KeyboardDevice], None]]

   .. attribute:: output_add_post

      Fired after a newly connected output is configured and added to the layout.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: output_add_pre

      Fired before a newly connected output is configured.
      
      Use this hook to set output resolution, position, and scale
      before the output becomes active.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: output_remove_post

      Fired after an output is disconnected and removed from the layout.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: output_remove_pre

      Fired before an output is disconnected.
      The output is still part of the layout.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: output_resize_post

      Fired after an output's resolution or mode changes.
      The layout has been updated to reflect the new size.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: output_resize_pre

      Fired before an output's resolution or mode changes.
      
      Callbacks receive an :class:`~ion.types.Output` argument.
      
      :type: Hook[Callable[[Output], None]]

   .. attribute:: pointer_add_post

      Fired after a pointer device is connected.
      
      Also fires for devices already present at startup. Callbacks
      registered in the init script are in place before the initial
      device discovery runs.
      
      Callbacks receive a :class:`~ion.types.PointerDevice` argument.
      
      :type: Hook[Callable[[PointerDevice], None]]

   .. attribute:: pointer_remove_pre

      Fired before a pointer device is disconnected (not on exit).
      The device is still accessible.
      
      Callbacks receive a :class:`~ion.types.PointerDevice` argument.
      
      :type: Hook[Callable[[PointerDevice], None]]

   .. attribute:: tablet_add_post

      Fired after a tablet device is connected.
      
      Also fires for devices already present at startup. Callbacks
      registered in the init script are in place before the initial
      device discovery runs.
      
      Callbacks receive a :class:`~ion.types.TabletDevice` argument.
      
      :type: Hook[Callable[[TabletDevice], None]]

   .. attribute:: tablet_remove_pre

      Fired before a tablet device is disconnected (not on exit).
      The device is still accessible.
      
      Callbacks receive a :class:`~ion.types.TabletDevice` argument.
      
      :type: Hook[Callable[[TabletDevice], None]]

   .. attribute:: window_app_id_change_post

      Fired after a window's app_id property is updated.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_app_id_change_pre

      Fired before a window's app_id property is updated.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_close_post

      Fired after a window is closed.
      The window has been removed from the layout.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_close_pre

      Fired before a window is closed.
      The window is still accessible and part of the layout.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_floating_post

      Fired after a window transitions between tiled and floating.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_floating_pre

      Fired before a window transitions between tiled and floating.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_focus_post

      Fired after a window gains keyboard focus.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_focus_pre

      Fired before a window gains keyboard focus.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_fullscreen_post

      Fired after a window's fullscreen state is toggled.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_fullscreen_pre

      Fired before a window's fullscreen state is toggled.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_move_post

      Fired after a window is moved to a different frame.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_move_pre

      Fired before a window is moved to a different frame.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_new_post

      Fired after a new window is mapped.
      The window is visible and has been assigned to a frame.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_new_pre

      Fired before a new window is mapped.
      The window exists but is not yet visible or assigned to a frame.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_title_change_post

      Fired after a window's title property is updated.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_title_change_pre

      Fired before a window's title property is updated.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_urgent_post

      Fired after a window's urgent hint changes.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: window_urgent_pre

      Fired before a window's urgent hint changes.
      Urgency is typically set by the client to request user attention.
      
      Callbacks receive a :class:`~ion.types.Window` argument.
      
      :type: Hook[Callable[[Window], None]]

   .. attribute:: workspace_delete_post

      Fired after a workspace is deleted and removed from the layout.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_delete_pre

      Fired before a workspace is deleted.
      The workspace is still accessible and its windows have not yet been relocated.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_map_floating_post

      Fired after a workspace is mapped as a floating overlay on an output.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_map_tiling_post

      Fired after a workspace is assigned to an output as the active tiled workspace.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_new_post

      Fired after a new workspace is created.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_rename_post

      Fired after a workspace is renamed.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_rename_pre

      Fired before a workspace is renamed.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_unmap_floating_post

      Fired after a floating workspace overlay is unmapped from its output.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]

   .. attribute:: workspace_unmap_tiling_post

      Fired after a tiled workspace is deactivated on its output.
      
      Callbacks receive a :class:`~ion.types.Workspace` argument.
      
      :type: Hook[Callable[[Workspace], None]]



.. class:: IdlePreferences

   Idle timeout and screensaver preferences.


   .. attribute:: dpms_timeout

      Seconds before DPMS off (default: 600).
      
      :type: int

   .. attribute:: timeout

      Seconds before idle (default: 300).
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: InputPreferences

   Input device preferences container.


   .. attribute:: keyboard_defaults

      Default settings for new keyboards (:class:`ion.types.KeyboardPreferences`) (read-only).
      
      :type: :class:`ion.types.KeyboardPreferences`

   .. attribute:: pointer_defaults

      Default settings for new mice/pointers (:class:`ion.types.PointerPreferences`) (read-only).
      
      :type: :class:`ion.types.PointerPreferences`

   .. attribute:: tablet_defaults

      Default settings for new tablets (:class:`ion.types.TabletPreferences`) (read-only).
      
      :type: :class:`ion.types.TabletPreferences`

   .. attribute:: touchpad_defaults

      Default settings for new touchpads (:class:`ion.types.TouchpadPreferences`) (read-only).
      
      :type: :class:`ion.types.TouchpadPreferences`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeyboardCollection

   Collection of keyboard devices accessible as ``ion.app.keyboards``.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, item)
   
      Check if a device exists in the collection.
   
      :param item: The device to check for membership.
      :type item: :class:`KeyboardDevice`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all keyboard devices.
   
      :rtype: Iterator[:class:`KeyboardDevice`]
   
   .. method:: __getitem__(self, key)
   
      Get a keyboard device by index or name.
   
      :param key: Device name, or zero-based index.
      :type key: str | int
      :rtype: :class:`KeyboardDevice`


   .. attribute:: active

      The keyboard that most recently produced input (read-only).
      
      :type: :class:`ion.types.KeyboardDevice` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeyboardDevice

   A single physical or virtual keyboard device.
   
   Setting layout properties on the active keyboard immediately applies the change
   to the seat. Setting them on a non-active keyboard stores the preference, which
   is applied when that device next becomes active.


   .. attribute:: layout

      Active XKB layout (e.g. ``"us"``, ``"de"``).
      
      .. note::
      
         Setting this property is deferred until the current callback returns.
      
      :type: str

   .. attribute:: layout_options

      Active XKB options (e.g. ``"ctrl:nocaps"``).
      
      .. note::
      
         Setting this property is deferred until the current callback returns.
      
      :type: str

   .. attribute:: layout_variant

      Active XKB variant (e.g. ``"dvorak"``).
      
      .. note::
      
         Setting this property is deferred until the current callback returns.
      
      :type: str

   .. attribute:: name

      Human-readable device name (read-only).
      
      :type: str

   .. attribute:: usb_id

      USB vendor and product IDs as a ``(vendor, product)`` tuple,
      or ``None`` for non-USB devices (read-only).
      
      :type: tuple[int, int] | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeyboardPreferences

   Keyboard input device preferences.


   .. attribute:: layout

      XKB layout (default: "us").
      
      :type: str

   .. attribute:: options

      XKB options (default: "").
      
      :type: str

   .. attribute:: repeat_delay

      Key repeat delay in ms (default: 400).
      
      :type: int

   .. attribute:: repeat_rate

      Key repeat rate per second (default: 25).
      
      :type: int

   .. attribute:: variant

      XKB variant (default: "").
      
      :type: str

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Keymap

   A keymap that can have keys bound to actions.


   .. attribute:: items

      All bindings in this keymap.
      
      :type: :class:`KeymapItemsCollection`

   .. attribute:: name

      The keymap name.
      
      :type: str

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeymapHandler

   Stateful event matcher for generators. Accepts events via :meth:`process_event`
   and matches them against keymaps or single patterns using the same
   trigger-lookup logic as the compositor's input handler.

   Supports Press, Release, Click, Drag, and DoubleClick event actions.
   Click is resolved on release when the pointer has not moved beyond the
   drag threshold. Drag is resolved on motion when the threshold is
   exceeded. DoubleClick fires when two clicks occur within the
   double-click time and distance.

   .. method:: __init__(self, event)

      Initialize from an :class:`Event` to capture the initial modifier
      state and cursor position.

      :param event: The initial event (typically the first event received
         by the generator).
      :type event: :class:`Event`
      :rtype: None

   .. method:: match_keymaps(self, keymaps)
   
      Search a list of keymaps for a binding that matches the last
      digested event. Returns the first match found.
   
      :param keymaps: Keymaps to search, checked in order.
      :type keymaps: list[:class:`Keymap`]
      :return: ``(KeymapItem, properties_dict)`` on match, or ``None``.
      :rtype: tuple[:class:`KeymapItem`, dict] | None

   .. method:: match_single(self, pattern)
   
      Check whether the last processed event matches a single
      :class:`MatchKey` or :class:`MatchPointer` pattern.
   
      :param pattern: The pattern to match against.
      :type pattern: :class:`MatchKey` | :class:`MatchPointer`
      :return: ``True`` if the event matches.
      :rtype: bool

   .. method:: process_event(self, event)
   
      Process an input event, updating internal state.
   
      After calling this, use :meth:`match_single` or :meth:`match_keymaps`
      to check whether the event matches a binding.
   
      :param event: The event to process.
      :type event: :class:`Event`
      :rtype: None



.. class:: KeymapItem

   A single binding in a keymap, returned by :attr:`Keymap.items`.


   .. attribute:: event

      The input event matcher.
      
      :type: :class:`MatchKey` | :class:`MatchPointer`

   .. attribute:: operator

      The operator instance (NamedTuple).
      
      :type: NamedTuple

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeymapItemsCollection

   Collection of keymap items with iteration and removal.
   
   .. method:: __iter__(self)
   
      Iterate over all bindings.
   
      :rtype: Iterator[:class:`KeymapItem`]
   
   .. method:: __len__(self)
   
      Number of bindings.
   
      :rtype: int
   
   .. method:: __contains__(self, item)
   
      Check if a binding exists in the keymap.
   
      :param item: The binding to check for membership.
      :type item: :class:`KeymapItem`
      :rtype: bool


   .. method:: new(self, event, operator, *, doc=None)
   
      Add a key or pointer binding to this keymap.
   
      :param event: A :class:`MatchKey` or :class:`MatchPointer` specifying the input event.
      :type event: :class:`ion.types.MatchKey` | :class:`ion.types.MatchPointer`
      :param operator: NamedTuple instance (from ``ion.ops.*(...)``).
      :type operator: NamedTuple
      :param doc: Optional description.
      :type doc: str | None
   
      :return: The newly created binding.
      :rtype: :class:`KeymapItem`

   .. method:: remove(self, item)
   
      Remove a binding from the keymap.
   
      :param item: The item to remove.
      :type item: :class:`KeymapItem`
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: KeymapsRegistry

   Registry for keymaps, accessed as ``ion.app.keymaps["global"]``, ``ion.app.keymaps["window"]``, etc.
   
   Keymaps are checked in registration order (first registered = highest priority).
   Standard keymaps:
   
   - ``"global"``: Always active, lowest priority.
   - ``"window"``: Active when any window has keyboard focus.
   - ``"tiling"``: Active when focus is on a tiled frame.
   - ``"floating"``: Active when focus is on a floating frame.
   - ``"fullscreen"``: Active when a fullscreen window has focus.
   - ``"tab"``: Active when the pointer is over a tab.
   - ``"title"``: Active when the pointer is over a frame title bar.
   - ``"root"``: Active when the pointer is over the empty background.
   - ``"divider"``: Active when hovering a split divider.
   - ``"decoration"``: Active when the pointer is over a window decoration.
   
   The registry follows the dict protocol: iteration yields keymap names,
   ``"name" in keymaps`` tests membership, ``keymaps["name"]`` returns the
   :class:`Keymap`, and ``keys()`` / ``values()`` / ``items()`` expose the
   three views.
   
   .. method:: __getitem__(self, key)
   
      Get a keymap by name.
   
      :param key: Keymap name.
      :type key: str
      :rtype: :class:`Keymap`
   
   .. method:: __len__(self)
   
      Number of keymaps.
   
      :rtype: int
   
   .. method:: __iter__(self)
   
      Iterate over keymap names (dict-like).
   
      :rtype: Iterator[str]
   
   .. method:: __contains__(self, key)
   
      Test whether a keymap with this name is registered.
   
      :param key: Keymap name.
      :type key: str
      :rtype: bool


   .. method:: clear(self)
   
      Remove all user-defined keymaps. Built-in keymaps are retained.
   
      :rtype: None

   .. method:: get(self, key, default=None)
   
      Get a keymap by name, returning ``default`` if no keymap with this
      name is registered. Unlike ``__getitem__``, this does not create a
      keymap on demand.
   
      :param key: Keymap name.
      :type key: str
      :param default: Value returned when the keymap is missing.
      :type default: Any
      :rtype: :class:`ion.types.Keymap` | Any

   .. method:: items(self)
   
      All (name, keymap) pairs.
   
      :return: List of (name, keymap) tuples.
      :rtype: list[tuple[str, :class:`ion.types.Keymap`]]

   .. method:: keys(self)
   
      All keymap names.
   
      :return: List of keymap name strings.
      :rtype: list[str]

   .. method:: prompt(self, name)
   
      Activate a keymap for the next key press (leader key).
   
      :param name: Name of the keymap to activate.
      :type name: str
      :rtype: None

   .. method:: remove(self, keymap)
   
      Remove a keymap.
   
      :param keymap: The keymap to remove.
      :type keymap: :class:`ion.types.Keymap`
      :rtype: None

   .. method:: values(self)
   
      All keymaps.
   
      :return: List of keymaps.
      :rtype: list[:class:`ion.types.Keymap`]

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: MatchKey

   A key event matcher for use with :meth:`KeymapItemsCollection.new`.

   .. method:: __init__(self, key, *, action=0, ctrl=False, alt=False, logo=False, hyper=False, shift=False, passthrough=False, consume=True)

      :param key: The key (from :mod:`ion.constants.keys`).
      :type key: int
      :param action: Event action (from :mod:`ion.constants.event_actions`).
      :type action: int
      :param ctrl: Require Ctrl modifier (None = ignored).
      :type ctrl: bool | None
      :param alt: Require Alt modifier (None = ignored).
      :type alt: bool | None
      :param logo: Require Logo modifier (None = ignored).
      :type logo: bool | None
      :param hyper: Require Hyper modifier (None = ignored).
      :type hyper: bool | None
      :param shift: Require Shift modifier (None = ignored).
      :type shift: bool | None
      :param passthrough: When True, forward the event to the focused
         client after the binding's operator runs. When False (the default),
         the compositor intercepts the event and does not forward it.
      :type passthrough: bool
      :param consume: Controls whether a binding suppresses later event
         types on the same key. Default is True.

         - **Press**: a consumed Press prevents Click, Drag, and DoubleClick
           evaluation on the same key. When False, deferred bindings can still
           fire on release after the Press operator has executed.
           To suppress a key press from reaching the client while still allowing
           Click or Drag, bind Press to a no-op with
           ``consume=False, passthrough=False``.
         - **Click**: a consumed Click prevents DoubleClick evaluation.
           When False, the click is recorded for future double-click detection.
         - **Release**: a consumed Release prevents Click and DoubleClick
           evaluation on the same key. When False, Click and DoubleClick can
           still fire after the Release operator has executed.
      :type consume: bool
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: MatchPointer

   A pointer event matcher for use with :meth:`KeymapItemsCollection.new`.

   .. method:: __init__(self, button, *, ctrl=False, alt=False, logo=False, hyper=False, shift=False, action=2, passthrough=False, consume=True)

      :param button: Pointer button code (see :mod:`ion.constants.pointer_buttons`).
      :type button: int
      :param ctrl: Require Ctrl modifier (None = ignored).
      :type ctrl: bool | None
      :param alt: Require Alt modifier (None = ignored).
      :type alt: bool | None
      :param logo: Require Logo modifier (None = ignored).
      :type logo: bool | None
      :param hyper: Require Hyper modifier (None = ignored).
      :type hyper: bool | None
      :param shift: Require Shift modifier (None = ignored).
      :type shift: bool | None
      :param action: Event action (from :mod:`ion.constants.event_actions`).
      :type action: int
      :param passthrough: When True, forward the event to the focused
         client after the binding's operator runs. When False (the default),
         the compositor intercepts the event and does not forward it.
      :type passthrough: bool
      :param consume: Controls whether a binding suppresses later event
         types on the same button. Default is True.

         - **Press**: a consumed Press prevents Click, Drag, and DoubleClick
           evaluation on the same button. When False, deferred bindings can
           still fire on release after the Press operator has executed.
           To suppress a button press from reaching the client while still
           allowing Click or Drag, bind Press to a no-op with
           ``consume=False, passthrough=False``.
         - **Click**: a consumed Click prevents DoubleClick evaluation.
           When False, the click is recorded for future double-click detection.
         - **Release**: a consumed Release prevents Click and DoubleClick
           evaluation on the same button. When False, Click and DoubleClick can
           still fire after the Release operator has executed.
      :type consume: bool
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Menu

   A reference to a registered menu in the registry.


   .. data:: idname

      The menu identifier.
      
      :type: str

      (readonly)

   .. data:: name

      The display name.
      
      :type: str | None

      (readonly)

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __repr__(self)

         :rtype: str



.. class:: MenuBuilder

   Builder passed to menu callbacks.
   
   The callback receives a fresh builder each time the menu is shown. GUI
   elements are added through its :class:`ion.types.UILayout`, accessed as
   ``menu.layout`` (see :class:`ion.types.UILayout` for the element methods).


   .. data:: layout

      The layout that collects this menu's GUI elements.
      
      :type: UILayout

      (readonly)



.. class:: MenuRegistry

   Registry of named menus with builder callbacks: ``ion.app.menus.new('tab', 'Tab', callback)``.
   
   Callbacks receive a :class:`ion.types.MenuBuilder` and are called each time the menu
   is shown, enabling dynamic items.
   
   .. code-block:: python
   
      import ion
      import ion.ops as ops
   
      def my_menu(menu):
          menu.layout.operator(ops.window_close())
          menu.layout.separator()
          menu.layout.operator(ops.frame_delete())
   
      ion.app.menus.new("context", "Context Menu", my_menu)
   
   The registry follows the dict protocol: iteration yields menu idnames,
   ``"name" in menus`` tests membership, ``menus["name"]`` returns the
   :class:`ion.types.Menu`, and ``keys()`` / ``values()`` / ``items()``
   expose the three views.
   
   .. method:: __len__(self)
   
      Number of menus.
   
      :rtype: int
   
   .. method:: __iter__(self)
   
      Iterate over menu idnames (dict-like).
   
      :rtype: Iterator[str]
   
   .. method:: __contains__(self, idname)
   
      Test whether a menu with this idname is registered.
   
      :param idname: The menu identifier.
      :type idname: str
      :rtype: bool
   
   .. method:: __getitem__(self, idname)
   
      Get a menu by idname.
   
      :param idname: The menu identifier.
      :type idname: str
      :rtype: :class:`ion.types.Menu`
      :raises KeyError: If no menu with this idname is registered.


   .. method:: clear(self) -> 'None'

      Remove all menus.
      
      :rtype: None

   .. method:: get(self, idname: 'str', default: 'object' = None) -> 'Menu | object'

      Get a menu by identifier, returning ``default`` if not found.
      
      :param idname: The menu identifier.
      :type idname: str
      :param default: Value returned when the menu is missing.
      :type default: object
      
      :return: The menu, or ``default`` if not found.
      :rtype: :class:`ion.types.Menu` | object

   .. method:: items(self) -> 'list[tuple[str, Menu]]'

      All (idname, menu) pairs.
      
      :return: List of (idname, menu) tuples.
      :rtype: list[tuple[str, :class:`ion.types.Menu`]]

   .. method:: keys(self) -> 'list[str]'

      All menu identifiers.
      
      :return: List of menu identifier strings.
      :rtype: list[str]

   .. method:: new(self, idname: 'str', name: 'str', callback: 'Callable[[MenuBuilder], None]', poll: 'Callable[..., str | None] | None' = None) -> 'None'

      Register a named menu with a builder callback.
      
      .. code-block:: python
      
         ion.app.menus.new("tab", "Tab", lambda menu: (
             menu.layout.operator(ion.ops.window_close()),
             menu.layout.operator(ion.ops.frame_delete()),
         ))
      
      :param idname: Unique identifier used to reference this menu.
      :type idname: str
      :param name: Human-readable display name (used as submenu label).
      :type name: str
      :param callback: Receives a :class:`ion.types.MenuBuilder`, called each time the menu is shown.
      :type callback: ``Callable[[MenuBuilder], None]``
      :param poll: Optional callable returning ``None`` if the menu is available,
          or a string reason if it should be hidden.
      :type poll: ``Callable[..., str | None]`` | None
      :rtype: None

   .. method:: remove(self, menu: 'Menu') -> 'None'

      Remove a menu.
      
      :param menu: The menu to remove.
      :type menu: :class:`ion.types.Menu`
      :rtype: None

   .. method:: show(self, idname: 'str') -> 'None'

      Show a named context menu.
      
      Must be called during a keybinding callback.
      
      .. code-block:: python
      
         ion.app.menus.show("context")
      
      :param idname: The menu identifier to show.
      :type idname: str
      :rtype: None

   .. method:: values(self) -> 'list[Menu]'

      All menus.
      
      :return: List of menus.
      :rtype: list[:class:`ion.types.Menu`]

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Output

   A physical display or monitor connected to the compositor (see :ref:`proxy-objects`).


   .. method:: configure(self, *, position=None, transform=None)
   
      Configure this output's position and/or transform.
   
      .. note::
   
         This action is deferred until the current callback returns.
   
      :param position: Tuple ``(x, y)`` for the output position in logical coordinates.
      :type position: tuple[int, int] | None
      :param transform: Rotation in degrees (0, 90, 180, or 270).
      :type transform: int | None
   
      :return: None.
      :rtype: None

   .. method:: dpms_set(self, on)
   
      Set the DPMS power state for this output.
   
      :param on: True to power on, False to power off.
      :type on: bool
   
      :return: None.
      :rtype: None

   .. method:: focus(self)
   
      Focus this output.
   
      :return: None.
      :rtype: None

   .. method:: pointer_warp(self)
   
      Warp the pointer to this output unconditionally.
   
      :return: None.
      :rtype: None

   .. method:: pointer_warp_if_needed(self)
   
      Warp the pointer to this output only if it's not already inside it.
   
      :return: ``True`` if the pointer was warped, ``False`` otherwise.
      :rtype: bool

   .. attribute:: data

      Per-output dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the output.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: dpms

      Whether this output's display is powered on (read-only).
      
      :type: bool

   .. attribute:: fullscreen_window

      The fullscreen window on this output, or None if no window is fullscreen here.
      
      :type: :class:`~ion.types.Window` | None

   .. attribute:: id

      Unique numeric identifier for this output (read-only).
      
      Stable for the lifetime of the output regardless of
      desktop or workspace changes.
      Not reused after the output is disconnected.
      
      :type: int

   .. attribute:: is_enabled

      Whether this output is enabled (DPMS on) (read-only).
      
      True if the display is on, False if it's in a power-saving state.
      
      :type: bool

   .. attribute:: is_focused

      Whether this output is focused (read-only).
      
      :type: bool

   .. attribute:: is_valid

      Whether this output still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: name

      Output name (read-only).
      
      :type: str

   .. attribute:: rect

      Output rectangle (read-only).
      
      :type: :class:`ion.types.Rect`

   .. attribute:: scale

      Output scale factor (read-only).
      
      :type: float

   .. attribute:: transform

      Current transform (rotation) in degrees (0, 90, 180, or 270) (read-only).
      
      :type: int

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: OutputCollection

   Collection accessor for outputs.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The output to check for membership.
      :type value: :class:`Output`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Output`]
   
   .. method:: __getitem__(self, key)
   
      Get an output by name or index.
   
      :param key: Output name, or zero-based index.
      :type key: str | int
      :rtype: :class:`Output`


   .. method:: bounds_calc(self)
   
      Compute the bounding rectangle of all enabled outputs.
   
      :return: The combined bounding rectangle, or ``None`` when there are no enabled outputs.
      :rtype: :class:`~ion.types.Rect` | None

   .. method:: find_by_frame(self, frame)
   
      Find the output containing a frame (by geometry).
   
      :param frame: The frame to locate.
      :type frame: :class:`ion.types.Frame`
   
      :return: The output containing the frame, or ``None`` if not found.
      :rtype: :class:`ion.types.Output` | None

   .. method:: find_by_id(self, id)
   
      Look up an output by its unique numeric :attr:`~ion.types.Output.id`.
   
      :param id: The output ID to look up.
      :type id: int
      :return: The output, or None if no output with that ID exists.
      :rtype: :class:`~ion.types.Output` | None

   .. method:: find_by_window(self, window)
   
      Find the output displaying the given window.
   
      :param window: The window to locate.
      :type window: :class:`ion.types.Window`
   
      :return: The output displaying the window, or ``None`` if the window
         is floating or not found.
      :rtype: :class:`ion.types.Output` | None

   .. method:: find_isect_all_point(self, point)
   
      Find all outputs containing the given point.
   
      :param point: The position to look up.
      :type point: :class:`ion.types.Point`
   
      :return: Outputs containing the point, most interior first.
      :rtype: list[:class:`ion.types.Output`]

   .. method:: find_isect_all_rect(self, rect)
   
      Find all outputs intersecting the given rectangle.
   
      :param rect: The area to check.
      :type rect: :class:`ion.types.Rect`
   
      :return: Outputs intersecting the rectangle, ordered by intersection area (largest first).
      :rtype: list[:class:`ion.types.Output`]

   .. method:: get(self, name)
   
      Get an output by its name (e.g., "DP-1", "HDMI-A-1").
   
      :param name: The output name.
      :type name: str
   
      :return: The output, or ``None`` if not found.
      :rtype: :class:`ion.types.Output` | None

   .. method:: index(self, output)
   
      Return the index of an output in the collection.
   
      :param output: The output to find.
      :type output: :class:`ion.types.Output`
      :rtype: int
      :raises ValueError: If the output is not in the collection.

   .. method:: items(self)
   
      All (name, output) pairs.
   
      :return: List of (name, output) tuples.
      :rtype: list[tuple[str, :class:`ion.types.Output`]]

   .. method:: keys(self)
   
      All output names.
   
      :return: List of output name strings.
      :rtype: list[str]

   .. attribute:: active

      Currently focused output (read-only).
      
      :type: :class:`ion.types.Output` | None

   .. attribute:: active_pointer

      Output the pointer is on (read-only).
      
      :type: :class:`ion.types.Output` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Overlay

   Base class for overlay proxies (see :ref:`proxy-objects`).
   
   Subclasses: :class:`OverlayRect`, :class:`OverlayWindow`, :class:`OverlayDesktop`,
   :class:`OverlayDesktopItem`, :class:`OverlayWindowIcon`, :class:`OverlayTextDynamic`, :class:`OverlayText`,
   :class:`OverlayExclusive`, :class:`OverlayGroup`.
   
   Overlay objects can be constructed independently and later added to the
   compositor via :meth:`OverlayCollection.append` (or :meth:`OverlayCollection.insert`).
   Properties are always readable. Setters update the compositor in real time
   when the overlay is live (has been added and not yet removed).


   .. attribute:: data

      Per-overlay dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the overlay.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: parent

      Parent group overlay, or ``None`` if this overlay has no parent.
      
      :type: :class:`OverlayGroup` | None

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayCollection

   Collection accessor for a group's overlays (e.g. ``ion.wm.overlay_root.overlays``).
   
   Overlays are drawn front-to-back in list order: the first overlay is
   in front and the last is behind. :meth:`append` adds the overlay to
   the end (behind existing overlays); use :meth:`insert` to place it at
   a specific z-position, or :meth:`sort` to reorder.
   
   .. method:: __len__(self)
   
      Get the number of overlays.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if an overlay is in the collection.
   
      :param value: The overlay to check for membership.
      :type value: :class:`Overlay`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all overlays in draw order (front to back).
   
      :rtype: Iterator[:class:`Overlay`]
   
   .. method:: __getitem__(self, index)
   
      Get an overlay by index. Supports negative indices. Index 0 is the
      front-most overlay.
   
      :param index: Zero-based index of the overlay.
      :type index: int
      :rtype: :class:`Overlay`
   
   .. method:: __getitem__(self, index)
      :noindex:
   
      :param index: A slice over the overlays in draw order.
      :type index: slice
      :rtype: tuple[:class:`Overlay`, ...]


   .. method:: append(self, overlay)
   
      Append an overlay to this group, behind all existing overlays.
      The overlay must be a detached :class:`Overlay` subclass
      (constructed but not yet added, or previously removed/popped).
   
      :param overlay: The overlay to append.
      :type overlay: :class:`Overlay`
      :rtype: None

   .. method:: clear(self)
   
      Remove all overlays.
   
      :rtype: None

   .. method:: index(self, overlay)
   
      Return the index of an overlay in the collection.
   
      :param overlay: The overlay to find.
      :type overlay: :class:`Overlay`
      :rtype: int
      :raises ValueError: If the overlay is not in the collection.

   .. method:: insert(self, index, overlay)
   
      Insert an overlay at the given index. Index 0 places the overlay
      in front; an index at or past the end appends. Negative indices
      follow :class:`list` semantics. The overlay must be a detached
      :class:`Overlay` subclass.
   
      :param index: Target z-position.
      :type index: int
      :param overlay: The overlay to insert.
      :type overlay: :class:`Overlay`
      :rtype: None

   .. method:: pop(self, index=-1)
   
      Remove and return the overlay at ``index`` (defaults to the last,
      back-most overlay). The returned overlay is detached with its
      last-known data preserved, equivalent to a freshly constructed
      but not-yet-added overlay, and can be re-added to this or another
      :class:`OverlayCollection`.
   
      For :class:`OverlayGroup` overlays the descendants are destroyed,
      matching :meth:`remove`; the returned group carries only its own
      attributes.
   
      :param index: Position to pop. Supports negative indices.
      :type index: int
      :rtype: :class:`Overlay`
      :raises IndexError: If the collection is empty or the index is out of range.

   .. method:: remove(self, overlay)
   
      Remove an overlay from the compositor. The Python object is left
      in a detached state with its last-known data preserved, so it
      can be re-added later via :meth:`append` or :meth:`insert`.
      Descendants of a removed :class:`OverlayGroup` are destroyed.
   
      :param overlay: The overlay to remove.
      :type overlay: :class:`Overlay`
      :rtype: None

   .. method:: reverse(self)
   
      Reverse the z-order of the overlays in place.
   
      :rtype: None

   .. method:: sort(self, key)
   
      Sort overlays by a key function, similar to ``list.sort(key=...)``.
      Lower key values are drawn in front of higher values.
   
      :param key: Callable taking an :class:`Overlay` and returning a comparable value.
      :type key: Callable[[Overlay], Any]
      :rtype: None

   .. method:: swap(self, a, b)
   
      Swap the z-order of two overlays.
   
      :param a: The first overlay.
      :type a: :class:`Overlay`
      :param b: The second overlay.
      :type b: :class:`Overlay`
      :rtype: None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayDesktop(Overlay)

   A desktop-content overlay (display-only, no input).

   .. method:: __init__(self, desktop)

      :param desktop: The desktop to display.
      :type desktop: :class:`Desktop`
      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: desktop

      The source desktop being displayed.
      
      :type: :class:`ion.types.Desktop`

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayDesktopItem(Overlay)

   A desktop-item overlay that displays a single floating or tiled item
   with its borders and decorations (display-only, no input).

   .. method:: __init__(self, item)

      :param item: The desktop item to display.
      :type item: :class:`DesktopItemFloatingFrame` | :class:`DesktopItemFloatingWorkspace` | :class:`DesktopItemTilingFrame` | :class:`DesktopItemTilingWorkspace`
      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: item

      The source desktop item being displayed.
      
      :type: :class:`DesktopItemFloatingFrame` | :class:`DesktopItemFloatingWorkspace` | :class:`DesktopItemTilingFrame` | :class:`DesktopItemTilingWorkspace`

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayExclusive(Overlay)

   An exclusive overlay that fills the entire display with a solid color,
   suppressing all normal scene rendering (windows, layer surfaces,
   decorations, menus, popups). Only overlays above this one in the
   z-order are drawn; all overlays behind it are skipped.

   This should almost always be the last overlay added so that all
   other overlays render in front of it.

   .. method:: __init__(self)

      :rtype: None

   .. attribute:: color

      Fill color of the exclusive overlay.
      
      :type: :class:`ion.types.ColorRGBA`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayGroup(Overlay)

   A grouping overlay that applies a position and scale transform to its
   children. When alpha is 1.0, children render individually (fast path).
   When alpha is less than 1.0 and ``use_alpha_merged`` is true (default),
   children are composited to an offscreen texture first, then the
   texture is drawn with the group's alpha, treating the group as a
   single visual unit. When ``use_alpha_merged`` is false, the alpha is
   applied to each child element individually (no FBO overhead, but
   overlapping children show through each other).

   .. method:: __init__(self)

      :rtype: None

   .. attribute:: alpha

      Opacity (0.0 = fully transparent, 1.0 = fully opaque).
      
      When less than 1.0 and ``use_alpha_merged`` is true, children are
      composited to an offscreen texture first, then the texture is drawn
      with this alpha.
      
      :type: float

   .. attribute:: overlays

      The collection of overlays in this group.
      
      :type: :class:`OverlayCollection`

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. attribute:: use_alpha_merged

      Whether children are composited to an offscreen texture before
      alpha is applied. When true (default), overlapping children blend
      correctly as a single unit. When false, alpha is applied per-element
      (faster, but overlapping children show through each other).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayRect(Overlay)

   A colored rectangle overlay.

   .. method:: __init__(self)

      :rtype: None

   .. attribute:: fill_color

      Fill color of the overlay.
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: outline_color

      Outline color of the overlay.
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: outline_width

      Outline width in logical pixels. Positive values grow outward from
      the rect edges, negative values grow inward.
      
      :type: int

   .. attribute:: rect

      Position and size of the overlay in global logical coordinates.
      
      :type: :class:`ion.types.Rect`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTab(Overlay)

   A tab overlay that renders a single styled tab (for drag ghost).

   .. method:: __init__(self, window, frame)

      :param window: The window whose tab is being displayed.
      :type window: :class:`Window`
      :param frame: The source frame (for styling: active, tagged, urgent state).
      :type frame: :class:`Frame`
      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: position

      Position in global logical coordinates.
      
      :type: :class:`ion.types.Point`

   .. attribute:: scale

      Display scale (1.0 = native size).
      
      :type: float

   .. attribute:: tab_size

      Tab size in logical pixels.
      
      :type: :class:`~ion.types.Size`



.. class:: OverlayText(Overlay)

   An arbitrary-text overlay.

   .. method:: __init__(self)

      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: background_color

      Background color behind the text (RGBA, 0.0-1.0).
      Not drawn when alpha is zero (the default).
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: color

      Text color (RGBA, 0.0-1.0).
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: font_size

      Font rasterization size in points (0 = use global font size).
      
      :type: int

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. attribute:: text

      The text string being displayed.
      
      :type: str

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTextDynamic(Overlay)

   Base class for dynamic-text overlays. Not constructed directly.
   Use a subclass: :class:`OverlayTextDynamicWindowTitle`,
   :class:`OverlayTextDynamicWindowAppId`,
   :class:`OverlayTextDynamicWorkspaceName`,
   :class:`OverlayTextDynamicOutputName`,
   :class:`OverlayTextDynamicDesktopName`.

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: background_color

      Background color behind the text (RGBA, 0.0-1.0).
      Not drawn when alpha is zero (the default).
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: color

      Text color (RGBA, 0.0-1.0).
      
      :type: :class:`ion.types.ColorRGBA`

   .. attribute:: position

      Position in global logical coordinates.
      
      :type: :class:`ion.types.Point`

   .. attribute:: scale

      Display scale (1.0 = native size).
      
      :type: float



.. class:: OverlayTextDynamicDesktopName(OverlayTextDynamic)

   .. method:: __init__(self, source)

      :param source: The source entity.
      :type source: :class:`Desktop`
      :rtype: None

   .. attribute:: source

      The source entity.
      
      :type: :class:`ion.types.Desktop`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTextDynamicOutputName(OverlayTextDynamic)

   .. method:: __init__(self, source)

      :param source: The source entity.
      :type source: :class:`Output`
      :rtype: None

   .. attribute:: source

      The source entity.
      
      :type: :class:`ion.types.Output`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTextDynamicWindowAppId(OverlayTextDynamic)

   .. method:: __init__(self, source)

      :param source: The source entity.
      :type source: :class:`Window`
      :rtype: None

   .. attribute:: source

      The source entity.
      
      :type: :class:`ion.types.Window`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTextDynamicWindowTitle(OverlayTextDynamic)

   .. method:: __init__(self, source)

      :param source: The source entity.
      :type source: :class:`Window`
      :rtype: None

   .. attribute:: source

      The source entity.
      
      :type: :class:`ion.types.Window`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayTextDynamicWorkspaceName(OverlayTextDynamic)

   .. method:: __init__(self, source)

      :param source: The source entity.
      :type source: :class:`Workspace`
      :rtype: None

   .. attribute:: source

      The source entity.
      
      :type: :class:`ion.types.Workspace`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayWindow(Overlay)

   A window-content overlay (display-only, no input, no frame decorations).

   .. method:: __init__(self, window)

      :param window: The window to display.
      :type window: :class:`Window`
      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. attribute:: window

      The window being displayed.
      
      :type: :class:`ion.types.Window`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: OverlayWindowIcon(Overlay)

   A window-icon overlay.

   .. method:: __init__(self, window)

      :param window: The window whose icon to display.
      :type window: :class:`Window`
      :rtype: None

   .. attribute:: align

      Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.
      
      :type: tuple[int, int]

   .. attribute:: position

      Undocumented.

   .. attribute:: scale

      Undocumented.

   .. attribute:: size

      Icon rasterization size in logical pixels (icons are square).
      
      :type: int

   .. attribute:: window

      The window whose icon is displayed.
      
      :type: :class:`ion.types.Window`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Point

   2D point with x and y coordinates.

   .. method:: __init__(self, point)

      :param point: Point as [x, y].
      :type point: tuple[int, int]
      :rtype: None

   .. method:: __getitem__(self, index)

      Get component by index (0=x, 1=y).

      :param index: ``0`` for x, ``1`` for y.
      :type index: int
      :rtype: int

   .. method:: __getitem__(self, index)
      :noindex:

      :param index: A slice over the two components.
      :type index: slice
      :rtype: tuple[int, ...]

   .. method:: __len__(self)

      Return the number of components (always 2).

      :rtype: int

   .. method:: __iter__(self)

      Iterate over components (x, y).

      :rtype: Iterator[int]

   .. method:: copy(self)
   
      Return a mutable (unfrozen) copy.
   
      :rtype: :class:`Point`

   .. method:: freeze(self)
   
      Freeze this value, making it read-only and hashable.
      Returns self for convenience (e.g. ``d[p.freeze()] = v``).
   
      :rtype: Self

   .. method:: lerp(self, other, t)
   
      Linear interpolation from ``self`` to *other*.
   
      :param other: Target point.
      :type other: :class:`Point`
      :param t: Interpolation factor (0.0 = self, 1.0 = other).
      :type t: float
      :rtype: :class:`Point`

   .. method:: to_tuple(self)
   
      Convert to tuple ``(x, y)``.
   
      :return: Tuple ``(x, y)``.
      :rtype: tuple[int, int]

   .. attribute:: is_frozen

      Whether this value is frozen (read-only).
      
      :type: bool

   .. attribute:: x

      X coordinate.
      
      :type: int

   .. attribute:: y

      Y coordinate.
      
      :type: int

   .. details:: Special Methods

      .. method:: __abs__(self)

         abs(self)

         :rtype: :class:`Point`

      .. method:: __add__(self, other)

         Return self+value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __copy__(self)

         :rtype: :class:`Point`

      .. method:: __deepcopy__(self, memo)

         :param memo: Memoization dict for shared subobjects.
         :type memo: dict
         :rtype: :class:`Point`

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __floordiv__(self, other)

         Return self//value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __format__(self, format_spec)

         :param format_spec: Format spec applied per component (empty spec returns ``repr(self)``).
         :type format_spec: str
         :rtype: str

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __iadd__(self, other)

         Return self+=value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __isub__(self, other)

         Return self-=value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __mul__(self, other)

         Return self*value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __neg__(self)

         -self

         :rtype: :class:`Point`

      .. method:: __pos__(self)

         +self

         :rtype: :class:`Point`

      .. method:: __radd__(self, other)

         Return value+self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __repr__(self)

         :rtype: str

      .. method:: __rfloordiv__(self, other)

         Return value//self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __rmul__(self, other)

         Return value*self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __rsub__(self, other)

         Return value-self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`

      .. method:: __setitem__(self, key, value)

         Set self[key] to value.

         :param key: Index or key.
         :type key: int
         :param value: Value to assign.
         :type value: object

      .. method:: __sub__(self, other)

         Return self-value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Point`



.. class:: PointerCollection

   Collection of pointer devices accessible as ``ion.app.input.pointers``.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, item)
   
      Check if a device exists in the collection.
   
      :param item: The device to check for membership.
      :type item: :class:`PointerDevice`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all pointer devices.
   
      :rtype: Iterator[:class:`PointerDevice`]
   
   .. method:: __getitem__(self, key)
   
      Get a pointer device by index or name.
   
      :param key: Device name, or zero-based index.
      :type key: str | int
      :rtype: :class:`PointerDevice`


   .. attribute:: active

      The pointer that most recently produced input (read-only).
      
      :type: :class:`ion.types.PointerDevice` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: PointerDevice

   A single physical or virtual pointer device.


   .. attribute:: accel_profile

      Acceleration profile.
      
      :type: Literal["ADAPTIVE", "FLAT"]

   .. attribute:: accel_speed

      Acceleration speed (-1.0 to 1.0).
      
      :type: float

   .. attribute:: click_method

      Click method (touchpad only).
      
      :type: Literal["CLICKFINGER", "BUTTON_AREAS"]

   .. attribute:: disable_while_typing

      Disable while typing (touchpad only).
      
      :type: bool

   .. attribute:: drag_lock

      Drag lock (touchpad only).
      
      :type: bool

   .. attribute:: is_enabled

      Whether this device is enabled.
      
      :type: bool

   .. attribute:: is_touchpad

      Whether this device is a touchpad (read-only).
      
      :type: bool

   .. attribute:: left_handed

      Swap left/right buttons.
      
      :type: bool

   .. attribute:: name

      Human-readable device name (read-only).
      
      :type: str

   .. attribute:: natural_scroll

      Invert scroll direction.
      
      :type: bool

   .. attribute:: scroll_method

      Scroll method (touchpad only).
      
      :type: Literal["TWO_FINGER", "EDGE", "BUTTON"]

   .. attribute:: tap_and_drag

      Tap and drag (touchpad only).
      
      :type: bool

   .. attribute:: tap_to_click

      Tap to click (touchpad only).
      
      :type: bool

   .. attribute:: usb_id

      USB vendor and product IDs as a ``(vendor, product)`` tuple,
      or ``None`` for non-USB devices (read-only).
      
      :type: tuple[int, int] | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: PointerPreferences

   Mouse/pointer device preferences.


   .. attribute:: accel_profile

      Acceleration profile (default: ``"ADAPTIVE"``).
      
      :type: Literal["ADAPTIVE", "FLAT"]

   .. attribute:: accel_speed

      Acceleration speed -1.0 to 1.0 (default: 0.0).
      
      :type: float

   .. attribute:: is_enabled

      Enable pointer (default: True).
      
      :type: bool

   .. attribute:: left_handed

      Swap left/right buttons (default: False).
      
      :type: bool

   .. attribute:: natural_scroll

      Invert scroll direction (default: False).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Preferences

   Main preferences object accessed via :data:`ion.app.preferences`.


   .. attribute:: animate

      Animation settings (:class:`ion.types.AnimatePreferences`) (read-only).
      
      :type: :class:`ion.types.AnimatePreferences`

   .. attribute:: background_desktop

      Desktop background color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: background_empty_frame

      Empty frame content area color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: background_fullscreen_frame

      Fullscreen frame container color.
      
      :type: :class:`ion.types.ColorRGB`

   .. attribute:: cursor

      Cursor appearance settings (:class:`ion.types.CursorPreferences`) (read-only).
      
      :type: :class:`ion.types.CursorPreferences`

   .. attribute:: decorations

      Window decoration mode (default: ``"SERVER"``).
      
      :type: Literal["SERVER", "CLIENT", "NONE"]

   .. attribute:: desktop_layout_providers

      List of callables that provide spatial desktop arrangements.
      
      Each provider is called with a list of desktops and returns
      ``list[tuple[tuple[int, int], Desktop]]`` - a list of
      ``((x_index, y_index), desktop)`` pairs where indices are
      non-negative integers identifying grid cells.
      
      Provider return values:
      
      - A list of ``((x_index, y_index), desktop)`` pairs to define the layout.
      - ``None`` to defer to the next provider.
      - An empty list to indicate no layout (operations become no-ops).
      
      Data validity:
      
      - Desktops omitted from the result are excluded from navigation.
        This may be intentional for empty desktops.
      - Desktops included multiple times raise an exception
        and the result is ignored.
      - Desktops occupying the same grid cell raise an exception
        and the result is ignored.
      
      Exceptions raised by a provider are caught, logged, and the
      provider is skipped.
      
      When no provider returns a result, a grid layout is used as
      fallback. Providers are queried by
      :meth:`~ion.types.DesktopCollection.layout_calc`.
      
      .. code-block:: python
      
         def my_layout(desktops):
             # Arrange desktops in a single row.
             return [((i, 0), d) for i, d in enumerate(desktops)]
      
         ion.app.preferences.desktop_layout_providers.append(my_layout)
      
      :type: list[Callable[[list[:class:`Desktop`]], list[tuple[tuple[int, int], :class:`Desktop`]] | None]]
      :rtype: list[Callable[[list[:class:`Desktop`]], list[tuple[tuple[int, int], :class:`Desktop`]] | None]]

   .. attribute:: floating

      Floating window placement settings (:class:`ion.types.FloatingPreferences`) (read-only).
      
      :type: :class:`ion.types.FloatingPreferences`

   .. attribute:: focus

      Window focus behavior settings (:class:`ion.types.FocusPreferences`) (read-only).
      
      :type: :class:`ion.types.FocusPreferences`

   .. attribute:: fonts

      Font rendering settings (:class:`ion.types.FontPreferences`) (read-only).
      
      :type: :class:`ion.types.FontPreferences`

   .. attribute:: idle

      Idle timeout and screensaver settings (:class:`ion.types.IdlePreferences`) (read-only).
      
      :type: :class:`ion.types.IdlePreferences`

   .. attribute:: input

      Input device settings (:class:`ion.types.InputPreferences`) (read-only).
      
      :type: :class:`ion.types.InputPreferences`

   .. attribute:: notify_on_error

      If true, show desktop notification on Python errors (default: False).
      
      :type: bool

   .. attribute:: startup

      Startup-only settings (:class:`ion.types.StartupPreferences`) (read-only).
      
      :type: :class:`ion.types.StartupPreferences`

   .. attribute:: tiling

      Tiling behaviour settings (:class:`ion.types.TilingPreferences`) (read-only).
      
      :type: :class:`ion.types.TilingPreferences`

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Rect

   Rectangle defined by minimum and maximum corners.

   .. method:: __init__(self, min, max)

      :param min: Top-left corner as [x, y].
      :type min: tuple[int, int] | Point
      :param max: Bottom-right corner as [x, y].
      :type max: tuple[int, int] | Point
      :rtype: None

   .. method:: __getitem__(self, index)

      Get corner by index (0=min, 1=max).

      :param index: ``0`` for the min corner, ``1`` for the max corner.
      :type index: int
      :rtype: :class:`Point`

   .. method:: __getitem__(self, index)
      :noindex:

      :param index: A slice over the two corners.
      :type index: slice
      :rtype: tuple[:class:`Point`, ...]

   .. method:: __len__(self)

      Number of corners (always 2).

      :rtype: int

   .. method:: __iter__(self)

      Iterate over corners (min, max).

      :rtype: Iterator[:class:`Point`]


   .. method:: area(self)
   
      Area of this rectangle.
   
      :rtype: int

   .. method:: center_ceil(self)
   
      Center point rounded toward positive infinity.
   
      :return: Center point.
      :rtype: :class:`ion.types.Point`

   .. method:: center_floor(self)
   
      Center point rounded toward negative infinity.
   
      :return: Center point.
      :rtype: :class:`ion.types.Point`

   .. method:: contains(self, other)
   
      Check if this rectangle contains a point or another rectangle.
      For rectangles, touching edges are considered inside, i.e. the
      union of the two would not expand this rectangle.
   
      :param other: A Point or Rect to test for containment.
      :type other: :class:`ion.types.Point` | :class:`ion.types.Rect`
   
      :return: True if this rectangle contains the point or rectangle.
      :rtype: bool

   .. method:: copy(self)
   
      Return a mutable (unfrozen) copy.
   
      :rtype: :class:`Rect`

   .. method:: freeze(self)
   
      Freeze this value, making it read-only and hashable.
      Returns self for convenience (e.g. ``d[p.freeze()] = v``).
   
      :rtype: Self

   .. method:: intersection(self, other)
   
      Return the overlapping region of two rectangles, or ``None`` if they
      do not intersect.
   
      :param other: Another rectangle.
      :type other: :class:`ion.types.Rect`
      :rtype: :class:`ion.types.Rect` | None

   .. method:: intersects(self, other)
   
      Check if this rectangle intersects with another rectangle.
   
      :param other: Another rectangle to test for intersection.
      :type other: :class:`ion.types.Rect`
   
      :return: True if this rectangle intersects with another rectangle.
      :rtype: bool

   .. method:: lerp(self, other, t)
   
      Linearly interpolate between two rectangles.
   
      :param other: Target rectangle.
      :type other: :class:`Rect`
      :param t: Interpolation factor (0.0 = self, 1.0 = other).
      :type t: float
      :rtype: :class:`Rect`

   .. method:: point_remap_ceil(self, point, dst)
   
      Map *point* from ``self`` to the corresponding position in *dst*,
      rounding toward positive infinity. The result is clamped inside *dst*.
   
      :param point: Point to map.
      :type point: :class:`Point`
      :param dst: Destination region.
      :type dst: :class:`Rect`
      :rtype: :class:`Point`

   .. method:: point_remap_floor(self, point, dst)
   
      Map *point* from ``self`` to the corresponding position in *dst*,
      rounding toward negative infinity. The result is clamped inside *dst*.
   
      :param point: Point to map.
      :type point: :class:`Point`
      :param dst: Destination region.
      :type dst: :class:`Rect`
      :rtype: :class:`Point`

   .. method:: rect_remap_ceil(self, rect, dst)
   
      Map *rect* from ``self`` to the corresponding rectangle in *dst*,
      rounding toward positive infinity.
      Both position and size are scaled proportionally.
   
      :param rect: Rectangle to map.
      :type rect: :class:`Rect`
      :param dst: Destination region.
      :type dst: :class:`Rect`
      :rtype: :class:`Rect`

   .. method:: rect_remap_floor(self, rect, dst)
   
      Map *rect* from ``self`` to the corresponding rectangle in *dst*,
      rounding toward negative infinity.
      Both position and size are scaled proportionally.
   
      :param rect: Rectangle to map.
      :type rect: :class:`Rect`
      :param dst: Destination region.
      :type dst: :class:`Rect`
      :rtype: :class:`Rect`

   .. method:: to_tuple(self)
   
      Convert to tuple ``(min, max)``.
   
      :return: Tuple ``(min, max)``.
      :rtype: tuple[tuple[int, int], tuple[int, int]]

   .. method:: translate(self, offset)
   
      Move the rectangle by adding an offset to its position.
   
      :param offset: Offset as ``[dx, dy]``.
      :type offset: :class:`Point` | :class:`Size` | tuple[int, int]
      :return: None.
      :rtype: None

   .. method:: union(self, other)
   
      Return the smallest rectangle enclosing both rectangles.
   
      :param other: Another rectangle.
      :type other: :class:`ion.types.Rect`
      :rtype: :class:`ion.types.Rect`

   .. attribute:: center_ceil_x

      X component of center, rounded toward positive infinity.
      
      :type: int

   .. attribute:: center_ceil_y

      Y component of center, rounded toward positive infinity.
      
      :type: int

   .. attribute:: center_floor_x

      X component of center, rounded toward negative infinity.
      
      :type: int

   .. attribute:: center_floor_y

      Y component of center, rounded toward negative infinity.
      
      :type: int

   .. attribute:: is_frozen

      Whether this value is frozen (read-only).
      
      :type: bool

   .. attribute:: max

      Maximum point (bottom-right corner). Setting moves the rectangle (size unchanged).
      
      :type: :class:`ion.types.Point`

   .. attribute:: min

      Minimum point (top-left corner). Setting moves the rectangle (size unchanged).
      
      :type: :class:`ion.types.Point`

   .. attribute:: size

      Size as ``Size(width, height)`` (read-only).
      
      :type: :class:`~ion.types.Size`

   .. attribute:: size_x

      Width (``max.x - min.x``) (read-only).
      
      :type: int

   .. attribute:: size_y

      Height (``max.y - min.y``) (read-only).
      
      :type: int

   .. details:: Special Methods

      .. method:: __copy__(self)

         :rtype: :class:`Rect`

      .. method:: __deepcopy__(self, memo)

         :param memo: Memoization dict for shared subobjects.
         :type memo: dict
         :rtype: :class:`Rect`

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __format__(self, format_spec)

         :param format_spec: Format spec applied per component (empty spec returns ``repr(self)``).
         :type format_spec: str
         :rtype: str

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str

      .. method:: __setitem__(self, key, value)

         Set self[key] to value.

         :param key: Index or key.
         :type key: int
         :param value: Value to assign.
         :type value: object



.. class:: Size

   2D size as [width, height].

   .. method:: __init__(self, size)

      :param size: Size as [width, height].
      :type size: tuple[int, int]
      :rtype: None

   .. method:: __getitem__(self, index)

      Get an item by index.

      :param index: ``0`` for width, ``1`` for height.
      :type index: int
      :rtype: int

   .. method:: __getitem__(self, index)
      :noindex:

      :param index: A slice over the two components.
      :type index: slice
      :rtype: tuple[int, ...]

   .. method:: __len__(self)

      Return the number of components (always 2).

      :rtype: int

   .. method:: __iter__(self)

      Iterate over components (width, height).

      :rtype: Iterator[int]

   .. method:: copy(self)
   
      Return a mutable (unfrozen) copy.
   
      :rtype: :class:`Size`

   .. method:: freeze(self)
   
      Freeze this value, making it read-only and hashable.
      Returns self for convenience (e.g. ``d[p.freeze()] = v``).
   
      :rtype: Self

   .. method:: is_negative(self)
   
      True if either dimension is negative.
   
      A size may go negative as an intermediate arithmetic result; this
      flags such a value before it is used as a final size.
   
      :rtype: bool

   .. method:: to_tuple(self)
   
      Convert to tuple ``(width, height)``.
   
      :return: Tuple ``(width, height)``.
      :rtype: tuple[int, int]

   .. attribute:: is_frozen

      Whether this value is frozen (read-only).
      
      :type: bool

   .. attribute:: x

      Width (first component).
      
      :type: int

   .. attribute:: y

      Height (second component).
      
      :type: int

   .. details:: Special Methods

      .. method:: __add__(self, other)

         Return self+value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __copy__(self)

         :rtype: :class:`Size`

      .. method:: __deepcopy__(self, memo)

         :param memo: Memoization dict for shared subobjects.
         :type memo: dict
         :rtype: :class:`Size`

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __floordiv__(self, other)

         Return self//value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __format__(self, format_spec)

         :param format_spec: Format spec applied per component (empty spec returns ``repr(self)``).
         :type format_spec: str
         :rtype: str

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __iadd__(self, other)

         Return self+=value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __isub__(self, other)

         Return self-=value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __mul__(self, other)

         Return self*value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __pos__(self)

         +self

         :rtype: :class:`Size`

      .. method:: __radd__(self, other)

         Return value+self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __repr__(self)

         :rtype: str

      .. method:: __rfloordiv__(self, other)

         Return value//self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __rmul__(self, other)

         Return value*self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __rsub__(self, other)

         Return value-self.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`

      .. method:: __setitem__(self, key, value)

         Set self[key] to value.

         :param key: Index or key.
         :type key: int
         :param value: Value to assign.
         :type value: object

      .. method:: __sub__(self, other)

         Return self-value.

         :param other: The other operand.
         :type other: Self
         :rtype: :class:`Size`



.. class:: SplitNode

   A node in the workspace split tree (read-only).
   
   Base class for :class:`SplitNodeLeaf` and :class:`SplitNodeContainer`.


   .. method:: find_adjacent(self, direction)
   
      Find the subtree adjacent to this node in the given direction.
   
      Walks up the split tree to the first axis-aligned ancestor whose
      other child sits in *direction*, and returns that subtree's root.
      Combine with :meth:`WorkspaceCollection.new_from_split_node` to
      extract the adjacent subtree into a floating workspace.
   
      :param direction: Direction to search.
      :type direction: Literal["LEFT", "RIGHT", "UP", "DOWN"]
      :return: The adjacent split node, or ``None`` if no adjacent
         subtree exists in that direction.
      :rtype: :class:`ion.types.SplitNode` | None

   .. attribute:: is_valid

      Whether this node still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: parent

      Parent container node, or ``None`` if this is the root (read-only).
      
      :type: :class:`SplitNodeContainer` | None

   .. attribute:: rect

      Node rectangle (read-only).
      
      :type: :class:`ion.types.Rect`

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: SplitNodeContainer(SplitNode)

   A container node in the workspace split tree with two children and a split direction (read-only).

   .. method:: axis_rotate(self, flip_axis, swap_children, pointer_warp=True)
   
      Rotate the split axis atomically: optionally flip the axis direction
      and/or swap children in a single relayout.
   
      :param flip_axis: Toggle the split axis (horizontal/vertical).
      :type flip_axis: bool
      :param swap_children: Swap ``child_min`` and ``child_max``.
      :type swap_children: bool
      :param pointer_warp: Warp the pointer to the focused frame after changing.
      :type pointer_warp: bool
      :return: None.
      :rtype: None

   .. method:: child_other(self, child)
   
      Return the sibling of *child* - this container's other child.
   
      Useful after :meth:`SplitNodeLeaf.split`: pass the node that was
      split to get the newly created node, without checking which side
      it landed on.
   
      :param child: One of this container's two children.
      :type child: :class:`SplitNode`
      :raises ValueError: If *child* is not a direct child of this container.
      :return: The other child.
      :rtype: :class:`SplitNode`

   .. method:: child_remove(self, child)
   
      Remove a child from this container. The child must be an empty
      leaf (no windows). The container collapses to the surviving child.
   
      :param child: The child leaf to remove.
      :type child: :class:`SplitNodeLeaf`
      :raises ValueError: If the child is not a direct child of this container.
      :rtype: None

   .. method:: child_swap(self, pointer_warp=True)
   
      Swap the two children so ``child_min`` becomes ``child_max`` and vice versa.
   
      :param pointer_warp: Warp the pointer to the focused frame after swapping.
      :type pointer_warp: bool
      :return: None.
      :rtype: None

   .. method:: join(self)
   
      Recursively merge all frames in this container's subtree into
      one frame (the last-active descendant), removing the rest.
   
      :return: None.
      :rtype: None

   .. method:: split_axis_set(self, axis, pointer_warp=True)
   
      Set the split direction.
   
      :param axis: ``0`` for horizontal, ``1`` for vertical.
      :type axis: int
      :param pointer_warp: Warp the pointer to the focused frame after changing.
      :type pointer_warp: bool
      :return: None.
      :rtype: None

   .. method:: split_divider_position_set(self, position)
   
      Set the split ratio from an absolute divider position.
   
      The position is in logical pixels (the center of the divider).
      The ratio is computed from the position relative to the
      container's rectangle and divider width.
   
      :param position: Absolute position in logical pixels.
      :type position: int
      :rtype: None

   .. method:: split_divider_position_to_ratio(self, position)
   
      Compute the split ratio for an absolute divider position without
      applying it.
   
      Mirrors :meth:`split_divider_position_set` but returns the ratio
      instead of setting it, so callers can adjust the value (for example
      snap it) and apply it once via :meth:`split_ratio_set`. This avoids
      reconfiguring the windows for the raw position before the adjusted
      ratio is applied.
   
      :param position: Absolute position in logical pixels.
      :type position: int
      :return: The unclamped ratio (0.0 to 1.0), or None when the container
         is too small for meaningful resizing.
      :rtype: float | None

   .. method:: split_ratio_set(self, ratio)
   
      Set the split ratio between the two children.
   
      :param ratio: Split ratio (0.0 to 1.0) where 0.5 is an even split (the default).
         The value is the fraction of space allocated to ``child_min``.
         Clamped so that neither child falls below the minimum split size.
      :type ratio: float
      :rtype: None

   .. attribute:: child_max

      Child at the maximum edge - right for horizontal, bottom for vertical (read-only).
      
      :type: :class:`SplitNode`

   .. attribute:: child_min

      Child at the minimum edge - left for horizontal, top for vertical (read-only).
      
      :type: :class:`SplitNode`

   .. attribute:: gapless

      Whether this divider is gapless.
      
      When ``True`` the divider has zero width: the two children abut with no
      gap, no divider bar is rendered, and the boundary offers no pointer
      resize handle. Defaults to ``False``.
      
      :type: bool

   .. attribute:: gapless_manual

      Whether this divider's gapless state is pinned by the user.
      
      When ``True`` the automatic rule does not change it. Set to ``False`` to
      release the divider back to automatic control.
      
      :type: bool

   .. attribute:: last_active

      Last-active child (read-only).
      
      :type: :class:`SplitNode`

   .. attribute:: split_axis

      Split axis: ``0`` for horizontal (left|right), ``1`` for vertical (top/bottom) (read-only).
      
      :type: int

   .. attribute:: split_ratio

      Split ratio (read-only).
      
      Fraction of space allocated to ``child_min`` (0.0 to 1.0, default 0.5).
      
      :type: float



.. class:: SplitNodeLeaf(SplitNode)

   A leaf node in the workspace split tree, holding a single frame.

   .. method:: split(self, axis, side, *, move_window=True)
   
      Split this leaf, creating a new sibling frame.
   
      *side* selects where the new frame goes: ``0`` = min
      (left/top), ``1`` = max (right/bottom). When *move_window* is
      ``True`` (the default), the active window moves into the new
      frame and focus follows it.
   
      Returns the divider created by the split. The original and new
      frames are reachable as its ``child_min`` / ``child_max`` (the new
      frame is on *side*); pass this leaf to
      :meth:`SplitNodeContainer.child_other` to get the new node directly.
   
      :param axis: Split axis (``0`` = horizontal, ``1`` = vertical).
      :type axis: Literal[0, 1]
      :param side: Side for the new frame (``0`` = min, ``1`` = max).
      :type side: Literal[0, 1]
      :param move_window: Move the active window into the new frame.
      :type move_window: bool
      :return: The divider created by the split, or ``None`` if the split failed.
      :rtype: :class:`SplitNodeContainer` | None

   .. attribute:: frame

      Frame at this leaf (read-only).
      
      :type: :class:`Frame`



.. class:: StartupPreferences

   Preferences read once at startup, settable only during config load.
   
   The setters accept writes during config load (initial load or reload) and
   raise ``RuntimeError`` from a hook or operator at runtime, but only the
   value present at startup takes effect - a reload does not re-apply them.


   .. attribute:: use_numlock

      Enable numlock at startup (default: False).
      
      Consulted once after the seat keyboard is created; changing it on config
      reload has no effect.
      
      :type: bool

   .. attribute:: use_xwayland

      Launch XWayland so X11 applications can connect (default: True).
      
      Consulted once at startup; changing it on config reload has no effect,
      because tearing down XWayland would kill all connected X11 clients.
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: TabletCollection

   Collection of tablet devices accessible as ``ion.app.input.tablets``.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, item)
   
      Check if a device exists in the collection.
   
      :param item: The device to check for membership.
      :type item: :class:`TabletDevice`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all tablet devices.
   
      :rtype: Iterator[:class:`TabletDevice`]
   
   .. method:: __getitem__(self, key)
   
      Get a tablet device by index or name.
   
      :param key: Device name, or zero-based index.
      :type key: str | int
      :rtype: :class:`TabletDevice`


   .. attribute:: active

      The tablet that most recently produced input (read-only).
      
      :type: :class:`ion.types.TabletDevice` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: TabletDevice

   A tablet device exposed to Python.


   .. attribute:: is_enabled

      Whether this device is enabled.
      
      :type: bool

   .. attribute:: left_handed

      Swap left/right buttons.
      
      :type: bool

   .. attribute:: name

      Human-readable device name (read-only).
      
      :type: str

   .. attribute:: rotation_angle

      Rotation angle in degrees, 0..360.
      
      :type: int

   .. attribute:: usb_id

      USB vendor and product IDs as a ``(vendor, product)`` tuple,
      or ``None`` for non-USB devices (read-only).
      
      :type: tuple[int, int] | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: TabletPreferences

   Tablet device preferences.


   .. attribute:: is_enabled

      Enable tablet (default: True).
      
      :type: bool

   .. attribute:: left_handed

      Swap left/right buttons (default: False).
      
      :type: bool

   .. attribute:: rotation_angle

      Rotation angle in degrees, 0..360 (default: 0).
      
      :type: int

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: TilingPreferences

   Tiling behaviour preferences.


   .. attribute:: auto_gaps

      Render dividers that fall on a monitor seam gapless automatically (default: False).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: TouchpadPreferences

   Touchpad device preferences.


   .. attribute:: accel_profile

      Acceleration profile (default: ``"ADAPTIVE"``).
      
      :type: Literal["ADAPTIVE", "FLAT"]

   .. attribute:: accel_speed

      Acceleration speed -1.0 to 1.0 (default: 0.0).
      
      :type: float

   .. attribute:: click_method

      Click method (default: ``"CLICKFINGER"``).
      
      :type: Literal["CLICKFINGER", "BUTTON_AREAS"]

   .. attribute:: disable_while_typing

      Disable while typing (default: True).
      
      :type: bool

   .. attribute:: drag_lock

      Drag lock (default: False).
      
      :type: bool

   .. attribute:: is_enabled

      Enable touchpad (default: True).
      
      :type: bool

   .. attribute:: left_handed

      Swap left/right buttons (default: False).
      
      :type: bool

   .. attribute:: natural_scroll

      Invert scroll direction (default: True).
      
      :type: bool

   .. attribute:: scroll_method

      Scroll method (default: ``"TWO_FINGER"``).
      
      :type: Literal["TWO_FINGER", "EDGE", "BUTTON"]

   .. attribute:: tap_and_drag

      Tap and drag (default: True).
      
      :type: bool

   .. attribute:: tap_to_click

      Tap to click (default: True).
      
      :type: bool

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: UILayout

   Collects the GUI elements of a container such as a menu.
   
   Elements are added through the layout, for example ``menu.layout.operator(...)``.
   Wrap additions in :meth:`context_store` to store the context an operator
   should act on when it runs, e.g. a divider a menu item targets.
   
   .. code-block:: python
   
      def my_menu(menu):
          layout = menu.layout
          layout.operator(ion.ops.window_close())
          # Pin a divider resolved elsewhere (e.g. the one bordering the
          # focused frame) so the operator acts on it even though it is not
          # under the pointer -- the reason `context_store` exists.
          with layout.context_store(split=target_divider):
              layout.operator(ion.ops.tiling_swap())
          layout.separator()
          layout.menu("submenu_id")


   .. method:: context_store(self, *, window: 'Window | None' = None, frame: 'Frame | None' = None, split: 'SplitNodeContainer | None' = None, output: 'Output | None' = None, workspace: 'Workspace | None' = None, desktop: 'Desktop | None' = None) -> 'AbstractContextManager[UILayout]'

      Store context values for operators added within the block.
      
      Unlike overriding the live context, this records the values and pins
      them to each operator added inside the ``with`` block; the operator
      targets them when it runs, after the menu has closed. Each attribute
      left ``None`` keeps the value from any enclosing block or the region's
      context. Stores nest.
      
      .. code-block:: python
      
         with menu.layout.context_store(split=divider):
             menu.layout.operator(ion.ops.tiling_swap())
      
      :param window: The window operators in the block should act on.
      :type window: :class:`ion.types.Window` | None
      :param frame: The frame operators in the block should act on.
      :type frame: :class:`ion.types.Frame` | None
      :param split: The split whose divider operators in the block should act on.
      :type split: :class:`ion.types.SplitNodeContainer` | None
      :param output: The output operators in the block should act on.
      :type output: :class:`ion.types.Output` | None
      :param workspace: The workspace operators in the block should act on.
      :type workspace: :class:`ion.types.Workspace` | None
      :param desktop: The desktop operators in the block should act on.
      :type desktop: :class:`ion.types.Desktop` | None
      :rtype: AbstractContextManager[UILayout]

   .. method:: menu(self, idname: 'str') -> 'None'

      Add a submenu reference item.
      
      The display label is taken from the referenced menu's name.
      
      .. code-block:: python
      
         menu.layout.menu("my_submenu")
      
      :param idname: Menu identifier to reference.
      :type idname: str
      :rtype: None

   .. method:: operator(self, operator: 'tuple[object, ...]', /, *, text: 'str | None' = None) -> 'None'

      Add an operator action item.
      
      The label defaults to the operator's name. Use ``text`` to override.
      
      .. code-block:: python
      
         menu.layout.operator(ion.ops.window_close())
         menu.layout.operator(ion.ops.tiling_split(direction='RIGHT'), text="Split Right")
      
      :param operator: NamedTuple instance (from ``ion.ops.*(...)``).
      :type operator: NamedTuple
      :param text: Optional override for the item label.
      :type text: str | None
      :rtype: None

   .. method:: separator(self) -> 'None'

      Add a visual separator line.
      
      :rtype: None



.. class:: Window

   A toplevel application window (see :ref:`proxy-objects`).


   .. method:: close(self)
   
      Request the window to close gracefully.
   
      :return: None.
      :rtype: None

   .. method:: find_children(self)
   
      All windows that have this window as their immediate parent.
   
      :return: Child windows.
      :rtype: list[:class:`~ion.types.Window`]

   .. method:: focus(self)
   
      Give keyboard focus to this window.
   
      :return: None.
      :rtype: None

   .. method:: fullscreen_move_to_output(self, output)
   
      Move this fullscreen window to another output, keeping it fullscreen.
      The window becomes the front-most fullscreen window on the target output.
   
      :param output: The target output.
      :type output: :class:`~ion.types.Output`
      :raises RuntimeError: If the window is not fullscreen.
      :rtype: None

   .. method:: kill(self)
   
      Force-kill an unresponsive window.
   
      :return: None.
      :rtype: None

   .. method:: move_to_floating(self, desktop, rect=None)
   
      Move this window to the floating layer on the given desktop.
      Does nothing if already floating.
   
      :param desktop: The target desktop.
      :type desktop: :class:`~ion.types.Desktop`
      :param rect: Optional position and size for the floating frame.
         When ``None`` (default), the position and size are derived
         from the window's current tiled geometry.
      :type rect: :class:`~ion.types.Rect` | None
      :return: The floating desktop item, or ``None`` if the window
         could not be floated.
      :rtype: :class:`~ion.types.DesktopItemFloatingFrame` | None

   .. method:: move_to_frame(self, frame, index=None, activate=True)
   
      Move this window to a different frame.
   
      :param frame: The target frame.
      :type frame: :class:`ion.types.Frame`
      :param index: Tab position in the target frame. Negative indices
         count from the end (Python-style). ``None`` inserts after the
         active tab (default).
      :type index: int | None
      :param activate: Whether to make this window the active tab and
         focus the target frame (default ``True``). When ``False``,
         the window is inserted without changing focus.
      :type activate: bool
      :raises RuntimeError: If the window is floating or otherwise cannot be moved.
      :rtype: None

   .. method:: move_to_tiling(self, workspace=None, frame=None)
   
      Move this window from the floating layer into the tiling layout.
      Does nothing if the window is already tiled.
   
      :param workspace: The target workspace; the window is tiled into
         its last-active frame. When ``None`` (default), the active
         output's workspace is used.
      :type workspace: :class:`~ion.types.Workspace` | None
      :param frame: The target frame. Takes precedence over ``workspace``
         when given.
      :type frame: :class:`~ion.types.Frame` | None
      :return: The frame the window was tiled into, or ``None`` if the
         window could not be tiled.
      :rtype: :class:`~ion.types.Frame` | None

   .. attribute:: app_id

      Application ID (read-only).
      
      :type: str | None

   .. attribute:: content_rect

      Window content rectangle, excluding decorations, or ``None`` if not yet
      placed (read-only).
      
      :type: :class:`ion.types.Rect` | None

   .. attribute:: data

      Per-window dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the window.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: frame_rect

      Window frame rectangle, including decorations, or ``None`` if not yet
      placed (read-only).
      
      :type: :class:`ion.types.Rect` | None

   .. attribute:: fullscreen

      Whether the window is fullscreen.
      
      :type: bool

   .. attribute:: id

      Unique numeric identifier for this window (read-only).
      
      Stable for the lifetime of the window regardless of workspace,
      desktop, frame, or tiling/floating state changes.
      Not reused after the window is closed.
      
      :type: int

   .. attribute:: is_floating

      Whether the window is floating (not tiled) (read-only).
      
      :type: bool

   .. attribute:: is_focused

      Whether this window has keyboard focus (read-only).
      
      :type: bool

   .. attribute:: is_valid

      Whether this window still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: output_fullscreen

      The output a fullscreen window is on, or None if not fullscreen.
      
      :type: :class:`~ion.types.Output` | None

   .. attribute:: parent

      Immediate parent window, or ``None`` if this window has no parent (read-only).
      
      :type: :class:`~ion.types.Window` | None

   .. attribute:: parent_root

      Root parent window, or ``None`` if this window has no parent (read-only).
      
      Walks the XDG parent chain to the topmost ancestor.
      Falls back to the immediate parent if a cycle is detected.
      
      :type: :class:`~ion.types.Window` | None

   .. attribute:: pid

      Process ID of the window's client (read-only).
      
      ``None`` is only for X11 windows that do not set ``_NET_WM_PID``.
      
      :type: int | None

   .. attribute:: size

      Committed geometry size (read-only).
      
      :type: :class:`~ion.types.Size`

   .. attribute:: size_max

      Client maximum size hint (read-only).
      
      A component of ``0`` means unconstrained.
      
      :type: :class:`~ion.types.Size`

   .. attribute:: size_min

      Client minimum size hint (read-only).
      
      A component of ``0`` means unconstrained.
      
      :type: :class:`~ion.types.Size`

   .. attribute:: tag

      Whether the window is tagged (marked for batch operations).
      
      :type: bool

   .. attribute:: title

      Window title (read-only).
      
      :type: str | None

   .. attribute:: urgent

      Whether the window is urgent.
      
      :type: bool

   .. attribute:: workspace

      Workspace this window is on, or ``None`` for floating windows (read-only).
      
      :type: :class:`ion.types.Workspace` | None

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: WindowCollection

   Collection accessor for windows.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The window to check for membership.
      :type value: :class:`Window`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Window`]
   
   .. method:: __getitem__(self, index)
   
      Get a window by index. Supports negative indices.
   
      :param index: Zero-based index of the window.
      :type index: int
      :rtype: :class:`Window`
   
   .. method:: __getitem__(self, index)
      :noindex:
   
      :param index: A slice over the windows.
      :type index: slice
      :rtype: tuple[:class:`Window`, ...]


   .. method:: active_goto(self, window)
   
      Jump to a window regardless of desktop, workspace visibility, or fullscreen state.
      Switches desktop, shows hidden workspaces, un-fullscreens obscuring windows,
      and focuses the target.
   
      :param window: The window to jump to.
      :type window: :class:`ion.types.Window`
      :return: None.
      :rtype: None

   .. method:: find_by_id(self, id)
   
      Look up a window by its unique numeric :attr:`~ion.types.Window.id`.
   
      :param id: The window ID to look up.
      :type id: int
      :return: The window, or None if no window with that ID exists.
      :rtype: :class:`~ion.types.Window` | None

   .. method:: focus_last(self)
   
      Focus the previously focused window.
   
      :return: None.
      :rtype: None

   .. method:: index(self, window)
   
      Return the index of a window in the collection.
   
      :param window: The window to find.
      :type window: :class:`ion.types.Window`
      :rtype: int
      :raises ValueError: If the window is not in the collection.

   .. attribute:: active

      Currently focused window (read-only).
      
      :type: :class:`ion.types.Window` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: Workspace

   A workspace containing a tiling layout of frames (see :ref:`proxy-objects`).


   .. attribute:: data

      Per-workspace dictionary for script-defined data.
      
      Created on first access and persists for the lifetime of the workspace.
      Scripts can store arbitrary keys and values here.
      
      :type: dict[Any, Any]

   .. attribute:: floating_rect

      Floating overlay rectangle.
      
      The rectangle used when this workspace is shown as a floating overlay.
      Always set (assigned at creation time) and never cleared, even when
      the workspace is tiled. For the tiled geometry, use
      :attr:`DesktopItemTiling.rect` instead.
      
      :type: :class:`ion.types.Rect`

   .. attribute:: frames

      All frames in this workspace (read-only).
      
      :type: :class:`ion.types.WorkspaceFrameCollection`

   .. attribute:: id

      Unique numeric identifier for this workspace (read-only).
      
      Stable for the lifetime of the workspace regardless of output,
      desktop, or tiling/floating state changes.
      Not reused after the workspace is closed.
      
      :type: int

   .. attribute:: is_empty

      Whether the workspace contains no windows (read-only).
      A workspace must be empty before it can be removed via
      :meth:`~ion.types.WorkspaceCollection.remove`.
      
      :type: bool

   .. attribute:: is_floating

      Whether this workspace is currently shown as a floating overlay (read-only).
      
      Floating ownership is exclusive: a workspace appears on at most one
      desktop's floating layer, so the check spans all desktops.
      
      :type: bool

   .. attribute:: is_focused

      Whether this workspace is focused (read-only).
      
      :type: bool

   .. attribute:: is_tiling

      Whether this workspace is currently tiled (read-only).
      
      Tiling ownership is exclusive: a workspace is tiled on at most one
      desktop, so the check spans all desktops.
      
      :type: bool

   .. attribute:: is_valid

      Whether this workspace still exists in the compositor (read-only).
      
      :type: bool

   .. attribute:: name

      Workspace name.
      
      :type: str

   .. attribute:: root

      Root of the tiling layout tree (read-only).
      
      :type: :class:`ion.types.SplitNode`

   .. attribute:: windows

      All windows in this workspace (read-only).
      
      :type: :class:`ion.types.WorkspaceWindowCollection`

   .. details:: Special Methods

      .. method:: __eq__(self, other)

         Return self==value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __ge__(self, other)

         Return self>=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __gt__(self, other)

         Return self>value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __hash__(self)

         :rtype: int

      .. method:: __le__(self, other)

         Return self<=value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __lt__(self, other)

         Return self<value.

         :param other: The other operand.
         :type other: Self
         :rtype: bool

      .. method:: __ne__(self, other)

         Return self!=value.

         :param other: The object to compare against.
         :type other: object
         :rtype: bool

      .. method:: __repr__(self)

         :rtype: str



.. class:: WorkspaceCollection

   Collection accessor for workspaces.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The workspace to check for membership.
      :type value: :class:`Workspace`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Workspace`]
   
   .. method:: __getitem__(self, key)
   
      Get a workspace by name or index.
   
      :param key: Workspace name, or zero-based index.
      :type key: str | int
      :rtype: :class:`Workspace`


   .. method:: find_by_frame(self, frame)
   
      Find the workspace containing the given frame.
   
      :param frame: The frame to search for.
      :type frame: :class:`ion.types.Frame`
   
      :return: The workspace containing the frame, or ``None`` if not found.
      :rtype: :class:`ion.types.Workspace` | None

   .. method:: find_by_id(self, id)
   
      Look up a workspace by its unique numeric :attr:`~ion.types.Workspace.id`.
   
      :param id: The workspace ID to look up.
      :type id: int
      :return: The workspace, or None if no workspace with that ID exists.
      :rtype: :class:`~ion.types.Workspace` | None

   .. method:: find_by_output(self, output)
   
      Find the tiled workspace visible on the given output.
   
      :param output: The output to query.
      :type output: :class:`ion.types.Output`
   
      :return: The workspace on that output, or ``None`` if none assigned.
      :rtype: :class:`ion.types.Workspace` | None

   .. method:: find_by_window(self, window)
   
      Find the workspace containing the given window.
   
      :param window: The window to search for.
      :type window: :class:`ion.types.Window`
   
      :return: The workspace containing the window, or ``None`` if the window
         is floating or not found.
      :rtype: :class:`ion.types.Workspace` | None

   .. method:: get(self, name)
   
      Get a workspace by name.
   
      :param name: The workspace name.
      :type name: str
   
      :return: The workspace, or ``None`` if not found.
      :rtype: :class:`ion.types.Workspace` | None

   .. method:: index(self, workspace)
   
      Return the index of a workspace in the collection.
   
      :param workspace: The workspace to find.
      :type workspace: :class:`ion.types.Workspace`
      :rtype: int
      :raises ValueError: If the workspace is not in the collection.

   .. method:: items(self)
   
      All (name, workspace) pairs.
   
      :return: List of (name, workspace) tuples.
      :rtype: list[tuple[str, :class:`ion.types.Workspace`]]

   .. method:: keys(self)
   
      All workspace names.
   
      :return: List of workspace name strings.
      :rtype: list[str]

   .. method:: new(self, floating_rect, name="")
   
      Create a new workspace with the given name.
   
      If a workspace with that name already exists, a unique name is generated
      by appending a number (e.g., "scratch.1", "scratch.2").
      When *name* is empty, a numbered name is generated automatically.
   
      The workspace is not yet visible. Use :meth:`DesktopTilingCollection.add`
      or :meth:`DesktopFloatingCollection.add` to place it on a desktop.
   
      :param floating_rect: Geometry in global coordinates, used when the workspace
         is shown as a floating overlay.
      :type floating_rect: :class:`ion.types.Rect`
      :param name: Base name for the new workspace.
      :type name: str
   
      :return: The newly created workspace.
      :rtype: :class:`ion.types.Workspace`

   .. method:: new_from_split_node(self, node)
   
      Create a new workspace by extracting a node from the tiling tree.
   
      For a leaf this extracts a single frame; for a container the entire
      subtree (including all children) is extracted. When the root node is
      extracted, the source workspace is reset to a single empty frame.
   
      The new workspace is not yet visible. Use
      :meth:`DesktopFloatingCollection.add` or
      :meth:`DesktopTilingCollection.add` to place it on a desktop.
   
      The new workspace's ``floating_rect`` is seeded from the extracted
      node's pre-extraction rect, so a subsequent floating placement
      appears where the user just saw the subtree. Override the seeded
      value by assigning ``ws.floating_rect`` before placement.
   
      :param node: The split node to extract.
      :type node: :class:`ion.types.SplitNode`
      :return: The newly created workspace.
      :rtype: :class:`ion.types.Workspace`
      :raises RuntimeError: If the node cannot be extracted.

   .. method:: remove(self, workspace)
   
      Remove a workspace. The workspace must not contain any windows.
   
      :param workspace: The workspace to remove.
      :type workspace: :class:`ion.types.Workspace`
      :raises RuntimeError: If the workspace contains windows.
      :rtype: None

   .. attribute:: active

      Currently focused workspace (read-only).
      
      Derived from the focus entry, which by design lives on the active
      desktop. The returned workspace is therefore guaranteed to be on
      the active desktop - either tiled there or shown as a floating
      overlay there. Workspaces tiled or floating on other desktops are
      never returned by this accessor.
      
      :type: :class:`ion.types.Workspace` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: WorkspaceFrameCollection

   Collection accessor for frames within a specific workspace.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The frame to check for membership.
      :type value: :class:`Frame`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Frame`]
   
   .. method:: __getitem__(self, index)
   
      Get a frame by index. Supports negative indices.
   
      :param index: Zero-based index of the frame.
      :type index: int
      :rtype: :class:`Frame`
   
   .. method:: __getitem__(self, index)
      :noindex:
   
      :param index: A slice over the frames in this workspace.
      :type index: slice
      :rtype: tuple[:class:`Frame`, ...]


   .. method:: find_by_id(self, id)
   
      Look up a frame by its unique numeric :attr:`~ion.types.Frame.id`,
      only if it belongs to this workspace.
   
      :param id: The frame ID to look up.
      :type id: int
      :return: The frame, or None if no matching frame exists in this workspace.
      :rtype: :class:`~ion.types.Frame` | None

   .. method:: index(self, frame)
   
      Return the index of a frame in this workspace.
   
      :param frame: The frame to find.
      :type frame: :class:`ion.types.Frame`
      :rtype: int
      :raises ValueError: If the frame is not in this workspace.

   .. attribute:: active

      Focused frame on this workspace (read-only).
      
      :type: :class:`ion.types.Frame` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str



.. class:: WorkspaceWindowCollection

   Collection accessor for windows within a specific workspace.
   
   .. method:: __len__(self)
   
      Get the number of items in the collection.
   
      :rtype: int
   
   .. method:: __contains__(self, value)
   
      Check if a value exists in the collection.
   
      :param value: The window to check for membership.
      :type value: :class:`Window`
      :rtype: bool
   
   .. method:: __iter__(self)
   
      Iterate over all items in the collection.
   
      :rtype: Iterator[:class:`Window`]
   
   .. method:: __getitem__(self, index)
   
      Get a window by index. Supports negative indices.
   
      :param index: Zero-based index of the window.
      :type index: int
      :rtype: :class:`Window`
   
   .. method:: __getitem__(self, index)
      :noindex:
   
      :param index: A slice over the windows.
      :type index: slice
      :rtype: tuple[:class:`Window`, ...]


   .. method:: find_by_id(self, id)
   
      Look up a window by its unique numeric :attr:`~ion.types.Window.id`,
      only if it belongs to this workspace.
   
      :param id: The window ID to look up.
      :type id: int
      :return: The window, or None if no matching window exists in this workspace.
      :rtype: :class:`~ion.types.Window` | None

   .. method:: index(self, window)
   
      Return the index of a window in this workspace.
   
      :param window: The window to find.
      :type window: :class:`ion.types.Window`
      :rtype: int
      :raises ValueError: If the window is not in this workspace.

   .. attribute:: active

      Focused window on this workspace (read-only).
      
      :type: :class:`ion.types.Window` | None

   .. details:: Special Methods

      .. method:: __repr__(self)

         :rtype: str