0
# Input Simulation
1
2
Mouse and keyboard input simulation for automating user interactions with Windows applications. These functions provide low-level input capabilities that work across all Windows applications, supporting clicking, typing, dragging, and special key combinations.
3
4
## Capabilities
5
6
### Mouse Operations
7
8
Global mouse functions that operate at the screen coordinate level.
9
10
```python { .api }
11
def Click(x: int, y: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
12
"""
13
Click the left mouse button at the specified screen coordinates.
14
15
Args:
16
x: X coordinate in screen pixels
17
y: Y coordinate in screen pixels
18
waitTime: Wait time after operation in seconds
19
"""
20
21
def RightClick(x: int, y: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
22
"""
23
Click the right mouse button at the specified screen coordinates.
24
25
Args:
26
x: X coordinate in screen pixels
27
y: Y coordinate in screen pixels
28
waitTime: Wait time after operation in seconds
29
"""
30
31
def MiddleClick(x: int, y: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
32
"""
33
Click the middle mouse button at the specified screen coordinates.
34
35
Args:
36
x: X coordinate in screen pixels
37
y: Y coordinate in screen pixels
38
waitTime: Wait time after operation in seconds
39
"""
40
41
def MoveTo(x: int, y: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
42
"""
43
Move the mouse cursor to the specified screen coordinates.
44
45
Args:
46
x: X coordinate in screen pixels
47
y: Y coordinate in screen pixels
48
waitTime: Wait time after operation in seconds
49
"""
50
51
def DragDrop(x1: int, y1: int, x2: int, y2: int, moveSpeed: int = 1, waitTime: float = OPERATION_WAIT_TIME) -> None:
52
"""
53
Perform a drag and drop operation from one point to another.
54
55
Args:
56
x1: Starting X coordinate in screen pixels
57
y1: Starting Y coordinate in screen pixels
58
x2: Ending X coordinate in screen pixels
59
y2: Ending Y coordinate in screen pixels
60
moveSpeed: Speed of drag movement (1=slow, higher=faster)
61
waitTime: Wait time after operation in seconds
62
"""
63
```
64
65
### Keyboard Operations
66
67
Global keyboard functions for sending keys and key combinations.
68
69
```python { .api }
70
def KeyDown(key: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
71
"""
72
Press a key down (without releasing).
73
74
Args:
75
key: Virtual key code (use Keys constants)
76
waitTime: Wait time after operation in seconds
77
"""
78
79
def KeyUp(key: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
80
"""
81
Release a previously pressed key.
82
83
Args:
84
key: Virtual key code (use Keys constants)
85
waitTime: Wait time after operation in seconds
86
"""
87
88
def SendKey(key: int, waitTime: float = OPERATION_WAIT_TIME) -> None:
89
"""
90
Send a single key (press and release).
91
92
Args:
93
key: Virtual key code (use Keys constants)
94
waitTime: Wait time after operation in seconds
95
"""
96
97
def SendKeys(keys: str, interval: float = 0.01, waitTime: float = OPERATION_WAIT_TIME, debug: bool = False) -> None:
98
"""
99
Send a sequence of keys from a string.
100
101
Args:
102
keys: String representing keys to send (supports special key notation)
103
interval: Time between individual key presses in seconds
104
waitTime: Wait time after operation in seconds
105
debug: Enable debug output for key sending
106
"""
107
```
108
109
### Mouse Wheel Operations
110
111
Functions for simulating mouse wheel scrolling.
112
113
```python { .api }
114
def WheelDown(wheelTimes: int = 1, waitTime: float = OPERATION_WAIT_TIME) -> None:
115
"""
116
Scroll the mouse wheel down.
117
118
Args:
119
wheelTimes: Number of wheel notches to scroll
120
waitTime: Wait time after operation in seconds
121
"""
122
123
def WheelUp(wheelTimes: int = 1, waitTime: float = OPERATION_WAIT_TIME) -> None:
124
"""
125
Scroll the mouse wheel up.
126
127
Args:
128
wheelTimes: Number of wheel notches to scroll
129
waitTime: Wait time after operation in seconds
130
"""
131
```
132
133
## Key Constants
134
135
### Virtual Key Codes
136
137
```python { .api }
138
class Keys:
139
"""Virtual key code constants for keyboard input."""
140
141
# Letter keys
142
VK_A: int = 65
143
VK_B: int = 66
144
# ... (VK_C through VK_Z)
145
VK_Z: int = 90
146
147
# Number keys
148
VK_0: int = 48
149
VK_1: int = 49
150
# ... (VK_2 through VK_9)
151
VK_9: int = 57
152
153
# Function keys
154
VK_F1: int = 112
155
VK_F2: int = 113
156
# ... (VK_F3 through VK_F12)
157
VK_F12: int = 123
158
159
# Navigation keys
160
VK_LEFT: int = 37
161
VK_UP: int = 38
162
VK_RIGHT: int = 39
163
VK_DOWN: int = 40
164
VK_HOME: int = 36
165
VK_END: int = 35
166
VK_PAGEUP: int = 33
167
VK_PAGEDOWN: int = 34
168
169
# Editing keys
170
VK_INSERT: int = 45
171
VK_DELETE: int = 46
172
VK_BACKSPACE: int = 8
173
VK_RETURN: int = 13
174
VK_ENTER: int = 13
175
VK_TAB: int = 9
176
VK_SPACE: int = 32
177
VK_ESCAPE: int = 27
178
179
# Modifier keys
180
VK_SHIFT: int = 16
181
VK_CONTROL: int = 17
182
VK_ALT: int = 18
183
VK_LWIN: int = 91
184
VK_RWIN: int = 92
185
186
# Lock keys
187
VK_CAPITAL: int = 20 # Caps Lock
188
VK_NUMLOCK: int = 144
189
VK_SCROLL: int = 145
190
191
# Numpad keys
192
VK_NUMPAD0: int = 96
193
VK_NUMPAD1: int = 97
194
# ... (VK_NUMPAD2 through VK_NUMPAD9)
195
VK_NUMPAD9: int = 105
196
VK_MULTIPLY: int = 106 # *
197
VK_ADD: int = 107 # +
198
VK_SEPARATOR: int = 108
199
VK_SUBTRACT: int = 109 # -
200
VK_DECIMAL: int = 110 # .
201
VK_DIVIDE: int = 111 # /
202
```
203
204
### Modifier Key Constants
205
206
```python { .api }
207
class ModifierKey:
208
"""Modifier key constants for use with SendKey function."""
209
ALT: int = 1 # Alt key modifier
210
CONTROL: int = 2 # Ctrl key modifier
211
SHIFT: int = 4 # Shift key modifier
212
WIN: int = 8 # Windows key modifier
213
```
214
215
## Clipboard Operations
216
217
Functions for interacting with the Windows clipboard.
218
219
```python { .api }
220
def GetClipboardText() -> str:
221
"""
222
Get text content from the Windows clipboard.
223
224
Returns:
225
str: Text content from clipboard, or empty string if no text
226
"""
227
228
def SetClipboardText(text: str) -> None:
229
"""
230
Set text content to the Windows clipboard.
231
232
Args:
233
text: Text to place on clipboard
234
"""
235
```
236
237
## Usage Examples
238
239
### Basic Mouse Operations
240
241
```python
242
import uiautomation
243
244
# Click at specific screen coordinates
245
uiautomation.Click(100, 200)
246
247
# Right-click to open context menu
248
uiautomation.RightClick(300, 400)
249
250
# Drag and drop operation
251
uiautomation.DragDrop(100, 100, 200, 200)
252
253
# Move cursor without clicking
254
uiautomation.MoveTo(150, 250)
255
```
256
257
### Keyboard Input
258
259
```python
260
# Send individual keys
261
uiautomation.SendKey(uiautomation.Keys.VK_RETURN)
262
uiautomation.SendKey(uiautomation.Keys.VK_TAB)
263
264
# Send key combinations
265
uiautomation.SendKey(
266
uiautomation.Keys.VK_S,
267
uiautomation.ModifierKey.CONTROL # Ctrl+S
268
)
269
270
uiautomation.SendKey(
271
uiautomation.Keys.VK_C,
272
uiautomation.ModifierKey.CONTROL | uiautomation.ModifierKey.SHIFT # Ctrl+Shift+C
273
)
274
275
# Send text sequences
276
uiautomation.SendKeys("Hello World!")
277
uiautomation.SendKeys("user@example.com{TAB}password123{ENTER}")
278
```
279
280
### Special Key Sequences
281
282
```python
283
# Navigation sequences
284
uiautomation.SendKeys("{HOME}") # Go to beginning of line
285
uiautomation.SendKeys("{END}") # Go to end of line
286
uiautomation.SendKeys("{CTRL+A}") # Select all
287
uiautomation.SendKeys("{CTRL+C}") # Copy
288
uiautomation.SendKeys("{CTRL+V}") # Paste
289
290
# Function keys
291
uiautomation.SendKeys("{F5}") # Refresh
292
uiautomation.SendKeys("{ALT+F4}") # Close window
293
294
# Arrow key navigation
295
uiautomation.SendKeys("{DOWN 3}") # Press down arrow 3 times
296
uiautomation.SendKeys("{RIGHT 5}") # Press right arrow 5 times
297
```
298
299
### Mouse Wheel Scrolling
300
301
```python
302
# Scroll down in a document or list
303
uiautomation.WheelDown(3) # Scroll down 3 notches
304
305
# Scroll up
306
uiautomation.WheelUp(5) # Scroll up 5 notches
307
308
# Scroll at specific location (move cursor first)
309
uiautomation.MoveTo(400, 300)
310
uiautomation.WheelDown(2)
311
```
312
313
### Clipboard Operations
314
315
```python
316
# Copy text to clipboard
317
uiautomation.SetClipboardText("Text to copy")
318
319
# Get text from clipboard
320
clipboard_content = uiautomation.GetClipboardText()
321
print(f"Clipboard contains: {clipboard_content}")
322
323
# Copy-paste workflow
324
uiautomation.SendKeys("{CTRL+A}") # Select all
325
uiautomation.SendKeys("{CTRL+C}") # Copy
326
original_text = uiautomation.GetClipboardText()
327
328
# Modify and paste back
329
modified_text = original_text.upper()
330
uiautomation.SetClipboardText(modified_text)
331
uiautomation.SendKeys("{CTRL+V}") # Paste
332
```
333
334
### Advanced Input Combinations
335
336
```python
337
# Hold key down for multiple operations
338
uiautomation.KeyDown(uiautomation.Keys.VK_SHIFT)
339
uiautomation.SendKey(uiautomation.Keys.VK_RIGHT) # Shift+Right (select)
340
uiautomation.SendKey(uiautomation.Keys.VK_RIGHT) # Shift+Right (select more)
341
uiautomation.KeyUp(uiautomation.Keys.VK_SHIFT)
342
343
# Complex application automation
344
def automate_text_editor():
345
# Open file dialog
346
uiautomation.SendKey(uiautomation.Keys.VK_O, uiautomation.ModifierKey.CONTROL)
347
348
# Type filename and open
349
uiautomation.SendKeys("document.txt{ENTER}")
350
351
# Select all and replace content
352
uiautomation.SendKeys("{CTRL+A}")
353
uiautomation.SendKeys("New content for the document")
354
355
# Save file
356
uiautomation.SendKey(uiautomation.Keys.VK_S, uiautomation.ModifierKey.CONTROL)
357
```
358
359
### Error Handling for Input Operations
360
361
```python
362
import time
363
364
def safe_click(x, y, retries=3):
365
"""Safely click with retries."""
366
for attempt in range(retries):
367
try:
368
uiautomation.Click(x, y)
369
return True
370
except Exception as e:
371
print(f"Click attempt {attempt + 1} failed: {e}")
372
if attempt < retries - 1:
373
time.sleep(0.5) # Brief pause before retry
374
return False
375
376
def safe_send_keys(keys, retries=3):
377
"""Safely send keys with retries."""
378
for attempt in range(retries):
379
try:
380
uiautomation.SendKeys(keys)
381
return True
382
except Exception as e:
383
print(f"SendKeys attempt {attempt + 1} failed: {e}")
384
if attempt < retries - 1:
385
time.sleep(0.5)
386
return False
387
```