winapi

Splits a registry path like HKLM\Software\Foo\BarValue into hive (HKLM), subkey (Software\Foo), and value_name (BarValue).

use plugin winapi::{registry_path_parts}

let parts = registry_path_parts("HKLM\\Software\\Microsoft\\Windows\\CurrentVersion")
print("hive={parts["hive"]} subkey={parts["subkey"]}")

When the path ends in a value name, that trailing segment is split out into value_name; the remainder becomes the subkey:

use plugin winapi::{registry_path_parts}

let p = registry_path_parts("HKCU\\Environment\\Path")
print("value={p["value_name"]} under {p["subkey"]}")

Returns true when the current platform is Windows, false otherwise. Safe to call cross-platform.

use plugin winapi::{is_windows}

if is_windows() {
  print("running on Windows")
}

Returns the path of a well-known folder: "desktop", "documents", "downloads", "music", "pictures", "videos", "appdata", "localappdata", "temp", or "home".

use plugin winapi::{known_folder_path}

let docs = known_folder_path("documents")
print("Documents: {docs}")

Aliases let you reach roaming and local app-data as well as the temp directory:

use plugin winapi::{known_folder_path}

print("roaming: {known_folder_path("appdata")}")
print("local:   {known_folder_path("localappdata")}")
print("temp:    {known_folder_path("temp")}")

Expands %VAR_NAME% patterns in the input string using the current process environment. Unknown variables are left unchanged.

use plugin winapi::{expand_env_vars}

let path = expand_env_vars("%APPDATA%\\MyApp\\config.json")
print(path)

Converts an HRESULT integer (e.g. 0, -2147024882) to a human-readable string like "0x00000000 (S_OK)".

use plugin winapi::{hresult_to_string}

print(hresult_to_string(0))          // "0x00000000 (S_OK)"
print(hresult_to_string(-2147467259)) // "0x80004005 (E_FAIL)"

Formats a Win32 last-error code (from GetLastError) as a human-readable string.

use plugin winapi::{last_error_format}

print(last_error_format(5))  // "Error 5 (ERROR_ACCESS_DENIED)"

Shows a native Windows message box dialog. style can be "ok", "okcancel", "yesno", "yesnocancel", "info", "warning", "error". Returns the clicked button name.

use plugin winapi::{message_box}

let result = message_box("Confirm", "Delete this file?", "yesno")
if result == "yes" {
  print("user confirmed")
}

style is optional and defaults to "ok"; use the "info", "warning", or "error" icon styles for plain notifications:

use plugin winapi::{message_box}

message_box("Done", "Export finished successfully.", "info")

Reads a system metric by name. Accepted names include "screen_width" ("cx_screen"), "screen_height" ("cy_screen"), "mouse_buttons", "monitors", "virtual_screen_x", "virtual_screen_y", "virtual_screen_width", and "virtual_screen_height". An unknown name raises an error.

use plugin winapi::{get_system_metrics}

let w = get_system_metrics("screen_width")
let h = get_system_metrics("screen_height")
print("screen: {w}x{h}")

Ask how many physical monitors and mouse buttons are present:

use plugin winapi::{get_system_metrics}

print("monitors: {get_system_metrics("monitors")}")
print("mouse buttons: {get_system_metrics("mouse_buttons")}")

Returns the HWND (as integer) of the first window matching the given class name and/or title. Returns nil if not found.

use plugin winapi::{find_window}

let hwnd = find_window("Notepad", "")
if hwnd != nil {
  print("Notepad HWND: {hwnd}")
}

Returns the current process ID.

Returns the machine's hostname from COMPUTERNAME or HOSTNAME environment variables.

Returns the current user's login name from USERNAME or USER environment variables.

Reads an environment variable by name. Returns nil if not set.

Sets an environment variable for the current process.

Returns the MIME type string for a file extension (with or without the leading .), e.g. ".png" → "image/png".

Returns milliseconds elapsed since the system started (from GetTickCount64 on Windows, 0 on other platforms).

Pauses the current thread for the specified number of milliseconds.

Returns the path to the current desktop wallpaper. Windows-only; returns nil on other platforms.

Sets the desktop wallpaper to the image at path. Windows-only.

use plugin winapi::{set_wallpaper, known_folder_path}

let pics = known_folder_path("pictures")
set_wallpaper("{pics}\\background.jpg")

Returns the HWND of the Progman shell window, which hosts the desktop icon layer. Returns nil if not found.

Finds the WorkerW window that sits below the desktop icons. Used when embedding custom content behind desktop icons. Windows-only.

Sends the magic 0x052C message to Progman to create the WorkerW desktop layer and returns its HWND. Windows-only.

use plugin winapi::{spawn_worker_w, set_window_parent}

let worker = spawn_worker_w()
set_window_parent(my_hwnd, worker)

Calls SetParent to re-parent child HWND under parent HWND. Returns the previous parent HWND. Windows-only.

Moves and resizes the window at hwnd. Windows-only.

Modifies the GWL_STYLE flags of a window by ORing in add and ANDing out remove. Returns the new style value. Windows-only.

use plugin winapi::{set_window_style, consts}

let c = consts()
// Make a window a borderless popup.
set_window_style(my_hwnd, c["WS_POPUP"], 0)

Modifies the GWL_EXSTYLE (extended style) flags of a window. Windows-only.

use plugin winapi::{set_window_ex_style, consts}

let c = consts()
// Hide a tool window from the Alt+Tab list and stop it from stealing focus.
set_window_ex_style(my_hwnd, c["WS_EX_TOOLWINDOW"], c["WS_EX_APPWINDOW"])

Shows or hides the SHELLDLL_DefView desktop icon layer. Pass true to show, false to hide. Windows-only.

Returns the usable desktop area (excluding taskbar) as {x, y, w, h}. Windows-only.

Returns the bounding rectangle of the entire virtual screen (all monitors combined). Windows-only.

Returns a table of monitor descriptors, each with x, y, w, h, is_primary, dpi, and name fields.

use plugin winapi::{enum_monitors}

let monitors = enum_monitors()
print("monitors: {#monitors}")

Returns a table of all HWND integers belonging to the given process ID.

use plugin winapi::{get_process_id, enum_windows_for_pid}

let hwnds = enum_windows_for_pid(get_process_id())
print("this process owns {#hwnds} windows")

Returns a table of common WinAPI constant values for use with set_window_style and set_window_ex_style. Includes the extended-style flags WS_EX_TOOLWINDOW, WS_EX_NOACTIVATE, WS_EX_APPWINDOW, WS_EX_TRANSPARENT, WS_EX_LAYERED, the window styles WS_POPUP and WS_VISIBLE, and the Z-order placement handles HWND_TOP, HWND_BOTTOM, HWND_TOPMOST, and HWND_NOTOPMOST.

use plugin winapi::{consts}

let c = consts()
print("WS_EX_LAYERED = {c["WS_EX_LAYERED"]}")
print("HWND_TOPMOST  = {c["HWND_TOPMOST"]}")