0
# Container Tree Navigation
1
2
Comprehensive functionality for navigating and searching the hierarchical window/container tree structure in i3/sway. Provides methods to find specific containers, traverse relationships, and access container properties.
3
4
## Capabilities
5
6
### Container Properties
7
8
```python { .api }
9
class Con:
10
"""
11
Container representation with comprehensive properties and navigation methods.
12
"""
13
# Core identification
14
id: int # Unique container ID
15
name: str # Container name
16
type: str # Container type (workspace, con, floating_con, etc.)
17
num: int # Workspace number (for workspace containers)
18
19
# Layout and positioning
20
layout: str # Layout type (splith, splitv, stacked, tabbed, etc.)
21
orientation: str # Container orientation
22
percent: float # Size percentage within parent
23
rect: Rect # Container rectangle (x, y, width, height)
24
window_rect: Optional[Rect] # Window rectangle within container (may be None)
25
deco_rect: Optional[Rect] # Decoration rectangle (may be None)
26
geometry: Optional[Rect] # Window geometry (may be None)
27
28
# State properties
29
urgent: bool # Urgent state
30
focused: bool # Focus state
31
focus: List[int] # Focus stack (container IDs)
32
sticky: bool # Sticky state
33
floating: bool # Floating state
34
fullscreen_mode: int # Fullscreen mode (0=none, 1=output, 2=global)
35
scratchpad_state: str # Scratchpad state
36
37
# Visual properties
38
border: str # Border style
39
current_border_width: int # Current border width in pixels
40
41
# Window-specific properties
42
window: int # X11 window ID (if applicable)
43
window_class: Optional[str] # Window class name (may be None)
44
window_instance: Optional[str] # Window instance name (may be None)
45
window_role: Optional[str] # Window role (may be None)
46
window_title: Optional[str] # Window title text (may be None)
47
48
# Tree structure
49
nodes: List[Con] # Child containers
50
floating_nodes: List[Con] # Floating child containers
51
marks: List[str] # Container marks
52
53
# Sway-specific properties
54
app_id: str # Application ID (sway/wayland)
55
pid: int # Process ID
56
visible: bool # Visibility state
57
representation: str # Container representation string
58
gaps: Optional[Gaps] # Gap configuration (may be None)
59
```
60
61
### Tree Navigation
62
63
```python { .api }
64
def root(self) -> Con:
65
"""
66
Get the root container of the tree.
67
68
Returns:
69
Con: root container at top of hierarchy
70
"""
71
72
def descendants(self) -> List[Con]:
73
"""
74
Get all descendant containers recursively.
75
76
Returns:
77
List[Con]: all containers below this one in the tree
78
"""
79
80
def leaves(self) -> List[Con]:
81
"""
82
Get all leaf containers (containers with no children).
83
84
Returns:
85
List[Con]: containers that have no child containers
86
"""
87
88
def workspaces(self) -> List[Con]:
89
"""
90
Get all workspace containers in the tree.
91
92
Returns:
93
List[Con]: all containers of type 'workspace'
94
"""
95
96
def workspace(self) -> Optional[Con]:
97
"""
98
Get the workspace container that contains this container.
99
100
Returns:
101
Optional[Con]: parent workspace container or None if not found
102
"""
103
104
def scratchpad(self) -> Optional[Con]:
105
"""
106
Get the scratchpad container.
107
108
Returns:
109
Optional[Con]: scratchpad container for hidden windows or None if not found
110
"""
111
```
112
113
### Search by Identity
114
115
```python { .api }
116
def find_focused(self) -> Optional[Con]:
117
"""
118
Find the currently focused container in the tree.
119
120
Returns:
121
Optional[Con]: focused container or None if no focus
122
"""
123
124
def find_by_id(self, id: int) -> Optional[Con]:
125
"""
126
Find container by unique ID.
127
128
Parameters:
129
- id: int, container ID to search for
130
131
Returns:
132
Optional[Con]: matching container or None if not found
133
"""
134
135
def find_by_window(self, window: int) -> Optional[Con]:
136
"""
137
Find container by X11 window ID.
138
139
Parameters:
140
- window: int, X11 window ID to search for
141
142
Returns:
143
Optional[Con]: container containing the window or None
144
"""
145
146
def find_by_pid(self, pid: int) -> List[Con]:
147
"""
148
Find containers by process ID (sway only).
149
150
Parameters:
151
- pid: int, process ID to search for
152
153
Returns:
154
List[Con]: containers belonging to the process
155
"""
156
```
157
158
### Search by Pattern
159
160
```python { .api }
161
def find_named(self, pattern: str) -> List[Con]:
162
"""
163
Find containers by name pattern using regex.
164
165
Parameters:
166
- pattern: str, regular expression to match against container names
167
168
Returns:
169
List[Con]: containers with names matching the pattern
170
"""
171
172
def find_titled(self, pattern: str) -> List[Con]:
173
"""
174
Find containers by window title pattern using regex.
175
176
Parameters:
177
- pattern: str, regular expression to match against window titles
178
179
Returns:
180
List[Con]: containers with titles matching the pattern
181
"""
182
183
def find_classed(self, pattern: str) -> List[Con]:
184
"""
185
Find containers by window class pattern using regex.
186
187
Parameters:
188
- pattern: str, regular expression to match against window classes
189
190
Returns:
191
List[Con]: containers with classes matching the pattern
192
"""
193
194
def find_instanced(self, pattern: str) -> List[Con]:
195
"""
196
Find containers by window instance pattern using regex.
197
198
Parameters:
199
- pattern: str, regular expression to match against window instances
200
201
Returns:
202
List[Con]: containers with instances matching the pattern
203
"""
204
205
def find_by_role(self, pattern: str) -> List[Con]:
206
"""
207
Find containers by window role pattern using regex.
208
209
Parameters:
210
- pattern: str, regular expression to match against window roles
211
212
Returns:
213
List[Con]: containers with roles matching the pattern
214
"""
215
```
216
217
### Search by State
218
219
```python { .api }
220
def find_marked(self, pattern: str = ".*") -> List[Con]:
221
"""
222
Find containers by mark pattern using regex.
223
224
Parameters:
225
- pattern: str, regular expression to match against marks (default matches all)
226
227
Returns:
228
List[Con]: containers with marks matching the pattern
229
"""
230
231
def find_fullscreen(self) -> List[Con]:
232
"""
233
Find all fullscreen containers.
234
235
Returns:
236
List[Con]: containers currently in fullscreen mode
237
"""
238
```
239
240
### Container Commands
241
242
```python { .api }
243
def command(self, command: str) -> List[CommandReply]:
244
"""
245
Execute i3/sway command on this container.
246
247
Parameters:
248
- command: str, command to execute (container will be implicitly focused)
249
250
Returns:
251
List[CommandReply]: results of command execution
252
"""
253
254
def command_children(self, command: str) -> Optional[List[CommandReply]]:
255
"""
256
Execute i3/sway command on all child containers.
257
258
Parameters:
259
- command: str, command to execute on each child
260
261
Returns:
262
Optional[List[CommandReply]]: results of command execution for each child, or None if no children
263
"""
264
```
265
266
### Model Classes
267
268
```python { .api }
269
class Rect:
270
"""Rectangle representation for container positioning."""
271
x: int # X coordinate
272
y: int # Y coordinate
273
width: int # Rectangle width
274
height: int # Rectangle height
275
276
class Gaps:
277
"""Gap configuration for containers with useless gaps."""
278
inner: int # Inner gap size
279
outer: int # Outer gap size
280
left: Optional[int] # Left outer gap (may be None)
281
right: Optional[int] # Right outer gap (may be None)
282
top: Optional[int] # Top outer gap (may be None)
283
bottom: Optional[int] # Bottom outer gap (may be None)
284
```