ion.types

This module contains all type definitions used across the ion API. Most types are reached through other modules - entity proxies via ion.wm collections, configuration objects via ion.app. The types you’ll typically import directly are the input matchers and geometry primitives.

See Proxy objects for the lifetime semantics of entity proxies.

All type definitions for the ion API.

Classes

class ion.types.AnimatePreferences

Animation preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

desktop_axis

Desktop layout axis: 0 = horizontal (side by side), 1 = vertical (stacked). Default: 0.

Any other value is substituted on assignment and logged.

Type:

int

desktop_axis_rows

Number of rows (horizontal axis) or columns (vertical axis) in the overview grid. 1 = single row/column, 2+ = wrap into a grid. Default: 1.

Zero is substituted on assignment and logged.

Type:

int

desktop_slide_duration

Desktop slide animation duration in milliseconds. Default: 300.

Type:

int

desktop_zoom_duration

Desktop zoom phase duration in milliseconds (each of zoom-out and zoom-in). Default: 500.

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.ColorRGB

RGB color with components in 0.0-1.0 range, accessed via [0]..[2].

__init__(self, rgb)
Parameters:

rgb (ColorRGB | tuple[float, float, float]) – RGB components in 0.0-1.0 range.

Return type:

None

__getitem__(self, index)

Get an item by index.

Parameters:

index (int) – 0 for red, 1 for green, 2 for blue.

Return type:

float

__getitem__(self, index)
Parameters:

index (slice) – A slice over the three components.

Return type:

tuple[float, …]

__len__(self)

Return the number of components (always 3).

Return type:

int

__iter__(self)

Iterate over components (r, g, b).

Return type:

Iterator[float]

classmethod from_rgb_hex(hex)

Create a ColorRGB from an RGB hex value. Accepts a string ("#rrggbb") or integer (0xRRGGBB).

Parameters:

hex (str | int) – Hex color as string or integer.

Return type:

ion.types.ColorRGB

copy(self)

Return a mutable (unfrozen) copy.

Return type:

ColorRGB

freeze(self)

Freeze this value, making it read-only and hashable. Returns self for convenience (e.g. d[p.freeze()] = v).

Return type:

Self

lerp(self, other, factor)

Linearly interpolate between this color and other.

Parameters:

  • other (ColorRGB | tuple[float, float, float]) – Target color.

  • factor (float) – Blend factor (0.0-1.0).

Return type:

ion.types.ColorRGB

offset(self, value)

Add a uniform value to all channels (clamped to 0.0-1.0).

Parameters:

value (float) – Value to add to each channel.

Return type:

ion.types.ColorRGB

to_hex(self)

Convert to hex string ("#rrggbb").

Return type:

str

to_rgba(self, alpha=1.0)

Convert to RGBA with the given alpha.

Parameters:

alpha (float) – Alpha component (default 1.0).

Return type:

ion.types.ColorRGBA

to_tuple(self)

Convert to tuple (r, g, b).

Returns:

Tuple (r, g, b).

Return type:

tuple[float, float, float]

is_frozen

Whether this value is frozen (read-only).

Type:

bool

Special Methods
__copy__(self)
Return type:

ColorRGB

__deepcopy__(self, memo)
Parameters:

memo (dict) – Memoization dict for shared subobjects.

Return type:

ColorRGB

__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__format__(self, format_spec)
Parameters:

format_spec (str) – Format spec applied per component (empty spec returns repr(self)).

Return type:

str

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

__setitem__(self, key, value)

Set self[key] to value.

Parameters:

  • key (int) – Index or key.

  • value (object) – Value to assign.

class ion.types.ColorRGBA

RGBA color with components in 0.0-1.0 range, accessed via [0]..[3].

__init__(self, rgba)
Parameters:

rgba (ColorRGBA | tuple[float, float, float, float]) – RGBA components in 0.0-1.0 range.

Return type:

None

__getitem__(self, index)

Get an item by index.

Parameters:

index (int) – 0 for red, 1 for green, 2 for blue, 3 for alpha.

Return type:

float

__getitem__(self, index)
Parameters:

index (slice) – A slice over the four components.

Return type:

tuple[float, …]

__len__(self)

Return the number of components (always 4).

Return type:

int

__iter__(self)

Iterate over components (r, g, b, a).

Return type:

Iterator[float]

classmethod from_rgb_hex(hex)

Create a ColorRGBA from an RGB hex value. Alpha defaults to 1.0. Accepts a string ("#rrggbb") or integer (0xRRGGBB).

Parameters:

hex (str | int) – Hex color as string or integer.

Return type:

ion.types.ColorRGBA

classmethod from_rgba_hex(hex)

Create a ColorRGBA from an RGBA hex value. Accepts a string ("#rrggbbaa") or integer (0xRRGGBBAA).

Parameters:

hex (str | int) – Hex color as string or integer.

Return type:

ion.types.ColorRGBA

copy(self)

Return a mutable (unfrozen) copy.

Return type:

ColorRGBA

freeze(self)

Freeze this value, making it read-only and hashable. Returns self for convenience (e.g. d[p.freeze()] = v).

Return type:

Self

lerp(self, other, factor)

Linearly interpolate between this color and other. A factor of 0.0 returns this color; 1.0 returns other. All four components (including alpha) are interpolated.

Parameters:

  • other (ColorRGBA | tuple[float, float, float, float]) – Target color.

  • factor (float) – Blend factor (0.0-1.0).

Return type:

ion.types.ColorRGBA

offset(self, value)

Add a uniform value to the R, G, B channels (clamped to 0.0-1.0). Alpha is preserved. Use positive values to brighten, negative to dim, without affecting saturation.

Parameters:

value (float) – Value to add to each RGB channel.

Return type:

ion.types.ColorRGBA

to_hex(self)

Convert to hex string ("#rrggbb" or "#rrggbbaa" if alpha != 1.0).

Returns:

Hex string ("#rrggbb" or "#rrggbbaa").

Return type:

str

to_rgb(self)

Convert to RGB, dropping the alpha channel.

Return type:

ion.types.ColorRGB

to_tuple(self)

Convert to tuple (r, g, b, a).

Returns:

Tuple (r, g, b, a).

Return type:

tuple[float, float, float, float]

is_frozen

Whether this value is frozen (read-only).

Type:

bool

Special Methods
__copy__(self)
Return type:

ColorRGBA

__deepcopy__(self, memo)
Parameters:

memo (dict) – Memoization dict for shared subobjects.

Return type:

ColorRGBA

__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__format__(self, format_spec)
Parameters:

format_spec (str) – Format spec applied per component (empty spec returns repr(self)).

Return type:

str

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

__setitem__(self, key, value)

Set self[key] to value.

Parameters:

  • key (int) – Index or key.

  • value (object) – Value to assign.

class ion.types.ContextAccessor

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.

capture(self)

Capture the current action context as an opaque snapshot, for replaying later. A region installs this context for the click (e.g. the divider’s split), so capturing it pins a menu operator to the same elements it was drawn against, even after the menu has closed.

Returns:

A snapshot of the active context, or None when none is set.

Return type:

ion.types.ContextSnapshot | None

button

The pointer button that triggered this action, or None when the action was not invoked by a pointer event.

Live only for the duration of a pointer-only operator’s dispatch and cleared afterwards, so reading it outside a live pointer event yields None. Codes match ion.constants.pointer_buttons.

Type:

int | None

desktop

The active desktop for this context: the overriding desktop if a region set one, else the active desktop, or None.

Type:

ion.types.Desktop | None

frame

The frame this context targets: the overriding frame if a region set one, else the focused frame, or None.

Type:

ion.types.Frame | None

output

The output this context targets: the overriding output if a region set one (the pointer’s output for a click), else the focused output, or None. For the output of a specific frame or split, use that object’s own accessors instead.

Type:

ion.types.Output | None

split

The split whose divider is under the pointer, or None when not over a divider. A divider is the boundary of a split, so this is the split. Override-only: a split has no focus to look up.

Type:

ion.types.SplitNodeContainer | None

window

The window this context targets: the overriding tab if a region set one (a clicked tab), else the focused window, or None.

Type:

ion.types.Window | None

workspace

The workspace this context targets: the overriding workspace if a region set one, else the focused workspace, or None.

Type:

ion.types.Workspace | None

class ion.types.ContextSnapshot

Opaque snapshot of action-context values, replayed as the action context when a menu item is activated.

Built by ContextAccessor.capture() (the region’s live context) and by ContextSnapshot.build() (explicit values a layout stores for an operator). The stored values become the context the operator runs against.

class ContextSnapshot
static build(base=None, *, window=None, frame=None, split=None, output=None, workspace=None, desktop=None)

Build a snapshot from explicit context values merged over an optional base snapshot: each value given replaces that attribute, and the rest fall back to base. Returns None when the result is empty.

This is how ion.types.UILayout stores per-operator overrides (e.g. the divider a menu item should act on) without touching the live context.

Parameters:
Returns:

The merged snapshot, or None when no value is set.

Return type:

ion.types.ContextSnapshot | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.CursorPreferences

Cursor appearance preferences.

A write reaches the compositor’s own cursor when the dispatch returns. Child processes are the exception: they read XCURSOR_THEME / XCURSOR_SIZE, which the compositor writes once as the backend is created, so already-running and later-spawned children alike keep the startup values.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

size

Cursor size in pixels (default: XCURSOR_SIZE, or 24).

Zero, or a size above the largest the compositor can scale, is substituted on assignment and logged, so reading the property back always gives the size in effect.

Type:

int

theme

Cursor theme name (default: XCURSOR_THEME, or “default”).

An empty name matches no theme, so it is substituted on assignment and logged, as an out-of-range size is.

Type:

str

Special Methods
__repr__(self)
Return type:

str

class ion.types.CursorToken

Opaque cursor stack token.

Returned by ion.wm.cursor_push(). Pass to ion.wm.cursor_pop() to pop this entry and any later ones.

class CursorToken
Special Methods
__repr__(self)
Return type:

str

class ion.types.Decor

Decoration configuration (geometry and visual properties).

geom

Decoration geometry, values that impact the layout.

Type:

DecorGeom

look

Visual decoration properties (colors, bevel settings).

Type:

DecorLook

Special Methods
__repr__(self)
Return type:

str

class ion.types.DecorGeom

Decoration geometry (divider width, window pad, titlebar height).

divider_width

Width of frame dividers in pixels.

Type:

int

tab_pad

Padding of the border drawn around each tab, in pixels (0 disables it).

Painted over the window_pad border rather than added to it, so a tab_pad of 3 with a window_pad of 5 shows 3px in the ion.app.decor.look.tab_pad color and 2px in the ion.app.decor.look.window_pad color. The color defaults to black, matching window_pad; set a contrasting color to visualize tab padding (a dragged tab shows the full border, as it has no window_pad border behind it).

Type:

int

titlebar_height

Height of window titlebars in pixels.

Type:

int

titlebar_icon_size

Size of titlebar tab icons in logical pixels (square).

Type:

int

window_pad

Padding of the border between a tiled window and an adjacent divider, in pixels (0 disables it).

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.DecorLook

Visual decoration properties (colors, bevel width).

Every color property accepts a ColorRGB or a tuple[float, float, float] when set.

bevel_highlight

Default bevel highlight.

Type:

ion.types.ColorRGB

bevel_shadow

Default bevel shadow.

Type:

ion.types.ColorRGB

bevel_width

Bevel line width in pixels.

Type:

int

border

Border color.

Type:

ion.types.ColorRGB

divider

Divider fill color.

Type:

ion.types.ColorRGB

floating_border

Floating border color (outline around floating window/workspace borders).

Type:

ion.types.ColorRGB

menu_bevel_highlight

Menu bevel highlight color.

Type:

ion.types.ColorRGB

menu_bevel_shadow

Menu bevel shadow color.

Type:

ion.types.ColorRGB

menu_bg

Menu background color.

Type:

ion.types.ColorRGB

menu_text

Menu text color (hovered items).

Type:

ion.types.ColorRGB

menu_text_inactive

Menu text color for inactive (non-hovered) items.

Type:

ion.types.ColorRGB

tab_focused_active

Active tab in focused frame.

Type:

ion.types.ColorRGB

tab_focused_active_bevel_highlight

Bevel highlight for focused active tab.

Type:

ion.types.ColorRGB

tab_focused_active_bevel_shadow

Bevel shadow for focused active tab.

Type:

ion.types.ColorRGB

tab_focused_inactive

Inactive tab in focused frame.

Type:

ion.types.ColorRGB

tab_pad

Color of the tab padding border (drawn around each tab).

Type:

ion.types.ColorRGB

tab_unfocused_active

Active tab in unfocused frame.

Type:

ion.types.ColorRGB

tab_unfocused_active_bevel_highlight

Bevel highlight for unfocused active tab.

Type:

ion.types.ColorRGB

tab_unfocused_active_bevel_shadow

Bevel shadow for unfocused active tab.

Type:

ion.types.ColorRGB

tab_unfocused_inactive

Inactive tab in unfocused frame.

Type:

ion.types.ColorRGB

tab_urgent

Urgent tab (wants attention).

Type:

ion.types.ColorRGB

tab_urgent_bevel_highlight

Bevel highlight for urgent tab.

Type:

ion.types.ColorRGB

tab_urgent_bevel_shadow

Bevel shadow for urgent tab.

Type:

ion.types.ColorRGB

text_disabled

Text color for disabled items.

Type:

ion.types.ColorRGB

text_focused_active

Text color for focused active tab.

Type:

ion.types.ColorRGB

text_inactive

Text color for inactive tabs.

Type:

ion.types.ColorRGB

text_urgent

Text color for urgent tabs.

Type:

ion.types.ColorRGB

window_pad

Color of the window padding border (between a tiled window and an adjacent divider).

Type:

ion.types.ColorRGB

Special Methods
__repr__(self)
Return type:

str

class ion.types.DecorPreferences

Decoration preferences: the compositor’s base fill colors and the window decoration mode.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

desktop_color

Desktop background color.

Setting accepts a ColorRGB or tuple[float, float, float].

Type:

ion.types.ColorRGB

empty_frame_color

Empty frame content area color.

Setting accepts a ColorRGB or tuple[float, float, float].

Type:

ion.types.ColorRGB

fullscreen_frame_color

Fullscreen frame container color.

Setting accepts a ColorRGB or tuple[float, float, float].

Type:

ion.types.ColorRGB

mode

Window decoration mode (default: "SERVER").

Type:

Literal[“SERVER”, “CLIENT”, “NONE”]

Special Methods
__repr__(self)
Return type:

str

class ion.types.Desktop

A desktop groups floating windows and per-output workspace assignments (see Proxy objects).

focus(self)

Switch to this desktop.

Returns:

None.

Return type:

None

data

Per-desktop dictionary for script-defined data.

Created on first access and persists for the lifetime of the desktop. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

id

Unique numeric identifier for this desktop (read-only).

Stable for the lifetime of the desktop regardless of ordering or other desktops being added or removed. Not reused after the desktop is removed.

Type:

int

is_empty

Whether this desktop contains no windows (read-only). A desktop must be empty before it can be removed via remove().

Type:

bool

is_valid

Whether this desktop still exists in the compositor (read-only).

Type:

bool

items_floating

Floating layer entries on this desktop (read-only).

Type:

ion.types.DesktopFloatingCollection

items_tiling

Tiling layer entries on this desktop (read-only).

Type:

ion.types.DesktopTilingCollection

name

Desktop name.

Type:

str

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.DesktopCollection

Collection accessor for desktops (ion.wm.desktops).

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Desktop) – The desktop to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Desktop]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Desktop]

__getitem__(self, key)

Get a desktop by name or index. Supports negative indices.

Parameters:

key (str | int) – Desktop name, or zero-based index.

Return type:

Desktop

__getitem__(self, key)
Parameters:

key (slice) – A slice over the desktops.

Return type:

tuple[Desktop, …]

find_adjacent(self, layout, desktop, direction, wrap=True)

Find the adjacent desktop in a spatial layout.

Returns the desktop in the neighboring grid cell, or None. When wrap is true, wraps to the opposite end of the same row or column.

Parameters:

  • layout (list[tuple[tuple[int, int], Desktop]]) – Layout from layout_calc().

  • desktop (Desktop) – The reference desktop.

  • direction (Literal['LEFT', 'RIGHT', 'UP', 'DOWN']) – 'LEFT', 'RIGHT', 'UP', or 'DOWN'.

  • wrap (bool) – Wrap to the opposite end of the same row or column. Defaults to True.

Returns:

The adjacent desktop, or None.

Return type:

Desktop | None

find_by_frame(self, frame)

Find the desktop containing the given frame.

Parameters:

frame (ion.types.Frame) – The frame to search for.

Returns:

The desktop containing the frame, or None if not found.

Return type:

ion.types.Desktop | None

find_by_id(self, id)

Look up a desktop by its unique numeric id.

Parameters:

id (int) – The desktop ID to look up.

Returns:

The desktop, or None if no matching desktop exists.

Return type:

Desktop | None

find_by_item(self, item)

Find the desktop containing the given floating or tiling item.

Parameters:

item (ion.types.DesktopItemFloating | ion.types.DesktopItemTiling) – A floating or tiling desktop item.

Returns:

The desktop containing the item, or None if not found.

Return type:

ion.types.Desktop | None

find_by_window(self, window)

Find the desktop containing the given window.

Parameters:

window (ion.types.Window) – The window to search for.

Returns:

The desktop containing the window, or None if not found.

Return type:

ion.types.Desktop | None

find_by_workspace(self, workspace)

Find the desktop containing the given workspace.

Parameters:

workspace (ion.types.Workspace) – The workspace to search for.

Returns:

The desktop containing the workspace, or None if not found.

Return type:

ion.types.Desktop | None

get(self, name)

Get a desktop by name.

Parameters:

name (str) – The desktop name.

Returns:

The desktop, or None if not found.

Return type:

ion.types.Desktop | None

index(self, desktop)

Return the index of a desktop in the collection.

Parameters:

desktop (ion.types.Desktop) – The desktop to find.

Return type:

int

Raises:

ValueError – If the desktop is not in the collection.

items(self)

All (name, desktop) pairs.

Returns:

List of (name, desktop) tuples.

Return type:

list[tuple[str, ion.types.Desktop]]

keys(self)

All desktop names.

Returns:

List of desktop name strings.

Return type:

list[str]

layout_calc(self, desktops=None)

Query desktop layout providers, falling back to a grid.

Iterates ion.types.SystemPreferences.desktop_layout_providers in order. The first provider that returns a non-None result wins. If no provider returns a result, a grid layout is used. Providers that raise exceptions are logged and skipped.

An empty list is a valid result (desktop operations become no-ops).

Parameters:

desktops (list[Desktop] | None) – Optional subset of desktops. When None, all desktops are used.

Returns:

List of ((x_index, y_index), desktop) pairs.

Return type:

list[tuple[tuple[int, int], Desktop]]

new(self, name='')

Create a new desktop with the given name.

If a desktop with that name already exists, a unique name is generated by appending a number (e.g., “work.1”, “work.2”). When name is empty, a numbered name is generated automatically.

Parameters:

name (str) – Base name for the new desktop.

Returns:

The newly created desktop.

Return type:

ion.types.Desktop

remove(self, desktop)

Remove a desktop (must be empty, cannot be the last).

Parameters:

desktop (ion.types.Desktop) – The desktop to remove.

Raises:

RuntimeError – If the desktop is not empty or is the last desktop.

Return type:

None

sort(self, key)

Sort desktops by a key function, similar to list.sort(key=...).

Parameters:

key (Callable[[Desktop], Any]) – Callable taking a Desktop and returning a comparable value.

Return type:

None

active

Currently active desktop (read-only). Use Desktop.focus() to queue a desktop to become active.

Type:

ion.types.Desktop

Special Methods
__repr__(self)
Return type:

str

class ion.types.DesktopFloatingCollection

Floating item collection for a desktop (see Proxy objects).

Access via Desktop.items_floating.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the floating layer has any entries.

Return type:

bool

__contains__(self, value)

Check whether a floating entry is on this desktop.

Parameters:

value (DesktopItemFloating) – The floating entry to check for membership.

Return type:

bool

__iter__(self)

Iterate over all floating entries (bottom to top).

Return type:

Iterator[DesktopItemFloating]

__reversed__(self)

Iterate over all floating entries top to bottom (front to back).

Return type:

Iterator[DesktopItemFloating]

__getitem__(self, index)

Get a floating entry by depth index. Supports negative indices.

Parameters:

index (int) – Zero-based depth index (0 is the bottom).

Return type:

DesktopItemFloating

__getitem__(self, index)
Parameters:

index (slice) – A slice over the floating entries, bottom to top.

Return type:

tuple[DesktopItemFloating, …]

add(self, workspace)

Add a workspace as a floating overlay on this desktop.

A workspace already floating on another desktop is moved here (the previous floating entry is removed - floating ownership is exclusive across desktops). A workspace tiled on any desktop is orphaned from tiling first; the workspace_unmap_tiling_post hook fires before the floating overlay is shown, and Workspace.floating_rect is overwritten with the tile rect so the overlay appears at the same visible position. Orphan workspaces (created via WorkspaceCollection.new() with a caller-supplied rect, or via WorkspaceCollection.new_from_split_node() which seeds the rect from the extracted node) are placed using their existing Workspace.floating_rect.

Parameters:

workspace (Workspace) – The workspace to add.

Returns:

The floating entry, or None if the workspace is already on this desktop’s floating layer.

Return type:

DesktopItemFloatingWorkspace | None

Raises:

ValueError – If the workspace’s floating_rect is empty (zero or inverted).

depth_sort(self, key)

Sort floating entries by a key function, similar to list.sort(key=...). Depth 0 gets the item with the smallest key value (back), highest depth gets the largest (front).

Parameters:

key (Callable[[DesktopItemFloating], Any]) – Callable taking a DesktopItemFloating and returning a comparable value.

Return type:

None

depth_swap(self, a, b)

Swap the depth positions of two floating entries.

Parameters:
Return type:

None

Raises:

  • ReferenceError – If either entry no longer exists.

  • ValueError – If either entry is on a different desktop.

depth_to_back(self, items)

Move the given entries to the back of the floating layer, preserving their relative order. Entries not in the sequence keep their original order at the front.

Parameters:

items (Sequence[DesktopItemFloating]) – Entries to lower (must be unique, must belong to this desktop).

Return type:

None

depth_to_front(self, items)

Move the given entries to the front of the floating layer, preserving their relative order. Entries not in the sequence keep their original order at the back.

Parameters:

items (Sequence[DesktopItemFloating]) – Entries to raise (must be unique, must belong to this desktop).

Return type:

None

find_by_frame(self, frame)

Find a floating entry by frame.

Parameters:

frame (Frame) – The frame to search for.

Returns:

The floating entry, or None if the frame is not in the floating layer.

Return type:

DesktopItemFloatingFrame | None

find_by_workspace(self, workspace)

Find a floating entry by workspace.

Parameters:

workspace (Workspace) – The workspace to search for.

Returns:

The floating entry, or None if the workspace is not in the floating layer.

Return type:

DesktopItemFloatingWorkspace | None

index(self, item)

Return the depth index of a floating entry.

Parameters:

item (DesktopItemFloating) – The floating entry to find.

Return type:

int

Raises:

ValueError – If the entry is not in the collection.

remove(self, item)

Remove a floating workspace overlay from this desktop.

Parameters:

item (DesktopItemFloatingWorkspace) – The floating workspace entry to remove.

Return type:

None

Raises:

ValueError – If the workspace overlay is not on this desktop.

active

The focused floating entry, or None when focus is on the tiling layer.

Type:

DesktopItemFloating | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.DesktopItemFloating

A floating layer entry (see Proxy objects).

Base class for DesktopItemFloatingFrame and DesktopItemFloatingWorkspace.

depth_to_back(self)

Lower this floating item to the back of the z-order.

Returns:

None.

Return type:

None

Raises:

ReferenceError – If this entry no longer exists.

depth_to_front(self)

Raise this floating item to the front of the z-order.

Returns:

None.

Return type:

None

Raises:

ReferenceError – If this entry no longer exists.

move_to_desktop(self, desktop)

Move this floating item to another desktop, keeping its rect, visibility, contents and stacking intact (appended topmost on the target). No-op when the item is already on the target desktop.

Parameters:

desktop (ion.types.Desktop) – The target desktop.

Returns:

None.

Return type:

None

Raises:

ReferenceError – If this entry no longer exists.

move_to_output(self, output, pointer_warp=True)

Move this floating item to a different output, remapping its position proportionally.

Parameters:

  • output (ion.types.Output) – The target output.

  • pointer_warp (bool) – Whether the pointer will be warped to follow the item. When false and focus-follows-pointer is enabled, focus updates to whatever is under the pointer.

Returns:

None.

Return type:

None

Raises:

ReferenceError – If this entry no longer exists.

depth

Depth index (0 = back, higher = closer to front).

Type:

int

is_valid

Whether this floating entry still exists on its desktop (read-only).

Type:

bool

rect

Bounding rectangle in logical pixels.

Setting accepts a Rect or a (min, max) pair of points.

Type:

ion.types.Rect

visible

Whether this entry is visible.

Assigning is the scratchpad toggle: hiding drops the fullscreen tracking of a window inside the entry and recovers focus when the entry held it, and showing promotes that window again.

A DesktopItemFloatingWorkspace is on the floating layer only while its overlay is shown, so this always reads True: assigning False removes the overlay from the desktop the entry belongs to, exactly as DesktopFloatingCollection.remove() does, and assigning True does nothing. Showing an overlay again goes through DesktopFloatingCollection.add().

Type:

bool

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.DesktopItemFloatingFrame(DesktopItemFloating)

A floating frame entry (see Proxy objects).

frame

The frame contained in this floating entry.

Type:

ion.types.Frame

class ion.types.DesktopItemFloatingWorkspace(DesktopItemFloating)

A floating workspace overlay entry (see Proxy objects).

workspace

The workspace contained in this floating entry.

Type:

ion.types.Workspace

class ion.types.DesktopItemTiling

A tiling layer entry on a desktop (see Proxy objects).

is_valid

Whether this workspace is still tiled on a desktop (read-only).

Type:

bool

output

Output this tiling entry is assigned to, or None for unified (spanning all outputs).

Type:

ion.types.Output | None

rect

Bounding rectangle in logical pixels (read-only). For per-output entries this is the output’s usable area; for unified entries it spans all outputs.

Type:

ion.types.Rect

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.DesktopItemTilingFrame

A tiling frame reference for use with OverlayDesktopItem.

__init__(self, frame)
Parameters:

frame (Frame) – The tiled frame.

Return type:

None

frame

The frame contained in this tiling entry.

Type:

ion.types.Frame

is_valid

Whether the referenced frame still exists (read-only).

Type:

bool

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.DesktopItemTilingWorkspace(DesktopItemTiling)

A tiling workspace entry (see Proxy objects).

workspace

The workspace contained in this tiling entry.

Type:

ion.types.Workspace

class ion.types.DesktopTilingCollection

Tiling item collection for a desktop (see Proxy objects).

Access via Desktop.items_tiling.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the desktop has any tiling entries.

Return type:

bool

__contains__(self, value)

Check whether a tiling entry is on this desktop.

Parameters:

value (DesktopItemTiling) – The tiling entry to check for membership.

Return type:

bool

__iter__(self)

Iterate over all tiling entries.

Return type:

Iterator[DesktopItemTiling]

__reversed__(self)

Iterate over all tiling entries in reverse order.

Return type:

Iterator[DesktopItemTiling]

__getitem__(self, index)

Get a tiling entry by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the tiling entry to retrieve.

Return type:

DesktopItemTiling

__getitem__(self, index)
Parameters:

index (slice) – A slice over the tiling entries.

Return type:

tuple[DesktopItemTiling, …]

add(self, workspace, output=None)

Add a workspace to this desktop’s tiling layer.

A workspace currently shown as a floating overlay on any desktop is auto-removed from the floating layer first. Orphan workspaces (created via WorkspaceCollection.new() or WorkspaceCollection.new_from_split_node()) are also accepted.

When output is None the workspace spans all outputs. When an Output is given the workspace is confined to that output.

A window that was fullscreen in the workspace takes its output back, whether or not focus lands on that window.

Parameters:

  • workspace (Workspace) – The workspace to tile.

  • output (Output | None) – The target output, or None for all outputs.

Returns:

The tiling entry, or None if the workspace is already tiled on any desktop.

Return type:

DesktopItemTilingWorkspace | None

find_by_output(self, output)

Find the tiling entry assigned to a specific output.

For unified desktops this returns the first entry (since all workspaces span every output). For per-output desktops it returns the entry confined to that output.

Parameters:

output (Output) – The output to look up.

Returns:

The tiling entry, or None if no workspace is assigned.

Return type:

DesktopItemTiling | None

find_by_workspace(self, workspace)

Find a tiling entry by workspace.

Parameters:

workspace (Workspace) – The workspace to search for.

Returns:

The tiling entry, or None if the workspace is not in the tiling layer.

Return type:

DesktopItemTilingWorkspace | None

index(self, item)

Return the index of a tiling entry.

Parameters:

item (DesktopItemTiling) – The tiling entry to find.

Return type:

int

Raises:

ValueError – If the entry is not in the collection.

remove(self, item)

Remove a tiling entry from this desktop.

The workspace’s Workspace.floating_rect is left unchanged. To surface the workspace as a floating overlay afterwards, assign DesktopItemTiling.rect first:

workspace.floating_rect = item.rect
desktop.items_tiling.remove(item)
desktop.items_floating.add(workspace)

The workspace stops being a container the user can see, so focus recovers off it when it held focus - onto the frame under the pointer when focus-follows-mouse is enabled - and a window it had fullscreen gives up its output. add() restores both.

Parameters:

item (DesktopItemTiling) – The tiling entry to remove.

Return type:

None

Raises:

ValueError – If the entry is not on this desktop.

active

The focused tiling entry, or None when focus is on the floating layer.

Type:

DesktopItemTiling | None

has_all_output

Whether this desktop has any all-output (spanning) workspaces (read-only).

Type:

bool

has_per_output

Whether this desktop has any per-output (confined) workspaces (read-only).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.Direction

Direction enum.

DOWN
Type:

str

Value:

‘DOWN’

LEFT
Type:

str

Value:

‘LEFT’

RIGHT
Type:

str

Value:

‘RIGHT’

UP
Type:

str

Value:

‘UP’

class ion.types.Event

Base type for input events.

Every event carries the held modifier flags and cursor position at the time it was created.

__init__(self, *, modifiers, position)
Parameters:
Return type:

None

modifiers

Held modifier flags (bitmask of ion.constants.modifiers constants).

Type:

int

position

Cursor position in logical coordinates.

Type:

Point

time_stamp

Monotonic timestamp in milliseconds.

An event delivered by the compositor carries the time the input arrived, and a constructor taking a time_stamp carries what it was given. The kinds whose constructor takes none - EventTimer, EventCancel, EventMenu, EventCommand and Event itself - are generated rather than delivered and hold 0, since the moment one is built is not the moment it is handled.

Take that from the kind, never from the value: 0 is a real time like any other on a wrapping counter, so it marks nothing.

Do not compare stamps of different kinds. A generated kind’s is read when the compositor dispatches it, where an input kind’s comes from the kernel before the compositor woke, so the two are not ordered against each other. Use time for elapsed wall time in a generator.

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventCancel(Event)

Sent to a generator when it is cancelled (e.g. compositor shutdown).

__init__(self, *, modifiers, position)
Parameters:
Return type:

None

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventCommand(Event)

Sent to an operator when it is invoked by an IPC command or test harness.

__init__(self, *, modifiers=None, position=None)
Parameters:

  • modifiers (int | None) – Modifier bitmask, or None for current keyboard state.

  • position (Point | tuple[int, int] | None) – Pointer position, or None for current pointer location.

Return type:

None

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventKey(Event)

Keyboard event.

__init__(self, key, press, *, modifiers, position, time_stamp)
Parameters:

  • key (int) – Key code (see ion.constants.keys).

  • press (bool) – True for press, False for release.

  • modifiers (int) – Modifier bitmask (see ion.constants.modifiers).

  • position (Point | tuple[int, int]) – Pointer position.

  • time_stamp (int) – Monotonic timestamp in milliseconds.

Return type:

None

key

The keysym code.

Type:

int

press

True for key press, False for key release.

Type:

bool

text

The printable character for this key, or empty string for non-printable keys.

Type:

str

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventMenu(Event)

Sent to an operator when it is invoked from a menu.

__init__(self, *, modifiers, position)
Parameters:
Return type:

None

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventMotion(Event)

Pointer motion event sent to a generator.

The cursor position is available via the inherited position attribute.

__init__(self, position, *, modifiers, time_stamp)
Parameters:

  • position (Point | tuple[int, int]) – Pointer position.

  • modifiers (int) – Modifier bitmask (see ion.constants.modifiers).

  • time_stamp (int) – Monotonic timestamp in milliseconds.

Return type:

None

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventPointer(Event)

Pointer button event.

__init__(self, button, press, *, modifiers, position, time_stamp)
Parameters:

  • button (int) – Pointer button code (see ion.constants.pointer_buttons).

  • press (bool) – True for press, False for release.

  • modifiers (int) – Modifier bitmask (see ion.constants.modifiers).

  • position (Point | tuple[int, int]) – Pointer position.

  • time_stamp (int) – Monotonic timestamp in milliseconds.

Return type:

None

button

The mouse button code.

Type:

int

press

True for button press, False for button release.

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventScroll(Event)

Scroll (axis) event sent to a generator.

__init__(self, delta_x, delta_y, *, modifiers, position, time_stamp)
Parameters:

  • delta_x (float) – Horizontal scroll delta.

  • delta_y (float) – Vertical scroll delta.

  • modifiers (int) – Modifier bitmask (see ion.constants.modifiers).

  • position (Point | tuple[int, int]) – Pointer position.

  • time_stamp (int) – Monotonic timestamp in milliseconds.

Return type:

None

delta_x

Horizontal scroll amount (positive = right).

Type:

float

delta_y

Vertical scroll amount (positive = down).

Type:

float

Special Methods
__repr__(self)
Return type:

str

class ion.types.EventTimer(Event)

Sent to a generator when its GeneratorStep(time=<ms>) delay elapses.

__init__(self, *, modifiers, position)
Parameters:
Return type:

None

Special Methods
__repr__(self)
Return type:

str

class ion.types.FloatingPreferences

Floating window placement preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

auto_float_dialog

Automatically float dialog windows (those with a parent) (default: True).

Type:

bool

auto_float_fixed_size

Automatically float fixed-size windows where min and max size are equal (default: True).

Type:

bool

corner_resize_size

Size of the corner grab zone in logical pixels (default: 12).

Controls how far along each edge the corner resize zones extend. Larger values make corners easier to grab; smaller values give more room for straight-edge resizing.

Type:

int

size_min

Minimum size for floating windows during interactive resize (default: 100).

This is the smallest width or height (in logical pixels) that a floating window can be resized to. Changing this at run-time only affects future resize operations; existing windows are not resized.

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.FocusPreferences

Window focus behavior preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

double_click_time

Maximum interval in milliseconds between two clicks for double-click detection (default: 400).

Type:

int

drag_threshold

Pointer motion threshold in logical pixels for drag detection (default: 3).

Type:

int

on_activation

Window activation behavior (default: "SMART").

Type:

Literal[“SMART”, “FOCUS”, “URGENT”, “NONE”]

pointer_click_to_raise

Clicking a floating window raises it to the top (default: True).

Type:

bool

pointer_follow

Focus follows mouse pointer (default: False).

Type:

bool

pointer_warp

Warp mouse to focused frame on directional focus change (default: True).

Type:

bool

pointer_warp_factor

Position factor (x, y) within frame for pointer warp. Each value is 0.0-1.0 where (0.0, 0.0)=top-left, (0.5, 0.5)=center, (1.0, 1.0)=bottom-right.

Type:

tuple[float, float]

pointer_warp_margin

Margin in pixels to inset from frame edges when warping (default: 5).

A negative margin is substituted on assignment and logged.

Type:

int

switch_to_new

Focus newly created windows (default: True).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.FontParams

Per-font rendering parameters (face pattern + vertical offset).

face

Font pattern in fontconfig format (e.g. "monospace:size=10").

Type:

str

offset_y

Vertical text offset as a fraction of the font’s full height.

Positive values shift text down, negative values up. The effective range is -1.0 to 1.0; either extreme moves the text fully outside the visible area. Default: 0.0.

Type:

float

Special Methods
__repr__(self)
Return type:

str

class ion.types.FontPreferences

Font rendering preferences.

reset(self)

Reset both fonts to their defaults, in place so held references stay valid. Marks the fonts group.

Return type:

None

message_font

Popup/message font (face pattern and vertical offset).

Type:

ion.types.FontParams

titlebar_font

Titlebar font (face pattern and vertical offset).

Type:

ion.types.FontParams

Special Methods
__repr__(self)
Return type:

str

class ion.types.Frame

A tiling frame that holds one or more tabbed windows (see Proxy objects).

attach_tagged(self)

Attach all tagged windows to this frame as tabs.

Returns:

Whether any tagged windows were attached.

Return type:

bool

focus(self)

Focus this frame.

Returns:

None.

Return type:

None

pointer_warp(self)

Warp the pointer to this frame unconditionally.

The pointer lands on preferences.focus.pointer_warp_factor, with no relative place kept from wherever it came.

Returns:

None.

Return type:

None

pointer_warp_if_needed(self)

Warp the pointer to this frame only if the pointer is not already inside it.

A pointer sitting in another frame keeps its relative place there, landing at the matching point in this one, so a window move the cursor follows does not throw it across the frame. This needs preferences.focus.pointer_follow; without it the pointer lands on preferences.focus.pointer_warp_factor, as it does when no frame holds the pointer.

Ask for the warp while the frame the cursor is leaving still exists. Tiling a floating window drops its frame, so a warp asked for after the move reads the tiled frame underneath instead.

Returns:

True if the pointer was warped, False otherwise.

Return type:

bool

tab_move_cycle(self, direction)

Move the current tab to the next/previous position in this frame.

Wraps around: moving past either end trades places with the tab at the opposite end, rather than shifting the others along.

Parameters:

direction (int) – Positive for next, negative for previous.

Returns:

None.

Return type:

None

tile(self)

Tile this floating workspace frame back into the tiling workspace on the active output.

Returns:

The target frame’s split node, or None if tiling failed (including a frame the active desktop does not show).

Return type:

SplitNodeLeaf | None

window_reorder(self, window, index)

Move a window to a different position within this frame’s tab bar.

Parameters:

  • window (Window) – The window to reorder.

  • index (int) – New tab position. Negative indices count from the end (Python-style).

Return type:

None

active_index

Index of the active tab (0-based) (read-only).

Type:

int

content_rect

Frame content rectangle, excluding the tab bar and border, or None if the frame is not currently placed (read-only).

Derived from frame geometry, so it is defined even for an empty frame with no window. For a floating frame this equals the frame rect, since its tab bar and border are drawn outside the frame rect.

Type:

ion.types.Rect | None

data

Per-frame dictionary for script-defined data.

Created on first access and persists for the lifetime of the frame. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

id

Unique numeric identifier for this frame (read-only).

Stable for the lifetime of the frame regardless of workspace, output, or desktop changes. Not reused after the frame is removed.

Type:

int

is_floating

Whether this frame is floating (read-only).

Type:

bool

is_focused

Whether this frame is focused (read-only).

Type:

bool

is_valid

Whether this frame still exists in the compositor (read-only).

Type:

bool

split_node

Split tree leaf node for this frame, or None if not in a workspace (read-only).

Type:

ion.types.SplitNodeLeaf | None

windows

All windows in this frame (read-only).

Type:

ion.types.FrameWindowCollection

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.FrameCollection

Collection accessor for frames.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Frame) – The frame to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Frame]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Frame]

__getitem__(self, index)

Get a frame by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the frame.

Return type:

Frame

__getitem__(self, index)
Parameters:

index (slice) – A slice over the frames.

Return type:

tuple[Frame, …]

find_by_id(self, id)

Look up a frame by its unique numeric id.

Parameters:

id (int) – The frame ID to look up.

Returns:

The frame, or None if no frame with that ID exists.

Return type:

Frame | None

find_by_window(self, window)

Find the frame containing the given window.

Parameters:

window (ion.types.Window) – The window to search for.

Returns:

The frame, or None if the window is floating or not found.

Return type:

ion.types.Frame | None

find_isect_all_point(self, point)

Find all frames containing the given point.

Floating frames are included alongside the tiled frames they cover, so a point over a floating window returns both. The ordering is geometric, not z-order.

The query is purely geometric: a frame keeps its rect while off screen - on a hidden workspace or an inactive desktop - so it still matches. Filter the result on what you need to restrict it to what is visible.

Parameters:

point (ion.types.Point | tuple[int, int]) – The position to look up.

Returns:

Frames containing the point, most interior first.

Return type:

list[ion.types.Frame]

find_isect_all_rect(self, rect)

Find all frames intersecting the given rectangle.

Floating frames are included alongside the tiled frames they cover, so a rect over a floating window returns both. The ordering is geometric, not z-order.

The query is purely geometric: a frame keeps its rect while off screen - on a hidden workspace or an inactive desktop - so it still matches. Filter the result on what you need to restrict it to what is visible.

Parameters:

rect (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – The area to check.

Returns:

Frames intersecting the rectangle, ordered by intersection area (largest first).

Return type:

list[ion.types.Frame]

index(self, frame)

Return the index of a frame in the collection.

Parameters:

frame (ion.types.Frame) – The frame to find.

Return type:

int

Raises:

ValueError – If the frame is not in the collection.

active

Currently focused frame (read-only).

Type:

ion.types.Frame | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.FrameWindowCollection

Collection accessor for windows within a specific frame.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Window) – The window to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Window]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Window]

__getitem__(self, index)

Get a window by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the window.

Return type:

Window

__getitem__(self, index)
Parameters:

index (slice) – A slice over the windows.

Return type:

tuple[Window, …]

find_by_id(self, id)

Look up a window by its unique numeric id, only if it belongs to this frame.

Parameters:

id (int) – The window ID to look up.

Returns:

The window, or None if no matching window exists in this frame.

Return type:

Window | None

index(self, window)

Return the index of a window in this frame.

Parameters:

window (ion.types.Window) – The window to find.

Return type:

int

Raises:

ValueError – If the window is not in this frame.

sort(self, key)

Sort windows by a key function, similar to list.sort(key=...).

Parameters:

key (Callable[[Window], Any]) – Callable taking a Window and returning a comparable value.

Return type:

None

active

Active window (visible tab) in this frame.

Type:

ion.types.Window | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.GeneratorStep

Yield value for generators scheduled with ion.utils.exec_generator().

Controls when the generator is next triggered and whether it receives input events.

__init__(self, *, time=0, consume_event=False)
Parameters:

  • time (int) – Delay in milliseconds before re-triggering with an EventTimer. 0 schedules no timer.

  • consume_event (bool) – When True, the next input event is delivered to this generator.

Return type:

None

def _overview():
    yield GeneratorStep(time=500)                        # Animate.
    while True:
        event = yield GeneratorStep(consume_event=True)  # Wait for input.
        if isinstance(event, EventPointer) and event.press:
            break
    yield GeneratorStep(time=500)                        # Animate.
consume_event

When True, input events are delivered to this generator.

Type:

bool

time

Time in milliseconds before the generator is triggered again.

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.Hook
append(self, callback)

Append a callback to the end of this hook’s callback list.

The callback is returned so this method can be used as a decorator:

@ion.app.hooks.window_new_post.append
def on_window_new(window):
    ...
Parameters:

callback (T) – A callable to register.

Returns:

The callback (for use as a decorator).

Return type:

T

clear(self)

Remove all callbacks from this hook.

Return type:

None

insert(self, index, callback)

Insert a callback at the given position in the callback list.

Follows list.insert() semantics: negative indices count from the end, and out-of-range indices are clamped to the bounds of the list (no IndexError is raised).

Parameters:

  • index (int) – Position at which to insert.

  • callback (T) – A callable to register.

Return type:

None

pop(self, index=-1)

Remove and return the callback at the given position. Defaults to the last callback, matching list.pop() semantics. Negative indices count from the end.

Parameters:

index (int) – Position of the callback to remove.

Returns:

The removed callback.

Return type:

T

Raises:

IndexError – If the hook is empty or the index is out of range.

remove(self, callback)

Remove the first occurrence of a callback from this hook. Callbacks are compared by identity (is), matching the way they were registered.

Parameters:

callback (T) – The callback to unregister.

Return type:

None

Raises:

ValueError – If the callback is not registered.

Special Methods
classmethod __class_getitem__(cls, item)

Subscript support so Hook[Callable[[Window], None]] evaluates at runtime (as required by typing.get_type_hints and the stubs that declare Hook(Generic[T])).

Parameters:

item (Any) – Type parameter; ignored at runtime.

Return type:

Any

__contains__(self, item)

Return bool(key in self).

Parameters:

item (object) – Item to test for membership.

Return type:

bool

__iter__(self)

Implement iter(self).

Return type:

Iterator[T]

__len__(self)
Return type:

int

__repr__(self)
Return type:

str

class ion.types.HooksRegistry

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 ion.types.Hook via ion.types.Hook.append(); they do not add or remove hooks themselves.

Special Methods
__repr__(self)
Return type:

str

compositor_session_pause_post

Fired after the session has been paused.

This occurs on TTY switch away or system suspend. Rendering and input have already been suspended.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

compositor_session_pause_pre

Fired before the session is paused.

This occurs on TTY switch away or system suspend. Rendering and input are suspended after this hook returns.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

compositor_session_resume_post

Fired after the session has resumed.

This occurs on TTY switch back or system resume. The displays are active again and have been rescanned, so outputs plugged or unplugged while switched away are already accounted for.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

compositor_session_resume_pre

Fired before the session resumes.

This occurs on TTY switch back or system resume. The displays are not yet reactivated, and outputs plugged or unplugged while switched away are still unaccounted for.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

compositor_shutdown_pre

Fired before the compositor begins shutting down.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

compositor_startup_post

Fired once after the compositor finishes startup. All outputs are configured and the config has been loaded.

Use this hook to create initial desktops, workspaces, and any other setup that requires live compositor state.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

desktop_new_post

Fired after a new desktop is created.

Callbacks receive a Desktop argument.

Type:

Hook[Callable[[Desktop], None]]

desktop_remove_post

Fired after a desktop is removed.

Callbacks receive a Desktop argument.

Type:

Hook[Callable[[Desktop], None]]

desktop_remove_pre

Fired before a desktop is removed. The desktop is still accessible and its workspaces have not yet been relocated.

Callbacks receive a Desktop argument.

Type:

Hook[Callable[[Desktop], None]]

desktop_rename_post

Fired after a desktop is renamed.

Callbacks receive a Desktop argument.

Type:

Hook[Callable[[Desktop], None]]

desktop_rename_pre

Fired before a desktop is renamed.

Callbacks receive a Desktop argument.

Type:

Hook[Callable[[Desktop], None]]

desktop_switch_post

Fired after the active desktop switches.

Callbacks receive the old and new Desktop as arguments.

Type:

Hook[Callable[[Desktop, Desktop], None]]

desktop_switch_pre

Fired before the active desktop switches.

Callbacks receive the old and new Desktop as arguments.

Type:

Hook[Callable[[Desktop, Desktop], None]]

idle_lock

Fired when the idle timeout triggers a screen lock. This hook is responsible for spawning the lock command (e.g. utils.exec(('swaylock',))). Without a registered callback, no locking occurs.

Callbacks receive no arguments.

Type:

Hook[Callable[[], None]]

keyboard_add_post

Fired after a keyboard device is connected.

Also fires for devices already present at startup. Callbacks registered in the init script are in place before the initial device discovery runs.

Callbacks receive a KeyboardDevice argument.

Type:

Hook[Callable[[KeyboardDevice], None]]

keyboard_remove_pre

Fired before a keyboard device is disconnected (not on exit). The device is still accessible.

Callbacks receive a KeyboardDevice argument.

Type:

Hook[Callable[[KeyboardDevice], None]]

output_add_post

Fired after a newly connected output is configured and added to the layout.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

output_add_pre

Fired before a newly connected output is configured.

Use this hook to set output resolution, position, and scale before the output becomes active.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

output_remove_post

Fired after an output is disconnected and removed from the layout.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

output_remove_pre

Fired before an output is disconnected. The output is still part of the layout.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

output_resize_post

Fired after an output’s resolution or mode changes. The layout has been updated to reflect the new size.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

output_resize_pre

Fired before an output’s resolution or mode changes.

Callbacks receive an Output argument.

Type:

Hook[Callable[[Output], None]]

pointer_add_post

Fired after a pointer device is connected.

Also fires for devices already present at startup. Callbacks registered in the init script are in place before the initial device discovery runs.

Callbacks receive a PointerDevice argument.

Type:

Hook[Callable[[PointerDevice], None]]

pointer_remove_pre

Fired before a pointer device is disconnected (not on exit). The device is still accessible.

Callbacks receive a PointerDevice argument.

Type:

Hook[Callable[[PointerDevice], None]]

tablet_add_post

Fired after a tablet device is connected.

Also fires for devices already present at startup. Callbacks registered in the init script are in place before the initial device discovery runs.

Callbacks receive a TabletDevice argument.

Type:

Hook[Callable[[TabletDevice], None]]

tablet_remove_pre

Fired before a tablet device is disconnected (not on exit). The device is still accessible.

Callbacks receive a TabletDevice argument.

Type:

Hook[Callable[[TabletDevice], None]]

window_app_id_change_post

Fired after a window’s app_id property is updated.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_app_id_change_pre

Fired before a window’s app_id property is updated.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_close_post

Fired after a window is closed. The window has been removed from the layout.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_close_pre

Fired before a window is closed. The window is still accessible and part of the layout.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_floating_post

Fired after a window transitions between tiled and floating.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_floating_pre

Fired before a window transitions between tiled and floating.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_focus_post

Fired after a window gains keyboard focus.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_focus_pre

Fired before a window gains keyboard focus.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_fullscreen_post

Fired after a window’s fullscreen state is toggled.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_fullscreen_pre

Fired before a window’s fullscreen state is toggled.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_move_post

Fired after a window is moved to a different frame.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_move_pre

Fired before a window is moved to a different frame.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_new_post

Fired after a new window is mapped. The window is visible and has been assigned to a frame.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_new_pre

Fired before a new window is mapped. The window exists but is not yet visible or assigned to a frame.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_title_change_post

Fired after a window’s title property is updated.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_title_change_pre

Fired before a window’s title property is updated.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_urgent_post

Fired after a window’s urgent hint changes.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

window_urgent_pre

Fired before a window’s urgent hint changes. Urgency is typically set by the client to request user attention.

Callbacks receive a Window argument.

Type:

Hook[Callable[[Window], None]]

workspace_delete_post

Fired after a workspace is deleted and removed from the layout.

Callbacks receive a Workspace argument, which is already stale: the workspace it names is gone, so only id and is_valid can be read. Every other attribute raises ReferenceError. Snapshot whatever the callback needs in workspace_delete_pre instead.

Type:

Hook[Callable[[Workspace], None]]

workspace_delete_pre

Fired before a workspace is deleted. The workspace is still accessible and its windows have not yet been relocated.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_map_floating_post

Fired after a workspace is mapped as a floating overlay on an output.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_map_tiling_post

Fired after a workspace is assigned to an output as the active tiled workspace.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_new_post

Fired after a new workspace is created.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_rename_post

Fired after a workspace is renamed.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_rename_pre

Fired before a workspace is renamed.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_unmap_floating_post

Fired after a floating workspace overlay is unmapped from its output.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

workspace_unmap_tiling_post

Fired after a tiled workspace is deactivated on its output.

Callbacks receive a Workspace argument.

Type:

Hook[Callable[[Workspace], None]]

class ion.types.IdlePreferences

Idle timeout and screensaver preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

dpms_timeout

Seconds before DPMS off (default: 600).

Type:

int

timeout

Seconds before idle (default: 300).

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.InputPreferences

Input device preferences container.

reset(self)

Reset every input-device default to its default, in place so held references stay valid. Marks the keyboard, pointer, touchpad and tablet groups (each nested reset marks its own).

Return type:

None

keyboard_defaults

Default settings for new keyboards (ion.types.KeyboardPreferences) (read-only).

Type:

ion.types.KeyboardPreferences

pointer_defaults

Default settings for new mice/pointers (ion.types.PointerPreferences) (read-only).

Type:

ion.types.PointerPreferences

tablet_defaults

Default settings for new tablets (ion.types.TabletPreferences) (read-only).

Type:

ion.types.TabletPreferences

touchpad_defaults

Default settings for new touchpads (ion.types.TouchpadPreferences) (read-only).

Type:

ion.types.TouchpadPreferences

Special Methods
__repr__(self)
Return type:

str

class ion.types.KeyboardCollection

Collection of keyboard devices accessible as ion.app.input.keyboards.

__len__(self)

Get the number of items in the collection.

Return type:

int

__contains__(self, item)

Check if a device exists in the collection.

Parameters:

item (KeyboardDevice) – The device to check for membership.

Return type:

bool

__iter__(self)

Iterate over all keyboard devices.

Return type:

Iterator[KeyboardDevice]

__getitem__(self, key)

Get a keyboard device by index or name. Supports negative indices. A name shared by several devices matches the first of them.

Parameters:

key (str | int) – Device name, or zero-based index.

Return type:

KeyboardDevice

__getitem__(self, key)
Parameters:

key (slice) – A slice over the keyboard devices.

Return type:

tuple[KeyboardDevice, …]

active

The keyboard that most recently produced input (read-only).

Type:

ion.types.KeyboardDevice | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.KeyboardDevice

A single physical or virtual keyboard device (see Proxy objects).

Setting layout properties on the active keyboard immediately applies the change to the seat. Setting them on a non-active keyboard stores the preference, which is applied when that device next becomes active.

is_valid

Whether this keyboard device is still connected (read-only).

Type:

bool

layout

Active XKB layout (e.g. "us", "de").

Note

Setting this property is deferred until the current callback returns.

Type:

str

layout_options

Active XKB options (e.g. "ctrl:nocaps").

Note

Setting this property is deferred until the current callback returns.

Type:

str

layout_variant

Active XKB variant (e.g. "dvorak").

Note

Setting this property is deferred until the current callback returns.

Type:

str

name

Human-readable device name (read-only).

Type:

str

usb_id

USB vendor and product IDs as a (vendor, product) tuple, or None for non-USB devices (read-only).

Type:

tuple[int, int] | None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.KeyboardPreferences

Keyboard input device preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

layout

XKB layout (default: “us”).

Type:

str

options

XKB options (default: “”).

Type:

str

repeat_delay

Key repeat delay in ms (default: 400).

Type:

int

repeat_rate

Key repeat rate per second (default: 25).

Type:

int

variant

XKB variant (default: “”).

Type:

str

Special Methods
__repr__(self)
Return type:

str

class ion.types.Keymap

A keymap that can have keys bound to actions.

Identified by an ID, so two handles are equal when they name the same registered keymap. Removing a keymap and re-creating its name yields a different keymap; the old handle reports is_valid as False rather than resolving to the replacement.

id

Unique numeric identifier for this keymap (read-only).

Stable for as long as the keymap stays registered, and not reused after it is removed.

Type:

int

is_builtin

Whether this is a built-in keymap (built-ins cannot be removed).

Type:

bool

is_valid

Whether this keymap is still registered in the compositor (read-only).

Type:

bool

items

All bindings in this keymap.

Type:

KeymapItemsCollection

name

The keymap name.

Type:

str

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.KeymapHandler

Stateful event matcher for generators. Accepts events via process_event() and matches them against keymaps or single patterns using the same trigger-lookup logic as the compositor’s input handler.

Supports Press, Release, Click, Drag, and DoubleClick event actions. Click is resolved on release when the pointer has not moved beyond the drag threshold. Drag is resolved on motion when the threshold is exceeded. DoubleClick fires when two clicks occur within the double-click time and distance.

Timing reads each event’s time_stamp, so a generator stepped slowly still sees the times the input arrived rather than the times Python got to them. An event the script builds carries whatever time it was given.

__init__(self, event)

Initialize from an Event to capture the initial modifier state and cursor position.

Parameters:

event (Event) – The initial event (typically the first event received by the generator).

Return type:

None

match_keymaps(self, keymaps)

Search a list of keymaps for a binding that matches the last digested event. Returns the first match found.

Parameters:

keymaps (list[Keymap]) – Keymaps to search, checked in order.

Returns:

(KeymapItem, properties_dict) on match, or None.

Return type:

tuple[KeymapItem, dict] | None

match_single(self, pattern)

Check whether the last processed event matches a single MatchKey or MatchPointer pattern.

Parameters:

pattern (MatchKey | MatchPointer) – The pattern to match against.

Returns:

True if the event matches.

Return type:

bool

process_event(self, event)

Process an input event, updating internal state.

After calling this, use match_single() or match_keymaps() to check whether the event matches a binding.

Parameters:

event (Event) – The event to process.

Return type:

None

class ion.types.KeymapItem

A single binding in a keymap, returned by Keymap.items.

Identified by an ID, so two bindings that are alike in every value stay distinct: removing one leaves the other in place. The event and operator are read from the live binding, so both raise ReferenceError once the binding is removed.

event

The input event matcher.

Type:

MatchKey | MatchPointer

id

Unique numeric identifier for this binding (read-only).

Stable for as long as the binding stays in its keymap, and not reused after it is removed.

Type:

int

is_valid

Whether this binding is still in its keymap (read-only).

Type:

bool

keymap

The keymap holding this binding.

Answers which keymap matched when an item comes back from KeymapHandler.match_keymaps(), which searches several.

Type:

Keymap

operator

The operator instance (NamedTuple).

Type:

NamedTuple

operator_idname

Identifier of the operator this binding runs, e.g. "window_close".

Read from the binding itself, so it answers even when the operator is no longer registered - unlike operator, which has to build an instance and raises when the class is gone.

Type:

str

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.KeymapItemsCollection

Collection of keymap items with iteration and removal.

__iter__(self)

Iterate over all bindings. Every binding is listed, including one whose operator no longer resolves - that surfaces when reading KeymapItem.operator.

Return type:

Iterator[KeymapItem]

__len__(self)

Number of bindings.

Return type:

int

__contains__(self, item)

Check whether this exact binding is still in the keymap. A binding is identified by identity, not by value, so a second binding declared with the same event and operator is not a member.

Parameters:

item (KeymapItem) – The binding to check for membership.

Return type:

bool

clear(self)

Remove all bindings from this keymap.

Return type:

None

new(self, event, operator, *, doc=None)

Add a key or pointer binding to this keymap.

Parameters:
Returns:

The newly created binding.

Return type:

KeymapItem

remove(self, item)

Remove a binding from the keymap.

Parameters:

item (KeymapItem) – The item to remove.

Return type:

None

is_valid

Whether the keymap these bindings belong to is still registered (read-only).

A collection outlives its keymap - it can be held after the keymap is removed - so it carries its own check rather than deferring to Keymap.is_valid.

Type:

bool

keymap

The keymap these bindings belong to.

Type:

Keymap

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.KeymapsRegistry

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 Keymap, and keys() / values() / items() expose the three views.

The views read the live compositor registry, so they require compositor state (a config, operator, hook, generator or ionwl-cmd) and raise RuntimeError outside those contexts.

__getitem__(self, key)

Get a keymap by name, registering an empty keymap when the name is unknown. Use get() to look up a name without creating it.

Parameters:

key (str) – Keymap name.

Return type:

Keymap

__len__(self)

Number of keymaps.

Return type:

int

__iter__(self)

Iterate over keymap names (dict-like).

Return type:

Iterator[str]

__contains__(self, key)

Test whether a keymap with this name is registered.

Parameters:

key (str) – Keymap name.

Return type:

bool

get(self, key, default=None)

Get a keymap by name, returning default if no keymap with this name is registered. Unlike __getitem__, this does not create a keymap on demand.

Parameters:

  • key (str) – Keymap name.

  • default (Any) – Value returned when the keymap is missing.

Return type:

ion.types.Keymap | Any

items(self)

All (name, keymap) pairs.

Returns:

List of (name, keymap) tuples.

Return type:

list[tuple[str, ion.types.Keymap]]

keys(self)

All keymap names.

Returns:

List of keymap name strings.

Return type:

list[str]

prompt(self, name)

Activate a keymap for the next key press (leader key).

Parameters:

name (str) – Name of the keymap to activate.

Return type:

None

remove(self, keymap)

Remove a keymap. It vanishes from Python immediately and its bindings stop matching; the compositor frees it once idle.

Parameters:

keymap (ion.types.Keymap) – The keymap to remove.

Return type:

None

values(self)

All keymaps.

Returns:

List of keymaps.

Return type:

list[ion.types.Keymap]

Special Methods
__repr__(self)
Return type:

str

class ion.types.MatchKey

A key event matcher for use with KeymapItemsCollection.new().

Matchers compare by value and are hashable, so a matcher read back from a keymap equals the one that declared the binding, and matchers can key a dictionary or set.

__init__(self, key, *, action=0, ctrl=False, alt=False, logo=False, hyper=False, shift=False, passthrough=False, consume=True)
Parameters:

  • key (int) – The key (from ion.constants.keys).

  • action (int) – Event action (from ion.constants.event_actions).

  • ctrl (bool | None) – Require Ctrl modifier (None = ignored).

  • alt (bool | None) – Require Alt modifier (None = ignored).

  • logo (bool | None) – Require Logo modifier (None = ignored).

  • hyper (bool | None) – Require Hyper modifier (None = ignored).

  • shift (bool | None) – Require Shift modifier (None = ignored).

  • passthrough (bool) –

    When True, forward the event to the focused client after the binding’s operator runs. When False (the default), the compositor intercepts the event and does not forward it.

    Honoured on Press only. A key release is forwarded exactly when its press was, so the client never sees a release for a press it did not get; passthrough on a Release, Click or DoubleClick binding has no effect on delivery. Bind Press with passthrough=True to let the client see both halves.

  • consume (bool) –

    Controls whether a binding suppresses later event types on the same key. Default is True.

    • Press: a consumed Press prevents Click, Drag, and DoubleClick evaluation on the same key. When False, deferred bindings can still fire on release after the Press operator has executed. To suppress a key press from reaching the client while still allowing Click or Drag, bind Press to a no-op with consume=False, passthrough=False.

    • Click: a consumed Click prevents DoubleClick evaluation. When False, the click is recorded for future double-click detection.

    • Release: a consumed Release prevents Click and DoubleClick evaluation on the same key. When False, Click and DoubleClick can still fire after the Release operator has executed.

Return type:

None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.MatchPointer

A pointer event matcher for use with KeymapItemsCollection.new().

Matchers compare by value and are hashable, so a matcher read back from a keymap equals the one that declared the binding, and matchers can key a dictionary or set.

__init__(self, button, *, ctrl=False, alt=False, logo=False, hyper=False, shift=False, action=2, passthrough=False, consume=True)
Parameters:

  • button (int) – Pointer button code (see ion.constants.pointer_buttons).

  • ctrl (bool | None) – Require Ctrl modifier (None = ignored).

  • alt (bool | None) – Require Alt modifier (None = ignored).

  • logo (bool | None) – Require Logo modifier (None = ignored).

  • hyper (bool | None) – Require Hyper modifier (None = ignored).

  • shift (bool | None) – Require Shift modifier (None = ignored).

  • action (int) – Event action (from ion.constants.event_actions).

  • passthrough (bool) – When True, forward the event to the focused client after the binding’s operator runs. When False (the default), the compositor intercepts the event and does not forward it.

  • consume (bool) –

    Controls whether a binding suppresses later event types on the same button. Default is True.

    • Press: a consumed Press prevents Click, Drag, and DoubleClick evaluation on the same button. When False, deferred bindings can still fire on release after the Press operator has executed. To suppress a button press from reaching the client while still allowing Click or Drag, bind Press to a no-op with consume=False, passthrough=False.

    • Click: a consumed Click prevents DoubleClick evaluation. When False, the click is recorded for future double-click detection.

    • Release: a consumed Release prevents Click and DoubleClick evaluation on the same button. When False, Click and DoubleClick can still fire after the Release operator has executed.

Return type:

None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.Menu

A reference to a registered menu in the registry.

idname

The menu identifier.

Type:

str

(readonly)

name

The display name.

Type:

str | None

(readonly)

Special Methods
__eq__(self, other)
Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__repr__(self)
Return type:

str

class ion.types.MenuBuilder

Builder passed to menu callbacks.

The callback receives a fresh builder each time the menu is shown. GUI elements are added through its ion.types.UILayout, accessed as menu.layout (see ion.types.UILayout for the element methods).

layout

The layout that collects this menu’s GUI elements.

Type:

UILayout

(readonly)

class ion.types.MenuRegistry

Registry of named menus with builder callbacks: ion.app.menus.new('tab', 'Tab', callback).

Callbacks receive a ion.types.MenuBuilder and are called each time the menu is shown, enabling dynamic items.

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 ion.types.Menu, and keys() / values() / items() expose the three views.

__len__(self)

Number of menus.

Return type:

int

__iter__(self)

Iterate over menu idnames (dict-like).

Return type:

Iterator[str]

__contains__(self, idname)

Test whether a menu with this idname is registered.

Parameters:

idname (str) – The menu identifier.

Return type:

bool

__getitem__(self, idname)

Get a menu by idname.

Parameters:

idname (str) – The menu identifier.

Return type:

ion.types.Menu

Raises:

KeyError – If no menu with this idname is registered.

clear(self) → 'None'

Remove all menus.

Return type:

None

get(self, idname: 'str', default: 'object' = None) → 'Menu | object'

Get a menu by identifier, returning default if not found.

Parameters:

  • idname (str) – The menu identifier.

  • default (object) – Value returned when the menu is missing.

Returns:

The menu, or default if not found.

Return type:

ion.types.Menu | object

items(self) → 'list[tuple[str, Menu]]'

All (idname, menu) pairs.

Returns:

List of (idname, menu) tuples.

Return type:

list[tuple[str, ion.types.Menu]]

keys(self) → 'list[str]'

All menu identifiers.

Returns:

List of menu identifier strings.

Return type:

list[str]

new(self, idname: 'str', name: 'str', callback: 'Callable[[MenuBuilder], None]', poll: 'Callable[..., str | None] | None' = None) → 'None'

Register a named menu with a builder callback.

ion.app.menus.new("tab", "Tab", lambda menu: (
    menu.layout.operator(ion.ops.window_close()),
    menu.layout.operator(ion.ops.frame_delete()),
))
Parameters:

  • idname (str) – Unique identifier used to reference this menu.

  • name (str) – Human-readable display name (used as submenu label).

  • callback (Callable[[MenuBuilder], None]) – Receives a ion.types.MenuBuilder, called each time the menu is shown.

  • poll (Callable[..., str | None] | None) – Optional callable returning None if the menu is available, or a string reason if it should be hidden.

Return type:

None

remove(self, menu: 'Menu') → 'None'

Remove a menu.

Parameters:

menu (ion.types.Menu) – The menu to remove.

Return type:

None

show(self, idname: 'str') → 'None'

Show a named context menu.

Must be called during a keybinding callback.

ion.app.menus.show("context")
Parameters:

idname (str) – The menu identifier to show.

Return type:

None

values(self) → 'list[Menu]'

All menus.

Returns:

List of menus.

Return type:

list[ion.types.Menu]

Special Methods
__repr__(self)
Return type:

str

class ion.types.Output

A physical display or monitor connected to the compositor (see Proxy objects).

configure(self, *, position=None, transform=None)

Configure this output’s position and/or transform.

Note

This action is deferred until the current callback returns.

Parameters:

  • position (ion.types.Point | tuple[int, int] | None) – The output position in logical coordinates. Each coordinate is bounded well above any real monitor arrangement, since the layout translates rects by it in unchecked arithmetic.

  • transform (int | None) – Rotation in degrees (0, 90, 180, or 270).

Raises:

ValueError – If position is out of range, or transform is not one of the four supported rotations.

Returns:

None.

Return type:

None

focus(self)

Focus this output.

Returns:

None.

Return type:

None

pointer_warp(self)

Warp the pointer to this output unconditionally.

Returns:

None.

Return type:

None

pointer_warp_if_needed(self)

Warp the pointer to this output only if it’s not already inside it.

Returns:

True if the pointer was warped, False otherwise.

Return type:

bool

data

Per-output dictionary for script-defined data.

Created on first access and persists for the lifetime of the output. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

dpms

Whether this output’s display is powered on.

The same compositor-side power state is_enabled reports; this accessor additionally raises RuntimeError on a backend without DPMS support, so a config can tell “powered on” from “no such control”. While the session is switched away the compositor is not driving the display at all, and this keeps reporting the state it will restore on return.

Note

A write is deferred until the current callback returns (as configure() is), so a read taken in between still reports the old value.

Type:

bool

fullscreen_window

The fullscreen window on this output, or None if no window is fullscreen here.

Type:

Window | None

id

Unique numeric identifier for this output (read-only).

Stable for the lifetime of the output regardless of desktop or workspace changes. Not reused after the output is disconnected.

Type:

int

is_enabled

Whether this output is enabled (DPMS on) (read-only).

True if the display is on, False if it’s in a power-saving state.

Type:

bool

is_focused

Whether this output is focused (read-only).

Type:

bool

is_valid

Whether this output still exists in the compositor (read-only).

Type:

bool

name

Output name (read-only).

Type:

str

rect

Output rectangle (read-only).

Type:

ion.types.Rect

scale

Output scale factor (read-only).

Type:

float

transform

Current transform (rotation) in degrees (0, 90, 180, or 270) (read-only).

Type:

int

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.OutputCollection

Collection accessor for outputs.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Output) – The output to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Output]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Output]

__getitem__(self, key)

Get an output by name or index. Supports negative indices.

Parameters:

key (str | int) – Output name, or zero-based index.

Return type:

Output

__getitem__(self, key)
Parameters:

key (slice) – A slice over the outputs.

Return type:

tuple[Output, …]

bounds_calc(self)

Compute the bounding rectangle of all enabled outputs.

Returns:

The combined bounding rectangle, or None when there are no enabled outputs.

Return type:

Rect | None

find_by_frame(self, frame)

Find the output containing a frame (by geometry).

Parameters:

frame (ion.types.Frame) – The frame to locate.

Returns:

The output containing the frame, or None if not found.

Return type:

ion.types.Output | None

find_by_id(self, id)

Look up an output by its unique numeric id.

Parameters:

id (int) – The output ID to look up.

Returns:

The output, or None if no output with that ID exists.

Return type:

Output | None

find_by_window(self, window)

Find the output displaying the given window.

Parameters:

window (ion.types.Window) – The window to locate.

Returns:

The output displaying the window, or None if the window is floating or not found.

Return type:

ion.types.Output | None

find_isect_all_point(self, point)

Find all outputs containing the given point.

Parameters:

point (ion.types.Point | tuple[int, int]) – The position to look up.

Returns:

Outputs containing the point, most interior first.

Return type:

list[ion.types.Output]

find_isect_all_rect(self, rect)

Find all outputs intersecting the given rectangle.

Parameters:

rect (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – The area to check.

Returns:

Outputs intersecting the rectangle, ordered by intersection area (largest first).

Return type:

list[ion.types.Output]

get(self, name)

Get an output by its name (e.g., “DP-1”, “HDMI-A-1”).

Parameters:

name (str) – The output name.

Returns:

The output, or None if not found.

Return type:

ion.types.Output | None

index(self, output)

Return the index of an output in the collection.

Parameters:

output (ion.types.Output) – The output to find.

Return type:

int

Raises:

ValueError – If the output is not in the collection.

items(self)

All (name, output) pairs.

Returns:

List of (name, output) tuples.

Return type:

list[tuple[str, ion.types.Output]]

keys(self)

All output names.

Returns:

List of output name strings.

Return type:

list[str]

active

Currently focused output (read-only).

Type:

ion.types.Output | None

active_pointer

Output the pointer is on (read-only).

Type:

ion.types.Output | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.Overlay

Base class for overlay proxies (see Proxy objects).

Subclasses: OverlayRect, OverlayWindow, OverlayDesktop, OverlayDesktopItem, OverlayWindowIcon, OverlayTextDynamic, OverlayText, OverlayExclusive, OverlayTab, OverlayGroup.

Overlay objects can be constructed independently and later added to the compositor via OverlayCollection.append() (or OverlayCollection.insert()). Properties are always readable. Setters update the compositor in real time when the overlay is live (has been added and not yet removed).

data

Per-overlay dictionary for script-defined data.

Created on first access and persists for the lifetime of the overlay. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

parent

Parent group overlay, or None if this overlay has no parent.

Type:

OverlayGroup | None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.OverlayCollection

Collection accessor for a group’s overlays (e.g. ion.wm.overlay_root.overlays).

Overlays are drawn front-to-back in list order: the first overlay is in front and the last is behind. append() adds the overlay to the end (behind existing overlays); use insert() to place it at a specific z-position, or sort() to reorder.

__len__(self)

Get the number of overlays.

Return type:

int

__contains__(self, value)

Check if an overlay is in the collection.

Parameters:

value (Overlay) – The overlay to check for membership.

Return type:

bool

__iter__(self)

Iterate over all overlays in draw order (front to back).

Return type:

Iterator[Overlay]

__reversed__(self)

Iterate over all overlays back to front (reverse draw order).

Return type:

Iterator[Overlay]

__getitem__(self, index)

Get an overlay by index. Supports negative indices. Index 0 is the front-most overlay.

Parameters:

index (int) – Zero-based index of the overlay.

Return type:

Overlay

__getitem__(self, index)
Parameters:

index (slice) – A slice over the overlays in draw order.

Return type:

tuple[Overlay, …]

append(self, overlay)

Append an overlay to this group, behind all existing overlays. The overlay must be a detached Overlay subclass (constructed but not yet added, or previously removed/popped).

Parameters:

overlay (Overlay) – The overlay to append.

Return type:

None

clear(self)

Remove all overlays.

Return type:

None

index(self, overlay)

Return the index of an overlay in the collection.

Parameters:

overlay (Overlay) – The overlay to find.

Return type:

int

Raises:

ValueError – If the overlay is not in the collection.

insert(self, index, overlay)

Insert an overlay at the given index. Index 0 places the overlay in front; an index at or past the end appends. Negative indices follow list semantics. The overlay must be a detached Overlay subclass.

Parameters:

  • index (int) – Target z-position.

  • overlay (Overlay) – The overlay to insert.

Return type:

None

pop(self, index=-1)

Remove and return the overlay at index (defaults to the last, back-most overlay). The returned overlay is detached with its last-known data preserved, equivalent to a freshly constructed but not-yet-added overlay, and can be re-added to this or another OverlayCollection.

For OverlayGroup overlays the descendants are destroyed, matching remove(); the returned group carries only its own attributes.

Parameters:

index (int) – Position to pop. Supports negative indices.

Return type:

Overlay

Raises:

IndexError – If the collection is empty or the index is out of range.

remove(self, overlay)

Remove an overlay from the compositor. The Python object is left in a detached state with its last-known data preserved, so it can be re-added later via append() or insert(). Descendants of a removed OverlayGroup are destroyed.

Parameters:

overlay (Overlay) – The overlay to remove.

Return type:

None

Raises:

  • ValueError – If the overlay is not a member of this collection.

  • ReferenceError – If the overlay handle is stale.

reverse(self)

Reverse the z-order of the overlays in place.

Return type:

None

sort(self, key)

Sort overlays by a key function, similar to list.sort(key=...). Lower key values are drawn in front of higher values.

Parameters:

key (Callable[[Overlay], Any]) – Callable taking an Overlay and returning a comparable value.

Return type:

None

swap(self, a, b)

Swap the z-order of two overlays.

Parameters:

  • a (Overlay) – The first overlay.

  • b (Overlay) – The second overlay.

Return type:

None

Raises:

  • ValueError – If either overlay is not a member of this collection.

  • ReferenceError – If either overlay handle is stale.

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayDesktop(Overlay)

A desktop-content overlay (display-only, no input).

__init__(self, desktop)
Parameters:

desktop (Desktop) – The desktop to display.

Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

desktop

The source desktop being displayed.

Type:

ion.types.Desktop

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayDesktopItem(Overlay)

A desktop-item overlay that displays a single floating or tiled item with its borders and decorations (display-only, no input).

__init__(self, item)
Parameters:

item (DesktopItemFloatingFrame | DesktopItemFloatingWorkspace | DesktopItemTilingFrame | DesktopItemTilingWorkspace) – The desktop item to display.

Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

item

The source desktop item being displayed.

Type:

DesktopItemFloatingFrame | DesktopItemFloatingWorkspace | DesktopItemTilingFrame | DesktopItemTilingWorkspace

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayExclusive(Overlay)

An exclusive overlay that fills the entire display with a solid color, suppressing all normal scene rendering (windows, layer surfaces, decorations, menus, popups). Only overlays above this one in the z-order are drawn; all overlays behind it are skipped.

This should almost always be the last overlay added so that all other overlays render in front of it.

__init__(self)
Return type:

None

color

Fill color of the exclusive overlay.

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

Special Methods
__repr__(self)
Return type:

str

class ion.types.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).

__init__(self)
Return type:

None

alpha

Opacity (0.0 = fully transparent, 1.0 = fully opaque).

When less than 1.0 and use_alpha_merged is true, children are composited to an offscreen texture first, then the texture is drawn with this alpha.

Type:

float

overlays

The collection of overlays in this group.

Type:

OverlayCollection

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Scale factor applied to children (1.0 = no scaling).

Type:

float

use_alpha_merged

Whether children are composited to an offscreen texture before alpha is applied. When true (default), overlapping children blend correctly as a single unit. When false, alpha is applied per-element (faster, but overlapping children show through each other).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayRect(Overlay)

A colored rectangle overlay.

__init__(self)
Return type:

None

fill_color

Fill color of the overlay.

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

outline_color

Outline color of the overlay.

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

outline_width

Outline width in logical pixels. Positive values grow outward from the rect edges, negative values grow inward.

Type:

int

rect

Position and size of the overlay in global logical coordinates.

Setting accepts a Rect or a (min, max) pair of points.

Type:

ion.types.Rect

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTab(Overlay)

A tab overlay that renders a single styled tab (for drag ghost).

__init__(self, window, frame)
Parameters:

  • window (Window) – The window whose tab is being displayed.

  • frame (Frame) – The source frame (for styling: active, tagged, urgent state).

Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

frame

The source frame (for styling: active, tagged, urgent state).

Type:

ion.types.Frame

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

tab_size

Tab size in logical pixels.

Setting accepts a Size or tuple[int, int].

Type:

Size

window

The window whose tab is being displayed.

Type:

ion.types.Window

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayText(Overlay)

An arbitrary-text overlay.

__init__(self)
Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

background_color

Background color behind the text (RGBA, 0.0-1.0). Not drawn when alpha is zero (the default).

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

color

Text color (RGBA, 0.0-1.0).

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

font_size

Font rasterization size in points (0 = use global font size).

Type:

int

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

text

The text string being displayed.

Type:

str

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTextDynamic(Overlay)

Base class for dynamic-text overlays. Not constructed directly. Use a subclass: OverlayTextDynamicWindowTitle, OverlayTextDynamicWindowAppId, OverlayTextDynamicWorkspaceName, OverlayTextDynamicOutputName, OverlayTextDynamicDesktopName.

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

background_color

Background color behind the text (RGBA, 0.0-1.0). Not drawn when alpha is zero (the default).

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

color

Text color (RGBA, 0.0-1.0).

Setting accepts a ColorRGBA or tuple[float, float, float, float].

Type:

ion.types.ColorRGBA

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

class ion.types.OverlayTextDynamicDesktopName(OverlayTextDynamic)
__init__(self, source)
Parameters:

source (Desktop) – The source entity.

Return type:

None

source

The source entity.

Type:

ion.types.Desktop

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTextDynamicOutputName(OverlayTextDynamic)
__init__(self, source)
Parameters:

source (Output) – The source entity.

Return type:

None

source

The source entity.

Type:

ion.types.Output

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTextDynamicWindowAppId(OverlayTextDynamic)
__init__(self, source)
Parameters:

source (Window) – The source entity.

Return type:

None

source

The source entity.

Type:

ion.types.Window

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTextDynamicWindowTitle(OverlayTextDynamic)
__init__(self, source)
Parameters:

source (Window) – The source entity.

Return type:

None

source

The source entity.

Type:

ion.types.Window

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayTextDynamicWorkspaceName(OverlayTextDynamic)
__init__(self, source)
Parameters:

source (Workspace) – The source entity.

Return type:

None

source

The source entity.

Type:

ion.types.Workspace

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayWindow(Overlay)

A window-content overlay (display-only, no input, no frame decorations).

__init__(self, window)
Parameters:

window (Window) – The window to display.

Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

window

The window being displayed.

Type:

ion.types.Window

Special Methods
__repr__(self)
Return type:

str

class ion.types.OverlayWindowIcon(Overlay)

A window-icon overlay.

__init__(self, window)
Parameters:

window (Window) – The window whose icon to display.

Return type:

None

align

Alignment (x, y) where each is -1 = min, 0 = center (floor), 1 = max.

Type:

tuple[int, int]

position

Position in global logical coordinates.

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

scale

Display scale (1.0 = native size).

Type:

float

size

Icon rasterization size in logical pixels (icons are square).

Type:

int

window

The window whose icon is displayed.

Type:

ion.types.Window

Special Methods
__repr__(self)
Return type:

str

class ion.types.Point

2D point with x and y coordinates.

__init__(self, point)
Parameters:

point (Point | tuple[int, int]) – Point as [x, y].

Return type:

None

__getitem__(self, index)

Get component by index (0=x, 1=y).

Parameters:

index (int) – 0 for x, 1 for y.

Return type:

int

__getitem__(self, index)
Parameters:

index (slice) – A slice over the two components.

Return type:

tuple[int, …]

__len__(self)

Return the number of components (always 2).

Return type:

int

__iter__(self)

Iterate over components (x, y).

Return type:

Iterator[int]

copy(self)

Return a mutable (unfrozen) copy.

Return type:

Point

freeze(self)

Freeze this value, making it read-only and hashable. Returns self for convenience (e.g. d[p.freeze()] = v).

Return type:

Self

lerp(self, other, t)

Linear interpolation from self to other.

Parameters:

  • other (Point | tuple[int, int]) – Target point.

  • t (float) – Interpolation factor (0.0 = self, 1.0 = other).

Return type:

Point

to_tuple(self)

Convert to tuple (x, y).

Returns:

Tuple (x, y).

Return type:

tuple[int, int]

is_frozen

Whether this value is frozen (read-only).

Type:

bool

x

X coordinate.

Type:

int

y

Y coordinate.

Type:

int

Special Methods
__abs__(self)

abs(self)

Return type:

Point

__add__(self, other)

Return self+value.

Parameters:

other (Self) – The other operand.

Return type:

Point

__copy__(self)
Return type:

Point

__deepcopy__(self, memo)
Parameters:

memo (dict) – Memoization dict for shared subobjects.

Return type:

Point

__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__floordiv__(self, other)

Return self//value.

Parameters:

other (Self) – The other operand.

Return type:

Point

__format__(self, format_spec)
Parameters:

format_spec (str) – Format spec applied per component (empty spec returns repr(self)).

Return type:

str

__hash__(self)
Return type:

int

__iadd__(self, other)

Return self+=value.

Parameters:

other (Self) – The other operand.

Return type:

Point

__isub__(self, other)

Return self-=value.

Parameters:

other (Self) – The other operand.

Return type:

Point

__mul__(self, other)

Return self*value.

Parameters:

other (Self) – The other operand.

Return type:

Point

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__neg__(self)

-self

Return type:

Point

__pos__(self)

+self

Return type:

Point

__radd__(self, other)

Return value+self.

Parameters:

other (Self) – The other operand.

Return type:

Point

__repr__(self)
Return type:

str

__rfloordiv__(self, other)

Return value//self.

Parameters:

other (Self) – The other operand.

Return type:

Point

__rmul__(self, other)

Return value*self.

Parameters:

other (Self) – The other operand.

Return type:

Point

__rsub__(self, other)

Return value-self.

Parameters:

other (Self) – The other operand.

Return type:

Point

__setitem__(self, key, value)

Set self[key] to value.

Parameters:

  • key (int) – Index or key.

  • value (object) – Value to assign.

__sub__(self, other)

Return self-value.

Parameters:

other (Self) – The other operand.

Return type:

Point

class ion.types.PointerCollection

Collection of pointer devices accessible as ion.app.input.pointers.

__len__(self)

Get the number of items in the collection.

Return type:

int

__contains__(self, item)

Check if a device exists in the collection.

Parameters:

item (PointerDevice) – The device to check for membership.

Return type:

bool

__iter__(self)

Iterate over all pointer devices.

Return type:

Iterator[PointerDevice]

__getitem__(self, key)

Get a pointer device by index or name. Supports negative indices. A name shared by several devices matches the first of them.

Parameters:

key (str | int) – Device name, or zero-based index.

Return type:

PointerDevice

__getitem__(self, key)
Parameters:

key (slice) – A slice over the pointer devices.

Return type:

tuple[PointerDevice, …]

active

The pointer that most recently produced input (read-only).

Type:

ion.types.PointerDevice | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.PointerDevice

A single physical or virtual pointer device (see Proxy objects).

accel_profile

Acceleration profile.

Type:

Literal[“ADAPTIVE”, “FLAT”]

accel_speed

Acceleration speed (-1.0 to 1.0).

Type:

float

click_method

Click method (touchpad only).

Type:

Literal[“CLICKFINGER”, “BUTTON_AREAS”]

disable_while_typing

Disable while typing (touchpad only).

Type:

bool

drag_lock

Drag lock (touchpad only).

Type:

bool

is_enabled

Whether this device is enabled.

Type:

bool

is_touchpad

Whether this device is a touchpad (read-only).

Type:

bool

is_valid

Whether this pointer device is still connected (read-only).

Type:

bool

left_handed

Swap left/right buttons.

Type:

bool

name

Human-readable device name (read-only).

Type:

str

natural_scroll

Invert scroll direction.

Type:

bool

scroll_method

Scroll method (touchpad only).

Type:

Literal[“TWO_FINGER”, “EDGE”, “BUTTON”]

tap_and_drag

Tap and drag (touchpad only).

Type:

bool

tap_to_click

Tap to click (touchpad only).

Type:

bool

usb_id

USB vendor and product IDs as a (vendor, product) tuple, or None for non-USB devices (read-only).

Type:

tuple[int, int] | None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.PointerPreferences

Mouse/pointer device preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

accel_profile

Acceleration profile (default: "ADAPTIVE").

Type:

Literal[“ADAPTIVE”, “FLAT”]

accel_speed

Acceleration speed -1.0 to 1.0 (default: 0.0).

Type:

float

is_enabled

Enable pointer (default: True).

Type:

bool

left_handed

Swap left/right buttons (default: False).

Type:

bool

natural_scroll

Invert scroll direction (default: False).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.Preferences

Main preferences object accessed via ion.app.preferences.

Writes apply after the current operator, hook or IPC call returns. startup.use_xwayland is the exception, consulted only at startup; so is the XCURSOR environment child processes read, though the compositor’s own cursor does follow ion.types.CursorPreferences.

reset(self)

Reset all preferences to their default values, in place: handles already held (e.g. a config’s prefs.focus) keep targeting the live objects. The changes apply like any other preference write, once the current callback returns.

Input devices reset to the (re-declared) defaults even when those are unchanged, discarding per-device runtime overrides such as a keyboard’s layout. A config that wants a keyboard XKB override re-applies it on reload: it lands after the reset’s re-apply. Pointer, touchpad and tablet overrides apply immediately, so ones re-applied in the same callback are still overwritten by the reset; re-apply those after the reload returns (e.g. from a hook or a later generator step).

Return type:

None

animate

Animation settings (ion.types.AnimatePreferences) (read-only).

Type:

ion.types.AnimatePreferences

cursor

Cursor appearance settings (ion.types.CursorPreferences) (read-only).

Type:

ion.types.CursorPreferences

decor

Decoration settings (ion.types.DecorPreferences) (read-only).

Type:

ion.types.DecorPreferences

floating

Floating window placement settings (ion.types.FloatingPreferences) (read-only).

Type:

ion.types.FloatingPreferences

focus

Window focus behavior settings (ion.types.FocusPreferences) (read-only).

Type:

ion.types.FocusPreferences

fonts

Font rendering settings (ion.types.FontPreferences) (read-only).

Type:

ion.types.FontPreferences

idle

Idle timeout and screensaver settings (ion.types.IdlePreferences) (read-only).

Type:

ion.types.IdlePreferences

input

Input device settings (ion.types.InputPreferences) (read-only).

Type:

ion.types.InputPreferences

startup

Startup behaviour settings (ion.types.StartupPreferences) (read-only).

Type:

ion.types.StartupPreferences

system

System settings (ion.types.SystemPreferences) (read-only).

Type:

ion.types.SystemPreferences

tiling

Tiling behaviour settings (ion.types.TilingPreferences) (read-only).

Type:

ion.types.TilingPreferences

Special Methods
__repr__(self)
Return type:

str

class ion.types.Rect

Rectangle defined by minimum and maximum corners.

__init__(self, min, max)
Parameters:

  • min (Point | tuple[int, int]) – Top-left corner as [x, y].

  • max (Point | tuple[int, int]) – Bottom-right corner as [x, y].

Return type:

None

__getitem__(self, index)

Get corner by index (0=min, 1=max).

Parameters:

index (int) – 0 for the min corner, 1 for the max corner.

Return type:

Point

__getitem__(self, index)
Parameters:

index (slice) – A slice over the two corners.

Return type:

tuple[Point, …]

__len__(self)

Number of corners (always 2).

Return type:

int

__iter__(self)

Iterate over corners (min, max).

Return type:

Iterator[Point]

area(self)

Area of this rectangle.

Return type:

int

center_ceil(self)

Center point rounded toward positive infinity.

Returns:

Center point.

Return type:

ion.types.Point

center_ceil_x(self)

X component of center, rounded toward positive infinity.

Return type:

int

center_ceil_y(self)

Y component of center, rounded toward positive infinity.

Return type:

int

center_floor(self)

Center point rounded toward negative infinity.

Returns:

Center point.

Return type:

ion.types.Point

center_floor_x(self)

X component of center, rounded toward negative infinity.

Return type:

int

center_floor_y(self)

Y component of center, rounded toward negative infinity.

Return type:

int

contains(self, other)

Check if this rectangle contains a point or another rectangle. For rectangles, touching edges are considered inside, i.e. the union of the two would not expand this rectangle.

Parameters:

other (ion.types.Point | tuple[int, int] | ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – A Point or Rect to test for containment.

Returns:

True if this rectangle contains the point or rectangle.

Return type:

bool

copy(self)

Return a mutable (unfrozen) copy.

Return type:

Rect

freeze(self)

Freeze this value, making it read-only and hashable. Returns self for convenience (e.g. d[p.freeze()] = v).

Return type:

Self

intersection(self, other)

Return the overlapping region of two rectangles, or None if they do not intersect.

Parameters:

other (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – Another rectangle.

Return type:

ion.types.Rect | None

intersects(self, other)

Check if this rectangle intersects with another rectangle.

Parameters:

other (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – Another rectangle to test for intersection.

Returns:

True if this rectangle intersects with another rectangle.

Return type:

bool

is_empty(self)

True if this rectangle encloses no area.

Covers both the zero-size (max == min) and inverted (max < min) cases; use Rect.is_inverted() to tell them apart.

Return type:

bool

is_inverted(self)

True if max < min on either axis, i.e. the corners are swapped.

An inverted rectangle is always empty, but an empty one need not be inverted - it may be zero-size.

Return type:

bool

lerp(self, other, t)

Linearly interpolate between two rectangles.

Parameters:

  • other (Rect | tuple[tuple[int, int], tuple[int, int]]) – Target rectangle.

  • t (float) – Interpolation factor (0.0 = self, 1.0 = other).

Return type:

Rect

point_remap_ceil(self, point, dst)

Map point from self to the corresponding position in dst, rounding toward positive infinity. The result is clamped inside dst.

Parameters:

  • point (Point | tuple[int, int]) – Point to map.

  • dst (Rect | tuple[tuple[int, int], tuple[int, int]]) – Destination region.

Return type:

Point

point_remap_floor(self, point, dst)

Map point from self to the corresponding position in dst, rounding toward negative infinity. The result is clamped inside dst.

Parameters:

  • point (Point | tuple[int, int]) – Point to map.

  • dst (Rect | tuple[tuple[int, int], tuple[int, int]]) – Destination region.

Return type:

Point

rect_remap_ceil(self, rect, dst)

Map rect from self to the corresponding rectangle in dst, rounding toward positive infinity. Both position and size are scaled proportionally.

Parameters:

  • rect (Rect | tuple[tuple[int, int], tuple[int, int]]) – Rectangle to map.

  • dst (Rect | tuple[tuple[int, int], tuple[int, int]]) – Destination region.

Return type:

Rect

rect_remap_floor(self, rect, dst)

Map rect from self to the corresponding rectangle in dst, rounding toward negative infinity. Both position and size are scaled proportionally.

Parameters:

  • rect (Rect | tuple[tuple[int, int], tuple[int, int]]) – Rectangle to map.

  • dst (Rect | tuple[tuple[int, int], tuple[int, int]]) – Destination region.

Return type:

Rect

to_tuple(self)

Convert to tuple (min, max).

Returns:

Tuple (min, max).

Return type:

tuple[tuple[int, int], tuple[int, int]]

translate(self, offset)

Move the rectangle by adding an offset to its position.

Parameters:

offset (Point | Size | tuple[int, int]) – Offset as [dx, dy].

Returns:

None.

Return type:

None

union(self, other)

Return the smallest rectangle enclosing both rectangles.

Parameters:

other (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – Another rectangle.

Return type:

ion.types.Rect

is_frozen

Whether this value is frozen (read-only).

Type:

bool

max

Maximum point (bottom-right corner). Setting moves the rectangle (size unchanged).

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

min

Minimum point (top-left corner). Setting moves the rectangle (size unchanged).

Setting accepts a Point or tuple[int, int].

Type:

ion.types.Point

size

Size as Size(width, height) (read-only).

Type:

Size

size_x

Width (max.x - min.x) (read-only).

Type:

int

size_y

Height (max.y - min.y) (read-only).

Type:

int

Special Methods
__copy__(self)
Return type:

Rect

__deepcopy__(self, memo)
Parameters:

memo (dict) – Memoization dict for shared subobjects.

Return type:

Rect

__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__format__(self, format_spec)
Parameters:

format_spec (str) – Format spec applied per component (empty spec returns repr(self)).

Return type:

str

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

__setitem__(self, key, value)

Set self[key] to value.

Parameters:

  • key (int) – Index or key.

  • value (object) – Value to assign.

class ion.types.Size

2D size as [width, height].

__init__(self, size)
Parameters:

size (Size | tuple[int, int]) – Size as [width, height].

Return type:

None

__getitem__(self, index)

Get an item by index.

Parameters:

index (int) – 0 for width, 1 for height.

Return type:

int

__getitem__(self, index)
Parameters:

index (slice) – A slice over the two components.

Return type:

tuple[int, …]

__len__(self)

Return the number of components (always 2).

Return type:

int

__iter__(self)

Iterate over components (width, height).

Return type:

Iterator[int]

area(self)

Area (width * height).

Return type:

int

copy(self)

Return a mutable (unfrozen) copy.

Return type:

Size

freeze(self)

Freeze this value, making it read-only and hashable. Returns self for convenience (e.g. d[p.freeze()] = v).

Return type:

Self

is_empty(self)

True if either dimension is zero or negative.

Return type:

bool

is_negative(self)

True if either dimension is negative.

A size may go negative as an intermediate arithmetic result; this flags such a value before it is used as a final size.

Return type:

bool

lerp(self, other, t)

Linear interpolation from self to other.

Parameters:

  • other (Size | tuple[int, int]) – Target size.

  • t (float) – Interpolation factor (0.0 = self, 1.0 = other).

Return type:

Size

to_tuple(self)

Convert to tuple (width, height).

Returns:

Tuple (width, height).

Return type:

tuple[int, int]

is_frozen

Whether this value is frozen (read-only).

Type:

bool

x

Width (first component).

Type:

int

y

Height (second component).

Type:

int

Special Methods
__abs__(self)

abs(self)

Return type:

Size

__add__(self, other)

Return self+value.

Parameters:

other (Self) – The other operand.

Return type:

Size

__copy__(self)
Return type:

Size

__deepcopy__(self, memo)
Parameters:

memo (dict) – Memoization dict for shared subobjects.

Return type:

Size

__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__floordiv__(self, other)

Return self//value.

Parameters:

other (Self) – The other operand.

Return type:

Size

__format__(self, format_spec)
Parameters:

format_spec (str) – Format spec applied per component (empty spec returns repr(self)).

Return type:

str

__hash__(self)
Return type:

int

__iadd__(self, other)

Return self+=value.

Parameters:

other (Self) – The other operand.

Return type:

Size

__isub__(self, other)

Return self-=value.

Parameters:

other (Self) – The other operand.

Return type:

Size

__mul__(self, other)

Return self*value.

Parameters:

other (Self) – The other operand.

Return type:

Size

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__neg__(self)

-self

Return type:

Size

__pos__(self)

+self

Return type:

Size

__radd__(self, other)

Return value+self.

Parameters:

other (Self) – The other operand.

Return type:

Size

__repr__(self)
Return type:

str

__rfloordiv__(self, other)

Return value//self.

Parameters:

other (Self) – The other operand.

Return type:

Size

__rmul__(self, other)

Return value*self.

Parameters:

other (Self) – The other operand.

Return type:

Size

__rsub__(self, other)

Return value-self.

Parameters:

other (Self) – The other operand.

Return type:

Size

__setitem__(self, key, value)

Set self[key] to value.

Parameters:

  • key (int) – Index or key.

  • value (object) – Value to assign.

__sub__(self, other)

Return self-value.

Parameters:

other (Self) – The other operand.

Return type:

Size

class ion.types.SplitNode

A node in the workspace split tree (read-only).

Base class for SplitNodeLeaf and SplitNodeContainer.

find_adjacent(self, direction)

Find the subtree adjacent to this node in the given direction.

Walks up the split tree to the first axis-aligned ancestor whose other child sits in direction, and returns that subtree’s root. Combine with WorkspaceCollection.new_from_split_node() to extract the adjacent subtree into a floating workspace.

Parameters:

direction (Literal["LEFT", "RIGHT", "UP", "DOWN"]) – Direction to search.

Returns:

The adjacent split node, or None if no adjacent subtree exists in that direction.

Return type:

ion.types.SplitNode | None

is_valid

Whether this node still exists in the compositor (read-only).

Type:

bool

parent

Parent container node, or None if this is the root (read-only).

Type:

SplitNodeContainer | None

rect

Node rectangle (read-only).

Type:

ion.types.Rect

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.SplitNodeContainer(SplitNode)

A container node in the workspace split tree with two children and a split direction (read-only).

axis_rotate(self, flip_axis, swap_children, pointer_warp=True)

Rotate the split axis atomically: optionally flip the axis direction and/or swap children in a single relayout.

Parameters:

  • flip_axis (bool) – Toggle the split axis (horizontal/vertical).

  • swap_children (bool) – Swap child_min and child_max.

  • pointer_warp (bool) – Warp the pointer to the focused frame after changing.

Returns:

None.

Return type:

None

child_other(self, child)

Return the sibling of child - this container’s other child.

Useful after SplitNodeLeaf.split(): pass the node that was split to get the newly created node, without checking which side it landed on.

Parameters:

child (SplitNode) – One of this container’s two children.

Raises:

ValueError – If child is not a direct child of this container.

Returns:

The other child.

Return type:

SplitNode

child_remove(self, child)

Remove a child from this container. The child must be an empty leaf (no windows). The container collapses to the surviving child.

Parameters:

child (SplitNodeLeaf) – The child leaf to remove.

Raises:

ValueError – If the child is not a direct child of this container.

Return type:

None

child_swap(self, pointer_warp=True)

Swap the two children so child_min becomes child_max and vice versa.

Parameters:

pointer_warp (bool) – Warp the pointer to the focused frame after swapping.

Returns:

None.

Return type:

None

join(self)

Recursively merge all frames in this container’s subtree into one frame (the last-active descendant), removing the rest.

Returns:

None.

Return type:

None

split_axis_set(self, axis, pointer_warp=True)

Set the split direction.

Parameters:

  • axis (int) – 0 for horizontal, 1 for vertical.

  • pointer_warp (bool) – Warp the pointer to the focused frame after changing.

Returns:

None.

Return type:

None

split_divider_position_set(self, position)

Set the split ratio from an absolute divider position.

The position is in logical pixels (the center of the divider). The ratio is computed from the position relative to the container’s rectangle and divider width.

Parameters:

position (int) – Absolute position in logical pixels.

Return type:

None

split_divider_position_to_ratio(self, position)

Compute the split ratio for an absolute divider position without applying it.

Mirrors split_divider_position_set() but returns the ratio instead of setting it, so callers can adjust the value (for example snap it) and apply it once by assigning split_ratio. This avoids reconfiguring the windows for the raw position before the adjusted ratio is applied.

Parameters:

position (int) – Absolute position in logical pixels.

Returns:

The unclamped ratio (0.0 to 1.0), or None when the container is too small for meaningful resizing.

Return type:

float | None

child_max

Child at the maximum edge - right for horizontal, bottom for vertical (read-only).

Type:

SplitNode

child_min

Child at the minimum edge - left for horizontal, top for vertical (read-only).

Type:

SplitNode

gapless

Whether this divider is gapless.

When True the divider has zero width: the two children abut with no gap, no divider bar is rendered, and the boundary offers no pointer resize handle. Defaults to False.

Type:

bool

gapless_manual

Whether this divider’s gapless state is pinned by the user.

When True the automatic rule does not change it. Set to False to release the divider back to automatic control.

Type:

bool

last_active

Last-active child (read-only).

Type:

SplitNode

split_axis

Split axis: 0 for horizontal (left|right), 1 for vertical (top/bottom).

Read-only as a property; assign with split_axis_set(), which also takes a pointer_warp flag.

Type:

int

split_ratio

Split ratio.

Fraction of space allocated to child_min (0.0 to 1.0, default 0.5). Assigning is clamped so neither child falls below the minimum split size.

Type:

float

class ion.types.SplitNodeLeaf(SplitNode)

A leaf node in the workspace split tree, holding a single frame.

split(self, axis, side, *, move_window=True)

Split this leaf, creating a new sibling frame.

side selects where the new frame goes: 0 = min (left/top), 1 = max (right/bottom). When move_window is True (the default), the active window moves into the new frame and focus follows it.

Returns the divider created by the split. The original and new frames are reachable as its child_min / child_max (the new frame is on side); pass this leaf to SplitNodeContainer.child_other() to get the new node directly.

Parameters:

  • axis (Literal[0, 1]) – Split axis (0 = horizontal, 1 = vertical).

  • side (Literal[0, 1]) – Side for the new frame (0 = min, 1 = max).

  • move_window (bool) – Move the active window into the new frame.

Returns:

The divider created by the split, or None if the split failed.

Return type:

SplitNodeContainer | None

frame

Frame at this leaf (read-only).

Type:

Frame

class ion.types.StartupPreferences

Startup behaviour preferences.

use_numlock applies like any preference - after the current callback returns. use_xwayland is consulted only at startup and a later write is inert.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

use_numlock

Enable numlock (default: False).

Applied when the seat keyboard is created and again on any later change.

Type:

bool

use_xwayland

Launch XWayland so X11 applications can connect (default: True).

Consulted once at startup; a later write is inert.

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.SystemPreferences

System preferences: session-wide compositor behaviour not owned by a visual subsystem.

Unlike the other preference groups, these settings are read where they are used rather than applied after the current callback returns, so a write needs no separate apply step and takes effect from its next use: notify_on_error when an error is reported, desktop_layout_providers when a layout is computed.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

desktop_layout_providers

List of callables that provide spatial desktop arrangements.

Each provider is called with a list of desktops and returns list[tuple[tuple[int, int], Desktop]] - a list of ((x_index, y_index), desktop) pairs where indices are non-negative integers identifying grid cells.

Provider return values:

  • A list of ((x_index, y_index), desktop) pairs to define the layout.

  • None to defer to the next provider.

  • An empty list to indicate no layout (operations become no-ops).

Data validity:

  • Desktops omitted from the result are excluded from navigation. This may be intentional for empty desktops.

  • Desktops included multiple times raise an exception and the result is ignored.

  • Desktops occupying the same grid cell raise an exception and the result is ignored.

Exceptions raised by a provider are caught, logged, and the provider is skipped.

When no provider returns a result, a grid layout is used as fallback. Providers are queried by layout_calc().

def my_layout(desktops):
    # Arrange desktops in a single row.
    return [((i, 0), d) for i, d in enumerate(desktops)]

ion.app.preferences.system.desktop_layout_providers.append(my_layout)
Type:

list[Callable[[list[Desktop]], list[tuple[tuple[int, int], Desktop]] | None]]

Return type:

list[Callable[[list[Desktop]], list[tuple[tuple[int, int], Desktop]] | None]]

notify_on_error

If true, show a desktop notification on Python errors (default: False).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.TabletCollection

Collection of tablet devices accessible as ion.app.input.tablets.

__len__(self)

Get the number of items in the collection.

Return type:

int

__contains__(self, item)

Check if a device exists in the collection.

Parameters:

item (TabletDevice) – The device to check for membership.

Return type:

bool

__iter__(self)

Iterate over all tablet devices.

Return type:

Iterator[TabletDevice]

__getitem__(self, key)

Get a tablet device by index or name. Supports negative indices. A name shared by several devices matches the first of them.

Parameters:

key (str | int) – Device name, or zero-based index.

Return type:

TabletDevice

__getitem__(self, key)
Parameters:

key (slice) – A slice over the tablet devices.

Return type:

tuple[TabletDevice, …]

active

The tablet that most recently produced input (read-only).

Type:

ion.types.TabletDevice | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.TabletDevice

A single physical or virtual tablet device (see Proxy objects).

is_enabled

Whether this device is enabled.

Type:

bool

is_valid

Whether this tablet device is still connected (read-only).

Type:

bool

left_handed

Swap left/right buttons.

Type:

bool

name

Human-readable device name (read-only).

Type:

str

rotation_angle

Rotation angle in degrees, 0..360.

Type:

int

usb_id

USB vendor and product IDs as a (vendor, product) tuple, or None for non-USB devices (read-only).

Type:

tuple[int, int] | None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.TabletPreferences

Tablet device preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

is_enabled

Enable tablet (default: True).

Type:

bool

left_handed

Swap left/right buttons (default: False).

Type:

bool

rotation_angle

Rotation angle in degrees: 0, 90, 180 or 270 (default: 0).

Any other angle is substituted on assignment and logged.

Type:

int

Special Methods
__repr__(self)
Return type:

str

class ion.types.TilingPreferences

Tiling behaviour preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

auto_gaps

Render dividers that fall on a monitor seam gapless automatically (default: False).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.TouchpadPreferences

Touchpad device preferences.

reset(self)

Reset every field in this preference group to its default.

Return type:

None

accel_profile

Acceleration profile (default: "ADAPTIVE").

Type:

Literal[“ADAPTIVE”, “FLAT”]

accel_speed

Acceleration speed -1.0 to 1.0 (default: 0.0).

Type:

float

click_method

Click method (default: "CLICKFINGER").

Type:

Literal[“CLICKFINGER”, “BUTTON_AREAS”]

disable_while_typing

Disable while typing (default: True).

Type:

bool

drag_lock

Drag lock (default: False).

Type:

bool

is_enabled

Enable touchpad (default: True).

Type:

bool

left_handed

Swap left/right buttons (default: False).

Type:

bool

natural_scroll

Invert scroll direction (default: True).

Type:

bool

scroll_method

Scroll method (default: "TWO_FINGER").

Type:

Literal[“TWO_FINGER”, “EDGE”, “BUTTON”]

tap_and_drag

Tap and drag (default: True).

Type:

bool

tap_to_click

Tap to click (default: True).

Type:

bool

Special Methods
__repr__(self)
Return type:

str

class ion.types.UILayout

Collects the GUI elements of a container such as a menu.

Elements are added through the layout, for example menu.layout.operator(...). Wrap additions in context_store() to store the context an operator should act on when it runs, e.g. a divider a menu item targets.

def my_menu(menu):
    layout = menu.layout
    layout.operator(ion.ops.window_close())
    # Pin a divider resolved elsewhere (e.g. the one bordering the
    # focused frame) so the operator acts on it even though it is not
    # under the pointer -- the reason `context_store` exists.
    with layout.context_store(split=target_divider):
        layout.operator(ion.ops.tiling_swap())
    layout.separator()
    layout.menu("submenu_id")
context_store(self, *, window: 'Window | None' = None, frame: 'Frame | None' = None, split: 'SplitNodeContainer | None' = None, output: 'Output | None' = None, workspace: 'Workspace | None' = None, desktop: 'Desktop | None' = None) → 'AbstractContextManager[UILayout]'

Store context values for operators added within the block.

Unlike overriding the live context, this records the values and pins them to each operator added inside the with block; the operator targets them when it runs, after the menu has closed. Each attribute left None keeps the value from any enclosing block or the region’s context. Stores nest.

with menu.layout.context_store(split=divider):
    menu.layout.operator(ion.ops.tiling_swap())
Parameters:
Return type:

AbstractContextManager[UILayout]

menu(self, idname: 'str') → 'None'

Add a submenu reference item.

The display label is taken from the referenced menu’s name.

menu.layout.menu("my_submenu")
Parameters:

idname (str) – Menu identifier to reference.

Return type:

None

operator(self, operator: 'tuple[object, ...]', /, *, text: 'str | None' = None) → 'None'

Add an operator action item.

The label defaults to the operator’s name. Use text to override.

menu.layout.operator(ion.ops.window_close())
menu.layout.operator(ion.ops.tiling_split(direction='RIGHT'), text="Split Right")
Parameters:

  • operator (NamedTuple) – NamedTuple instance (from ion.ops.*(...)).

  • text (str | None) – Optional override for the item label.

Return type:

None

separator(self) → 'None'

Add a visual separator line.

Return type:

None

class ion.types.Window

A toplevel application window (see Proxy objects).

close(self)

Request the window to close gracefully.

Returns:

None.

Return type:

None

find_children(self)

All windows that have this window as their immediate parent.

Returns:

Child windows.

Return type:

list[Window]

focus(self)

Give keyboard focus to this window.

Does nothing while the window is out of reach of the active desktop - in an untiled workspace, a hidden entry, or another desktop - since focus must never name a container the desktop does not show. Use WindowCollection.active_goto() to reach a window regardless of where it is.

Returns:

None.

Return type:

None

fullscreen_move_to_output(self, output)

Move this fullscreen window to another output, keeping it fullscreen. The window becomes the front-most fullscreen window on the target output.

Parameters:

output (Output) – The target output.

Raises:

RuntimeError – If the window is not fullscreen.

Return type:

None

kill(self)

Force-kill an unresponsive window.

Returns:

None.

Return type:

None

move_to_floating(self, desktop, rect=None)

Move this window to the floating layer on the given desktop. Does nothing if already floating.

Parameters:

  • desktop (Desktop) – The target desktop.

  • rect (Rect | tuple[tuple[int, int], tuple[int, int]] | None) – Optional position and size for the floating frame. When None (default), the position and size are derived from the window’s current tiled geometry.

Returns:

The floating desktop item, or None if the window could not be floated.

Return type:

DesktopItemFloatingFrame | None

move_to_frame(self, frame, index=None, activate=True)

Move this window to a different frame.

Parameters:

  • frame (ion.types.Frame) – The target frame.

  • index (int | None) – Tab position in the target frame. Negative indices count from the end (Python-style). None inserts after the active tab (default).

  • activate (bool) – Whether to make this window the active tab and focus the target frame (default True). When False, the window is inserted without changing focus.

Raises:

RuntimeError – If the window is floating or otherwise cannot be moved.

Return type:

None

move_to_tiling(self, workspace=None, frame=None)

Move this window from the floating layer into the tiling layout. Does nothing if the window is already tiled.

Parameters:

  • workspace (Workspace | None) – The target workspace; the window is tiled into its last-active frame. When None (default), the active output’s workspace is used.

  • frame (Frame | None) – The target frame. Takes precedence over workspace when given.

Returns:

The frame the window was tiled into, or None if the window could not be tiled.

Return type:

Frame | None

move_to_workspace(self, workspace)

Move this window to a workspace without following it: focus stays where it is. A tiled window moves into the target’s last-active frame; a floating window is tiled onto the target, since floating windows belong to a desktop, not a workspace. Does nothing if the window is already on the target workspace.

Parameters:

workspace (Workspace) – The target workspace.

Return type:

None

app_id

Application ID (read-only).

Type:

str | None

content_rect

Window content rectangle, excluding decorations, or None if not yet placed (read-only).

Type:

ion.types.Rect | None

data

Per-window dictionary for script-defined data.

Created on first access and persists for the lifetime of the window. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

frame_rect

Window frame rectangle, including decorations, or None if not yet placed (read-only).

Type:

ion.types.Rect | None

fullscreen

Whether the window is fullscreen.

Type:

bool

id

Unique numeric identifier for this window (read-only).

Stable for the lifetime of the window regardless of workspace, desktop, frame, or tiling/floating state changes. Not reused after the window is closed.

Type:

int

is_floating

Whether the window is floating (not tiled) (read-only).

Type:

bool

is_focused

Whether this window has keyboard focus (read-only).

Type:

bool

is_valid

Whether this window still exists in the compositor (read-only).

Type:

bool

output_fullscreen

The output a fullscreen window is on, or None if not fullscreen.

Type:

Output | None

parent

Immediate parent window, or None if this window has no parent (read-only).

Type:

Window | None

parent_root

Root parent window, or None if this window has no parent (read-only).

Walks the XDG parent chain to the topmost ancestor. Falls back to the immediate parent if a cycle is detected.

Type:

Window | None

pid

Process ID of the window’s client (read-only).

None wherever there is no PID to be had: an X11 window that does not set _NET_WM_PID or sets it to something no process wears, and any Wayland window on a platform whose peer credentials cannot be read (everything but Linux and Android).

Type:

int | None

size

Committed geometry size (read-only).

Type:

Size

size_max

Client maximum size hint (read-only).

A component of 0 means unconstrained.

Type:

Size

size_min

Client minimum size hint (read-only).

A component of 0 means unconstrained.

Type:

Size

tag

Whether the window is tagged (marked for batch operations).

Type:

bool

title

Window title (read-only).

Type:

str | None

urgent

Whether the window is urgent.

Type:

bool

workspace

Workspace this window is on, or None for floating windows (read-only).

Type:

ion.types.Workspace | None

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.WindowCollection

Collection accessor for windows.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Window) – The window to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Window]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Window]

__getitem__(self, index)

Get a window by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the window.

Return type:

Window

__getitem__(self, index)
Parameters:

index (slice) – A slice over the windows.

Return type:

tuple[Window, …]

active_goto(self, window)

Jump to a window regardless of desktop, workspace visibility, or fullscreen state. Switches desktop, shows hidden workspaces, un-fullscreens obscuring windows, and focuses the target.

Parameters:

window (ion.types.Window) – The window to jump to.

Returns:

None.

Return type:

None

find_by_id(self, id)

Look up a window by its unique numeric id.

Parameters:

id (int) – The window ID to look up.

Returns:

The window, or None if no window with that ID exists.

Return type:

Window | None

focus_last(self)

Focus the previously focused window.

Does nothing while that window is out of reach of the active desktop - in an untiled workspace, a hidden entry, or another desktop - and resumes once it is reachable again. Use active_goto() to reach a window regardless of where it is.

Returns:

None.

Return type:

None

index(self, window)

Return the index of a window in the collection.

Parameters:

window (ion.types.Window) – The window to find.

Return type:

int

Raises:

ValueError – If the window is not in the collection.

active

Currently focused window (read-only).

Type:

ion.types.Window | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.Workspace

A workspace containing a tiling layout of frames (see Proxy objects).

data

Per-workspace dictionary for script-defined data.

Created on first access and persists for the lifetime of the workspace. Scripts can store arbitrary keys and values here.

Type:

dict[Any, Any]

floating_rect

Floating overlay rectangle.

The rectangle used when this workspace is shown as a floating overlay. Always set (assigned at creation time) and never cleared, even when the workspace is tiled. For the tiled geometry, use DesktopItemTiling.rect instead.

Assigning moves the overlay when the workspace is currently shown as one - on whichever desktop that is, not only the one on screen - relayouting its contents and reconfiguring its windows when the size changed. For a workspace that is an overlay nowhere the rectangle is remembered for the next time it is shown.

Setting accepts a Rect or a (min, max) pair of points.

Type:

ion.types.Rect

frames

All frames in this workspace (read-only).

Type:

ion.types.WorkspaceFrameCollection

id

Unique numeric identifier for this workspace (read-only).

Stable for the lifetime of the workspace regardless of output, desktop, or tiling/floating state changes. Not reused after the workspace is closed.

Type:

int

is_empty

Whether the workspace contains no windows (read-only). A workspace must be empty before it can be removed via remove().

Type:

bool

is_floating

Whether this workspace is currently shown as a floating overlay (read-only).

Floating ownership is exclusive: a workspace appears on at most one desktop’s floating layer, so the check spans all desktops.

Type:

bool

is_focused

Whether this workspace is focused (read-only).

Type:

bool

is_tiling

Whether this workspace is currently tiled (read-only).

Tiling ownership is exclusive: a workspace is tiled on at most one desktop, so the check spans all desktops.

Type:

bool

is_valid

Whether this workspace still exists in the compositor (read-only).

Type:

bool

name

Workspace name.

Type:

str

root

Root of the tiling layout tree (read-only).

Type:

ion.types.SplitNode

windows

All windows in this workspace (read-only).

Type:

ion.types.WorkspaceWindowCollection

Special Methods
__eq__(self, other)

Return self==value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__hash__(self)
Return type:

int

__ne__(self, other)

Return self!=value.

Parameters:

other (object) – The object to compare against.

Return type:

bool

__repr__(self)
Return type:

str

class ion.types.WorkspaceCollection

Collection accessor for workspaces.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Workspace) – The workspace to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Workspace]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Workspace]

__getitem__(self, key)

Get a workspace by name or index. Supports negative indices.

Parameters:

key (str | int) – Workspace name, or zero-based index.

Return type:

Workspace

__getitem__(self, key)
Parameters:

key (slice) – A slice over the workspaces.

Return type:

tuple[Workspace, …]

find_by_frame(self, frame)

Find the workspace containing the given frame.

Parameters:

frame (ion.types.Frame) – The frame to search for.

Returns:

The workspace containing the frame, or None if not found.

Return type:

ion.types.Workspace | None

find_by_id(self, id)

Look up a workspace by its unique numeric id.

Parameters:

id (int) – The workspace ID to look up.

Returns:

The workspace, or None if no workspace with that ID exists.

Return type:

Workspace | None

find_by_output(self, output)

Find the tiled workspace visible on the given output.

Parameters:

output (ion.types.Output) – The output to query.

Returns:

The workspace on that output, or None if none assigned.

Return type:

ion.types.Workspace | None

find_by_window(self, window)

Find the workspace containing the given window.

Parameters:

window (ion.types.Window) – The window to search for.

Returns:

The workspace containing the window, or None if the window is floating or not found.

Return type:

ion.types.Workspace | None

get(self, name)

Get a workspace by name.

Parameters:

name (str) – The workspace name.

Returns:

The workspace, or None if not found.

Return type:

ion.types.Workspace | None

index(self, workspace)

Return the index of a workspace in the collection.

Parameters:

workspace (ion.types.Workspace) – The workspace to find.

Return type:

int

Raises:

ValueError – If the workspace is not in the collection.

items(self)

All (name, workspace) pairs.

Returns:

List of (name, workspace) tuples.

Return type:

list[tuple[str, ion.types.Workspace]]

keys(self)

All workspace names.

Returns:

List of workspace name strings.

Return type:

list[str]

new(self, floating_rect, name='')

Create a new workspace with the given name.

If a workspace with that name already exists, a unique name is generated by appending a number (e.g., “scratch.1”, “scratch.2”). When name is empty, a numbered name is generated automatically.

The workspace is not yet visible. Use DesktopTilingCollection.add() or DesktopFloatingCollection.add() to place it on a desktop.

Parameters:

  • floating_rect (ion.types.Rect | tuple[tuple[int, int], tuple[int, int]]) – Geometry in global coordinates, used when the workspace is shown as a floating overlay.

  • name (str) – Base name for the new workspace.

Returns:

The newly created workspace.

Return type:

ion.types.Workspace

new_from_split_node(self, node)

Create a new workspace by extracting a node from the tiling tree.

For a leaf this extracts a single frame; for a container the entire subtree (including all children) is extracted. When the root node is extracted, the source workspace is reset to a single empty frame.

The new workspace is not yet visible. Use DesktopFloatingCollection.add() or DesktopTilingCollection.add() to place it on a desktop.

The new workspace’s floating_rect is seeded from the extracted node’s pre-extraction rect, so a subsequent floating placement appears where the user just saw the subtree. Override the seeded value by assigning ws.floating_rect before placement.

Parameters:

node (ion.types.SplitNode) – The split node to extract.

Returns:

The newly created workspace.

Return type:

ion.types.Workspace

Raises:

RuntimeError – If the node cannot be extracted.

remove(self, workspace)

Remove a workspace. The workspace must not contain any windows.

Parameters:

workspace (ion.types.Workspace) – The workspace to remove.

Raises:

RuntimeError – If the workspace contains windows.

Return type:

None

active

Currently focused workspace (read-only).

Derived from the focus entry, which by design lives on the active desktop. The returned workspace is therefore guaranteed to be on the active desktop - either tiled there or shown as a floating overlay there. Workspaces tiled or floating on other desktops are never returned by this accessor.

Type:

ion.types.Workspace | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.WorkspaceFrameCollection

Collection accessor for frames within a specific workspace.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Frame) – The frame to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Frame]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Frame]

__getitem__(self, index)

Get a frame by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the frame.

Return type:

Frame

__getitem__(self, index)
Parameters:

index (slice) – A slice over the frames.

Return type:

tuple[Frame, …]

find_by_id(self, id)

Look up a frame by its unique numeric id, only if it belongs to this workspace.

Parameters:

id (int) – The frame ID to look up.

Returns:

The frame, or None if no matching frame exists in this workspace.

Return type:

Frame | None

index(self, frame)

Return the index of a frame in this workspace.

Parameters:

frame (ion.types.Frame) – The frame to find.

Return type:

int

Raises:

ValueError – If the frame is not in this workspace.

active

Focused frame on this workspace (read-only).

Type:

ion.types.Frame | None

Special Methods
__repr__(self)
Return type:

str

class ion.types.WorkspaceWindowCollection

Collection accessor for windows within a specific workspace.

__len__(self)

Get the number of items in the collection.

Return type:

int

__bool__(self)

True if the collection is non-empty.

Return type:

bool

__contains__(self, value)

Check if a value exists in the collection.

Parameters:

value (Window) – The window to check for membership.

Return type:

bool

__iter__(self)

Iterate over all items in the collection.

Return type:

Iterator[Window]

__reversed__(self)

Iterate over all items in reverse order.

Return type:

Iterator[Window]

__getitem__(self, index)

Get a window by index. Supports negative indices.

Parameters:

index (int) – Zero-based index of the window.

Return type:

Window

__getitem__(self, index)
Parameters:

index (slice) – A slice over the windows.

Return type:

tuple[Window, …]

find_by_id(self, id)

Look up a window by its unique numeric id, only if it belongs to this workspace.

Parameters:

id (int) – The window ID to look up.

Returns:

The window, or None if no matching window exists in this workspace.

Return type:

Window | None

index(self, window)

Return the index of a window in this workspace.

Parameters:

window (ion.types.Window) – The window to find.

Return type:

int

Raises:

ValueError – If the window is not in this workspace.

active

Focused window on this workspace (read-only).

Type:

ion.types.Window | None

Special Methods
__repr__(self)
Return type:

str