Win API

This API allows AngelScript scripts to interact with Windows:

  • Find windows by title or class

  • Read window titles, classes, positions, sizes

  • Detect whether a window is foreground or active

  • Read or write clipboard text

  • Discover the thread & process IDs for a window

  • Send messages (WM_CHAR, WM_KEYDOWN, WM_KEYUP, etc.)

  • Send global keyboard/mouse events (SendInput)

Handles (hwnd) are represented as uint64 values.

Window Lookup

uint64 find_window(const string &in title)

Finds a top-level window by its title.

Returns 0 if not found.

uint64 find_window(const string &in title, const string &in className)

Finds a window by title and class name.

Pass empty string ("") to ignore a filter.

Returns 0 if not found.

Window Information

bool get_window_size(uint64 hwnd, int &out w, int &out h)

Retrieves the window’s width and height (outer size).

Returns false if the window is invalid.

bool get_window_rect(uint64 hwnd, int &out x, int &out y, int &out w, int &out h)

Retrieves full window rect:

  • x, y — top-left screen coordinates

  • w, h — size in pixels

Returns false on failure.

bool get_window_title(uint64 hwnd, string &out title)

Gets the window’s title text (UTF-8).

  • Returns true even for empty titles.

  • Returns false only when the hwnd is invalid.

bool get_window_class(uint64 hwnd, string &out cls)

Gets the Win32 window class name.

Returns false if the window is invalid.

Foreground / Activity

bool set_foreground_window(uint64 hwnd)

Attempts to bring the window to foreground.

bool is_foreground_window(uint64 hwnd)

Returns true if the given window is currently foreground.

bool is_window_active(uint64 hwnd)

Checks whether the window:

  • is valid

  • is visible

  • is not minimized

This is a broader “is active” check.

Clipboard

All clipboard strings are UTF-8.

bool copy_to_clipboard(const string &in text)

Copies text into the Windows clipboard.

bool copy_from_clipboard(string &out text)

Reads text from the Windows clipboard.

  • Returns true if any text was successfully retrieved.

  • Empty clipboard → empty string.

Thread & Process Info

bool get_window_thread_process_id(uint64 hwnd, uint &out tid, uint &out pid)

Retrieves:

  • tid — thread ID

  • pid — process ID

Returns false if the hwnd is invalid.

Messaging

bool post_message(uint64 hwnd, uint msg, uint64 wparam, uint64 lparam)

Posts a raw Win32 message to a window.

Examples:

  • post_message(hwnd, 0x0010, 0, 0) → WM_CLOSE

  • post_message(hwnd, 0x0100, VK_A, 0) → WM_KEYDOWN for ‘A’

Returns false if the hwnd is invalid.

Keyboard Input

Global keyboard (SendInput)

These functions simulate real keyboard events globally.

void win_key_down(uint vk)

Simulates a key-down.

void win_key_up(uint vk)

Simulates a key-up.

void win_key_press(uint vk, uint delay_ms = 30)

Press → delay → release.

  • delay_ms clamped to 0..1000.

Window-targeted typing (PostMessage)

bool send_char(uint64 hwnd, const string &in text)

Sends a single character to a window using WM_CHAR.

  • Only the first UTF-16 code unit is used.

bool send_key(uint64 hwnd, uint vk)

Sends:

  • WM_KEYDOWN

  • WM_KEYUP

…to a specific window.

Mouse Input

Mouse input uses real global SendInput events.

void mouse_move(int x, int y)

Moves the mouse to absolute screen coordinates.

void mouse_move_relative(int dx, int dy)

Moves the mouse relative to the current cursor position.

void mouse_left_click()

Left button click.

void mouse_right_click()

Right button click.

void mouse_middle_click()

Middle button click.

Each sends DOWN → small wait → UP.

void mouse_scroll(int amount)

Scroll amount in “wheel notches”:

  • positive → scroll up

  • negative → scroll down

Util

int64 get_tickcount64()

  • GetTickCount64()

Examples

Find a window & print info

string title;
string cls;

uint64 hwnd = find_window("Untitled - Notepad");

if (hwnd != 0)
{
    int x, y, w, h;
    get_window_rect(hwnd, x, y, w, h);

    get_window_title(hwnd, title);
    get_window_class(hwnd, cls);

    log("Title: " + title);
    log("Class: " + cls);
    log("Rect: " + x + "," + y + "  size " + w + "x" + h);
}

Clipboard

copy_to_clipboard("AngelScript clipboard test こんにちは 🌸");

string out;
copy_from_clipboard(out);

log("Clipboard: " + out);

Global keyboard

// Type “HELLO”
win_key_press(0x48); // H
win_key_press(0x45); // E
win_key_press(0x4C); // L
win_key_press(0x4C); // L
win_key_press(0x4F); // O

// Ctrl+V
win_key_down(0x11); // Ctrl
win_key_press(0x56); // V
win_key_up(0x11);

Send chars to a window

uint64 hwnd = find_window("Untitled - Notepad");

set_foreground_window(hwnd);

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

send_key(hwnd, 0x0D); // Enter

Mouse interaction

mouse_move(100, 200);
mouse_left_click();

mouse_move_relative(50, 0);
mouse_right_click();

mouse_scroll(3);   // up
mouse_scroll(-3);  // down

Full API Test

const string TARGET_TITLE = "Untitled - Notepad"; // change as you like

void log_line(const string &in msg)
{
    log("[AS-WINAPI] " + msg);
}

void dump_window_info(uint64 hwnd)
{
    if (hwnd == 0)
    {
        log_line("HWND = 0");
        return;
    }
    
    log_line("HWND = 0x" + formatInt(int64(hwnd), "H"));
    
    string title, cls;
    if (get_window_title(hwnd, title))
    log_line("  title: " + title);
    else
    log_line("  title: <failed>");
    
    if (get_window_class(hwnd, cls))
    log_line("  class: " + cls);
    else
    log_line("  class: <failed>");
    
    int x, y, w, h;
    if (get_window_rect(hwnd, x, y, w, h))
    log_line("  rect:  x=" + x + " y=" + y + " w=" + w + " h=" + h);
    else
    log_line("  rect:  <failed>");
    
    uint tid, pid;
    if (get_window_thread_process_id(hwnd, tid, pid))
    log_line("  tid=" + tid + " pid=" + pid);
    else
    log_line("  tid/pid: <failed>");
}

uint64 get_target_hwnd()
{
    log_line("Target window title: " + TARGET_TITLE);
    
    uint64 hwnd = find_window(TARGET_TITLE);
    if (hwnd == 0)
    {
        log_line("Window not found.");
        return 0;
    }
    
    log_line("Found window.");
    dump_window_info(hwnd);
    
    bool fg = set_foreground_window(hwnd);
    log_line("set_foreground_window -> " + (fg ? "true" : "false"));
    
    return hwnd;
}

void test_mouse_basic()
{
    log_line("=== TEST: mouse movement & clicks ===");
    log_line("Move your eyes to where the cursor goes. :)");
    
    mouse_move(100, 100);
    mouse_left_click();
    log_line("  mouse_move(100,100) + left click");
    
    mouse_move_relative(80, 0);
    mouse_right_click();
    log_line("  mouse_move_relative(80,0) + right click");
    
    mouse_move_relative(0, 60);
    mouse_middle_click();
    log_line("  mouse_move_relative(0,60) + middle click");
    
    mouse_scroll(3);
    mouse_scroll(-3);
    log_line("  mouse_scroll(3) then mouse_scroll(-3)");
}

void test_clipboard()
{
    log_line("=== TEST: clipboard ===");
    
    string src = "Hello from AngelScript WinAPI! こんにちは 🌸";
    bool okSet = copy_to_clipboard(src);
    log_line("  copy_to_clipboard -> " + (okSet ? "true" : "false"));
    
    string got;
    bool okGet = copy_from_clipboard(got);
    log_line("  copy_from_clipboard -> " + (okGet ? "true" : "false"));
    log_line("  clipboard text: " + got);
}

void test_send_char_key(uint64 hwnd)
{
    log_line("=== TEST: send_char / send_key ===");
    
    if (hwnd == 0)
    {
        log_line("No hwnd, skipping send_char/send_key test.");
        return;
    }
    
    log_line("Make sure the target window has a focused text field.");
    
    // Send "Hi " + a flower
    bool ok1 = send_char(hwnd, "H");
    bool ok2 = send_char(hwnd, "i");
    bool ok3 = send_char(hwnd, " ");
    bool ok4 = send_char(hwnd, "🌸"); // first UTF-16 unit is used
    
    log_line("  send_char H -> " + (ok1 ? "true" : "false"));
    log_line("  send_char i -> " + (ok2 ? "true" : "false"));
    log_line("  send_char ' ' -> " + (ok3 ? "true" : "false"));
    log_line("  send_char 🌸 -> " + (ok4 ? "true" : "false"));
    
    // send Enter via WM_KEYDOWN/UP
    const uint VK_RETURN = 0x0D;
    bool okEnter = send_key(hwnd, VK_RETURN);
    log_line("  send_key(VK_RETURN) -> " + (okEnter ? "true" : "false"));
}

void test_global_keys()
{
    log_line("=== TEST: global key_press ===");
    log_line("Make sure some text field is focused if you want to see output.");
    
    // Type 'HELLO'
    const uint VK_H = 0x48;
    const uint VK_E = 0x45;
    const uint VK_L = 0x4C;
    const uint VK_O = 0x4F;
    
    win_key_press(VK_H, 40);
    win_key_press(VK_E, 40);
    win_key_press(VK_L, 40);
    win_key_press(VK_L, 40);
    win_key_press(VK_O, 40);
    
    // Ctrl+V (paste)
    const uint VK_CONTROL = 0x11;
    const uint VK_V       = 0x56;
    
    win_key_down(VK_CONTROL);
    win_key_press(VK_V, 30);
    win_key_up(VK_CONTROL);
    
    log_line("  typed HELLO and sent Ctrl+V");
}

int main()
{
    log_line("=== AS WinAPI Input Test START ===");
    
    uint64 hwnd = get_target_hwnd();
    
    test_mouse_basic();
    test_clipboard();
    test_global_keys();
    test_send_char_key(hwnd);
    
    log_line("=== AS WinAPI Input Test END ===");
    return 1; // keep script loaded if your host uses this
}
PreviousExtended Math APINextEngine Specific API

Last updated