### Getting Started with UI Automation

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/MANIFEST.md

A basic example demonstrating how to start with UI automation by finding a window and a control within it.

```python
import py_uiautomation as pua

# Find a window by its title
window = pua.WindowControl(Name='Untitled - Notepad')

# Check if the window exists and is active
if window.Exists(timeout=5, searchDepth=1):
    print('Notepad window found.')
    # Find a control within the window (e.g., the Edit control)
    edit_control = window.EditControl() 
    if edit_control.Exists(timeout=2):
        edit_control.SendKeys('Hello, UI Automation!')
else:
    print('Notepad window not found.')
```

--------------------------------

### Getting Started with UI Automation

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/quick-reference.md

Initializes the automation library, gets the desktop root control, and finds a window by its class name. Includes a check for window existence with a timeout.

```python
import uiautomation as auto

# Get desktop root
root = auto.GetRootControl()

# Find a window
window = auto.WindowControl(searchDepth=1, ClassName='Notepad')

# Find with timeout check (no exception)
if window.Exists(timeout=5):
    # Safe to proceed
    pass
```

--------------------------------

### Control Type Instantiation Examples

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Examples of how to instantiate various specific control types. Default search parameters are used.

```python
SliderControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'SliderControl'
```

```python
SpinnerControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'SpinnerControl'
```

```python
SplitButtonControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'SplitButtonControl'
```

```python
StatusBarControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'StatusBarControl'
```

```python
TabControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TabControl'
```

```python
TabItemControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TabItemControl'
```

```python
TableControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TableControl'
```

```python
TextControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TextControl'
```

```python
ThumbControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'ThumbControl'
```

```python
TitleBarControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TitleBarControl'
```

```python
ToolBarControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'ToolBarControl'
```

```python
ToolTipControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'ToolTipControl'
```

```python
TreeControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TreeControl'
```

```python
TreeItemControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'TreeItemControl'
```

```python
WindowControl(searchDepth=4294967295, searchInterval=0.5, foundIndex=1, element=0, **searchProperties) -> 'WindowControl'
```

--------------------------------

### ValuePattern Example

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-patterns.md

Example demonstrating how to set and get the value of an edit control using ValuePattern. Access the pattern via `control.GetValuePattern()`.

```python
edit = window.EditControl()
edit.GetValuePattern().SetValue('Hello')
current = edit.GetValuePattern().Value
print(f"Value: {current}")
```

--------------------------------

### Example: Find and Select Text

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-patterns.md

Demonstrates how to get the text pattern from a document control, retrieve the document range, find specific text within that range, and then select the found text. Ensure the text control and its pattern are correctly initialized before use.

```python
text_control = window.DocumentControl()
pattern = text_control.GetTextPattern()
doc_range = pattern.DocumentRange
print(f"Full text: {doc_range.Text}")

# Find and select text
found = doc_range.FindText('search term', backwards=False, ignoreCase=True)
if found:
    found.Select()
```

--------------------------------

### Example: Scrolling a Control

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-patterns.md

Demonstrates how to get the ScrollPattern from a control and use its Scroll method to scroll horizontally.

```python
scrollable = window.Control(ControlType=ControlType.CustomControl)
pattern = scrollable.GetScrollPattern()
pattern.Scroll(ScrollAmount.LargeIncrement, ScrollAmount.NoAmount)  # Scroll right
```

--------------------------------

### Install UIAutomation Module

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/readme.md

Install the uiautomation module using pip. Ensure you are not using Python versions 3.7.6 or 3.8.1 due to comtypes compatibility issues.

```bash
pip install uiautomation
```

--------------------------------

### InvokePattern Example

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-patterns.md

Example of how to invoke a button control using the InvokePattern. Ensure the control is correctly identified before attempting to invoke.

```python
button = window.ButtonControl(Name='OK')
button.GetInvokePattern().Invoke()
```

--------------------------------

### ShowWindow

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets a native handle and calls the native `ShowWindow` function.

```APIDOC
## ShowWindow

### Description
Gets a native handle from the control or its ancestors and calls the native `ShowWindow` function with the specified command.

### Method
```python
ShowWindow(self, cmdShow: int, waitTime: float = 0.5) -> Optional[bool]
```

### Parameters
* **cmdShow** (int) - A value from the `SW` class indicating how to show the window.
* **waitTime** (float, optional) - The time to wait after showing. Defaults to 0.5 seconds.

### Returns
* bool - True if successful, False otherwise.
* None - If the handle could not be obtained.
```

--------------------------------

### Get Ancestor Controls

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control.md

Returns a list of ancestor controls, starting from the parent and going up to the root control.

```python
def GetAncestors(self) -> List['Control']:
    """Return list of ancestor controls from parent to root."""
```

--------------------------------

### Example Usage: Finding and Interacting with Notepad

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control.md

Demonstrates finding the root control, locating a Notepad window, interacting with its edit control by sending keys and retrieving text, navigating its children, and finding/clicking a close button using a custom comparison.

```python
import uiautomation as auto

# Get root (Desktop)
root = auto.GetRootControl()

# Find notepad window
notepad = auto.WindowControl(searchDepth=1, ClassName='Notepad')
if notepad.Exists(3):
    print(f"Found: {notepad.Name}")
    
    # Find edit control inside notepad
    edit = notepad.EditControl()
    edit.SendKeys('Hello World')
    
    # Get text value via pattern
    value = edit.GetValuePattern().Value
    print(f"Text: {value}")
    
    # Navigate children
    for child in notepad.GetChildren():
        print(f"  - {child.ControlTypeName}: {child.Name}")
    
    # Find button by name with search
    close_btn = notepad.ButtonControl(
        searchDepth=2,
        Compare=lambda c, d: c.Name in ['Close', '关闭']
    )
    if close_btn.Exists(1):
        close_btn.Click()
```

--------------------------------

### Automate Notepad with uiautomation

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/readme.md

Launches Notepad, interacts with its controls, captures images, and generates a GIF. This example demonstrates comprehensive UI automation, including value setting, text input, image capture, and GIF creation. Ensure Python is run as administrator if COMError occurs.

```python
# -*- coding: utf-8 -*-
# this script only works with Win32 notepad.exe
# if your notepad.exe is the Windows Store version in Windows 11, you need to uninstall it.
import subprocess
import uiautomation as auto

def test():
    print(auto.GetRootControl())
    subprocess.Popen('notepad.exe', shell=True)
    # you should find the top level window first, then find children from the top level window
    notepadWindow = auto.WindowControl(searchDepth=1, ClassName='Notepad')
    if not notepadWindow.Exists(3, 1):
        print('Can not find Notepad window')
        exit(0)
    print(notepadWindow)
    notepadWindow.SetTopmost(True)
    # find the first EditControl in notepadWindow
    edit = notepadWindow.EditControl()
    # usually you don't need to catch exceptions
    # but if you encounter a COMError exception, put it in a try block
    try:
        # use value pattern to get or set value
        edit.GetValuePattern().SetValue('Hello')  # or edit.GetPattern(auto.PatternId.ValuePattern)
    except auto.comtypes.COMError as ex:
        # maybe you aren't running Python as administrator
        # or the control doesn't have an implementation for the pattern method (there is no workaround for this)
        pass
    edit.Click() # this step is optional, but some edits need it
    edit.SendKeys('{Ctrl}{End}{Enter}World')
    print('current text:', edit.GetValuePattern().Value)
    notepadWindow.CaptureToImage('notepad.png')
    notepadWindow.MenuBarControl(searchDepth=1).CaptureToImage('notepad_menubar.png')

    # generate an animated gif
    bitmap = notepadWindow.ToBitmap(x=0, y=0, width=160, height=160)
    side = int(bitmap.Width * 1.42)
    gifBmp = auto.Bitmap(side, side)
    gifBmp.Clear(0xFFFF_FFFF) # set bitmap background color to white
    gifBmp.Paste(x=(side-bitmap.Width)//2, y=(side-bitmap.Height)//2, bitmap=bitmap)
    gifFrameCount = 20
    bmps = [gifBmp.RotateWithSameSize(gifBmp.Width//2, gifBmp.Height//2, i*360/gifFrameCount) for i in range(0, gifFrameCount)]
    auto.GIF.ToGifFile('notepad_part.gif', bitmaps=bmps, delays=[100]*gifFrameCount)

    # find the first TitleBarControl in notepadWindow,
    # then find the second ButtonControl in TitleBarControl, which is the Maximize button
    maximizeButton = notepadWindow.TitleBarControl().ButtonControl(foundIndex=2)
    maximizeButton.Click(waitTime=2)
    maximizeButton.Click()
    # find the first button in notepadWindow whose Name is '关闭' or 'Close', the close button
    # the relative depth from Close button to Notepad window is 2
    notepadWindow.ButtonControl(searchDepth=2, Compare=lambda c, d: c.Name in ['Close', '关闭']).Click()
    # then notepad will pop up a window asking whether to save, press Alt+N to discard
    notepadWindow.WindowControl(searchDepth=1).CaptureToImage('notepad_save.png')
    auto.SendKeys('{Alt}n')

if __name__ == '__main__':
    test()

```

--------------------------------

### Get Ancestor Control

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Retrieves an ancestor control that matches a given condition. The search depth starts from -1 and decreases as it moves up the control hierarchy.

```APIDOC
## GetAncestorControl

### Description
Get an ancestor control that matches the condition.

### Parameters
- **condition**: Callable[[Control, int], bool] - A function that takes a control and its depth as input and returns a boolean indicating if the control matches the condition. Depth starts at -1 and decreases when searching upwards.

### Return
- [Control](#Control) subclass or None.
```

--------------------------------

### StartListening

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Starts the Microsoft UI Automation provider listening for mouse or keyboard input.

```APIDOC
## StartListening

### Description
Causes the Microsoft UI Automation provider to start listening for mouse or keyboard input.

### Method
Call `IUIAutomationSynchronizedInputPattern::StartListening`.

### Return Value
Returns `bool`: `True` if successful, otherwise `False`.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationsynchronizedinputpattern-startlistening](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationsynchronizedinputpattern-startlistening)
```

--------------------------------

### Window Control Interaction Example

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-patterns.md

Demonstrates how to access the WindowPattern for a specific window and perform actions like maximizing, waiting for idle state, and closing.

```python
window = auto.WindowControl(Name='Notepad')
pattern = window.GetWindowPattern()
pattern.SetWindowVisualState(auto.WindowVisualState.Maximized)
pattern.WaitForInputIdle(5000)
pattern.Close()
```

--------------------------------

### Get Process Information

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-functions.md

Functions to retrieve details about running processes. GetProcessPath returns the executable path, GetProcessCommandLine returns the start command line, and GetProcesses can list all processes or filter by name.

```python
def GetProcessPath(processId: int) -> str:
    """
    Get file path of running process by PID.
    Return: str, full path to executable.
    """

def GetProcessCommandLine(processId: int) -> str:
    """Get command line used to start process."""

def GetProcesses(name: Optional[str] = None) -> List[ProcessInfo]:
    """
    Get list of running processes.
    name: Optional[str], if provided, filter by process name.
    Return: List[ProcessInfo] with name, processId, parentProcessId.
    """
```

--------------------------------

### ShowDesktop

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the desktop by pressing the 'Win + D' keys.

```APIDOC
## ShowDesktop

### Description
Shows the desktop by simulating the 'Win + D' key press.

### Parameters
- **waitTime** (float, optional) - The time to wait after simulating the key press. Defaults to 1 second.
```

--------------------------------

### Factory Methods for Control Instantiation and Search

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control-types.md

Demonstrates using factory methods to get the root control, find windows, buttons, edit fields, and lists. Shows how to use various search parameters including ControlType, Name, searchDepth, and a custom Compare function.

```python
import uiautomation as auto

# Get root
root = auto.GetRootControl()

# Factory methods work from any control
window = auto.WindowControl(searchDepth=1, Name='App')
button = window.ButtonControl(Name='Click Me')
edit = window.EditControl(Name='Enter Text')
list_ctrl = window.ListControl()

# All support the same search parameters
control = window.Control(
    ControlType=auto.ControlType.ButtonControl,
    Name='OK',
    searchDepth=2,
    Compare=lambda c, d: c.NativeWindowHandle > 0
)
```

--------------------------------

### Get Control Position

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the position of the center of the control relative to the screen.

```APIDOC
## GetControlPosition

### Description
Gets the position of the center of the control.

### Parameters
- **ratioX** (float) - The X-axis ratio for the center position.
- **ratioY** (float) - The Y-axis ratio for the center position.

### Return
Tuple[int, int] - A tuple containing the (x, y) coordinates of the control's center relative to the screen.
```

--------------------------------

### Common Workflow: Automating Notepad Text Entry

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/MANIFEST.md

A complete workflow example demonstrating how to open Notepad, type text, and save the file.

```python
import py_uiautomation as pua
import os

# Define file path
file_path = os.path.join(os.getcwd(), 'my_test_file.txt')

# Launch Notepad
notepad = pua.Start Rússia('notepad.exe')

# Wait for Notepad window and set focus
if notepad.Exists(timeout=5):
    print('Notepad launched.')
    notepad.SetFocus()
    
    # Find the edit control and type text
    edit_control = notepad.EditControl()
    if edit_control.Exists(timeout=2):
        edit_control.SetText('This is automated text entry.')
        print('Text entered into Notepad.')
        
        # Save the file
        notepad.MenuSelect('File->Save As...')
        
        # Handle the Save As dialog
        save_as_dialog = pua.DialogControl(Name='Save As')
        if save_as_dialog.Exists(timeout=5):
            file_name_edit = save_as_dialog.EditControl(Name='File name:')
            if file_name_edit.Exists(timeout=2):
                file_name_edit.SetText(file_path)
                print(f'Set file path to: {file_path}')
                
                save_button = save_as_dialog.ButtonControl(Name='Save')
                if save_button.Exists(timeout=2):
                    save_button.Click()
                    print('Clicked Save button.')
                else:
                    print('Save button not found in Save As dialog.')
            else:
                print('File name edit control not found.')
        else:
            print('Save As dialog not found.')
    else:
        print('Edit control not found in Notepad.')
    
    # Close Notepad
    notepad.Close()
    print('Notepad closed.')
else:
    print('Notepad window did not appear.')

```

--------------------------------

### Get Status Items from StatusBarControl

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control-types.md

Demonstrates finding a status bar and iterating through its child elements to get status information.

```python
# Find status bar
statusbar = window.StatusBarControl(searchDepth=1)

# Get status items
for child in statusbar.GetChildren():
    print(f"Status: {child.Name}")
```

--------------------------------

### Threading Example

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/MANIFEST.md

Demonstrates how to use threading for concurrent UI automation tasks, allowing multiple operations to run in parallel.

```python
import py_uiautomation as pua
import threading
import time

def task1():
    print('Task 1 started')
    window = pua.WindowControl(Name='Notepad')
    if window.Exists(timeout=5):
        edit = window.EditControl()
        edit.SetText('Task 1 typing')
        time.sleep(1)
        edit.SetText('') # Clear for next task
    print('Task 1 finished')

def task2():
    print('Task 2 started')
    window = pua.WindowControl(Name='Notepad')
    if window.Exists(timeout=5):
        edit = window.EditControl()
        time.sleep(0.5) # Ensure Notepad is ready
        edit.SetText('Task 2 typing')
        time.sleep(1)
        edit.SetText('') # Clear for next task
    print('Task 2 finished')

# Start Notepad first if not already running
pua.Start Rússia('notepad.exe')

t1 = threading.Thread(target=task1)
t2 = threading.Thread(target=task2)

t1.start()
t2.start()

t1.join()
t2.join()

print('All tasks completed.')
# Close Notepad after tasks are done
pua.WindowControl(Name='Notepad').Close()
```

--------------------------------

### Bringing a Window to the Foreground

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/MANIFEST.md

Shows how to activate a window and bring it to the foreground, making it the active window for user interaction.

```python
import py_uiautomation as pua

# Find the target window
my_window = pua.WindowControl(Name='My Application')

if my_window.Exists(timeout=5):
    # Bring the window to the foreground
    my_window.SetFocus()
    print('Window brought to foreground.')
else:
    print('Target window not found.')
```

--------------------------------

### Basic UI Automation Interaction

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-functions.md

Demonstrates finding a window, sending keyboard input, manipulating the clipboard, performing mouse operations, and walking the UI tree. Ensure the 'uiautomation' library is imported.

```python
import uiautomation as auto

# Get root and set search timeout
root = auto.GetRootControl()
auto.SetGlobalSearchTimeout(15)

# Find window and interact
notepad = auto.WindowControl(searchDepth=1, ClassName='Notepad')
if notepad.Exists(3):
    # Move and resize
    auto.SetForegroundWindow(notepad.NativeWindowHandle)
    
    # Send keyboard input
    auto.SendKeys('Hello World')
    
    # Get clipboard
    text = auto.GetClipboardText()
    auto.SetClipboardText('Modified text')
    
    # Mouse operations
    x, y = auto.GetCursorPos()
    auto.Click(x + 100, y + 50)
    
    # Screen info
    width, height = auto.GetScreenSize()
    print(f"Screen: {width}x{height}")
    
    # Walk tree
    for control in auto.WalkTree(notepad, depth=2):
        print(f"{control.ControlTypeName}: {control.Name}")
```

--------------------------------

### Get Control Center Position

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the position of the center of the control. Returns a tuple of two integers (x, y) representing the cursor position relative to the screen.

```APIDOC
## GetCenterPosition

### Description
Gets the position of the center of the control.

### Parameters
- **ratioX** (float) - The X-axis ratio for the center position.
- **ratioY** (float) - The Y-axis ratio for the center position.

### Return
Tuple[int, int] - A tuple containing the X and Y coordinates of the control's center relative to the screen (0, 0).
```

--------------------------------

### Bitmap Class - Creation from File

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-bitmap.md

Demonstrates creating Bitmap objects from existing image files using various constructor shortcuts.

```APIDOC
## Bitmap Creation from File

### Description
Create Bitmap instances from image files.

### Methods
* `auto.Bitmap()`
* `auto.BMP(filePath)`
* `auto.JPEG(filePath)`
* `auto.PNG(filePath)`

### Parameters
* **filePath** (str) - Required - Path to the image file.

### Request Example
```python
bitmap = auto.Bitmap()
bitmap = auto.BMP('image.bmp')
bitmap = auto.JPEG('image.jpg')
bitmap = auto.PNG('image.png')
```

### Response
#### Success Response
* **Bitmap** - A new Bitmap instance loaded from the specified file.

#### Response Example
None explicitly provided, returns a Bitmap object.
```

--------------------------------

### Reference Documentation - Configuration

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/README.md

Documentation on global settings and module configuration options.

```APIDOC
## Global Settings and Module Configuration

### Global Constants
- `SEARCH_INTERVAL`: Interval between search attempts.
- `TIME_OUT_SECOND`: Timeout for control searches.
- `OPERATION_WAIT_TIME`: Wait time after operations.

### Platform Detection
- `IsPy38OrHigher`: Boolean indicating if Python 3.8 or higher is used.
- `IsNT6orHigher`: Boolean indicating if the OS is Windows Vista or higher.
- `CurrentProcessIs64Bit`: Boolean indicating if the current process is 64-bit.

### Debug Flags
- `DEBUG_SEARCH_TIME`: Flag to enable debugging of search times.
- `DEBUG_EXIST_DISAPPEAR`: Flag to enable debugging of control existence checks.

### Search Parameters
- Configuration options for individual control searches.

### DPI Awareness Configuration
- Settings related to DPI awareness.

### Threading Support
- `UIAutomationInitializerInThread`: Configuration for initializing UIAutomation in a thread.

### Clipboard Format Constants
- Constants related to clipboard formats.

### Best Practices
- Recommendations for configuring the module for optimal performance and reliability.
```

--------------------------------

### Control.Culture

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the culture information for the control.

```APIDOC
## Control.Culture

### Description
Gets the culture information for the control.

### Returns
- str - The culture string.
```

--------------------------------

### Control.ControlTypeName

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the name of the control type.

```APIDOC
## Control.ControlTypeName

### Description
Gets the name of the control type.

### Returns
- str - The control type name.
```

--------------------------------

### Factory Methods for Control Instantiation

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control-types.md

Demonstrates how to use factory methods to instantiate and search for various control types.

```APIDOC
## Factory Methods

All control type classes can be instantiated and used as search starting points:

```python
import uiautomation as auto

# Get root
root = auto.GetRootControl()

# Factory methods work from any control
window = auto.WindowControl(searchDepth=1, Name='App')
button = window.ButtonControl(Name='Click Me')
edit = window.EditControl(Name='Enter Text')
list_ctrl = window.ListControl()

# All support the same search parameters
control = window.Control(
    ControlType=auto.ControlType.ButtonControl,
    Name='OK',
    searchDepth=2,
    Compare=lambda c, d: c.NativeWindowHandle > 0
)
```

See api-reference-control.md for complete documentation of all Control methods and properties available on each subclass.
```

--------------------------------

### Find and Interact with Window Controls

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-control-types.md

Demonstrates finding a window by class name or name, getting the root control, and interacting with window patterns like maximizing and closing.

```python
import uiautomation as auto

# Find a window by class name
notepad = auto.WindowControl(searchDepth=1, ClassName='Notepad')

# Find a window by name
dialog = auto.WindowControl(searchDepth=1, Name='Save As')

# Get the root (desktop)
root = auto.GetRootControl()  # Returns PaneControl representing desktop

# Window-specific pattern
pattern = notepad.GetWindowPattern()
pattern.SetWindowVisualState(auto.WindowVisualState.Maximized)
pattern.Close()
```

--------------------------------

### Control.ClassName

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the class name of the control.

```APIDOC
## Control.ClassName

### Description
Gets the class name of the control. This is equivalent to calling IUIAutomationElement::get_CurrentClassName.

### Returns
- str - The class name string.
```

--------------------------------

### Control.AutomationId

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the Automation ID of the control.

```APIDOC
## Control.AutomationId

### Description
Gets the Automation ID of the control. This is equivalent to calling IUIAutomationElement::get_CurrentAutomationId.

### Returns
- str - The Automation ID string.
```

--------------------------------

### Automate Notepad with Python

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/quick-reference.md

Launches Notepad, types text, and saves the file using UI automation. Ensure the 'uiautomation' and 'subprocess' libraries are installed.

```python
import uiautomation as auto
import subprocess

# Launch
subprocess.Popen('notepad.exe')

# Find window
notepad = auto.WindowControl(searchDepth=1, ClassName='Notepad')
if not notepad.Exists(timeout=3):
    print("Notepad not found")
    exit()

# Find edit and type
edit = notepad.EditControl()
edit.SendKeys('Hello World')

# Save with Ctrl+S
auto.SendKeys('{Ctrl}s')
```

--------------------------------

### Control.AriaRole

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the Aria role of the control.

```APIDOC
## Control.AriaRole

### Description
Gets the Aria role of the control. This is equivalent to calling IUIAutomationElement::get_CurrentAriaRole.

### Returns
- str - The Aria role string.
```

--------------------------------

### __init__ (Control)

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Initializes a Control object, allowing for searching of UI elements with various properties.

```APIDOC
## __init__ (Control)

### Description
Initializes a Control object. This constructor is used to find and represent UI elements. It can search from a specified control or from the root (Desktop) and allows for detailed search criteria.

### Parameters
#### Path Parameters
None

#### Query Parameters
* **searchFromControl** (Optional[Control]) - Optional - The control to start searching from. If None, searches from the root control (Desktop).
* **searchDepth** (int) - Optional - The maximum depth to search from `searchFromControl` (default: 4294967295).
* **searchInterval** (float) - Optional - The time in seconds to wait after each search operation (default: 0.5). The global timeout is `TIME_OUT_SECOND`.
* **foundIndex** (int) - Optional - The index of the found control if multiple controls match the criteria (starts from 1, default: 1).
* **element** (ctypes.POINTER(IUIAutomationElement)) - Internal use only.
* **searchProperties** (dict) - A dictionary defining the search criteria. Supported keys include:
    * **ControlType** (int): A value from the `ControlType` enum.
    * **ClassName** (str): The class name of the control.
    * **AutomationId** (str): The automation ID of the control.
    * **Name** (str): The name of the control. Only one of Name, SubName, or RegexName can be used.
    * **SubName** (str): A substring of the control's name. Only one of Name, SubName, or RegexName can be used.
    * **RegexName** (str): A regular expression to match the control's name (using `re.match`). Only one of Name, SubName, or RegexName can be used.
    * **Depth** (int): Specifies a relative depth for searching. If set, `searchDepth` will also be set to this value.
    * **Compare** (Callable[[Control, int], bool]): A custom comparison function that takes a `Control` object and its depth, returning `True` if it matches.

### Method
This is a constructor for the Control class.

### Endpoint
N/A (Python class instantiation)

### Request Example
```python
import uiautomation

# Find a button with AutomationId 'myButton'
button = uiautomation.Button(AutomationId='myButton')

# Find the first text control within a specific window
window = uiautomation.WindowControl(Name='My Application')
text_control = window.TextControl(foundIndex=1)

# Find a control using a custom search function
def custom_search(control, depth):
    return control.Name == 'Specific Item' and control.ControlType == uiautomation.ControlType.ListItemControl

found_item = uiautomation.Control(Compare=custom_search)
```

### Response
#### Success Response (200)
* **Control** - An instance of the `Control` class or its subclass, representing the found UI element.

```

--------------------------------

### Control.AriaProperties

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the Aria properties of the control.

```APIDOC
## Control.AriaProperties

### Description
Gets the Aria properties of the control. This is equivalent to calling IUIAutomationElement::get_CurrentAriaProperties.

### Returns
- str - The Aria properties string.
```

--------------------------------

### Start Listening for Synchronized Input

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Initiates listening for mouse or keyboard input by the UI Automation provider. Returns True on success, False otherwise.

```python
StartListening(self) -> bool
```

--------------------------------

### Show

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Calls the native `ShowWindow` method to display the control. It attempts to get a valid native handle first.

```APIDOC
## Show

### Description
Calls the native `ShowWindow` method to display the control. It attempts to get a valid native handle first.

### Method
Show

### Parameters
#### Path Parameters
- **waitTime** (float) - Optional - Defaults to 0.5.

### Returns
- Optional[bool] - True if successful, False otherwise. Returns None if the handle could not be obtained.
```

--------------------------------

### Control.AccessKey

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the access key for the control.

```APIDOC
## Control.AccessKey

### Description
Gets the access key for the control. This is equivalent to calling IUIAutomationElement::get_CurrentAccessKey.

### Returns
- str - The access key string.
```

--------------------------------

### Getting Window Information

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/MANIFEST.md

Demonstrates how to retrieve information about open windows, such as their titles, process IDs, and visibility status.

```python
import py_uiautomation as pua

# Get a specific window by its title
notepad_window = pua.WindowControl(Name='Untitled - Notepad')

if notepad_window.Exists(timeout=5):
    # Get window properties
    title = notepad_window.Name
    process_id = notepad_window.ProcessId
    is_visible = notepad_window.IsVisible()
    is_topmost = notepad_window.IsTopmost()

    print(f'Window Title: {title}')
    print(f'Process ID: {process_id}')
    print(f'Is Visible: {is_visible}')
    print(f'Is Topmost: {is_topmost}')
else:
    print('Notepad window not found.')
```

--------------------------------

### AutomationId

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the AutomationId property of the control.

```APIDOC
## AutomationId

### Description
Property AutomationId. Calls IUIAutomationElement::get_CurrentAutomationId.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentautomationid](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentautomationid)
```

--------------------------------

### AriaRole

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the AriaRole property of the control.

```APIDOC
## AriaRole

### Description
Property AriaRole. Calls IUIAutomationElement::get_CurrentAriaRole.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentariarole](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentariarole)
```

--------------------------------

### ShowWindow

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets a native handle and calls the native ShowWindow function with a specified command. Returns true if successful, false otherwise, and None if the handle could not be obtained.

```APIDOC
## ShowWindow

### Description
Retrieves a native handle for the control (or its ancestors) and calls the native `ShowWindow` function with the provided command. It returns a boolean indicating success or failure, and None if the handle cannot be obtained.

### Method
ShowWindow

### Parameters
#### Path Parameters
- **cmdShow** (int) - A value from the `SW` class indicating how the window should be shown.
- **waitTime** (float, optional) - The time to wait before performing the action. Defaults to 0.5.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (Optional[bool])
Returns `True` if the window was shown successfully, `False` otherwise. Returns `None` if the native handle could not be obtained.

#### Response Example
None
```

--------------------------------

### AriaProperties

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the AriaProperties property of the control.

```APIDOC
## AriaProperties

### Description
Property AriaProperties. Calls IUIAutomationElement::get_CurrentAriaProperties.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentariaproperties](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentariaproperties)
```

--------------------------------

### Common UI Automation Operations

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/api-reference-functions.md

Examples demonstrating common UI automation tasks such as finding windows, sending keystrokes, mouse operations, and navigating the UI tree.

```APIDOC
## Examples

```python
import uiautomation as auto

# Get root and set search timeout
root = auto.GetRootControl()
auto.SetGlobalSearchTimeout(15)

# Find window and interact
notepad = auto.WindowControl(searchDepth=1, ClassName='Notepad')
if notepad.Exists(3):
    # Move and resize
    auto.SetForegroundWindow(notepad.NativeWindowHandle)
    
    # Send keyboard input
    auto.SendKeys('Hello World')
    
    # Get clipboard
    text = auto.GetClipboardText()
    auto.SetClipboardText('Modified text')
    
    # Mouse operations
    x, y = auto.GetCursorPos()
    auto.Click(x + 100, y + 50)
    
    # Screen info
    width, height = auto.GetScreenSize()
    print(f"Screen: {width}x{height}")
    
    # Walk tree
    for control in auto.WalkTree(notepad, depth=2):
        print(f"{control.ControlTypeName}: {control.Name}")
```
```

--------------------------------

### AccessKey

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the AccessKey property of the control.

```APIDOC
## AccessKey

### Description
Property AccessKey. Calls IUIAutomationElement::get_CurrentAccessKey.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentaccesskey](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentaccesskey)
```

--------------------------------

### Show

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the control's window using the native ShowWindow function with the SW_SHOW flag.

```APIDOC
## Show

### Description
Shows the control's window. This method internally calls the native `ShowWindow` function with the `SW_SHOW` command. It attempts to retrieve a valid native handle from the control or its ancestors.

### Method
`Show(waitTime: float = 0.5) -> Optional[bool]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **waitTime** (float) - Optional - The time to wait after attempting to show the window. Defaults to 0.5 seconds.

### Returns
- **Optional[bool]**: `True` if the window was successfully shown, `False` if it failed, or `None` if a valid native handle could not be obtained.
```

--------------------------------

### AcceleratorKey

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the AcceleratorKey property of the control.

```APIDOC
## AcceleratorKey

### Description
Property AcceleratorKey. Calls IUIAutomationElement::get_CurrentAcceleratorKey.

### Reference
[https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentacceleratorkey](https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentacceleratorkey)
```

--------------------------------

### Capture and Save Control as PNG

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/_autodocs/configuration.md

Capture a UI control as a bitmap and save it to a file in PNG format. Demonstrates basic bitmap usage.

```python
# Capture control and save as PNG
bitmap = control.ToBitmap()
bitmap.SaveToFile('control.png')
```

--------------------------------

### Height Property

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the height of the bitmap.

```APIDOC
## Height Property

### Description
Gets the height of the bitmap.

### Property Signature
`Height`

### Returns
* **int** - The height of the bitmap.
```

--------------------------------

### Width Property

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the width of the bitmap.

```APIDOC
## Width Property

### Description
Gets the width of the bitmap.

### Property Signature
`Width`

### Returns
* **int** - The width of the bitmap.
```

--------------------------------

### Automating Notepad with UI Automation

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/readme.md

This script demonstrates launching Notepad, interacting with its edit control using SendKeys, and closing the window. It highlights how control elements are searched and cached, and the necessity of refinding controls after window closure or modification. Includes error handling for control lookup failures.

```python
#!python3
# -*- coding:utf-8 -*-
# this script only works with Win32 notepad.exe
# if your notepad.exe is the Windows Store version in Windows 11, you need to uninstall it.
import subprocess
import uiautomation as auto
auto.uiautomation.SetGlobalSearchTimeout(15)  # set new timeout 15


def main():
    subprocess.Popen('notepad.exe', shell=True)
    window = auto.WindowControl(searchDepth=1, ClassName='Notepad')
    # or use Compare for custom search
    # window = auto.WindowControl(searchDepth=1, ClassName='Notepad', Compare=lambda control, depth: control.ProcessId==100)
    edit = window.EditControl()
    # when calling SendKeys, uiautomation starts searching the window and edit controls in 15 seconds
    # because SendKeys indirectly calls Control.Element and Control.Element is None
    # if the window and edit controls don't exist within 15 seconds, a LookupError exception will be raised
    try:
        edit.SendKeys('first notepad')
    except LookupError as ex:
        print("The first notepad doesn't exist in 15 seconds")
        return
    # the second call to SendKeys doesn't trigger a search; the previous call makes sure that Control.Element is valid
    edit.SendKeys('{Ctrl}a{Del}')
    window.GetWindowPattern().Close()  # close the first Notepad, the window and edit controls become invalid even though their Elements have values

    subprocess.Popen('notepad.exe')  # run second Notepad
    window.Refind()  # need to re-find the window, trigger a new search
    edit.Refind()  # need to re-find the edit, trigger a new search
    edit.SendKeys('second notepad')
    edit.SendKeys('{Ctrl}a{Del}')
    window.GetWindowPattern().Close()  # close the second Notepad, window and edit become invalid again

    subprocess.Popen('notepad.exe')  # run third Notepad
    if window.Exists(3, 1): # trigger a new search
        if edit.Exists(3):  # trigger a new search
            edit.SendKeys('third notepad')  # edit.Exists makes sure that edit.Element has a valid value now
            edit.SendKeys('{Ctrl}a{Del}')
        window.GetWindowPattern().Close()
    else:
        print("The third notepad doesn't exist in 3 seconds")


if __name__ == '__main__':
    main()

```

--------------------------------

### Show Method

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the control's window using the native `ShowWindow` function.

```APIDOC
## Show

### Description
Shows the control's window using the native `ShowWindow` function with the `SW_SHOW` command.

### Parameters
- **waitTime** (float) - Time in seconds to wait after showing the window (default is 0.5).

### Returns
- **Optional[bool]** - True if successful, False if it failed, or None if the handle could not be obtained.
```

--------------------------------

### BoundingRectangle

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the bounding rectangle of the control.

```APIDOC
## BoundingRectangle

### Description
Gets the bounding rectangle of the control. This property calls `IUIAutomationElement::get_CurrentBoundingRectangle`.

### Return Value
- **Rect** - An object representing the control's bounding rectangle with properties like `left`, `top`, `right`, `bottom`, `width()`, `height()`, `xcenter()`, and `ycenter()`.
```

--------------------------------

### Get Bounding Rectangle of a Control

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Access the BoundingRectangle property to get the dimensions and position of a control. The returned Rect object provides methods to access its properties like left, top, right, bottom, width, height, and center coordinates.

```python
rect = control.BoundingRectangle
print(rect.left, rect.top, rect.right, rect.bottom, rect.width(), rect.height(), rect.xcenter(), rect.ycenter())
```

--------------------------------

### Show

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the control using the native `ShowWindow` function. Returns True if successful, False otherwise.

```APIDOC
## Show

### Description
Displays the control by invoking the native `ShowWindow` function. This method attempts to retrieve a valid native handle for the control before calling the underlying Windows API.

### Method
`Show(waitTime: float = 0.5)`

### Parameters
* **waitTime** (float) - Optional - The time in seconds to wait for a valid native handle to be obtained. Defaults to 0.5 seconds.

### Returns
- `Optional[bool]`: True if the control was successfully shown, False if it failed, and None if a valid native handle could not be obtained.
```

--------------------------------

### Control.ControlTypeName

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the string name of the control type.

```APIDOC
## ControlTypeName

### Description
Gets the string name of the control type.
```

--------------------------------

### Show

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the control by calling the native ShowWindow function with the SW_SHOW flag. Returns whether the operation was successful.

```APIDOC
## Show

### Description
Shows the control by calling the native `ShowWindow` function with the `SW_SHOW` flag. Returns whether the operation was successful.

### Method Signature
`Show(self, waitTime: float = 0.5) -> Optional[bool]`

### Parameters
- **waitTime** (float, optional) - The time to wait after attempting to show the control. Defaults to 0.5 seconds.

### Returns
- **Optional[bool]**: True if successful, False if failed. Returns None if the control's handle could not be obtained.
```

--------------------------------

### ShowWindow

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Calls the native ShowWindow function with a specified command.

```APIDOC
## ShowWindow

### Description
Gets a native handle from the control or its ancestors and calls the native ShowWindow function with the specified command.

### Method
ShowWindow(cmdShow: int, waitTime: float = 0.5)

### Parameters
- **cmdShow** (int) - Required - A value from the SW class indicating how to show the window.
- **waitTime** (float) - Optional - The time to wait for the operation to complete. Defaults to 0.5 seconds.

### Response
- Optional[bool]: True if the operation succeeded, False if it failed, None if the handle could not be obtained.
```

--------------------------------

### Get Name

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Retrieves the name of the UI element.

```APIDOC
## Get Name

### Description
Property Name. Retrieves the name of the UI element.

### Method
IUIAutomationElement::get_CurrentName

### Refer
https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-get_currentname
```

--------------------------------

### Control.AcceleratorKey

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Gets the accelerator key associated with the control.

```APIDOC
## Control.AcceleratorKey

### Description
Gets the accelerator key associated with the control. This is equivalent to calling IUIAutomationElement::get_CurrentAcceleratorKey.

### Returns
- str - The accelerator key string.
```

--------------------------------

### Show

Source: https://github.com/yinkaisheng/python-uiautomation-for-windows/blob/master/document.html

Shows the control by calling the native ShowWindow function. Returns True if successful, False otherwise, and None if the handle could not be obtained.

```APIDOC
## Show

### Description
Shows the control by calling the native ShowWindow function. Returns True if successful, False otherwise, and None if the handle could not be obtained.

### Method
```python
Show(self, waitTime: float = 0.5) -> Optional[bool]
```

### Parameters
* **waitTime** (float, optional) - The time to wait. Defaults to 0.5.
```