winput API Reference

Package winput provides a high-level interface for Windows background input automation.

Index

Variables
Constants
func EnablePerMonitorDPI
func GetCursorPos
func SetBackend
func SetHIDLibraryPath
func MoveMouseTo
func ClickMouseAt
func KeyDown
func KeyUp
func Press
func PressHotkey
func Type
func CaptureVirtualDesktop
func CaptureRegion
type Backend
type Key
- func KeyFromRune
type Window

Variables

var (
    // ErrWindowNotFound implies the target window could not be located by Title, Class, or PID.
    ErrWindowNotFound = errors.New("window not found")

    // ErrWindowGone implies the window handle is no longer valid.
    ErrWindowGone = errors.New("window is gone or invalid")

    // ErrWindowNotVisible implies the window is hidden or minimized.
    ErrWindowNotVisible = errors.New("window is not visible")

    // ErrUnsupportedKey implies the character cannot be mapped to a key.
    ErrUnsupportedKey = errors.New("unsupported key or character")

    // ErrBackendUnavailable implies the selected backend (e.g. HID) failed to initialize.
    ErrBackendUnavailable = errors.New("input backend unavailable")

    // ErrDriverNotInstalled specific to BackendHID, implies the Interception driver is missing or not accessible.
    ErrDriverNotInstalled = errors.New("interception driver not installed or accessible")

    // ErrDLLLoadFailed implies interception.dll could not be loaded.
    ErrDLLLoadFailed = errors.New("failed to load interception library")

    // ErrPermissionDenied implies the operation failed due to system privilege restrictions (e.g. UIPI).
    ErrPermissionDenied = errors.New("permission denied")

    // ErrPostMessageFailed implies the PostMessageW call returned 0 (e.g., queue full or invalid handle).
    ErrPostMessageFailed = errors.New("PostMessageW failed")
)

Screen Package (`github.com/rpdg/winput/screen`)

func ImageToVirtual

func ImageToVirtual(imageX, imageY int32) (int32, int32)

ImageToVirtual converts coordinates from a "Full Virtual Desktop Screenshot" (OpenCV match) to actual Windows Virtual Desktop coordinates usable by MoveMouseTo. Requires the image to be a capture of the entire virtual desktop (origin 0,0 of the image corresponds to the top-left of the virtual canvas).

func VirtualBounds

func VirtualBounds() Rect

VirtualBounds returns the bounding rectangle of the entire virtual desktop.

func Monitors

func Monitors() ([]Monitor, error)

Monitors returns a list of all active monitors and their geometries.

Constants

Backend Constants

const (
    // BackendMessage uses standard Windows Messages (PostMessage) for input.
    BackendMessage Backend = iota

    // BackendHID uses the Interception driver to simulate hardware input.
    BackendHID
)

Key Constants

Common keyboard scan codes.

const (
    KeyEsc, KeyEnter, KeySpace, KeyTab, KeyBkSp Key = ...
    KeyShift, KeyCtrl, KeyAlt, KeyCaps          Key = ...
    KeyF1 .. KeyF12                             Key = ...
    KeyA .. KeyZ                                Key = ...
    Key0 .. Key9                                Key = ...
    KeyArrowUp, KeyArrowDown, KeyLeft, KeyRight Key = ...
    KeyHome, KeyEnd, KeyPageUp, KeyPageDown     Key = ...
    KeyInsert, KeyDelete                        Key = ...
)

Functions

func EnablePerMonitorDPI

func EnablePerMonitorDPI() error

EnablePerMonitorDPI sets the current process to be Per-Monitor (v2) DPI aware.

func GetCursorPos

func GetCursorPos() (int32, int32, error)

GetCursorPos returns the current absolute screen coordinates of the mouse cursor.

func SetBackend

func SetBackend(b Backend) error

SetBackend sets the input simulation backend. If BackendHID is selected, it attempts to initialize the driver immediately and returns an error if it fails (e.g. driver not installed).

func SetHIDLibraryPath

func SetHIDLibraryPath(path string)

SetHIDLibraryPath sets the custom path for interception.dll.

func MoveMouseTo

func MoveMouseTo(x, y int32) error

MoveMouseTo moves the mouse cursor to the absolute screen coordinates (Virtual Desktop).

func ClickMouseAt

func ClickMouseAt(x, y int32) error

ClickMouseAt moves the mouse to the specified screen coordinates and performs a left click.

func ClickRightMouseAt

func ClickRightMouseAt(x, y int32) error

ClickRightMouseAt moves the mouse to the specified screen coordinates and performs a right click.

func ClickMiddleMouseAt

func ClickMiddleMouseAt(x, y int32) error

ClickMiddleMouseAt moves the mouse to the specified screen coordinates and performs a middle click.

func DoubleClickMouseAt

func DoubleClickMouseAt(x, y int32) error

DoubleClickMouseAt moves the mouse to the specified screen coordinates and performs a left double-click.

func KeyDown

func KeyDown(k Key) error

KeyDown simulates a global key down event.

func KeyUp

func KeyUp(k Key) error

KeyUp simulates a global key up event.

func Press

func Press(k Key) error

Press simulates a global key press (down then up) with a short delay.

func PressHotkey

func PressHotkey(keys ...Key) error

PressHotkey simulates a key combination (e.g., Ctrl+C). It presses keys in order, waits 50ms, then releases them in reverse order.

func Type

func Type(text string) error

Type simulates global text input by simulating keystrokes for each character.

func CaptureVirtualDesktop

func CaptureVirtualDesktop() (*image.RGBA, error)

CaptureVirtualDesktop (in package screen) captures the entire virtual desktop (all monitors) using GDI. It requires the process to be Per-Monitor DPI Aware. Returns an *image.RGBA.

func CaptureRegion

func CaptureRegion(x, y, w, h int32) (*image.RGBA, error)

CaptureRegion (in package screen) captures a specific region of the virtual desktop. x, y are Virtual Desktop coordinates (allowed to be negative). w, h are pixel dimensions. It internally calls CaptureVirtualDesktop, converts coordinates, and performs a safe crop.

Types

type Window

func FindByTitle

func FindByTitle(title string) (*Window, error)

FindByTitle searches for a top-level window matching the exact title.

func FindByClass

func FindByClass(class string) (*Window, error)

FindByClass searches for a top-level window matching the class name.

func FindByPID

func FindByPID(pid uint32) ([]*Window, error)

FindByPID returns all top-level windows belonging to the specified Process ID.

func FindByProcessName

func FindByProcessName(name string) ([]*Window, error)

FindByProcessName returns all top-level windows belonging to the process with the given executable name.

func (*Window) FindChildByClass

func (w *Window) FindChildByClass(class string) (*Window, error)

FindChildByClass searches for a child window with the specified class name (e.g. "Edit" inside Notepad).

func (*Window) Move

func (w *Window) Move(x, y int32) error

Move moves the mouse cursor to the specified coordinates relative to the window's client area.

func (*Window) MoveRel

func (w *Window) MoveRel(dx, dy int32) error

MoveRel moves the mouse cursor relative to its current position.

func (*Window) Click

func (w *Window) Click(x, y int32) error

Click performs a left mouse button click at the specified client coordinates.

func (*Window) ClickRight

func (w *Window) ClickRight(x, y int32) error

ClickRight performs a right mouse button click at the specified client coordinates.

func (*Window) ClickMiddle

func (w *Window) ClickMiddle(x, y int32) error

ClickMiddle performs a middle mouse button click at the specified client coordinates.

func (*Window) DoubleClick

func (w *Window) DoubleClick(x, y int32) error

DoubleClick performs a left mouse button double-click.

func (*Window) Scroll

func (w *Window) Scroll(x, y int32, delta int32) error

Scroll performs a vertical mouse wheel scroll at the specified coordinates.

func (*Window) KeyDown

func (w *Window) KeyDown(key Key) error

KeyDown sends a key down event to the window.

func (*Window) KeyUp

func (w *Window) KeyUp(key Key) error

KeyUp sends a key up event to the window.

func (*Window) Press

func (w *Window) Press(key Key) error

Press simulates a full keystroke (KeyDown followed by KeyUp).

func (*Window) PressHotkey

func (w *Window) PressHotkey(keys ...Key) error

PressHotkey presses a combination of keys in order and releases them in reverse order.

func (*Window) Type

func (w *Window) Type(text string) error

Types a string, automatically handling Shift modifiers.

func (*Window) DPI

func (w *Window) DPI() (uint32, uint32, error)

DPI returns the horizontal and vertical DPI for the window.

func (*Window) ClientRect

func (w *Window) ClientRect() (width, height int32, err error)

ClientRect returns the width and height of the window's client area.

func (*Window) ScreenToClient

func (w *Window) ScreenToClient(x, y int32) (cx, cy int32, err error)

ScreenToClient converts screen-relative coordinates to window-client-relative coordinates.

func (*Window) ClientToScreen

func (w *Window) ClientToScreen(x, y int32) (sx, sy int32, err error)

ClientToScreen converts window-client-relative coordinates to screen-relative coordinates.

FilesExpand file tree

API.md

Latest commit

History