Metadata-Version: 2.4
Name: xcontroller
Version: 0.1
Summary: Library for controlling an X desktop Environment.
Keywords: x11,xvfb,ewmh,keyboard,mouse
Author: H. Turgut Uyar
Author-email: H. Turgut Uyar <uyar@tekir.org>
License-Expression: GPL-3.0-only
License-File: LICENSE.pyewmh.txt
License-File: LICENSE.pynput.txt
License-File: LICENSE.txt
License-File: LICENSE.xvfb.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Framebuffer
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Desktop Environment :: Window Managers
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: python-xlib>=0.33
Requires-Python: ~=3.12
Description-Content-Type: text/x-rst

xcontroller
===========

xcontroller is a Python library for developing X11 automation scripts.
It includes functionality for controlling the window manager,
the keyboard, and the mouse.

It is based on the following projects:

`pyewmh <https://github.com/parkouss/pyewmh>`_ by Julien Pagès
  The functionality for controlling the window manager and windows,
  like getting the desktop geometry or setting the active window,
  are taken from this project.
  The code has only been refactored to follow Python style naming
  and some type hints were modified.

`pynput <https://github.com/moses-palmer/pynput>`_  by Moses Palmér
  The keyboard and mouse controllers were adapted from this project.
  A lot of the capabilities of pynput have been left out,
  most importantly support for Windows and MacOS, listeners and thread safety.
  Type hints have been improved.

`python-xvfb <https://github.com/jonathanultis/python-xvfb>`_ by Jonathan Ultis
  The function for starting an Xvfb server was taken from this project
  with only some minor modifications.


Usage examples:
---------------

*Note*: All controllers take a ``display`` parameter to which they connect.
If no display parameter is given, they will connect to the default display.

- get the desktop geometry:

  .. code-block:: python

     from xcontroller.ewmh import WMController

     wm = WMController()
     width, height = wm.get_desktop_geometry()

- find a window and raise it:

  .. code-block:: python

     from xcontroller.ewmh import WMController

     wm = WMController()
     windows = wm.get_client_list()
     for window in windows:
         if "Shell" in window.get_wm_name():
             window.raise_window()

- Press and release keys on the keyboard:

  .. code-block:: python

     from xcontroller.keyboard import KeyboardController, SpecialKey

     kb = KeyboardController()

     kb.tap("x")

     kb.press(SpecialKey.ENTER)
     kb.release(SpecialKey.ENTER)

     with kb.pressed(SpecialKey.CTRL):
         kb.tap("s")

- Start an Xvfb server:

  .. code-block:: python

     from xcontroller.xvfb import start_xvfb
     from pathlib import Path

     start_xvfb(Path("/usr/bin/Xvfb"), 1920, 1080, 24)

  *Note*: If no display number is given, this will choose a random number
  and export the ``DISPLAY`` environment variable
  (unless otherwise instructed).
