DirectInput 1.2.2
A Windows-specific package for simulating keyboard and mouse inputs
Requires Python: >=3.8

# DirectInput

**DirectInput** is born out of a desire to enhance and extend the capabilities left untouched by PyAutoGUI. It's a robust tool designed for developers and automation enthusiasts. This module excels in detecting key inputs and offers an improved screenshot functionality using mss, providing a faster alternative for real-time applications like object detection with OpenCV.

This module is a testament to innovation in automation, filling gaps and pushing the boundaries of what's possible in automated input control.

## Installation

To start using DirectInput, simply install it via pip:
```bash
pip install DirectInput
```

After installation, you can import and use the module in your Python scripts:
```Python
import directinput
```

## Dependencies

**DirectInput** thrives on the shoulders of powerful dependencies and requires Python 3.8 or higher. Key dependencies include:

- `opencv-python`: For image processing and object detection integrations.
- `numpy`: Essential for handling arrays and complex mathematical operations.
- `mss`: The secret ingredient for lightning-fast screenshots.
- `pyscreeze`, `pyperclip`: Supporting libraries enhancing the module's functionality.

## Functionalities
- `keyDown(key=str)`
- `keyUp(key=str)`
- `keyHold(key=str)`: Simulates holding down one or more specified keys. The keys parameter can be a single key or a list of keys. This function should be used with a with statement to ensure that the keys are released after the block of code is executed. For example:
    ```python
    with directinput.keyHold("ctrl", "shift"):
        directinput.keyPress("esc")
    ```
- `keyPress(key=str, presses=int, simultaneously=bool)`: Simulates pressing one or more keys. The `keys` parameter can be a single key or a list of keys. Additionally, the `simultaneously` parameter can be set to True to press all keys at once, rather than sequentially.
- `hotKey(*keys=str)`: Simulates pressing a combination of keys simultaneously. This function can accept multiple key arguments, e.g., `hotKey('ctrl', 'shift', 's')`.
- `write(text=str, speed=float)`: Types out a given text string. Optionally, `speed` (in seconds) between key presses can be specified to simulate a more natural typing speed.
- `keyDetect(key=str)`: Checks if one or more specified keys are currently pressed. The `keys` parameter can be a single key (as a string) or a list of keys. The function returns `True` if all specified keys are pressed, and `False` if any key is not pressed or not recognized.
- `mouseClick(button=str, presses=int)`
- `mouseDown(button=str)`
- `mouseUp(button=str)`
- `mouseHold(button=str)`: Simulates holding down a specified mouse button, similar to the `keyHold` function. The `button` parameter can be 'left', 'right', or 'middle'. This function should be used with a `with` statement to ensure that the mouse button is released after the block of code is executed.
- `moveMouseTo(x=int/float, y=int/float, duration=int/float)`
- `moveMouse(xOffset=int/float, yOffset=int/float, duration=int/float)`: Moves the mouse cursor relative to its current position by specified x and y offsets over a specified duration.
- `scrollMouse(clicks=int)`: Scrolls the mouse wheel vertically. The `clicks` parameter determines the amount and direction of the scroll: a positive value scrolls up, while a negative value scrolls down. For a visible result, it is recommended to use a value of 100 or more, as smaller numbers may not produce a significant scrolling.
- `screenshot(filename=str, region=tuple)`: Takes a screenshot of the entire screen. Additionally, there's a `region` parameter which captures specified region of the screen. It takes a tuple specifying the top-left x, top-left y, width, and height.
- `getMousePosition()`: Returns the current (x, y) position of the mouse cursor.
- `getDisplaySize()`
- `locateImage(needleImage=str, haystackImage=str, grayscale=bool, region=tuple, threshold=float)`: Searches for an image (`needleImage`) within another image (`haystackImage`) or the screen. If `haystackImage` is not provided, the entire screen is used. The `grayscale` parameter can be set to `True` to perform the search in grayscale, which can improve performance. The `region` parameter can specify a specific area to search within, and `threshold` sets the accuracy required for a match.

## Available Keys and Mouse Buttons

All the keys listed can be detected as well as pressed, except `xbutton1` and `xbutton2`, which cannot be pressed.

### Keyboard Keys

- **Alphabets**: 
  - `a`, `A`, `b`, `B`, `c`, `C`, `d`, `D`, `e`, `E`, `f`, `F`, `g`, `G`, `h`, `H`, `i`, `I`, `j`, `J`, `k`, `K`, `l`, `L`, `m`, `M`, `n`, `N`, `o`, `O`, `p`, `P`, `q`, `Q`, `r`, `R`, `s`, `S`, `t`, `T`, `u`, `U`, `v`, `V`, `w`, `W`, `x`, `X`, `y`, `Y`, `z`, `Z`

- **Numbers**: 
  - `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
  - `num0`, `num1`, `num2`, `num3`, `num4`, `num5`, `num6`, `num7`, `num8`, `num9`

- **Symbols**:
  - `` ` ``, `~`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `-`, `_`, `=`, `+`, `[`, `{`, `]`, `}`, `\`, `|`, `;`, `:`, `'`, `"`, `,`, `<`, `.`, `>`, `/`, `?`

- **Function Keys**: 
  - `f1`, `f2`, `f3`, `f4`, `f5`, `f6`, `f7`, `f8`, `f9`, `f10`, `f11`, `f12`

- **Control Keys**:
  - `space`, `esc`, `tab`, `backspace`, `enter`, `numenter`, `shift`, `lshift`, `rshift`, `ctrl`, `lctrl`, `rctrl`, `alt`, `lalt`, `ralt`, `win`, `lwin`, `rwin`, `apps`, `capslock`, `numlock`, `scrolllock`, `insert`, `delete`, `home`, `end`, `pageup`, `pagedown`, `prtsc`, `sysrq`

- **Calculation Keys**:
  - `num-`, `num/`, `num*`, `num+`, `num.`

- **Arrow Keys**: 
  - `up`, `down`, `left`, `right`

### Mouse Buttons

- **Primary Buttons**: 
  - `left`, `right`, `middle`

- **Additional Buttons**: 
  - `xbutton1` (can only be detected), `xbutton2` (can only be detected)

## Example Usage

### Writing Complex Strings

```Python
import directinput

# Writing a string with special characters
directinput.write("Hello, world! ✌️")
```

This demonstrates the enhanced write function, capable of handling a wide range of characters, surpassing limitations you might find in other modules.

### Detecting Key Presses

```Python
import directinput

# Detect if the 'A' key is being pressed
if directinput.keyDetect('a'):
    print("The 'A' key is pressed!")

# Detect if both 'left_mouse' and 'xbutton1' is being pressed
if directinput.keyDetect(['left_mouse', 'xbutton1']):
    print("Pressed!")
```

### Locating an Image on the Screen

The locateImage function in DirectInput adds a layer of flexibility to image detection. Whether you're automating tasks based on visual cues or integrating with image processing, this function is incredibly handy.

```Python
import directinput

# Locate an image on the screen
point = directinput.locateImage("path_to_needle_image.png")

if point is not None:
    print(f"Image found at {point}")
else:
    print("Image not found")
```

Advanced Usage
- `locateImage` comes with several parameters for refined control:
- `needleImage`: Path to the image you want to find.
- `haystackImage`: Path to the screenshot or image in which to search. If not provided, it captures the entire screen.
- `grayscale`: Set to True for grayscale comparison, which can improve performance.
- `region`: A specific region on the screen to search in.
- `threshold`: The confidence level for image matching, allowing for slight variations.

This functionality is especially useful in scenarios where you need to interact with UI elements based on their appearance, or in cases where dynamic content changes the screen layout.

## How Does It Work?

**DirectInput** is tailored for Windows 10 or higher systems, harnessing the underlying Windows API to deliver its functionalities. This specific design choice ensures compatibility and performance, particularly in how keyboard and mouse inputs are handled and how screenshots are captured and processed.

## Your Contribution Matters

Your insights and contributions are pivotal to the evolution of DirectInput. Here's how you can get involved:

- Report Bugs or Request Features: Encounter a bug or have an idea for a new feature? Open an issue on our [GitHub](https://github.com/abdulrahimpds/DirectInput) page.
- Code Contributions: Got a fix or enhancement? Submit a pull request to improve the codebase.