0
# Workspace Operations
1
2
Complete workspace querying and management functionality for i3/sway workspaces. Provides detailed workspace information including visibility, focus state, dimensions, and output assignments.
3
4
## Capabilities
5
6
### Workspace Querying
7
8
```python { .api }
9
def get_workspaces(self) -> List[WorkspaceReply]:
10
"""
11
Get information about all workspaces.
12
13
Returns:
14
List[WorkspaceReply]: comprehensive workspace details for all workspaces
15
"""
16
```
17
18
### Workspace Reply Structure
19
20
```python { .api }
21
class WorkspaceReply:
22
"""Complete workspace information from GET_WORKSPACES response."""
23
24
# Identification
25
num: int # Logical workspace number (-1 for named workspaces)
26
name: str # Workspace name (default: num+1, or custom name)
27
28
# State properties
29
visible: bool # Whether workspace is currently visible on any output
30
focused: bool # Whether workspace currently has keyboard focus
31
urgent: bool # Whether workspace contains urgent windows
32
33
# Layout and positioning
34
rect: Rect # Workspace rectangle (dimensions and position)
35
output: str # Name of output (monitor) displaying this workspace
36
37
# Raw data access
38
ipc_data: dict # Complete raw IPC response data
39
```
40
41
### Workspace Container Navigation
42
43
```python { .api }
44
# From Con class - workspace-specific methods
45
def workspaces(self) -> List[Con]:
46
"""
47
Get all workspace containers from the tree.
48
49
Returns:
50
List[Con]: all containers of type 'workspace'
51
"""
52
53
def workspace(self) -> Optional[Con]:
54
"""
55
Get the workspace container that contains this container.
56
57
Returns:
58
Optional[Con]: parent workspace container or None if at root level
59
"""
60
```
61
62
### Workspace Container Properties
63
64
```python { .api }
65
# Workspace-specific properties available on Con objects of type 'workspace'
66
class Con:
67
# When type == 'workspace':
68
num: int # Workspace number (matches WorkspaceReply.num)
69
name: str # Workspace name (matches WorkspaceReply.name)
70
urgent: bool # Urgent state
71
focused: bool # Focus state
72
rect: Rect # Workspace dimensions and position
73
74
# Layout properties
75
layout: str # Workspace layout (splith, splitv, stacked, tabbed)
76
orientation: str # Primary split orientation
77
78
# Child containers
79
nodes: List[Con] # Tiled child containers
80
floating_nodes: List[Con] # Floating child containers
81
```
82
83
### Rectangle Geometry
84
85
```python { .api }
86
class Rect:
87
"""Rectangle dimensions and positioning for workspaces."""
88
x: int # X coordinate of workspace area
89
y: int # Y coordinate of workspace area
90
width: int # Workspace width in pixels
91
height: int # Workspace height in pixels
92
```
93
94
### Workspace Examples
95
96
```python
97
# Get all workspaces and display their status
98
workspaces = i3.get_workspaces()
99
for ws in workspaces:
100
status = []
101
if ws.focused:
102
status.append("focused")
103
if ws.visible:
104
status.append("visible")
105
if ws.urgent:
106
status.append("urgent")
107
108
status_str = f" ({', '.join(status)})" if status else ""
109
print(f"Workspace {ws.name} on {ws.output}{status_str}")
110
print(f" Dimensions: {ws.rect.width}x{ws.rect.height} at ({ws.rect.x}, {ws.rect.y})")
111
112
# Find the currently focused workspace
113
focused_ws = next((ws for ws in workspaces if ws.focused), None)
114
if focused_ws:
115
print(f"Currently focused: {focused_ws.name}")
116
117
# Get workspace containers from tree
118
tree = i3.get_tree()
119
workspace_cons = tree.workspaces()
120
for ws_con in workspace_cons:
121
print(f"Workspace {ws_con.name} has {len(ws_con.nodes)} tiled windows")
122
print(f" and {len(ws_con.floating_nodes)} floating windows")
123
124
# Find workspace containing a specific container
125
some_container = tree.find_focused()
126
if some_container:
127
workspace = some_container.workspace()
128
if workspace:
129
print(f"Focused container is on workspace: {workspace.name}")
130
```