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.

desktop_axis¶

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

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.

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 (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) – 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

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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 (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) – 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

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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:

base (ion.types.ContextSnapshot | None) – Snapshot whose values fill attributes left unset, or None.
window (ion.types.Window | None) – The window the operator should target.
frame (ion.types.Frame | None) – The frame the operator should target.
split (ion.types.SplitNodeContainer | None) – The split whose divider the operator should target.
output (ion.types.Output | None) – The output the operator should target.
workspace (ion.types.Workspace | None) – The workspace the operator should target.
desktop (ion.types.Desktop | None) – The desktop the operator should target.

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.

size¶

Cursor size in pixels (default: 24).

Type:: int

theme¶

Cursor theme name (default: “default”).

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).

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

focused_active_bevel_highlight¶

Bevel highlight for focused active tab.

Type:: ion.types.ColorRGB

focused_active_bevel_shadow¶

Bevel shadow for focused active tab.

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_color¶

Menu text color (hovered items).

Type:: ion.types.ColorRGB

menu_text_color_inactive¶

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

Type:: ion.types.ColorRGB

outline¶

Outline color. Currently unused by the renderer (the tab-bar outline it drove was replaced by ion.app.decor.geom.tab_pad); retained for configuration compatibility.

Type:: ion.types.ColorRGB

tab_focused_active¶

Active tab in focused frame.

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_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

unfocused_active_bevel_highlight¶

Bevel highlight for unfocused active tab.

Type:: ion.types.ColorRGB

unfocused_active_bevel_shadow¶

Bevel shadow for unfocused active tab.

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.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

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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

__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]

__getitem__(self, key)¶

Get a desktop by name or index.

Parameters:: key (str | int) – Desktop name, or zero-based index.
Return type:: 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.Preferences.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

__iter__(self)¶

Iterate over all floating entries (bottom to top).

Return type:: Iterator[DesktopItemFloating]

__getitem__(self, index)¶

Get a floating entry by depth index.

Parameters:: index (int) – Zero-based depth index (0 is the bottom).
Return type:: 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:

a (DesktopItemFloating) – First entry (must belong to this desktop).
b (DesktopItemFloating) – Second entry (must belong to this desktop).

Return type:

None

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

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

depth_to_front(self)¶

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

Returns:: None.
Return type:: None

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

depth¶

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

Type:: int

rect¶

Bounding rectangle in logical pixels.

Type:: ion.types.Rect

visible¶

Whether this entry is visible.

Type:: bool

Special Methods

__eq__(self, other)¶

Return self==value.

Parameters:: other (object) – The object to compare against.
Return type:: bool

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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).

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

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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

Special Methods

__eq__(self, other)¶

Return self==value.

Parameters:: other (object) – The object to compare against.
Return type:: bool

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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

__iter__(self)¶

Iterate over all tiling entries.

Return type:: Iterator[DesktopItemTiling]

__getitem__(self, index)¶

Get a tiling entry by index.

Parameters:: index (int) – Zero-based index of the tiling entry to retrieve.
Return type:: 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.

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

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)

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:

modifiers (int) – Modifier bitmask (see ion.constants.modifiers).
position (Point) – Pointer position.

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.

Type:: int

Special Methods

__repr__(self)¶

Return type:: str

class ion.types.EventCancel¶

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

Return type:: EventCancel

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 | 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)¶

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) – Pointer position.

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:

modifiers (int) – Modifier bitmask (see ion.constants.modifiers).
position (Point) – Pointer position.

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)¶

Parameters:

position (Point) – Pointer position.
modifiers (int) – Modifier bitmask (see ion.constants.modifiers).

Return type:

None

Special Methods

__repr__(self)¶

Return type:: str

class ion.types.EventPointer(Event)¶

Pointer button event.

__init__(self, button, press, *, modifiers, position)¶

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) – Pointer position.

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)¶

Parameters:

delta_x (float) – Horizontal scroll delta.
delta_y (float) – Vertical scroll delta.
modifiers (int) – Modifier bitmask (see ion.constants.modifiers).
position (Point) – Pointer position.

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¶

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

Return type:: EventTimer

Special Methods

__repr__(self)¶

Return type:: str

class ion.types.FloatingPreferences¶

Floating window placement preferences.

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.

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).

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.

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.

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.

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.

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.
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.

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

__ge__(self, other)¶

Return self>=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__gt__(self, other)¶

Return self>value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__hash__(self)¶

Return type:: int

__le__(self, other)¶

Return self<=value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__lt__(self, other)¶

Return self<value.

Parameters:: other (Self) – The other operand.
Return type:: bool

__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

__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]

__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.

Parameters:: point (ion.types.Point) – 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.

Parameters:: rect (ion.types.Rect) – 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

__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]

__getitem__(self, index)¶

Get a window by index.

Parameters:: index (int) – Zero-based index of the window to retrieve.
Return type:: 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_reload_post¶

Fired after the config script has been re-executed.

Callbacks receive no arguments.

Type:: Hook[Callable[[], None]]

compositor_reload_pre¶

Fired before the config script is re-executed. All keybindings, menus, and hook callbacks are cleared before reload.

Callbacks receive no arguments.

Type:: Hook[Callable[[], None]]

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_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.