Metadata-Version: 2.4
Name: xcontroller
Version: 0.2
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/markdown

# 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 size 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

- get the desktop geometry

  ```python
  from xcontroller.ewmh import WMController

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

- find a shell window and raise it

  ```python
  from xcontroller.ewmh import WMController

  wmc = WMController()
  for window in wmc.get_client_list():
      if "Shell" in window.get_wm_name():
          window.raise_window()
  ```

- press and release keys on the keyboard

  ```python
  from xcontroller.keyboard import KeyboardController, SpecialKey

  kc = KeyboardController()

  kc.tap("x")

  kc.press(SpecialKey.ENTER)
  kc.release(SpecialKey.ENTER)

  with kc.pressed(SpecialKey.CTRL):
      kc.tap("s")
  ```

- move the mouse pointer and click the right button

  ```python
  from xcontroller.mouse import MouseController, Button

  mc = MouseController()

  mc.move(800, 500)
  mc.click(Button.RIGHT)
  ```

- start an 1920x1080x24 Xvfb server on display 42

  ```python
  from xcontroller.xvfb import start_xvfb

  process = start_xvfb(42, 1920, 1080, 24)
  ```
