Win API

This API exposes a small subset of the Win32 window, clipboard, keyboard, mouse and messaging functions to Lua:

• Work with windows via handles (hwnd as integer).

• Inspect window rectangles and sizes.

• Check if a window is foreground or “active”.

• Read / write text to the clipboard (UTF-8).

• Look up the thread & process IDs for a window.

• Send messages, keys, and characters to a window.

• Send global keyboard and mouse input via SendInput.

---

Window Lookup & Info

find_window(title [, class]) -> hwnd | nil

Search for a top-level window.

• title — window title to match (UTF-8 string).

• class — optional window class name (UTF-8 string).

If both are provided, both must match. Returns hwnd (integer) or nil if not found.

---

get_window_size(hwnd) -> width, height | nil, nil

Get the window’s outer size in pixels.

• hwnd — window handle (integer).

Returns:

• width, height (integers), or

• nil, nil if the handle is invalid or the call fails.

---

get_window_rect(hwnd) -> x, y, width, height | nil, nil, nil, nil

Get the window’s full rectangle in screen coordinates.

• x, y — top-left screen coordinates.

• width, height — size in pixels.

Returns all nil on failure.

---

Window Focus & Activity

is_foreground_window(hwnd) -> bool

Checks if hwnd is the current foreground window.

---

is_window_active(hwnd) -> bool

Checks if a window is “active” in a broad sense:

• is a valid window,

• is visible,

• is not minimized.

Returns true or false.

---

Window Text & Class

get_window_title(hwnd) -> string | nil

Get the window’s title as a UTF-8 string.

• Returns "" for empty titles.

• Returns nil if the handle is invalid.

---

get_window_class(hwnd) -> string | nil

Get the window’s class name.

• Returns "" if class name can’t be read.

• Returns nil if the handle is invalid.

---

set_foreground_window(hwnd) -> bool

Attempts to bring the given window to the foreground.

Returns true on success, false otherwise.

---

Clipboard

All clipboard operations use UTF-8 strings.

copy_to_clipboard(text) -> bool

Copies a Lua string into the system clipboard.

• text — UTF-8 string.

• Returns true on success, false on failure.

---

copy_from_clipboard() -> string

Reads UTF-8 text from the system clipboard.

• Returns "" (empty string) if:

  • clipboard cannot be opened,

  • the clipboard doesn’t contain text, or

  • any error occurs.

---

Thread / Process Info

get_window_thread_process_id(hwnd) -> thread_id, process_id | nil, nil

Returns IDs associated with a given window.

• thread_id — thread that owns the window.

• process_id — process that owns the thread.

If the handle is invalid or the IDs can’t be obtained, returns nil, nil.

---

Messages & Keys

post_message(hwnd, msg, wparam, lparam) -> bool

Low-level API to post a message to a window.

• hwnd — window handle.

• msg — message ID (e.g., 0x0010 for WM_CLOSE).

• wparam, lparam — integer parameters.

Returns true on success.

---

Global key input (SendInput)

These functions send global keyboard input (not scoped to a specific window). Use when you simply want to simulate key presses.

Virtual keys are integers (e.g. 0x41 for A, 0x11 for Ctrl, 0x0D for Enter).

win_key_down(vk)

Simulate key down for virtual key vk.

win_key_up(vk)

Simulate key up for virtual key vk.

win_key_press(vk [, delay_ms])

Press and release a key, with an optional delay.

• vk — virtual key code.

• delay_ms — optional delay in milliseconds between down and up (default ~30, clamped to 0..1000).

---

Message-based character & key sending

These functions target a specific window using messages (WM_CHAR, WM_KEYDOWN, WM_KEYUP).

send_char(hwnd, text) -> bool

Sends a single character via WM_CHAR.

• text — Lua string; only the first UTF-16 code unit is used, which is fine for most BMP characters.

Returns true on success.

send_key(hwnd, vk) -> bool

Sends a key to a specific window using WM_KEYDOWN and WM_KEYUP.

• vk — virtual key code.

Returns true if both messages were posted successfully.

---

Mouse Input

All mouse functions send global input via SendInput.

Coordinates are in screen pixels (primary monitor), unless noted otherwise.

mouse_move(x, y)

Moves the cursor to absolute screen coordinates.

• (0,0) is top-left of the primary display.

• Coordinates are converted to the normalized range expected by SendInput.

---

mouse_move_relative(dx, dy)

Moves the cursor relative to its current position.

• dx — horizontal delta (pixels).

• dy — vertical delta (pixels).

---

mouse_left_click()

Performs a left button click at the current cursor position.

mouse_right_click()

Performs a right button click.

mouse_middle_click()

Performs a middle button click.

Each click sends a down event, waits ~10 ms, then sends an up event.

---

send_mouse_input(dx, dy, flags, mouse_data)

Send input manually via raw input.

---

mouse_scroll(amount)

Scrolls the mouse wheel vertically.

• amount is in “notches”:

  • positive → scroll up

  • negative → scroll down

Example: mouse_scroll(3) scrolls up 3 notches.

---

Util

get_tickcount64()

• GetTickCount64()

---

Usage Examples

Find a window and print info

local title   = "Untitled - Notepad"
local hwnd    = find_window(title)

if not hwnd then
  print("Window not found:", title)
  return
end

print("HWND:", string.format("0x%X", hwnd))

local x, y, w, h = get_window_rect(hwnd)
print("Rect:", x, y, w, h)

local winTitle = get_window_title(hwnd) or "<nil>"
local winClass = get_window_class(hwnd) or "<nil>"
print("Title:", winTitle)
print("Class:", winClass)

local tid, pid = get_window_thread_process_id(hwnd)
print("Thread ID:", tid, "Process ID:", pid)

---

Clipboard

copy_to_clipboard("Hello from Lua! こんにちは 🌸")

local txt = copy_from_clipboard()
print("Clipboard:", txt)

---

Global keystrokes

-- Type 'HELLO'
local letters = { 0x48, 0x45, 0x4C, 0x4C, 0x4F } -- H E L L O
for _, vk in ipairs(letters) do
  win_key_press(vk, 40)
end

-- Ctrl+V
local VK_CONTROL = 0x11
local VK_V       = 0x56

win_key_down(VK_CONTROL)
win_key_press(VK_V, 30)
win_key_up(VK_CONTROL)

---

Message-based typing into a window

local hwnd = find_window("Untitled - Notepad")
if not hwnd then return end

-- make sure Notepad has focus (if you expose set_foreground_window)
set_foreground_window(hwnd)

send_char(hwnd, "H")
send_char(hwnd, "i")
send_char(hwnd, " ")
send_char(hwnd, "🌸")

local VK_RETURN = 0x0D
send_key(hwnd, VK_RETURN)

---

Mouse movement & clicks

-- Move to near top-left, left-click
mouse_move(100, 100)
mouse_left_click()

-- Move a bit to the right and right-click
mouse_move_relative(80, 0)
mouse_right_click()

-- Move down and middle-click
mouse_move_relative(0, 60)
mouse_middle_click()

-- Scroll up then down
mouse_scroll(3)
mouse_scroll(-3)

Full API Test

local TARGET_TITLE = "Untitled - Notepad"  -- change to your target window

local function has_global(name)
    return _G[name] ~= nil
end

local function get_target_hwnd()
    if not has_global("find_window") then
        log("ERROR: find_window is not available.")
        return nil
    end

    local hwnd = find_window(TARGET_TITLE)
    if not hwnd then
        log("Window not found:", TARGET_TITLE)
        return nil
    end

    log("Found hwnd:", string.format("0x%X", hwnd))

    if has_global("set_foreground_window") then
        local ok = set_foreground_window(hwnd)
        log("set_foreground_window:", ok)
    else
        log("set_foreground_window not available, skipping.")
    end

    return hwnd
end

local function test_mouse_basic()
    log("=== TEST: mouse movement & clicks ===")
    log("Move your eyes to where the cursor goes. :)")

    -- Move to approximate top-left of the primary screen
    mouse_move(100, 100)
    mouse_left_click()
    log("  mouse_move(100,100) + left click")

    -- Move a bit to the right and right-click
    mouse_move_relative(80, 0)
    mouse_right_click()
    log("  mouse_move_relative(80,0) + right click")

    -- Move a bit down and middle-click
    mouse_move_relative(0, 60)
    mouse_middle_click()
    log("  mouse_move_relative(0,60) + middle click")

    -- Scroll up then down a bit
    mouse_scroll(3)   -- up 3 notches
    mouse_scroll(-3)  -- down 3 notches
    log("  mouse_scroll(3) then mouse_scroll(-3)")
end

local function test_send_char_key(hwnd)
    if not hwnd then
        log("No hwnd, skipping send_char/send_key test.")
        return
    end

    if not has_global("send_char") or not has_global("send_key") then
        log("send_char / send_key not available, skipping.")
        return
    end

    log("=== TEST: send_char / send_key ===")
    log("Make sure the target window has a focused text field.")

    -- Send "Hi " + emoji via WM_CHAR
    send_char(hwnd, "H")
    send_char(hwnd, "i")
    send_char(hwnd, " ")
    send_char(hwnd, "🌸") -- only 

    -- Press Enter via WM_KEYDOWN/UP
    local VK_RETURN = 0x0D
    local ok = send_key(hwnd, VK_RETURN)
    log("send_key(VK_RETURN) ->", ok)
end

function main()
    log("Target window title:", TARGET_TITLE)

    local hwnd = get_target_hwnd()

    test_mouse_basic()
    test_send_char_key(hwnd)

    log("=== winapi_input_test.lua done ===")
    return 1;
end