ion.ops ======= .. module:: ion.ops .. include:: ../rst/ion.ops.rst Operators that can be bound to keys or called directly. Functions --------- .. function:: register(idname, *, name, exec, poll=None, description="", properties=None, pointer_only=False, properties_type) Register a dynamic operator from Python. .. code-block:: python ion.ops.register("my_op", name=MyOp.name, exec=MyOp.exec, properties_type=MyProperties) :param idname: Unique operator identifier. :type idname: str :param name: Display name callback receiving a ``properties_type`` instance. :type name: ``Callable[..., str]`` :param exec: Callback receiving a ``properties_type`` instance and an :class:`~ion.types.Event`. Must return ``bool`` or ``None``: - ``True`` - the operator handled the event (binding consumed). - ``False`` - the operator failed (binding still consumed). - ``None`` - pass-through. The operator declined to handle this event. When the same key is bound to multiple operators (across keymaps or within a single keymap), the binding system tries the next matching operator. This allows context-sensitive fall-through where several operators share one key and each checks whether it should act. :type exec: ``Callable[[Any, :class:`~ion.types.Event`], bool | None]`` :param poll: Optional callback receiving a ``properties_type`` instance, returning None if the operator is available, or a reason string if not. :type poll: ``Callable[..., Any]`` | None :param description: Description of the operator. :type description: str :param properties: Property definitions for the operator. :type properties: dict[str, Any] | None :param pointer_only: If true, operator can only be triggered by pointer bindings. :type pointer_only: bool :param properties_type: NamedTuple class for typed operator properties. :type properties_type: type **Custom Operator** Register a custom operator with :func:`ion.ops.register` and bind it to a key. The ``exec`` callback receives a NamedTuple whose fields are declared at registration time via ``properties_type``, and an :class:`~ion.types.Event` describing the input that triggered it. .. literalinclude:: ../examples/ion.ops.register.0.py :lines: 9- .. function:: unregister(idname) Unregister a dynamic operator by identifier. Only operators registered via :func:`register` can be removed. Static (built-in) operators cannot be unregistered. .. code-block:: python ion.ops.unregister("my_op") :param idname: Operator identifier to remove. :type idname: str :returns: Whether the operator was found and removed. :rtype: bool Operators --------- .. function:: compositor_logout() Graceful logout: close all windows, exit when none remain. .. function:: compositor_quit() Exit the compositor. .. function:: compositor_reload() Reload the configuration file. .. function:: delete_empty_workspace() Delete the current workspace. .. function:: desktop_delete() Delete the current desktop. .. function:: desktop_focus_cycle(direction, wrap=True, animate=False) Cycle through desktops. :param direction: Positive for next, negative for previous. :type direction: int :param wrap: Wrap around at the ends. :type wrap: bool :param animate: Use zoom animation. :type animate: bool .. function:: desktop_focus_directional(direction, wrap=True, animate=False) Focus the adjacent desktop in a direction. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] :param wrap: Wrap to the opposite desktop when at the edge. :type wrap: bool :param animate: Use zoom animation. :type animate: bool .. function:: desktop_focus_empty_cycle(direction, wrap=True, name='', animate=False) Cycle through empty desktops, creating one if none exist. :param direction: Positive for next, negative for previous. :type direction: int :param wrap: Wrap around at the ends. :type wrap: bool :param name: Name for the new desktop if one is created. :type name: str :param animate: Use zoom animation. :type animate: bool .. function:: desktop_focus_occupied_cycle(direction, wrap=True, animate=False) Cycle through occupied desktops. :param direction: Positive for next, negative for previous. :type direction: int :param wrap: Wrap around at the ends. :type wrap: bool :param animate: Use zoom animation. :type animate: bool .. function:: desktop_item_carousel_cancel() Cancel desktop item carousel. .. function:: desktop_item_carousel_confirm() Confirm selection in desktop item carousel. .. function:: desktop_item_cycle_carousel(keymap) Show all desktop items on a 3D carousel, select one to focus. :param keymap: Keymap name for input handling. :type keymap: str .. function:: desktop_new(name='') Create a new empty desktop. :param name: Desktop name. Empty string uses a default name. :type name: str .. function:: desktop_overview(keymap, trim_empty=False) Zoom out to show all desktops, click one to switch. :param keymap: Keymap name for input handling. :type keymap: str :param trim_empty: Trim empty desktops from end-points (active desktop always included). :type trim_empty: bool .. function:: desktop_overview_cancel() Cancel desktop overview. .. function:: desktop_overview_confirm() Confirm selection in desktop overview. .. function:: desktop_overview_navigate(direction) Navigate selection in desktop overview. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] .. function:: desktop_overview_select() Select desktop at pointer position in desktop overview. .. function:: floating_depth_to_back() Lower a floating item to the back. .. function:: floating_depth_to_front() Raise a floating item to the front. .. function:: floating_lower() Lower the floating item under the pointer (pointer binding only). .. function:: floating_move() Move a floating item by dragging (pointer binding only). .. function:: floating_raise() Raise the floating item under the pointer (pointer binding only). .. function:: floating_resize(border=False) Resize a floating item by dragging (pointer binding only). :param border: Use border-relative edge detection (drag initiated from border). :type border: bool .. function:: frame_delete() Remove the current frame from its parent split. .. function:: frame_focus_cycle(direction) Cycle frame focus in the workspace, wrapping around. :param direction: Positive for next, negative for previous. :type direction: int .. function:: frame_join() Recursively merge the parent split into a single frame. .. function:: frame_tab_activate() Activate the tab under the pointer. .. function:: frame_tab_cycle(direction) Cycle tabs in the current frame. :param direction: Positive for next, negative for previous. :type direction: int .. function:: frame_tab_drag() Drag a tiled tab to move it between frames (pointer binding only). .. function:: frame_tab_index_move(direction) Move the current tab to the next/previous position. :param direction: Positive for next, negative for previous. :type direction: int .. function:: frame_tab_nth(tab_index) Switch to tab N in the current frame. :param tab_index: Zero-based tab index. :type tab_index: int .. function:: frame_tile() Tile floating workspace frame back into the tiling workspace. .. function:: frame_untile() Extract frame from tiling into a floating workspace. .. function:: keymap_prompt(name) Activate a keymap for the next key press (leader key). :param name: The keymap name. :type name: str .. function:: menu_show(idname) Show a named context menu. :param idname: The menu identifier. :type idname: str .. function:: output_focus_directional(direction, wrap=True) Focus the adjacent output (monitor) in a direction. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] :param wrap: Wrap to an aligned or diagonal corner-touch output. :type wrap: bool .. function:: output_move_directional(direction, pointer_warp=True, wrap=True) Move the focused item (floating, tiled, or fullscreen) to the output in a direction. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] :param pointer_warp: Warp pointer to follow the moved item. :type pointer_warp: bool :param wrap: Wrap to an aligned or diagonal corner-touch output. :type wrap: bool .. function:: python_exec(filepath) Execute a Python script. :param filepath: Path to the Python file. :type filepath: str .. function:: system_exec(command) Execute a command directly (no shell). :param command: Program and arguments. :type command: tuple[str, ...] .. function:: system_noop() Do nothing. Useful for overriding bindings in higher-priority keymaps. .. function:: system_shell(command) Execute a shell command. :param command: Shell command to execute. :type command: str .. function:: tag_attach() Attach all tagged windows to the current frame as tabs. .. function:: tag_clear() Untag all tagged windows. .. function:: tag_set(mode=-1) Set the tagged state of the focused window. :param mode: -1 to toggle, 0 to untag, 1 to tag. :type mode: Literal[-1, 0, 1] .. function:: tiling_divider_gapless_set(mode=-1, parent_depth=0) Set whether the split divider renders flush, with no gap between its frames. :param mode: -1 to toggle, 0 to show the divider, 1 to make it gapless, 2 for automatic. :type mode: Literal[-1, 0, 1, 2] :param parent_depth: 0 for the frame's parent, 1 for grandparent, etc. -1 for root. :type parent_depth: int .. function:: tiling_divider_resize() Resize by dragging the split divider under the pointer (pointer binding only). .. function:: tiling_floating_split(direction) Extract the sibling subtree of the current frame into a floating workspace. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] .. function:: tiling_focus_directional(direction, wrap=True) Focus the frame in a direction. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] :param wrap: Wrap to an aligned output, diagonal output, or this output. :type wrap: bool .. function:: tiling_orient_directional(direction) Orient the split so the active frame is located in a particular direction. This provides a convenient way to orient the active frame without having to perform separate axis-rotate and swap operation. :param direction: Direction to place the active frame in relation to it's sibling. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] .. function:: tiling_resize(delta) Resize the current frame by a delta in logical pixels. :param delta: Amount in logical pixels (positive grows, negative shrinks). :type delta: int .. function:: tiling_split(direction) Split the current frame in a direction. :param direction: Direction to place the new frame. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] .. function:: tiling_split_axis_rotate(angle=90, parent_depth=0, pointer_warp=True) Rotate the split axis by 90, 180, or 270 degrees. :param angle: 90 (left), 180 (flip), or 270 (right). :type angle: Literal[90, 180, 270] :param parent_depth: 0 for the frame's parent, 1 for grandparent, etc. -1 for root. :type parent_depth: int :param pointer_warp: Warp pointer to the active frame after changing. :type pointer_warp: bool .. function:: tiling_split_axis_set(axis=-1, parent_depth=0, pointer_warp=True) Set or toggle the split direction at a given depth. :param axis: -1 to toggle, 0 for horizontal, 1 for vertical. :type axis: int :param parent_depth: 0 for the frame's parent, 1 for grandparent, etc. -1 for root. :type parent_depth: int :param pointer_warp: Warp pointer to the active frame after changing. :type pointer_warp: bool .. function:: tiling_swap(parent_depth=0, pointer_warp=True) Swap the two children at a given depth. :param parent_depth: 0 for the frame's parent, 1 for grandparent, etc. -1 for root. :type parent_depth: int :param pointer_warp: Warp pointer to the active frame after swapping. :type pointer_warp: bool .. function:: window_carousel_cancel() Cancel window carousel. .. function:: window_carousel_confirm() Confirm selection in window carousel. .. function:: window_close(delete_empty_frame=False, delete_empty_workspace=False) Close focused window, or remove frame if empty. :param delete_empty_frame: Remove the frame when it has no windows. :type delete_empty_frame: bool :param delete_empty_workspace: Delete the workspace if it has only one empty frame. :type delete_empty_workspace: bool .. function:: window_cycle_carousel(keymap) Show all windows on a 3D carousel, select one to focus. :param keymap: Keymap name for input handling. :type keymap: str .. function:: window_floating_set(mode=-1) Set the floating state of the focused window. :param mode: -1 to toggle, 0 to tile, 1 to float. :type mode: Literal[-1, 0, 1] .. function:: window_focus_last() Focus the previously focused window. .. function:: window_fullscreen_set(mode=-1) Set the fullscreen state of the focused window. :param mode: -1 to toggle, 0 to disable, 1 to enable. :type mode: Literal[-1, 0, 1] .. function:: window_kill() Force-kill an unresponsive window. .. function:: window_overview(keymap) Zoom out to show all windows across desktops in a grid. :param keymap: Keymap name for input handling. :type keymap: str .. function:: window_overview_cancel() Cancel window overview. .. function:: window_overview_confirm() Confirm selection in window overview. .. function:: window_overview_navigate(direction) Navigate selection in window overview. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] .. function:: window_overview_select() Select window at pointer position in window overview. .. function:: window_switcher(keymap, direction=1) Alt-Tab style switcher for windows on the current desktop. :param keymap: Keymap name for input handling. :type keymap: str :param direction: Initial step applied on invocation: `1` keeps the active window selected (forward shortcut), `-1` steps one backwards (reverse shortcut). :type direction: int .. function:: window_switcher_cancel() Cancel the window switcher without activating a window. .. function:: window_switcher_next() Advance the window switcher selection. .. function:: window_switcher_prev() Retreat the window switcher selection. .. function:: window_tiling_move_directional(direction, wrap=True) Move the focused window to a frame in a direction. :param direction: Direction to move. :type direction: Literal['LEFT', 'RIGHT', 'UP', 'DOWN'] :param wrap: Wrap to an aligned output, diagonal output, or this output. :type wrap: bool .. function:: window_workspace_pop(name, window_index=-1) Move a window from a named workspace to the focused frame. :param name: Source workspace name. :type name: str :param window_index: Window index. -1 is the most recently added window, 0 is the oldest. Supports negative indexing, clamped to range. :type window_index: int .. function:: window_workspace_push(name) Send focused window to named workspace. :param name: Target workspace name. :type name: str .. function:: workspace_floating_set(name, mode=-1, use_active_output=True) Set a named workspace as floating overlay. :param name: Workspace name. :type name: str :param mode: -1 to toggle, 0 to hide, 1 to show. :type mode: Literal[-1, 0, 1] :param use_active_output: Reposition overlay to active output when showing. :type use_active_output: bool .. function:: workspace_new_floating(name='') Create a new floating workspace. :param name: Workspace name. Empty string uses a default name. :type name: str .. function:: workspace_new_tiling_on_desktop(name='') Create a new tiling workspace. :param name: Workspace name. Empty string uses a default name. :type name: str .. function:: workspace_new_tiling_on_output(name='') Create a new tiling workspace confined to the output under the cursor. :param name: Workspace name. Empty string uses a default name. :type name: str .. function:: workspace_tile_on_desktop() Convert floating workspace to a tiled workspace. .. function:: workspace_tile_on_output() Convert floating workspace to a per-output tiled workspace. .. function:: workspace_untile() Convert tiled workspace to a floating workspace.