Cortile Addons

Python bindings for the linux auto tiling manager cortile.

Cortile provides auto tiling for XFCE, LXDE, LXQt, KDE and GNOME (Mate, Deepin, Cinnamon, Budgie) based desktop environments. There is build in support for Openbox, Fluxbox, IceWM, Xfwm, KWin, Marco, Muffin, Mutter and other EWMH compliant window managers using the X11 window system.

This package only provides the python bindings and does not contain the cortile release binary. To use this package, you need to install the binary from the main repository. For more details, please refer to the cortile README.md file.

Installation

To get started, install it via pip:

pip install cortile

Usage

If cortile is installed and running as described here, the python bindings will connect to the running instance, allowing you to fully communicate with cortile using python:

from cortile import Cortile

# connects to the running cortile instance
ct = Cortile()
...

Documentation

Documentation is provided through docstring literals, which appear immediately after the definition of a method, class, or module. While all methods and classes include docstrings, the primary interface for interacting with a running cortile instance is the Cortile() class, which is documented here:

class Cortile()

__init__

def __init__(log: int = Logger.LEVELS.WARN)

Initialize the cortile connector.

This main class wraps methods of the base connector and should be used as primary interface to communicate with a running cortile instance.

Arguments:

• log: Logging level, default is warn

log

@property
def log() -> Logger

Return the logger instance.

Returns:

Logger instance that writes to syslog

listen

def listen(callback: Callable[[Dict], None] | None) -> None

Start listening for events.

Arguments:

• callback: Function to call when an event is received

wait

def wait(sleep: float = 0.5) -> None

Keeps the process running for the connector to listen.

Arguments:

• sleep: Time to sleep in between, default is 0.5 seconds

close

def close() -> None

Close the connection gracefully.

get_active_layout

def get_active_layout() -> Dict | None

Get the active layout for the current desktop and screen.

Returns:

Active layout with tiling enabled or None

get_active_layouts

def get_active_layouts() -> Iterator[Dict]

Get the active layouts from the workspaces.

Returns:

Iterator of active layouts with tiling enabled

get_active_client

def get_active_client() -> Dict | None

Get the current focused client window.

Returns:

Active client or None

get_active_clients

def get_active_clients() -> Iterator[Dict]

Get information of clients on the current active screen.

Returns:

Iterator of tracked clients on the current screen

get_active_desktop

def get_active_desktop() -> int | None

Get the current active desktop.

Returns:

Active desktop index or None

get_active_screen

def get_active_screen() -> int | None

Get the current active screen.

Returns:

Active screen index or None

get_desktop_count

def get_desktop_count() -> int | None

Get the number of desktops.

Returns:

Number of desktops or None

get_screen_count

def get_screen_count() -> int | None

Get the number of screens.

Returns:

Number of screens or None

get_desktop_dimensions

def get_desktop_dimensions() -> List[Dict]

Get the dimensions of all desktops.

Returns:

LTR sorted list of desktop dimensions or None

get_screen_dimensions

def get_screen_dimensions() -> List[Dict]

Get the dimensions of all screens.

Returns:

LTR sorted list of screen dimensions or None

get_clients

def get_clients() -> List[Dict]

Get all the clients information.

Returns:

List of tracked clients or None

get_windows

def get_windows() -> Dict | None

Get all the windows information.

Returns:

List of tracked window ids or None

desktop_switch

def desktop_switch(desktop: int) -> bool

Switch to a different desktop.

Arguments:

• desktop: Index of the desktop to switch to

Returns:

True if successful, False otherwise

window_activate

def window_activate(id: int) -> bool

Activate a window by its id.

Arguments:

• id: Id of the window to activate

Returns:

True if successful, False otherwise

window_to_desktop

def window_to_desktop(id: int, desktop: int) -> bool

Move a window to a different desktop.

Arguments:

• id: Id of the window to move
• desktop: Index of the desktop to move the window to

Returns:

True if successful, False otherwise

window_to_position

def window_to_position(id: int, x: int, y: int) -> bool

Move a window to a specific position.

Arguments:

• id: Id of the window to move
• x: X coordinate to move the window to
• y: Y coordinate to move the window to

Returns:

True if successful, False otherwise

window_to_screen

def window_to_screen(id: int, screen: int) -> bool

Move a window to a different screen.

Arguments:

• id: Id of the window to move
• screen: Index of the screen to move the window to

Returns:

True if successful, False otherwise

action_execute_enable

def action_execute_enable(desktop: int, screen: int) -> bool

Execute the enable action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_disable

def action_execute_disable(desktop: int, screen: int) -> bool

Execute the disable action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_toggle

def action_execute_toggle(desktop: int, screen: int) -> bool

Execute the toggle action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_decoration

def action_execute_decoration(desktop: int, screen: int) -> bool

Execute the decoration action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_restore

def action_execute_restore(desktop: int, screen: int) -> bool

Execute the restore action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_reset

def action_execute_reset(desktop: int, screen: int) -> bool

Execute the reset action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_cycle_next

def action_execute_cycle_next(desktop: int, screen: int) -> bool

Execute the cycle_next action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_cycle_previous

def action_execute_cycle_previous(desktop: int, screen: int) -> bool

Execute the cycle_previous action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_vertical_left

def action_execute_layout_vertical_left(desktop: int, screen: int) -> bool

Execute the layout_vertical_left action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_vertical_right

def action_execute_layout_vertical_right(desktop: int, screen: int) -> bool

Execute the layout_vertical_right action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_horizontal_top

def action_execute_layout_horizontal_top(desktop: int, screen: int) -> bool

Execute the layout_horizontal_top action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_horizontal_bottom

def action_execute_layout_horizontal_bottom(desktop: int, screen: int) -> bool

Execute the layout_horizontal_bottom action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_maximized

def action_execute_layout_maximized(desktop: int, screen: int) -> bool

Execute the layout_maximized action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_layout_fullscreen

def action_execute_layout_fullscreen(desktop: int, screen: int) -> bool

Execute the layout_fullscreen action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_slave_increase

def action_execute_slave_increase(desktop: int, screen: int) -> bool

Execute the slave_increase action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_slave_decrease

def action_execute_slave_decrease(desktop: int, screen: int) -> bool

Execute the slave_decrease action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_master_increase

def action_execute_master_increase(desktop: int, screen: int) -> bool

Execute the master_increase action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_master_decrease

def action_execute_master_decrease(desktop: int, screen: int) -> bool

Execute the master_decrease action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_window_next

def action_execute_window_next(desktop: int, screen: int) -> bool

Execute the window_next action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_window_previous

def action_execute_window_previous(desktop: int, screen: int) -> bool

Execute the window_previous action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_screen_next

def action_execute_screen_next(desktop: int, screen: int) -> bool

Execute the screen_next action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_screen_previous

def action_execute_screen_previous(desktop: int, screen: int) -> bool

Execute the screen_previous action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_master_make

def action_execute_master_make(desktop: int, screen: int) -> bool

Execute the master_make action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_master_make_next

def action_execute_master_make_next(desktop: int, screen: int) -> bool

Execute the master_make_next action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_master_make_previous

def action_execute_master_make_previous(desktop: int, screen: int) -> bool

Execute the master_make_previous action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_proportion_increase

def action_execute_proportion_increase(desktop: int, screen: int) -> bool

Execute the proportion_increase action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

action_execute_proportion_decrease

def action_execute_proportion_decrease(desktop: int, screen: int) -> bool

Execute the proportion_decrease action.

Arguments:

• desktop: Index of the desktop
• screen: Index of the screen

Returns:

True if successful, False otherwise

Examples

To help you get started quickly, example scripts are available in the examples folder.

These scripts demonstrate various use cases and can serve as a practical guide to utilizing the full potential of cortile through python. Feel free to explore these resources to make the most out of your cortile setup.

Integration

You can execute a script on demand or trigger it by any other external means. To ensure a script is activated every time cortile starts, place it in a folder named addons within the cortile configuration directory, e.g. ~/.config/cortile/addons/.

Any executable script (chmod +x script_name.py) in this folder will automatically run when cortile starts. The script will execute with the same user permission and environment as cortile, so python and additional required dependencies (pip packages) must be available in this environment.

The output from python’s print() function and error logs within the script will appear in the terminal where cortile is running. Depending on the log level, additional messages from the script will be written to the system log (cat /var/log/syslog).

Compatibility

Since the python integration relies on internal cortile properties and the provided interfaces via dbus, it’s crucial that all custom scripts are compatible with the running cortile instance.

This table provides the officially supported combination of versions:

Addons (Python)	Cortile (go)
v1.0.0	v2.5.1
v1.0.1	v2.5.1
v1.0.1	v2.5.2

Contributing

Contributions into the examples folder are greatly welcomed!

If you have a script that could benefit the community, please submit a pull request. Include a brief explanation of the script in the header comment (refer to existing files for guidance). The script should be runnable or serve at least as a useful skeleton for others.

License

MIT