0
# Windows API
1

2
Comprehensive Windows API wrapper providing low-level system operations for window management, process control, and system utilities. The Win32API class offers access to essential Windows functions through a Python interface.
3

4
## Capabilities
5

6
### Win32API Class
7

8
Central class providing static methods for Windows API operations.
9

10
```python { .api }
11
class Win32API:
12
    """Comprehensive wrapper for Windows API functions."""
13
    
14
    # Window Management
15
    @staticmethod
16
    def SetForegroundWindow(handle: int) -> bool:
17
        """
18
        Bring window to foreground.
19
        
20
        Args:
21
            handle: Window handle (HWND)
22
            
23
        Returns:
24
            bool: True if successful
25
        """
26
    
27
    @staticmethod
28
    def ShowWindow(handle: int, state: int) -> bool:
29
        """
30
        Set window display state.
31
        
32
        Args:
33
            handle: Window handle (HWND)
34
            state: ShowWindow constant (SW_HIDE, SW_SHOW, etc.)
35
            
36
        Returns:
37
            bool: True if successful
38
        """
39
    
40
    @staticmethod
41
    def MoveWindow(handle: int, x: int, y: int, width: int, height: int, repaint: bool = True) -> bool:
42
        """
43
        Move and resize a window.
44
        
45
        Args:
46
            handle: Window handle (HWND)
47
            x: New X position
48
            y: New Y position
49
            width: New width
50
            height: New height
51
            repaint: Whether to repaint the window
52
            
53
        Returns:
54
            bool: True if successful
55
        """
56
    
57
    @staticmethod
58
    def GetWindowRect(handle: int) -> tuple[int, int, int, int]:
59
        """
60
        Get window rectangle coordinates.
61
        
62
        Args:
63
            handle: Window handle (HWND)
64
            
65
        Returns:
66
            tuple: (left, top, right, bottom) coordinates
67
        """
68
    
69
    @staticmethod
70
    def GetWindowText(handle: int) -> str:
71
        """
72
        Get window title text.
73
        
74
        Args:
75
            handle: Window handle (HWND)
76
            
77
        Returns:
78
            str: Window title text
79
        """
80
    
81
    @staticmethod
82
    def FindWindow(className: str = None, windowName: str = None) -> int:
83
        """
84
        Find window by class name and/or window name.
85
        
86
        Args:
87
            className: Window class name (optional)
88
            windowName: Window title (optional)
89
            
90
        Returns:
91
            int: Window handle (HWND) or 0 if not found
92
        """
93
    
94
    @staticmethod
95
    def EnumWindows() -> list[int]:
96
        """
97
        Enumerate all top-level windows.
98
        
99
        Returns:
100
            list: List of window handles (HWNDs)
101
        """
102
```
103

104
### Mouse Operations
105

106
```python { .api }
107
class Win32API:
108
    @staticmethod
109
    def MouseClick(x: int, y: int, button: int = 1) -> None:
110
        """
111
        Click mouse at coordinates.
112
        
113
        Args:
114
            x: Screen X coordinate
115
            y: Screen Y coordinate
116
            button: Mouse button (1=left, 2=right, 3=middle)
117
        """
118
    
119
    @staticmethod
120
    def MouseRightClick(x: int, y: int) -> None:
121
        """Right-click at coordinates."""
122
    
123
    @staticmethod
124
    def MouseDoubleClick(x: int, y: int) -> None:
125
        """Double-click at coordinates."""
126
    
127
    @staticmethod
128
    def MouseMoveTo(x: int, y: int) -> None:
129
        """Move mouse to coordinates."""
130
    
131
    @staticmethod
132
    def MouseDragDrop(x1: int, y1: int, x2: int, y2: int) -> None:
133
        """Drag from (x1,y1) to (x2,y2)."""
134
    
135
    @staticmethod
136
    def GetCursorPos() -> tuple[int, int]:
137
        """
138
        Get current cursor position.
139
        
140
        Returns:
141
            tuple: (x, y) cursor coordinates
142
        """
143
    
144
    @staticmethod
145
    def SetCursorPos(x: int, y: int) -> bool:
146
        """
147
        Set cursor position.
148
        
149
        Args:
150
            x: Screen X coordinate
151
            y: Screen Y coordinate
152
            
153
        Returns:
154
            bool: True if successful
155
        """
156
```
157

158
### Keyboard Operations
159

160
```python { .api }
161
class Win32API:
162
    @staticmethod
163
    def SendKey(key: int, modifiers: int = 0) -> None:
164
        """
165
        Send key with modifiers.
166
        
167
        Args:
168
            key: Virtual key code
169
            modifiers: Modifier key flags
170
        """
171
    
172
    @staticmethod
173
    def SendKeys(keys: str) -> None:
174
        """
175
        Send sequence of keys.
176
        
177
        Args:
178
            keys: Key sequence string
179
        """
180
    
181
    @staticmethod
182
    def KeyDown(key: int) -> None:
183
        """Press key down."""
184
    
185
    @staticmethod
186
    def KeyUp(key: int) -> None:
187
        """Release key."""
188
    
189
    @staticmethod
190
    def GetKeyState(key: int) -> int:
191
        """
192
        Get key state.
193
        
194
        Args:
195
            key: Virtual key code
196
            
197
        Returns:
198
            int: Key state flags
199
        """
200
    
201
    @staticmethod
202
    def GetAsyncKeyState(key: int) -> int:
203
        """
204
        Get asynchronous key state.
205
        
206
        Args:
207
            key: Virtual key code
208
            
209
        Returns:
210
            int: Key state flags
211
        """
212
```
213

214
### System Information
215

216
```python { .api }
217
class Win32API:
218
    @staticmethod
219
    def GetScreenSize() -> tuple[int, int]:
220
        """
221
        Get screen dimensions.
222
        
223
        Returns:
224
            tuple: (width, height) in pixels
225
        """
226
    
227
    @staticmethod
228
    def GetPixelColor(x: int, y: int) -> int:
229
        """
230
        Get pixel color from screen.
231
        
232
        Args:
233
            x: Screen X coordinate
234
            y: Screen Y coordinate
235
            
236
        Returns:
237
            int: Color value
238
        """
239
    
240
    @staticmethod
241
    def GetSystemMetrics(index: int) -> int:
242
        """
243
        Get system metrics.
244
        
245
        Args:
246
            index: System metrics index
247
            
248
        Returns:
249
            int: Metric value
250
        """
251
    
252
    @staticmethod
253
    def GetComputerName() -> str:
254
        """
255
        Get computer name.
256
        
257
        Returns:
258
            str: Computer name
259
        """
260
    
261
    @staticmethod
262
    def GetUserName() -> str:
263
        """
264
        Get current user name.
265
        
266
        Returns:
267
            str: User name
268
        """
269
```
270

271
### Process Management
272

273
```python { .api }
274
class Win32API:
275
    @staticmethod
276
    def GetCurrentProcessId() -> int:
277
        """
278
        Get current process ID.
279
        
280
        Returns:
281
            int: Process ID
282
        """
283
    
284
    @staticmethod
285
    def GetWindowThreadProcessId(handle: int) -> tuple[int, int]:
286
        """
287
        Get thread and process ID for window.
288
        
289
        Args:
290
            handle: Window handle (HWND)
291
            
292
        Returns:
293
            tuple: (thread_id, process_id)
294
        """
295
    
296
    @staticmethod
297
    def TerminateProcess(processId: int) -> bool:
298
        """
299
        Terminate process by ID.
300
        
301
        Args:
302
            processId: Process ID to terminate
303
            
304
        Returns:
305
            bool: True if successful
306
        """
307
    
308
    @staticmethod
309
    def CreateProcess(commandLine: str) -> int:
310
        """
311
        Create new process.
312
        
313
        Args:
314
            commandLine: Command line to execute
315
            
316
        Returns:
317
            int: Process ID or 0 if failed
318
        """
319
```
320

321
### Message Box and Dialogs
322

323
```python { .api }
324
class Win32API:
325
    @staticmethod
326
    def MessageBox(text: str, title: str = "", type: int = 0) -> int:
327
        """
328
        Display message box.
329
        
330
        Args:
331
            text: Message text
332
            title: Dialog title
333
            type: Message box type (MB_OK, MB_YESNO, etc.)
334
            
335
        Returns:
336
            int: User response (IDOK, IDYES, etc.)
337
        """
338
    
339
    @staticmethod
340
    def InputBox(prompt: str, title: str = "", default: str = "") -> str:
341
        """
342
        Display input dialog.
343
        
344
        Args:
345
            prompt: Input prompt
346
            title: Dialog title
347
            default: Default input value
348
            
349
        Returns:
350
            str: User input or empty string if cancelled
351
        """
352
```
353

354
### File and Directory Operations
355

356
```python { .api }
357
class Win32API:
358
    @staticmethod
359
    def GetCurrentDirectory() -> str:
360
        """
361
        Get current working directory.
362
        
363
        Returns:
364
            str: Current directory path
365
        """
366
    
367
    @staticmethod
368
    def SetCurrentDirectory(path: str) -> bool:
369
        """
370
        Set current working directory.
371
        
372
        Args:
373
            path: Directory path
374
            
375
        Returns:
376
            bool: True if successful
377
        """
378
    
379
    @staticmethod
380
    def GetTempPath() -> str:
381
        """
382
        Get temporary files directory.
383
        
384
        Returns:
385
            str: Temp directory path
386
        """
387
    
388
    @staticmethod
389
    def GetSpecialFolderPath(folder: int) -> str:
390
        """
391
        Get special folder path.
392
        
393
        Args:
394
            folder: Special folder constant
395
            
396
        Returns:
397
            str: Folder path
398
        """
399
```
400

401
## Constants
402

403
### Window Show States
404

405
```python { .api }
406
class ShowWindow:
407
    """Constants for ShowWindow function."""
408
    SW_HIDE: int = 0
409
    SW_SHOWNORMAL: int = 1
410
    SW_SHOWMINIMIZED: int = 2
411
    SW_SHOWMAXIMIZED: int = 3
412
    SW_SHOWNOACTIVATE: int = 4
413
    SW_SHOW: int = 5
414
    SW_MINIMIZE: int = 6
415
    SW_SHOWMINNOACTIVE: int = 7
416
    SW_SHOWNA: int = 8
417
    SW_RESTORE: int = 9
418
    SW_SHOWDEFAULT: int = 10
419
```
420

421
### Message Box Types
422

423
```python { .api }
424
class MB:
425
    """Message box type constants."""
426
    MB_OK: int = 0
427
    MB_OKCANCEL: int = 1
428
    MB_ABORTRETRYIGNORE: int = 2
429
    MB_YESNOCANCEL: int = 3
430
    MB_YESNO: int = 4
431
    MB_RETRYCANCEL: int = 5
432
    MB_ICONHAND: int = 16
433
    MB_ICONQUESTION: int = 32
434
    MB_ICONEXCLAMATION: int = 48
435
    MB_ICONASTERISK: int = 64
436
```
437

438
### Message Box Return Values
439

440
```python { .api }
441
class MessageBoxResult:
442
    """Message box return value constants."""
443
    IDOK: int = 1
444
    IDCANCEL: int = 2
445
    IDABORT: int = 3
446
    IDRETRY: int = 4
447
    IDIGNORE: int = 5
448
    IDYES: int = 6
449
    IDNO: int = 7
450
```
451

452
### Key Dictionaries
453

454
```python { .api }
455
class Win32API:
456
    # Special key name to virtual key code mapping
457
    SpecialKeyDict: dict = {
458
        '{ENTER}': 13,
459
        '{TAB}': 9,
460
        '{ESC}': 27,
461
        '{SPACE}': 32,
462
        '{BACKSPACE}': 8,
463
        '{DELETE}': 46,
464
        '{HOME}': 36,
465
        '{END}': 35,
466
        '{LEFT}': 37,
467
        '{UP}': 38,
468
        '{RIGHT}': 39,
469
        '{DOWN}': 40,
470
        '{PAGEUP}': 33,
471
        '{PAGEDOWN}': 34,
472
        '{F1}': 112,
473
        # ... additional special keys
474
    }
475
    
476
    # Character to virtual key code mapping
477
    CharacterDict: dict = {
478
        'a': 65, 'A': 65,
479
        'b': 66, 'B': 66,
480
        # ... additional character mappings
481
    }
482
```
483

484
## Usage Examples
485

486
### Window Management
487

488
```python
489
import uiautomation
490

491
# Find window by title
492
handle = uiautomation.Win32API.FindWindow(None, "Calculator")
493
if handle:
494
    # Bring to foreground
495
    uiautomation.Win32API.SetForegroundWindow(handle)
496
    
497
    # Get window position and size
498
    left, top, right, bottom = uiautomation.Win32API.GetWindowRect(handle)
499
    print(f"Window bounds: ({left}, {top}, {right}, {bottom})")
500
    
501
    # Move and resize window
502
    uiautomation.Win32API.MoveWindow(handle, 100, 100, 800, 600)
503
    
504
    # Maximize window
505
    uiautomation.Win32API.ShowWindow(handle, uiautomation.ShowWindow.SW_SHOWMAXIMIZED)
506
```
507

508
### System Information
509

510
```python
511
# Get screen dimensions
512
width, height = uiautomation.Win32API.GetScreenSize()
513
print(f"Screen size: {width} x {height}")
514

515
# Get computer and user info
516
computer = uiautomation.Win32API.GetComputerName()
517
user = uiautomation.Win32API.GetUserName()
518
print(f"Computer: {computer}, User: {user}")
519

520
# Get cursor position
521
x, y = uiautomation.Win32API.GetCursorPos()
522
print(f"Cursor at: ({x}, {y})")
523
```
524

525
### Message Boxes and User Interaction
526

527
```python
528
# Simple message box
529
result = uiautomation.Win32API.MessageBox("Hello World!", "Greeting")
530

531
# Yes/No question
532
result = uiautomation.Win32API.MessageBox(
533
    "Do you want to continue?", 
534
    "Confirmation", 
535
    uiautomation.MB.MB_YESNO | uiautomation.MB.MB_ICONQUESTION
536
)
537

538
if result == uiautomation.MessageBoxResult.IDYES:
539
    print("User clicked Yes")
540
elif result == uiautomation.MessageBoxResult.IDNO:
541
    print("User clicked No")
542

543
# Input dialog
544
user_input = uiautomation.Win32API.InputBox("Enter your name:", "Input Required", "Default Name")
545
if user_input:
546
    print(f"User entered: {user_input}")
547
```
548

549
### Process Management
550

551
```python
552
# Get current process ID
553
current_pid = uiautomation.Win32API.GetCurrentProcessId()
554
print(f"Current process ID: {current_pid}")
555

556
# Get process ID for a window
557
handle = uiautomation.Win32API.FindWindow(None, "Notepad")
558
if handle:
559
    thread_id, process_id = uiautomation.Win32API.GetWindowThreadProcessId(handle)
560
    print(f"Notepad process ID: {process_id}")
561

562
# Launch new process
563
new_pid = uiautomation.Win32API.CreateProcess("notepad.exe")
564
if new_pid:
565
    print(f"Launched process with ID: {new_pid}")
566
```
567

568
### Advanced Input Operations
569

570
```python
571
# Check if key is currently pressed
572
if uiautomation.Win32API.GetAsyncKeyState(uiautomation.Keys.VK_SHIFT) & 0x8000:
573
    print("Shift key is currently pressed")
574

575
# Send complex key combinations
576
uiautomation.Win32API.KeyDown(uiautomation.Keys.VK_CONTROL)
577
uiautomation.Win32API.SendKey(uiautomation.Keys.VK_C)  # Ctrl+C
578
uiautomation.Win32API.KeyUp(uiautomation.Keys.VK_CONTROL)
579
```
580

581
### File System Operations
582

583
```python
584
# Get and set working directory
585
current_dir = uiautomation.Win32API.GetCurrentDirectory()
586
print(f"Current directory: {current_dir}")
587

588
# Change directory
589
success = uiautomation.Win32API.SetCurrentDirectory("C:\\Users")
590
if success:
591
    print("Directory changed successfully")
592

593
# Get special folder paths
594
temp_path = uiautomation.Win32API.GetTempPath()
595
print(f"Temp directory: {temp_path}")
596
```
597

598
### Window Enumeration
599

600
```python
601
def list_all_windows():
602
    """List all top-level windows."""
603
    window_handles = uiautomation.Win32API.EnumWindows()
604
    for handle in window_handles:
605
        title = uiautomation.Win32API.GetWindowText(handle)
606
        if title:  # Only show windows with titles
607
            left, top, right, bottom = uiautomation.Win32API.GetWindowRect(handle)
608
            print(f"Window: '{title}' at ({left}, {top}) size ({right-left}x{bottom-top})")
609

610
# List all windows
611
list_all_windows()
612
```
613

614
### Utility Functions
615

616
```python
617
def wait_for_window(window_title, timeout=30):
618
    """Wait for a window to appear."""
619
    import time
620
    start_time = time.time()
621
    
622
    while time.time() - start_time < timeout:
623
        handle = uiautomation.Win32API.FindWindow(None, window_title)
624
        if handle:
625
            return handle
626
        time.sleep(0.5)
627
    
628
    return None
629

630
def ensure_window_visible(window_title):
631
    """Ensure window is visible and in foreground."""
632
    handle = uiautomation.Win32API.FindWindow(None, window_title)
633
    if handle:
634
        # Restore if minimized
635
        uiautomation.Win32API.ShowWindow(handle, uiautomation.ShowWindow.SW_RESTORE)
636
        # Bring to foreground
637
        uiautomation.Win32API.SetForegroundWindow(handle)
638
        return True
639
    return False
640
```