ion.wm
======

.. module:: ion.wm

.. include:: ../rst/ion.wm.rst

Window manager state access with proxy objects.

**Querying Runtime State**

The :mod:`ion.wm` module exposes live collections for windows,
workspaces, outputs, frames, and desktops. Each collection supports
iteration, indexing, ``len()``, and an ``active`` property.

These queries are typically used inside hook callbacks or operator
``exec`` functions.

.. literalinclude:: ../examples/ion.wm.0.py
   :lines: 11-

Functions
---------

.. function:: cursor_pop(token)

   Pop a cursor stack entry and all entries pushed after it.

   If the token has already been popped, this is a no-op.

   :param token: Token returned by :func:`cursor_push`.
   :type token: :class:`~ion.types.CursorToken`
   :rtype: None

.. function:: cursor_push(name)

   Push a cursor icon onto the cursor stack.

   The top of the stack determines the displayed cursor.
   When all generators exit, the entire cursor stack is cleared.

   :param name: CSS cursor name (e.g. ``"grabbing"``, ``"col-resize"``).
   :type name: str
   :return: Opaque token for :func:`cursor_pop`.
   :rtype: :class:`~ion.types.CursorToken`

Data
----

.. data:: context

   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.

   :type: :class:`ion.types.ContextAccessor`


.. data:: desktops

   Collection accessor for desktops (:data:`ion.wm.desktops`).

   :type: :class:`ion.types.DesktopCollection`


.. data:: frames

   Collection accessor for frames.

   :type: :class:`ion.types.FrameCollection`


.. data:: outputs

   Collection accessor for outputs.

   :type: :class:`ion.types.OutputCollection`


.. data:: overlay_root

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

   :type: :class:`ion.types.OverlayGroup`


.. data:: windows

   Collection accessor for windows.

   :type: :class:`ion.types.WindowCollection`


.. data:: workspaces

   Collection accessor for workspaces.

   :type: :class:`ion.types.WorkspaceCollection`