0
# Event Handling
1
2
Comprehensive event subscription and handling system for real-time monitoring of window manager state changes. Supports fine-grained event filtering and both synchronous and asynchronous event processing.
3
4
## Capabilities
5
6
### Event Subscription
7
8
```python { .api }
9
def on(self, event: Union[Event, str], handler: Callable[[Connection, IpcBaseEvent], None]) -> None:
10
"""
11
Subscribe to window manager events.
12
13
Parameters:
14
- event: Union[Event, str], event type to subscribe to
15
- handler: Callable, function called when event occurs (receives connection and event data)
16
"""
17
18
def off(self, handler: Callable[[Connection, IpcBaseEvent], None]) -> None:
19
"""
20
Unsubscribe event handler from all events.
21
22
Parameters:
23
- handler: Callable, handler function to remove from all subscriptions
24
"""
25
```
26
27
### Event Loop Management
28
29
```python { .api }
30
def main(self, timeout: float = 0.0) -> None:
31
"""
32
Start the main event loop to process subscribed events.
33
34
Parameters:
35
- timeout: float, timeout in seconds (0 = run forever until main_quit called)
36
"""
37
38
def main_quit(self) -> None:
39
"""
40
Stop the main event loop and exit event processing.
41
"""
42
```
43
44
### Event Types
45
46
```python { .api }
47
class Event(Enum):
48
"""Enumeration of all available event types for subscription."""
49
50
# Primary event categories
51
WORKSPACE = 'workspace' # Any workspace change
52
WINDOW = 'window' # Any window change
53
OUTPUT = 'output' # Output/monitor changes
54
MODE = 'mode' # Binding mode changes
55
BARCONFIG_UPDATE = 'barconfig_update' # Bar configuration changes
56
BINDING = 'binding' # Key/mouse binding events
57
SHUTDOWN = 'shutdown' # Window manager shutdown events
58
TICK = 'tick' # Tick events from send_tick()
59
INPUT = 'input' # Input device changes (sway only)
60
61
# Specific workspace events
62
WORKSPACE_FOCUS = 'workspace::focus' # Workspace gained focus
63
WORKSPACE_INIT = 'workspace::init' # New workspace created
64
WORKSPACE_EMPTY = 'workspace::empty' # Workspace became empty
65
WORKSPACE_URGENT = 'workspace::urgent' # Workspace urgency changed
66
WORKSPACE_RELOAD = 'workspace::reload' # Workspace configuration reloaded
67
WORKSPACE_RENAME = 'workspace::rename' # Workspace was renamed
68
WORKSPACE_RESTORED = 'workspace::restored' # Workspace restored from session
69
WORKSPACE_MOVE = 'workspace::move' # Workspace moved to different output
70
71
# Specific window events
72
WINDOW_NEW = 'window::new' # New window created
73
WINDOW_CLOSE = 'window::close' # Window closed
74
WINDOW_FOCUS = 'window::focus' # Window gained focus
75
WINDOW_TITLE = 'window::title' # Window title changed
76
WINDOW_FULLSCREEN_MODE = 'window::fullscreen_mode' # Fullscreen state changed
77
WINDOW_MOVE = 'window::move' # Window moved to different container
78
WINDOW_FLOATING = 'window::floating' # Window floating state changed
79
WINDOW_URGENT = 'window::urgent' # Window urgency changed
80
WINDOW_MARK = 'window::mark' # Window mark added/removed
81
82
# Shutdown events
83
SHUTDOWN_RESTART = 'shutdown::restart' # Window manager restarting
84
SHUTDOWN_EXIT = 'shutdown::exit' # Window manager exiting
85
86
# Input events (sway only)
87
INPUT_ADDED = 'input::added' # Input device connected
88
INPUT_REMOVED = 'input::removed' # Input device disconnected
89
```
90
91
### Event Classes
92
93
```python { .api }
94
class IpcBaseEvent:
95
"""Abstract base class for all event objects."""
96
ipc_data: dict # Raw IPC event data from window manager
97
98
class WorkspaceEvent(IpcBaseEvent):
99
"""Workspace-related event information."""
100
change: str # Type of change (focus, init, empty, urgent, etc.)
101
current: Con # Current workspace container (may be None)
102
old: Con # Previous workspace container (may be None)
103
104
class WindowEvent(IpcBaseEvent):
105
"""Window-related event information."""
106
change: str # Type of change (new, close, focus, title, etc.)
107
container: Con # Affected window container
108
109
class OutputEvent(IpcBaseEvent):
110
"""Output/monitor-related event information."""
111
change: str # Type of change (output added, removed, etc.)
112
113
class ModeEvent(IpcBaseEvent):
114
"""Binding mode change event information."""
115
change: str # Mode change type
116
pango_markup: bool # Whether pango markup is enabled for mode display
117
118
class BarconfigUpdateEvent(BarConfigReply):
119
"""Bar configuration update event (inherits all BarConfigReply properties)."""
120
# Inherits: id, mode, position, status_command, font, colors, etc.
121
122
class BindingEvent(IpcBaseEvent):
123
"""Key or mouse binding event information."""
124
change: str # Binding change type
125
binding: BindingInfo # Details about the binding
126
127
class ShutdownEvent(IpcBaseEvent):
128
"""Window manager shutdown event information."""
129
change: str # Shutdown type (restart, exit)
130
131
class TickEvent(IpcBaseEvent):
132
"""Tick event information from send_tick() calls."""
133
first: Optional[bool] # Whether this is the first tick (None in i3 ≤4.15)
134
payload: str # Payload data sent with tick
135
136
class InputEvent(IpcBaseEvent):
137
"""Input device change event (sway only)."""
138
change: str # Change type (added, removed)
139
input: InputReply # Input device information
140
```
141
142
### Binding Information
143
144
```python { .api }
145
class BindingInfo:
146
"""Detailed information about key/mouse bindings."""
147
command: str # Command associated with binding
148
event_state_mask: List[str] # Modifier keys (Shift, Ctrl, Alt, etc.)
149
input_code: int # Key code or mouse button code
150
symbol: Optional[str] # Key symbol or mouse button name (may be None)
151
input_type: str # Input type ('keyboard' or 'mouse')
152
symbols: List[str] # Additional symbols for binding (sway only)
153
mods: List[str] # Modifier keys (i3 only, not included in sway)
154
ipc_data: dict # Raw IPC binding data
155
```
156
157
### Event Handler Examples
158
159
```python
160
# Simple event handler
161
def on_window_focus(i3, event):
162
print(f"Window focused: {event.container.name}")
163
164
# Handler with event data access
165
def on_workspace_change(connection, event):
166
if event.change == 'focus':
167
print(f"Switched to workspace: {event.current.name}")
168
if event.old:
169
print(f"Previous workspace: {event.old.name}")
170
171
# Handler for binding events
172
def on_binding(i3, event):
173
binding = event.binding
174
print(f"Key pressed: {binding.symbol} -> {binding.command}")
175
print(f"Modifiers: {', '.join(binding.event_state_mask)}")
176
177
# Subscribe to events
178
i3.on(Event.WINDOW_FOCUS, on_window_focus)
179
i3.on(Event.WORKSPACE_FOCUS, on_workspace_change)
180
i3.on(Event.BINDING, on_binding)
181
182
# Start event processing
183
i3.main() # Runs until main_quit() called
184
```