ion.app
=======

.. module:: ion.app

.. include:: ../rst/ion.app.rst

Application settings.

.. data:: is_init

   True during config loading (both initial startup and reload), False otherwise.

   :type: bool

.. data:: is_init_startup

   True only during the initial startup config load, False during reload and at runtime.

   :type: bool

.. data:: ipc_args

   Arguments passed to the current IPC command. Empty list outside of IPC execution.

   :type: list[str]

Functions
---------

.. function:: config_dir()

   Config directory (``XDG_CONFIG_HOME/ionwl`` or ``~/.config/ionwl``).

   :rtype: str

.. function:: data_dir()

   Data directory containing resources and bundled Python packages.
   Resolved once at startup from the XDG data directory search path.

   :rtype: str

.. function:: logout()

   Graceful logout: request all windows to close, then exit when
   none remain. Windows that need confirmation (unsaved files etc.)
   will stay open until the user handles them.

   :rtype: None

.. function:: quit()

   Quit the compositor.

.. function:: reload()

   Reload the configuration file.

   All keybindings, hooks, and menus are cleared before the config
   re-runs, so the config file is always the complete declaration of
   these settings. Check :data:`ion.app.is_init_startup` to gate
   actions that should only run on initial startup.

   .. note::

      This action is deferred until the current callback returns.

.. function:: version()

   Get IonWL version.

   :rtype: str

Data
----

.. data:: decor

   .. class:: Decor()
   
      Decoration configuration (geometry and visual properties).

   :type: :class:`ion.types.Decor`


.. data:: hooks

   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.

   :type: :class:`ion.types.HooksRegistry`


   **Output Hotplug**
   
   Use the ``output_add_pre`` hook to configure monitors as they are
   connected. The callback receives the :class:`ion.types.Output` object before it
   is used, so properties like position and transform take effect
   immediately.

   .. literalinclude:: ../examples/ion.app.hooks.0.py
      :lines: 9-

   **Startup Layout**
   
   Use the ``compositor_startup_post`` hook to create desktops and
   workspaces when the compositor starts. Desktop 0 always exists, so
   only additional desktops need to be created explicitly.

   .. literalinclude:: ../examples/ion.app.hooks.1.py
      :lines: 8-

.. data:: keymaps

   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.

   :type: :class:`ion.types.KeymapsRegistry`


   **Basic Keybindings**
   
   Set up keyboard and pointer bindings using :class:`ion.types.MatchKey` and
   :class:`ion.types.MatchPointer`. Modifiers such as ``logo``, ``shift``, ``ctrl``
   and ``alt`` can be combined freely.

   .. literalinclude:: ../examples/ion.app.keymaps.0.py
      :lines: 8-

.. data:: menus

   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.

   :type: :class:`ion.types.MenuRegistry`


   **Context Menus**
   
   Register context menus with :meth:`ion.types.MenuRegistry.new`. The
   callback receives a :class:`ion.types.MenuBuilder` and populates its
   :class:`ion.types.UILayout` (``menu.layout``) with operators, separators,
   and sub-menus. Bind the menu to a pointer event with the built-in
   ``menu_show`` operator.

   .. literalinclude:: ../examples/ion.app.menus.0.py
      :lines: 10-

.. data:: preferences

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

   :type: :class:`ion.types.Preferences`