0
# Control Management
1
2
Core functionality for finding, accessing, and managing UI controls within the Windows control tree. These functions provide the foundation for all automation operations by enabling discovery and traversal of the UI hierarchy.
3
4
## Capabilities
5
6
### Root and System Controls
7
8
Functions to access top-level system controls and entry points into the UI hierarchy.
9
10
```python { .api }
11
def GetRootControl() -> Control:
12
"""
13
Get the desktop root control (top of the control tree).
14
15
Returns:
16
Control: Desktop control representing the root of all UI elements
17
"""
18
19
def GetFocusedControl() -> Control:
20
"""
21
Get the currently focused control.
22
23
Returns:
24
Control: The control that currently has keyboard focus, or None if none
25
"""
26
27
def GetForegroundControl() -> Control:
28
"""
29
Get the foreground window control.
30
31
Returns:
32
Control: The control representing the currently active window
33
"""
34
35
def GetConsoleWindow() -> Control:
36
"""
37
Get the console window control.
38
39
Returns:
40
Control: The control representing the console window
41
"""
42
```
43
44
### Point-Based Control Discovery
45
46
Find controls based on screen coordinates, useful for mouse-driven automation scenarios.
47
48
```python { .api }
49
def ControlFromPoint(x: int, y: int) -> Control:
50
"""
51
Get the control at the specified screen coordinates.
52
53
Args:
54
x: X coordinate in screen pixels
55
y: Y coordinate in screen pixels
56
57
Returns:
58
Control: The control at the specified point, or None if none found
59
"""
60
61
def ControlFromPoint2(x: int, y: int) -> Control:
62
"""
63
Alternative method to get control at screen coordinates.
64
65
Args:
66
x: X coordinate in screen pixels
67
y: Y coordinate in screen pixels
68
69
Returns:
70
Control: The control at the specified point, or None if none found
71
"""
72
73
def ControlFromCursor() -> Control:
74
"""
75
Get the control under the current mouse cursor position.
76
77
Returns:
78
Control: The control under the cursor, or None if none found
79
"""
80
81
def ControlFromCursor2() -> Control:
82
"""
83
Alternative method to get control under cursor.
84
85
Returns:
86
Control: The control under the cursor, or None if none found
87
"""
88
```
89
90
### Handle-Based Control Access
91
92
Access controls using Windows handles for interoperability with other Windows APIs.
93
94
```python { .api }
95
def ControlFromHandle(handle: int) -> Control:
96
"""
97
Get a control from its window handle.
98
99
Args:
100
handle: Windows handle (HWND) of the control
101
102
Returns:
103
Control: Control wrapper for the window handle, or None if invalid
104
"""
105
```
106
107
### Control Search and Discovery
108
109
Advanced search functions for finding controls based on property criteria.
110
111
```python { .api }
112
def FindControl(control: Control, compareFunc: callable, maxDepth: int = 0xFFFFFFFF,
113
findFromSelf: bool = False, foundIndex: int = 1) -> Control:
114
"""
115
Find a control using a comparison function.
116
117
Args:
118
control: Root control to start search from
119
compareFunc: Function that takes (control, depth) and returns True/False
120
maxDepth: Maximum depth to search (default: unlimited)
121
findFromSelf: Whether to include the root control in search
122
foundIndex: Which match to return (1-based index)
123
124
Returns:
125
Control: Matching control found, or None if no match
126
"""
127
128
def ControlsAreSame(control1: Control, control2: Control) -> bool:
129
"""
130
Check if two control references point to the same UI element.
131
132
Args:
133
control1: First control to compare
134
control2: Second control to compare
135
136
Returns:
137
bool: True if controls represent the same UI element
138
"""
139
```
140
141
### Control Tree Traversal
142
143
Functions for walking and analyzing the UI control hierarchy.
144
145
```python { .api }
146
def WalkControl(control: Control, includeTop: bool = False, maxDepth: int = 0xFFFFFFFF) -> None:
147
"""
148
Walk the control tree starting from the given control.
149
150
Args:
151
control: Root control to start walking from
152
includeTop: Whether to include the root control in iteration
153
maxDepth: Maximum depth to traverse (default: unlimited)
154
"""
155
156
def WalkTree(root: Control, depth: int, callback: callable) -> None:
157
"""
158
Walk the control tree to a specified depth.
159
160
Args:
161
root: Root control to start from
162
depth: Maximum depth to traverse
163
callback: Function called for each control visited
164
"""
165
```
166
167
### Timing and Synchronization
168
169
Functions for waiting and timing control operations.
170
171
```python { .api }
172
def WaitForExist(control: Control, timeout: float) -> bool:
173
"""
174
Wait for a control to exist/appear.
175
176
Args:
177
control: Control to wait for
178
timeout: Maximum time to wait in seconds
179
180
Returns:
181
bool: True if control exists, False if timeout
182
"""
183
184
def WaitForDisappear(control: Control, timeout: float) -> bool:
185
"""
186
Wait for a control to disappear/become unavailable.
187
188
Args:
189
control: Control to wait for disappearance
190
timeout: Maximum time to wait in seconds
191
192
Returns:
193
bool: True if control disappeared, False if timeout
194
"""
195
196
def SetGlobalSearchTimeOut(seconds: float) -> None:
197
"""
198
Set the global timeout for control search operations.
199
200
Args:
201
seconds: Timeout value in seconds
202
"""
203
```
204
205
## Usage Examples
206
207
### Basic Control Discovery
208
209
```python
210
import uiautomation
211
212
# Get the desktop root and enumerate top-level windows
213
root = uiautomation.GetRootControl()
214
for window in root.GetChildren():
215
print(f"Window: {window.Name}")
216
217
# Find a specific application window
218
calculator = uiautomation.FindControl(root, Name='Calculator', ControlType=uiautomation.ControlType.WindowControl)
219
220
# Get the currently active window
221
active_window = uiautomation.GetForegroundControl()
222
print(f"Active window: {active_window.Name}")
223
```
224
225
### Point-Based Control Access
226
227
```python
228
# Get control at specific screen coordinates
229
control_at_point = uiautomation.ControlFromPoint(100, 200)
230
if control_at_point:
231
print(f"Control at (100,200): {control_at_point.Name}")
232
233
# Get control under current cursor position
234
cursor_control = uiautomation.ControlFromCursor()
235
if cursor_control:
236
print(f"Control under cursor: {cursor_control.Name}")
237
```
238
239
### Waiting for Controls
240
241
```python
242
# Wait for a button to appear
243
ok_button = uiautomation.ButtonControl(Name='OK')
244
if uiautomation.WaitForExist(ok_button, 10):
245
ok_button.Click()
246
else:
247
print("OK button did not appear within 10 seconds")
248
249
# Wait for a dialog to disappear
250
dialog = uiautomation.WindowControl(Name='Progress Dialog')
251
if dialog.Exists():
252
disappeared = uiautomation.WaitForDisappear(dialog, timeout=30)
253
if disappeared:
254
print("Dialog closed successfully")
255
```
256
257
### Performance Optimization
258
259
```python
260
# Use hierarchical search for better performance
261
# Instead of searching the entire tree:
262
# button = uiautomation.ButtonControl(searchDepth=10, Name='Submit')
263
264
# Use parent-child relationships:
265
app_window = uiautomation.WindowControl(searchDepth=1, Name='MyApp')
266
dialog = app_window.WindowControl(searchDepth=1, Name='Settings')
267
submit_button = dialog.ButtonControl(searchDepth=2, Name='Submit')
268
```