Builtin signatures
Every builtin, grouped by area. Each line shows the parameter names and kinds, in order, and the kind returned. Simple marks the builtins the config UI's Simple mode offers. Examples filters the example library down to scripts that call that builtin. The editor's autocomplete tooltip shows the same signatures.
AutoHotkey
AutoHotkeyExecuteScript
AutoHotkeyExecuteScript(script: Text) → Integer · Simple
Runs AutoHotkey v2 code with the AutoHotkey program set in the settings and waits until it exits. The trigger's context is passed in as variables, and output lines are printed with an AHK: prefix.
Parameters
script: Text— The AutoHotkey v2 script text to run. Stopping the action ends the AutoHotkey process.
Returns
The AutoHotkey exit code, or -1 if AutoHotkey support is turned off, its program path is not set or not found, or the program failed to start.
1 example: Hand off to AutoHotkey
Capture
CaptureSaveRegion
CaptureSaveRegion(fileName: Text, x: Integer, y: Integer, width: Integer, height: Integer) → Bool
Captures a rectangle of the screen and saves it as an image file. First removes this app's own gesture trail and hint from the screen, waiting up to 250 milliseconds for that.
Parameters
fileName: Text— Path of the image file to write. Its extension (.bmp, .png, .jpg or .jpeg) picks the format. An existing file is overwritten; missing folders are not created.x: Integer— Left edge of the rectangle, in screen pixels.y: Integer— Top edge of the rectangle, in screen pixels.width: Integer— Width of the rectangle, in pixels. Must be greater than 0.height: Integer— Height of the rectangle, in pixels. Must be greater than 0.
Returns
true if the image file was written; false if width or height is not positive, the capture failed, or the file could not be written. A fileName not ending in .bmp, .png, .jpg or .jpeg stops the script with an error.
1 example: Screenshot the area you circled
CaptureShowImage
CaptureShowImage(fileName: Text) → Bool
Shows an image file at its native size in a borderless, always-on-top preview window, centered on the monitor under the cursor. Drag to move it, double-click to close it, right-click for Copy, Save and Close.
Parameters
fileName: Text— Path of the .bmp, .png, .jpg or .jpeg file to show.
Returns
true if the image loaded and its preview window is opening; false if the file is missing or is not a readable image. A fileName not ending in .bmp, .png, .jpg or .jpeg stops the script with an error.
CaptureShowRegion
CaptureShowRegion(x: Integer, y: Integer, width: Integer, height: Integer) → Bool
Captures a rectangle of the screen and shows the copy in a borderless, always-on-top preview window placed exactly over that area. First removes this app's own gesture trail and hint, waiting up to 250 milliseconds.
Parameters
x: Integer— Left edge of the rectangle, in screen pixels.y: Integer— Top edge of the rectangle, in screen pixels.width: Integer— Width of the rectangle, in pixels. Must be greater than 0.height: Integer— Height of the rectangle, in pixels. Must be greater than 0.
Returns
true if the capture succeeded and its preview window is opening; false if width or height is not positive or the screen could not be captured.
Clipboard
ClipboardClear
ClipboardClear() → Bool
Empties the clipboard, removing text, images and every other format, without putting anything new on it.
Parameters
No parameters.
Returns
true if the clipboard was emptied; false if another program kept the clipboard busy.
1 example: Uppercase the selected text
ClipboardCopySelection
ClipboardCopySelection(timeoutMs: Integer) → Text · Simple
Sends Ctrl+C to the active window and returns the copied text, waiting first for Ctrl, Shift, Alt and Windows keys to be released. The copy replaces the clipboard; use ClipboardSave and ClipboardRestore to keep it.
Parameters
timeoutMs: Integer— Total time to wait for the keys to be released and for the copy to arrive, in milliseconds, from 0 to 60000. Larger values count as 60000. 1000 suits most programs.
Returns
The copied text, or empty text if the keys stayed held, nothing was copied (no selection) or the copy holds no text before timeoutMs runs out.
1 example: Search the web for the selected text
ClipboardGetHtml
ClipboardGetHtml() → Text
Returns the HTML on the clipboard, such as what a browser puts there when you copy part of a web page.
Parameters
No parameters.
Returns
The copied HTML fragment without the clipboard's HTML header, or empty text if the clipboard holds no HTML or is busy.
ClipboardGetRtf
ClipboardGetRtf() → Text
Returns the rich text (RTF) on the clipboard, such as what a word processor puts there when you copy formatted text.
Parameters
No parameters.
Returns
The RTF markup as text, or empty text if the clipboard holds no RTF or is busy.
ClipboardGetSequenceNumber
ClipboardGetSequenceNumber() → Integer
Returns a number Windows changes every time the clipboard contents change. Read it before something that should copy, then compare to know the copy has landed.
Parameters
No parameters.
Returns
The current clipboard sequence number. Only a change in the number is meaningful, not the value itself.
ClipboardGetText
ClipboardGetText() → Text · Simple
Returns the plain text currently on the clipboard. Formatting, images and files on the clipboard are ignored.
Parameters
No parameters.
Returns
The clipboard text, or empty text if the clipboard holds no text or another program kept it busy.
6 examples: Pull a value out of copied text with a regex, Count words on the clipboard, Join clipboard lines into one line, Today's date, and a timestamped file name, Uppercase the selected text, Search the web for the selection
ClipboardLoadImage
ClipboardLoadImage(path: Text) → Bool
Loads an image file and puts it on the clipboard, replacing the current contents, ready to paste into other programs. Transparent areas of a PNG become white.
Parameters
path: Text— Full path of the image file, ending in .bmp, .png, .jpg or .jpeg. Any other extension stops the script with an error.
Returns
true if the image is on the clipboard; false if the file is missing, is not a readable image, or the clipboard is busy.
ClipboardPasteReplacementText
ClipboardPasteReplacementText(text: Text) → Bool · Simple
Puts text on the clipboard and sends Ctrl+V to paste it into the active window. Does not wait for the paste to land, so wait briefly with UtilityWait before ClipboardRestore.
Parameters
text: Text— The text to paste.
Returns
true if the clipboard was set and Ctrl+V was sent; false if the clipboard was busy or Windows blocked the keystrokes.
2 examples: Fill a template and paste it, Uppercase the selected text
ClipboardRestore
ClipboardRestore() → Bool
Puts back the clipboard contents saved by the last ClipboardSave in this script run, in every format. Without an earlier ClipboardSave in this run, it empties the clipboard.
Parameters
No parameters.
Returns
true if everything saved was put back; false if the clipboard was busy or a format could not be restored.
5 examples: Fill a template and paste it, Search the web for the selected text, Uppercase the selected text, Search the web for the selection, Let only one action run a section at a time
ClipboardSave
ClipboardSave() → Bool
Saves a copy of everything on the clipboard, in every format, so ClipboardRestore can put it back later in the same script run. A second call replaces the saved copy.
Parameters
No parameters.
Returns
true if the clipboard was read; false if another program kept it busy.
5 examples: Fill a template and paste it, Search the web for the selected text, Uppercase the selected text, Search the web for the selection, Let only one action run a section at a time
ClipboardSaveImage
ClipboardSaveImage(path: Text) → Bool
Saves the image on the clipboard to a file, in the format the file extension names, such as a screenshot taken with Print Screen. An existing file is overwritten.
Parameters
path: Text— Full path of the file to write, ending in .bmp, .png, .jpg or .jpeg. Any other extension stops the script with an error.
Returns
true if the file was written; false if the clipboard holds no image or the file could not be written.
1 example: Save a copied image to a file
ClipboardSetHtml
ClipboardSetHtml(html: Text) → Bool
Puts an HTML fragment on the clipboard, replacing the current contents, so pasting into an email or word processor keeps the formatting. A plain-text copy with the tags removed is added too, for programs that only paste text.
Parameters
html: Text— The HTML fragment to place, such as <b>bold</b> text. Do not add the clipboard's HTML header; it is added for you.
Returns
true if the HTML and its plain-text copy were placed on the clipboard; false if the clipboard was busy.
ClipboardSetRtf
ClipboardSetRtf(rtf: Text) → Bool
Puts rich text (RTF) on the clipboard, replacing the current contents, so pasting into WordPad, Word or Outlook keeps the formatting. A plain-text copy of the words is added too, for programs that only paste text.
Parameters
rtf: Text— A complete RTF document as text. Any character can be typed directly; characters outside plain ASCII are written as RTF Unicode escapes for you.
Returns
true if the RTF and its plain-text copy were placed on the clipboard; false if the clipboard was busy.
ClipboardSetText
ClipboardSetText(text: Text) → Bool · Simple
Puts text on the clipboard, replacing whatever is there, ready to paste into any program.
Parameters
text: Text— The text to place on the clipboard.
Returns
true if the text was placed on the clipboard; false if another program kept the clipboard busy.
2 examples: Pull a value out of copied text with a regex, Join clipboard lines into one line
Context
ContextGetActionName
ContextGetActionName() → Text
Returns the name of the action that is running. A global event returns Global_Event_ followed by the event's id, such as Global_Event_release.
Parameters
No parameters.
Returns
The action's name, a Global_Event_ name for a global event, or empty text in a timer, folder watch or serial monitor script.
1 example: Everything the trigger context knows
ContextGetApplicationName
ContextGetApplicationName() → Text
Returns the name of the application group whose action is running, for an action triggered by a gesture, hotkey or text expansion.
Parameters
No parameters.
Returns
The application group's name (usually Global for the global group), or empty text for a global event, timer, folder watch or serial monitor script.
4 examples: Fill a template and paste it, Everything the trigger context knows, Let an unrecognized drawing through, Append to a log file
ContextGetBoundingBoxHeight
ContextGetBoundingBoxHeight() → Integer
Returns the height of the rectangle around the whole drawn gesture, in pixels. Outside a gesture this returns 0.
Parameters
No parameters.
Returns
The height in pixels, or 0 outside a gesture.
2 examples: Everything the trigger context knows, Screenshot the area you circled
ContextGetBoundingBoxWidth
ContextGetBoundingBoxWidth() → Integer
Returns the width of the rectangle around the whole drawn gesture, in pixels. Outside a gesture this returns 0.
Parameters
No parameters.
Returns
The width in pixels, or 0 outside a gesture.
2 examples: Everything the trigger context knows, Screenshot the area you circled
ContextGetBoundingBoxX
ContextGetBoundingBoxX() → Integer
Returns the left edge of the rectangle around the whole drawn gesture, in virtual-screen pixels. Outside a gesture this returns 0.
Parameters
No parameters.
Returns
The left edge in virtual-screen pixels, or 0 outside a gesture.
2 examples: Everything the trigger context knows, Screenshot the area you circled
ContextGetBoundingBoxY
ContextGetBoundingBoxY() → Integer
Returns the top edge of the rectangle around the whole drawn gesture, in virtual-screen pixels. Outside a gesture this returns 0.
Parameters
No parameters.
Returns
The top edge in virtual-screen pixels, or 0 outside a gesture.
2 examples: Everything the trigger context knows, Screenshot the area you circled
ContextGetButtonState
ContextGetButtonState() → Text
Returns whether a global mouse-button event fired on the button press or on its release. Only a global mouse-button event's script gets a value.
Parameters
No parameters.
Returns
'down' for the press, 'up' for the release, or empty text for any other trigger, including a gesture.
ContextGetControl
ContextGetControl() → Window
Returns the exact control the trigger was aimed at, such as an edit box under the gesture or mouse, or the window focused for a hotkey or text expansion. Use ContextGetWindow for its application window.
Parameters
No parameters.
Returns
The control as a Window, or a null window when the trigger has no window, as in a timer, folder watch, serial monitor or Load script.
ContextGetGestureName
ContextGetGestureName() → Text
Returns the name of the gesture that was drawn to run this action. This is the gesture's own name, not the action's; see ContextGetActionName.
Parameters
No parameters.
Returns
The gesture's name, or empty text outside a gesture.
2 examples: Everything the trigger context knows, Append to a log file
ContextGetPointCount
ContextGetPointCount() → Integer
Returns how many cursor positions were recorded along the drawn gesture. Read each one with ContextGetPointX and ContextGetPointY.
Parameters
No parameters.
Returns
The number of points, or 0 outside a gesture.
3 examples: Length of a gesture stroke, Everything the trigger context knows, Which way did the stroke go?
ContextGetPointX
ContextGetPointX(index: Integer) → Integer
Returns the horizontal screen position of one recorded point of the drawn gesture, in virtual-screen pixels.
Parameters
index: Integer— Zero-based point number, from 0 to ContextGetPointCount() minus 1. Point 0 is where the gesture started.
Returns
The x coordinate, or 0 if index is out of range or the action was not triggered by a gesture.
2 examples: Length of a gesture stroke, Which way did the stroke go?
ContextGetPointY
ContextGetPointY(index: Integer) → Integer
Returns the vertical screen position of one recorded point of the drawn gesture, in virtual-screen pixels.
Parameters
index: Integer— Zero-based point number, from 0 to ContextGetPointCount() minus 1. Point 0 is where the gesture started.
Returns
The y coordinate, or 0 if index is out of range or the action was not triggered by a gesture.
2 examples: Length of a gesture stroke, Which way did the stroke go?
ContextGetSerialMonitorName
ContextGetSerialMonitorName() → Text
Returns the name of the serial monitor whose received line started this script, as given to SerialMonitorCreate. Only a serial monitor's script gets a value.
Parameters
No parameters.
Returns
The monitor's name, or empty text for any other trigger.
ContextGetSerialPortName
ContextGetSerialPortName() → Text
Returns the COM port, such as COM3, that the received line arrived on. Only a serial monitor's script gets a value.
Parameters
No parameters.
Returns
The port name, or empty text for any other trigger.
ContextGetSerialTextLine
ContextGetSerialTextLine() → Text
Returns the line of text that arrived on the serial port and started this script, such as a sensor reading an Arduino sent with Serial.println. The line ending is removed.
Parameters
No parameters.
Returns
The received line without its terminator, or empty text for any other trigger.
2 examples: Map a serial device's buttons to media keys, Turn an Arduino knob into a volume control
ContextGetStrokeButton
ContextGetStrokeButton() → Integer
Returns the mouse button that drew the gesture, or that fired a global mouse-button event, as a MouseButton constant: MouseButton.Primary or MouseButton.Secondary for the buttons Windows treats as a left and a right click, after any primary/secondary swap, otherwise MouseButton.Middle, MouseButton.X1 or MouseButton.X2. Pass it to MouseClick or MouseButtonDown to press the same button.
Parameters
No parameters.
Returns
A MouseButton value such as MouseButton.Secondary, or -1 for any other trigger.
2 examples: Everything the trigger context knows, Branch on the stroke button
ContextGetWatchAction
ContextGetWatchAction() → Text
Returns what happened in the watched folder to start this script: 'created', 'deleted', 'modified', 'renamed-old-name', 'renamed-new-name' or 'overflow'.
Parameters
No parameters.
Returns
The kind of change, or empty text for any other trigger. 'overflow' means too many changes arrived at once and the folder must be checked again.
1 example: Watch a folder
ContextGetWatchName
ContextGetWatchName() → Text
Returns the name of the folder watch that started this script, as given to FolderWatchCreate. Only a folder watch's script gets a value.
Parameters
No parameters.
Returns
The watch's name, or empty text for any other trigger.
ContextGetWatchPath
ContextGetWatchPath() → Text
Returns the path of the file or folder that changed and started this folder watch script, relative to the watched folder.
Parameters
No parameters.
Returns
The changed item's path relative to the watched folder, or empty text for an 'overflow' change or any other trigger.
1 example: Watch a folder
ContextGetWindow
ContextGetWindow() → Window
Returns the application window the trigger was aimed at: the top-level window around the control under the gesture or mouse, or around the focused control for a hotkey or text expansion.
Parameters
No parameters.
Returns
The window, or a null window when the trigger has no window, as in a timer, folder watch, serial monitor or Load script.
16 examples: One gesture, several choices, Toggle maximize for the gesture's window, Pin a window on top, Cycle window transparency, Snap a window into a 3×2 grid cell under the cursor, Throw a window to the next monitor, Remember and restore a window's position, Inspect a window's child controls, Hide a window in the tray, Everything the trigger context knows, Branch on the stroke button, Confine the cursor to a window for 5 seconds, Change behavior while Ctrl is held, A list kept in Storage, Send a window to a specific monitor, Snippets as reusable functions
ContextRelayGesture
ContextRelayGesture() → Bool
Replays the drawn gesture as a real mouse drag with the same button along the same path, so the application underneath receives it, for example to select text. Real input is held back during the drag.
Parameters
No parameters.
Returns
true if the whole drag was sent; false outside a gesture or if Windows rejected part of the input.
1 example: Let an unrecognized drawing through
DateTime
DateTimeFormat
DateTimeFormat(iso: Text, style: Integer) → Text · Simple
Formats a date and time as readable text in the user's regional format, or as a sortable FileStamp. A time with Z or a UTC offset is converted to local time first.
Parameters
iso: Text— A date and time in ISO 8601 form, as DateTimeGetNow returns it (2026-10-05T14:05:09-04:00). A date alone means midnight; without Z or an offset it is taken as local time. Years 1601 to 9999.style: Integer— A DateTimeStyle constant, such as DateTimeStyle.ShortDate, DateTimeStyle.LongDateTime or DateTimeStyle.FileStamp. Any other value stops the action with an error.
Returns
The formatted text, such as 20261005-140509 for DateTimeStyle.FileStamp, or empty text if iso is empty. Text that is not ISO 8601 stops the action with an error.
1 example: Today's date, and a timestamped file name
DateTimeGetNow
DateTimeGetNow() → Text · Simple
Returns the current local date and time as ISO 8601 text, to the second, with the UTC offset. Pass it to DateTimeFormat or DateTimeGetPart.
Parameters
No parameters.
Returns
Text such as 2026-10-05T14:05:09-04:00, or empty text if Windows cannot report the time zone.
1 example: Today's date, and a timestamped file name
DateTimeGetPart
DateTimeGetPart(iso: Text, part: Integer) → Integer
Returns one part of a date and time as a number: the year, month, day, hour, minute, second or weekday, in local time.
Parameters
iso: Text— A date and time in ISO 8601 form, as DateTimeGetNow returns it. A time with Z or a UTC offset is converted to local time; without one it is taken as local time.part: Integer— A DateTimePart constant, such as DateTimePart.Hour or DateTimePart.Weekday. Any other value stops the action with an error.
Returns
The part's value: month 1 to 12, hour 0 to 23, weekday 1 (Monday) to 7 (Sunday). -1 if iso is empty. Text that is not ISO 8601 stops the action with an error.
1 example: Today's date, and a timestamped file name
Display
DisplayGetMonitorDpiFromPoint
DisplayGetMonitorDpiFromPoint(x: Integer, y: Integer) → Integer
Returns the DPI Windows currently uses for the monitor containing a screen point. A point off every monitor uses the nearest monitor.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.
Returns
The DPI, such as 96 at 100 percent scaling or 144 at 150 percent. If Windows cannot report it, the system DPI.
DisplayGetPixelColorFromPoint
DisplayGetPixelColorFromPoint(x: Integer, y: Integer) → Integer
Returns the color of the screen pixel at a point, as currently shown on the monitor.
Parameters
x: Integer— Horizontal screen position of the pixel, in pixels.y: Integer— Vertical screen position of the pixel, in pixels.
Returns
The color as an Integer packed as 0xRRGGBB (red in the highest byte, blue in the lowest), or -1 if the point is off every monitor or the screen cannot be read.
1 example: Read the pixel color under the cursor
DisplayMonitorEnumeratedAll
DisplayMonitorEnumeratedAll() → Integer
Takes a snapshot of every connected monitor, ordered left to right then top to bottom, for the DisplayMonitorGetEnumerated builtins to read by index. Call it again after monitors change.
Parameters
No parameters.
Returns
The number of monitors in the snapshot. Valid indexes run from 0 to this number minus 1.
2 examples: List monitors, Send a window to a specific monitor
DisplayMonitorExistsByName
DisplayMonitorExistsByName(name: Text) → Bool
Checks whether a monitor saved by name is connected right now. Use it before the FromName rectangle builtins, which return 0 both for a missing monitor and for a real 0 coordinate.
Parameters
name: Text— A monitor device path (the reliable choice, from DisplayMonitorGetDevicePathFromPoint) or a model name such as DELL U2720Q. Not case-sensitive; an exact device path match wins over a model name.
Returns
true if a connected monitor matches the name; false if none does or name is empty.
DisplayMonitorGetDevicePathFromPoint
DisplayMonitorGetDevicePathFromPoint(x: Integer, y: Integer) → Text
Returns the device path of the monitor containing a screen point: a unique name to save and later pass to the FromName builtins. It changes if the monitor is moved to another video port.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.
Returns
The device path, or empty text if Windows cannot identify the monitor. A point off every monitor uses the nearest monitor.
DisplayMonitorGetEnumeratedDevicePathAt
DisplayMonitorGetEnumeratedDevicePathAt(index: Integer) → Text
Returns the device path, a unique name to save, of a monitor in the last DisplayMonitorEnumeratedAll snapshot.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).
Returns
The device path, or empty text if index is out of range or the monitors changed since the snapshot.
DisplayMonitorGetEnumeratedDpiAt
DisplayMonitorGetEnumeratedDpiAt(index: Integer) → Integer
Returns the DPI of a monitor in the last DisplayMonitorEnumeratedAll snapshot, as it was when the snapshot was taken.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).
Returns
The DPI, such as 96 at 100 percent scaling or 144 at 150 percent, or 0 if index is out of range.
1 example: List monitors
DisplayMonitorGetEnumeratedFriendlyNameAt
DisplayMonitorGetEnumeratedFriendlyNameAt(index: Integer) → Text
Returns the model name a monitor reports, such as DELL U2720Q, for a monitor in the last DisplayMonitorEnumeratedAll snapshot. Two identical monitors report the same name.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).
Returns
The model name, or empty text if index is out of range, the monitor reports no name (common for built-in laptop screens), or the monitors changed since the snapshot.
1 example: List monitors
DisplayMonitorGetEnumeratedHeightAt
DisplayMonitorGetEnumeratedHeightAt(index: Integer, workArea: Bool) → Integer
Returns the height of a monitor in the last DisplayMonitorEnumeratedAll snapshot, either its full area or its work area, as it was when the snapshot was taken.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The height in pixels, or 0 if index is out of range.
1 example: List monitors
DisplayMonitorGetEnumeratedWidthAt
DisplayMonitorGetEnumeratedWidthAt(index: Integer, workArea: Bool) → Integer
Returns the width of a monitor in the last DisplayMonitorEnumeratedAll snapshot, either its full area or its work area, as it was when the snapshot was taken.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The width in pixels, or 0 if index is out of range.
1 example: List monitors
DisplayMonitorGetEnumeratedXAt
DisplayMonitorGetEnumeratedXAt(index: Integer, workArea: Bool) → Integer
Returns the left edge of a monitor in the last DisplayMonitorEnumeratedAll snapshot, either of its full area or of its work area, as it was when the snapshot was taken.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The left edge in screen pixels (negative for a monitor left of the primary one), or 0 if index is out of range. 0 is also a real edge, so check index against the monitor count.
DisplayMonitorGetEnumeratedYAt
DisplayMonitorGetEnumeratedYAt(index: Integer, workArea: Bool) → Integer
Returns the top edge of a monitor in the last DisplayMonitorEnumeratedAll snapshot, either of its full area or of its work area, as it was when the snapshot was taken.
Parameters
index: Integer— Zero-based position of the monitor in the last DisplayMonitorEnumeratedAll snapshot (left to right, then top to bottom).workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The top edge in screen pixels (negative for a monitor above the primary one), or 0 if index is out of range. 0 is also a real edge, so check index against the monitor count.
DisplayMonitorGetFriendlyNameFromPoint
DisplayMonitorGetFriendlyNameFromPoint(x: Integer, y: Integer) → Text
Returns the model name, such as DELL U2720Q, of the monitor containing a screen point. Readable but not unique: two identical monitors report the same name.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.
Returns
The model name, or empty text if the monitor reports none (common for built-in laptop screens). A point off every monitor uses the nearest monitor.
DisplayMonitorGetRectHeightFromName
DisplayMonitorGetRectHeightFromName(name: Text, workArea: Bool) → Integer
Returns the height of a connected monitor found by its saved device path or model name, either its full area or its work area.
Parameters
name: Text— A monitor device path (the reliable choice) or a model name such as DELL U2720Q. Not case-sensitive; an exact device path match wins over a model name.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The height in pixels, or 0 if no connected monitor matches the name.
DisplayMonitorGetRectHeightFromPoint
DisplayMonitorGetRectHeightFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer
Returns the height of the monitor containing a screen point, either its full area or its work area. A point off every monitor uses the nearest monitor.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The height in pixels.
2 examples: Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
DisplayMonitorGetRectWidthFromName
DisplayMonitorGetRectWidthFromName(name: Text, workArea: Bool) → Integer
Returns the width of a connected monitor found by its saved device path or model name, either its full area or its work area.
Parameters
name: Text— A monitor device path (the reliable choice) or a model name such as DELL U2720Q. Not case-sensitive; an exact device path match wins over a model name.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The width in pixels, or 0 if no connected monitor matches the name.
DisplayMonitorGetRectWidthFromPoint
DisplayMonitorGetRectWidthFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer
Returns the width of the monitor containing a screen point, either its full area or its work area. A point off every monitor uses the nearest monitor.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The width in pixels.
3 examples: else-if chain, Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
DisplayMonitorGetRectXFromName
DisplayMonitorGetRectXFromName(name: Text, workArea: Bool) → Integer
Returns the left edge of a connected monitor found by its saved device path or model name, either of its full area or of its work area.
Parameters
name: Text— A monitor device path (the reliable choice) or a model name such as DELL U2720Q. Not case-sensitive; an exact device path match wins over a model name.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The left edge in screen pixels, or 0 if no connected monitor matches the name. 0 is also a real edge, so check DisplayMonitorExistsByName first.
DisplayMonitorGetRectXFromPoint
DisplayMonitorGetRectXFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer
Returns the left edge of the monitor containing a screen point, either of its full area or of its work area. A point off every monitor uses the nearest monitor.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The left edge in screen pixels; negative for a monitor left of the primary one.
3 examples: else-if chain, Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
DisplayMonitorGetRectYFromName
DisplayMonitorGetRectYFromName(name: Text, workArea: Bool) → Integer
Returns the top edge of a connected monitor found by its saved device path or model name, either of its full area or of its work area.
Parameters
name: Text— A monitor device path (the reliable choice) or a model name such as DELL U2720Q. Not case-sensitive; an exact device path match wins over a model name.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The top edge in screen pixels, or 0 if no connected monitor matches the name. 0 is also a real edge, so check DisplayMonitorExistsByName first.
DisplayMonitorGetRectYFromPoint
DisplayMonitorGetRectYFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer
Returns the top edge of the monitor containing a screen point, either of its full area or of its work area. A point off every monitor uses the nearest monitor.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.workArea: Bool— true for the work area, which excludes the taskbar and docked toolbars; false for the full monitor.
Returns
The top edge in screen pixels; negative for a monitor above the primary one.
2 examples: Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
Engine
EngineConsumePhysicalInput
EngineConsumePhysicalInput(enable: Bool, timeoutSeconds: Integer) → Bool
Stops the user's real mouse and keyboard input from reaching any window, or ends that block. Input sent by scripts still works, and the block ends on its own after the timeout.
Parameters
enable: Bool— true to start or restart blocking real input; false to end the block, whichever script started it.timeoutSeconds: Integer— The longest the block lasts, in seconds; 1 or more when enable is true. Longer values are shortened to the maximum on the Scripts settings page (120 seconds by default). Ignored when enable is false.
Returns
Always true. With enable set to true, a timeoutSeconds of 0 or less stops the script with an error.
EngineDisable
EngineDisable() → Bool · Simple
Disables the engine, the same as disabling it from the tray icon, until EngineEnable or the tray turns it back on. The change happens just after the call returns. Does nothing in Safe Mode.
Parameters
No parameters.
Returns
true if the request was sent; false if the engine has not finished starting.
1 example: Engine state
EngineDisableNextGesture
EngineDisableNextGesture() → Bool · Simple
Lets the next press of a draw button pass straight through to the application instead of starting a gesture, one time only. Has no effect while the engine is disabled.
Parameters
No parameters.
Returns
Always true.
1 example: Let the next right-drag through
EngineEnable
EngineEnable() → Bool · Simple
Enables the engine again after EngineDisable or a disable from the tray icon. The change happens just after the call returns. Does nothing in Safe Mode.
Parameters
No parameters.
Returns
true if the request was sent; false if the engine has not finished starting.
EngineExit
EngineExit() → Bool · Simple
Closes the engine with a normal shutdown, the same as Exit on the tray menu: windows hidden in the tray are restored and the config UI closes. The shutdown starts just after the call returns.
Parameters
No parameters.
Returns
true if the shutdown request was sent; false if the engine has not finished starting.
EngineIsDisabled
EngineIsDisabled() → Bool
Returns whether the engine is disabled now, either by EngineDisable or the tray icon, or automatically for the focused application.
Parameters
No parameters.
Returns
true if the engine is disabled; false if it is active.
1 example: Engine state
EngineIsSafeMode
EngineIsSafeMode() → Bool
Returns whether the engine was started in Safe Mode. In Safe Mode only scripts run from the diagnostic console can run.
Parameters
No parameters.
Returns
true in Safe Mode; otherwise false.
1 example: Engine state
EngineReload
EngineReload() → Bool · Simple
Reloads the configuration from disk without a restart, like Reload Config on the tray menu. Waits up to 3 seconds. Every other running script is stopped; this one continues.
Parameters
No parameters.
Returns
true once the new configuration is in use; false if it could not be loaded or the reload took longer than 3 seconds.
EngineStopAllActions
EngineStopAllActions() → Bool · Simple
Asks every running action and script to stop, including the one that calls it. Nothing is killed: each script stops at its next step, so the caller may run a little further first.
Parameters
No parameters.
Returns
Always true.
File
FileAppendText
FileAppendText(path: Text, text: Text) → Bool
Adds text to the end of a text file, creating the file if it does not exist. Handy for logs. The text is written as UTF-8 and no line break is added for you.
Parameters
path: Text— Full path of the file. Its folder must already exist.text: Text— The text to add. End it with '\n' to keep one entry per line.
Returns
true if the text was written; false if the folder does not exist, the file is locked, or the start of the existing file looks like binary data.
1 example: Append to a log file
FileCopy
FileCopy(source: Text, destination: Text, overwrite: Bool) → Bool
Copies a file of any type to a new path. The destination folder must already exist.
Parameters
source: Text— Full path of the file to copy.destination: Text— Full path of the new copy, including its file name.overwrite: Bool— true to replace an existing file at destination; false to leave it alone and return false.
Returns
true if the file was copied; false if the source is missing, the destination exists and overwrite is false, or the copy failed.
1 example: Back up a file before editing it
FileCreate
FileCreate(path: Text, text: Text) → Bool
Creates a new text file with the given content, written as UTF-8. Refuses if anything already exists at that path; use FileEditText to replace an existing file's content.
Parameters
path: Text— Full path of the new file. Its folder must already exist.text: Text— The file's content. Empty text creates an empty file.
Returns
true if the file was created; false if a file or folder already exists there, or the file could not be written.
2 examples: Today's date, and a timestamped file name, Append to a log file
FileDelete
FileDelete(path: Text) → Bool
Deletes a file permanently; it does not go to the Recycle Bin. A file that is already gone counts as success. A folder is never deleted; use FolderDelete for that.
Parameters
path: Text— Full path of the file to delete.
Returns
true if the file is gone, including when it never existed; false if the path is a folder, or the file is locked or access is denied.
FileEditText
FileEditText(path: Text, text: Text) → Bool
Replaces the entire content of an existing text file, written as UTF-8. Refuses a file that looks like binary data. Use FileCreate for a new file.
Parameters
path: Text— Full path of an existing text file.text: Text— The new content, replacing everything in the file.
Returns
true if the file was rewritten; false if it does not exist, the start of it looks like binary data, or it could not be written.
1 example: Back up a file before editing it
FileExists
FileExists(path: Text) → Bool
Checks whether a file exists at a path. A folder at that path does not count; use FolderExists for folders.
Parameters
path: Text— Full path of the file to check.
Returns
true if a file exists there; false if nothing does, or it is a folder.
2 examples: Append to a log file, Back up a file before editing it
FileGetCreationDate
FileGetCreationDate(path: Text) → Text
Returns when a file was created, as an ISO 8601 date and time in UTC that DateTimeFormat and the other DateTime builtins can read.
Parameters
path: Text— Full path of the file.
Returns
The creation time, such as 2026-10-01T18:05:09Z, or empty text if the file does not exist or the path is a folder.
FileGetModifiedDate
FileGetModifiedDate(path: Text) → Text
Returns when a file's content was last changed, as an ISO 8601 date and time in UTC that DateTimeFormat and the other DateTime builtins can read.
Parameters
path: Text— Full path of the file.
Returns
The last-modified time, such as 2026-10-01T18:05:09Z, or empty text if the file does not exist or the path is a folder.
1 example: Read a file and count its lines
FileGetProductVersion
FileGetProductVersion(path: Text) → Text
Returns the product version stored in a program or library file, such as an .exe or .dll. This is the version of the product the file ships with, which can differ from FileGetVersion.
Parameters
path: Text— Full path of the .exe, .dll or other file with version information.
Returns
The version as four numbers, such as 10.0.22621.1, or empty text if the file has no version information or does not exist.
FileGetSize
FileGetSize(path: Text) → Integer
Returns the size of a file in bytes, without opening or reading the file.
Parameters
path: Text— Full path of the file.
Returns
The size in bytes, or -1 if the file does not exist or the path is a folder.
1 example: Read a file and count its lines
FileGetVersion
FileGetVersion(path: Text) → Text
Returns the file version stored in a program or library file, such as an .exe or .dll, as shown on the Details tab of its Properties.
Parameters
path: Text— Full path of the .exe, .dll or other file with version information.
Returns
The version as four numbers, such as 10.0.22621.1, or empty text if the file has no version information or does not exist.
FileMove
FileMove(source: Text, destination: Text, overwrite: Bool) → Bool
Moves a file of any type to a new path, which can also give it a new name, including a change of letter case only. The destination folder must already exist.
Parameters
source: Text— Full path of the file to move.destination: Text— Full path of the file's new location, including its file name.overwrite: Bool— true to replace an existing file at destination in one step; false to leave it alone and return false. A destination that differs from the source only in letter case is not an existing file.
Returns
true if the file was moved; false if the source is missing, the destination exists and overwrite is false, or the move failed.
FileReadText
FileReadText(path: Text) → Text
Reads a whole text file and returns its content. Understands UTF-8, UTF-16 with a byte order mark, and files in the system's legacy code page. Refuses binary files.
Parameters
path: Text— Full path of the text file.
Returns
The file's content, or empty text if the file does not exist, cannot be read, or looks like binary data.
2 examples: Read a file and count its lines, Back up a file before editing it
FileRename
FileRename(path: Text, newName: Text) → Bool
Renames a file and keeps it in its current folder. A change of letter case only, such as report.txt to Report.txt, works too. To move a file to another folder, use FileMove.
Parameters
path: Text— Full path of the file to rename.newName: Text— The new file name only, such as report-old.txt. A name containing a slash or backslash stops the script with an error.
Returns
true if the file was renamed; false if it does not exist, another file or folder with the new name already exists, or the rename failed.
Folder
FolderCreate
FolderCreate(path: Text) → Bool
Creates a folder, including any missing parent folders. A folder that already exists counts as success.
Parameters
path: Text— Full path of the folder to create.
Returns
true if the folder exists afterwards; false if a file is in the way or the folder could not be created.
FolderDelete
FolderDelete(path: Text, recursive: Bool) → Bool
Deletes a folder permanently; it does not go to the Recycle Bin. With recursive set to true, everything inside it is deleted too. A folder that is already gone counts as success. A file is never deleted; use FileDelete for that.
Parameters
path: Text— Full path of the folder to delete.recursive: Bool— true to delete the folder and everything inside it; false to delete it only when it is empty.
Returns
true if the folder is gone; false if the path is a file, the folder is not empty and recursive is false, or something in it is locked or protected.
FolderEnumerateAll
FolderEnumerateAll(path: Text, recursive: Bool) → Integer
Lists the files and subfolders in a folder and returns how many there are. Read each full path with FolderGetEnumeratedPathAt. Subfolders it cannot access are skipped.
Parameters
path: Text— Full path of the folder to list.recursive: Bool— true to also list everything inside all subfolders; false for the folder's direct contents only.
Returns
The number of entries found, or -1 if the folder does not exist or cannot be read.
1 example: Count file types in a folder
FolderExists
FolderExists(path: Text) → Bool
Checks whether a folder exists at a path. A file at that path does not count; use FileExists for files.
Parameters
path: Text— Full path of the folder to check.
Returns
true if a folder exists there; false if nothing does, or it is a file.
FolderGetEnumeratedPathAt
FolderGetEnumeratedPathAt(index: Integer) → Text
Returns one full path from the list made by the last FolderEnumerateAll call in this script run.
Parameters
index: Integer— Position in the list, from 0 to the count FolderEnumerateAll returned minus 1.
Returns
The full path of a file or folder, or empty text if index is out of range or FolderEnumerateAll has not been called.
1 example: Count file types in a folder
FolderRename
FolderRename(path: Text, newName: Text) → Bool
Renames a folder and keeps it, with its contents, in its current parent folder. A change of letter case only works too.
Parameters
path: Text— Full path of the folder to rename.newName: Text— The new folder name only. A name containing a slash or backslash stops the script with an error.
Returns
true if the folder was renamed; false if it does not exist, another file or folder with the new name already exists, or the rename failed, for example because a file inside is open.
FolderWatchCreate
FolderWatchCreate(name: Text, path: Text, recursive: Bool, filterMask: Integer, script: Text) → Bool
Starts watching a folder and runs a script for every change Windows reports, such as a file being created, changed, renamed or deleted. The watch keeps running after this script ends.
Parameters
name: Text— A name for the watch. Creating a watch with a name already in use replaces that watch. Names are case-sensitive.path: Text— Full path of the folder to watch.recursive: Bool— true to also watch all subfolders; false to watch the folder itself only.filterMask: Integer— Which kinds of change to report: FileNotify constants combined with |, such as FileNotify.FileName | FileNotify.LastWrite.script: Text— The script to run for each change, as Text. It reads the change with ContextGetWatchAction (created, deleted, modified, renamed-old-name, renamed-new-name or overflow) and ContextGetWatchPath.
Returns
true if the watch is running; false if the folder does not exist, cannot be opened, or filterMask is 0.
1 example: Watch a folder
FolderWatchDelete
FolderWatchDelete(name: Text) → Bool
Stops a folder watch created with FolderWatchCreate, so its script no longer runs.
Parameters
name: Text— The name given to FolderWatchCreate. Names are case-sensitive.
Returns
true if a watch with that name was found and stopped; false if there was none.
1 example: Watch a folder
FolderWatchDeleteAll
FolderWatchDeleteAll() → Bool
Stops every folder watch created with FolderWatchCreate, so none of their scripts run any more.
Parameters
No parameters.
Returns
Always true.
FolderWatchGetCount
FolderWatchGetCount() → Integer
Returns how many folder watches are running and takes a snapshot of their names for FolderWatchGetEnumeratedNameAt.
Parameters
No parameters.
Returns
The number of running folder watches, or 0 if there are none.
FolderWatchGetEnumeratedNameAt
FolderWatchGetEnumeratedNameAt(index: Integer) → Text
Returns one watch name from the snapshot taken by the last FolderWatchGetCount call in this script run.
Parameters
index: Integer— Position in the snapshot, from 0 to the count minus 1. The order has no meaning.
Returns
The watch name, or empty text if index is out of range or FolderWatchGetCount has not been called.
GestureProfile
GestureProfileEnumerateAll
GestureProfileEnumerateAll() → Integer
Takes a list of every gesture profile in the configuration and returns how many there are. Read each one with GestureProfileGetEnumeratedIdAt and GestureProfileGetEnumeratedNameAt.
Parameters
No parameters.
Returns
The number of gesture profiles, or 0 if there are none.
1 example: Cycle to the next gesture profile
GestureProfileGetActiveId
GestureProfileGetActiveId() → Text
Returns the id of the gesture profile that is active now.
Parameters
No parameters.
Returns
The active profile's id, or empty text if no profile is active.
2 examples: A Windows notification, Cycle to the next gesture profile
GestureProfileGetEnumeratedIdAt
GestureProfileGetEnumeratedIdAt(index: Integer) → Text
Returns the id of one profile from the list GestureProfileEnumerateAll last took in this script. Pass the id to GestureProfileSwitch.
Parameters
index: Integer— Zero-based position in the list, from 0 to the count minus 1.
Returns
The profile's id, or empty text if index is out of range or GestureProfileEnumerateAll has not been called.
1 example: Cycle to the next gesture profile
GestureProfileGetEnumeratedNameAt
GestureProfileGetEnumeratedNameAt(index: Integer) → Text
Returns the display name of one profile from the list GestureProfileEnumerateAll last took in this script.
Parameters
index: Integer— Zero-based position in the list, from 0 to the count minus 1.
Returns
The profile's name, or empty text if index is out of range or GestureProfileEnumerateAll has not been called.
1 example: Cycle to the next gesture profile
GestureProfileSwitch
GestureProfileSwitch(profileId: Text) → Bool · Simple
Switches to another gesture profile, the same as choosing it from the tray menu, and remembers the choice after a restart. The switch happens just after the call returns.
Parameters
profileId: Text— The id of the profile to switch to, such as one from GestureProfileGetEnumeratedIdAt, or empty text for no profile.
Returns
true if the request was sent; false for an id that no profile has, and nothing changes. The switch happens just after the call returns; use GestureProfileGetActiveId to confirm it.
1 example: Cycle to the next gesture profile
Keyboard
KeyboardGetKeyState
KeyboardGetKeyState(key: Integer) → Integer
Returns the raw Windows state of a key as it is right now. While another desktop, such as a UAC prompt or the lock screen, is in front, every key reads as up. For a plain yes or no, use KeyboardIsKeyDown or KeyboardIsKeyToggled.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.CapsLock, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
A raw Integer: negative (highest bit set) when the key is down, and odd (lowest bit set) when a lock key such as Caps Lock is switched on.
1 example: Key state bits
KeyboardGetKeyStateAsync
KeyboardGetKeyStateAsync(key: Integer) → Integer
Returns the raw Windows state of a key at this very moment, whichever window has focus.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.ShiftKey, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
A raw Integer: negative (highest bit set) when the key is down right now. The lowest bit may be set if the key was pressed since an earlier check, which Windows does not guarantee.
KeyboardIsKeyDown
KeyboardIsKeyDown(key: Integer) → Bool
Checks whether a key is held down right now. While another desktop, such as a UAC prompt or the lock screen, is in front, every key reads as up.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.ControlKey, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
true if the key is down; false if it is up.
2 examples: Key state bits, Change behavior while Ctrl is held
KeyboardIsKeyToggled
KeyboardIsKeyToggled(key: Integer) → Bool
Checks whether a lock key is switched on. Meaningful only for VirtualKey.CapsLock, VirtualKey.NumLock and VirtualKey.Scroll.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.CapsLock, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
true if the lock key is on; false if it is off.
1 example: Key state bits
KeyboardKeyDown
KeyboardKeyDown(key: Integer) → Bool
Presses a key and keeps it down until KeyboardKeyUp releases it. With the setting Send media and browser keys as commands on, a media, volume or browser key sends its command instead.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.ShiftKey, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
true if the key press was sent; false if Windows blocked it or, for a key sent as a command, no window has focus.
1 example: Shift-click
KeyboardKeyUp
KeyboardKeyUp(key: Integer) → Bool
Releases a key pressed with KeyboardKeyDown. For a media, volume or browser key sent as a command, it does nothing, since the command already went out on the press.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.ShiftKey, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
true if the key release was sent, and always true for a key sent as a command; false if Windows blocked it.
1 example: Shift-click
KeyboardPressKey
KeyboardPressKey(key: Integer) → Bool · Simple
Presses and releases one key, which can be any key Windows has a code for, media keys included. With the setting Send media and browser keys as commands on, those keys send their command instead.
Parameters
key: Integer— A VirtualKey constant, such as VirtualKey.MediaPlayPause, or a virtual-key code from 0 to 255. Any other value stops the script with an error.
Returns
true if the key press was sent; false if Windows blocked it or, for a key sent as a command, no window has focus.
3 examples: Named constants vs raw numbers, Media keys, Map a serial device's buttons to media keys
KeyboardPressKeyCombo
KeyboardPressKeyCombo(combo: Text) → Bool · Simple
Presses one key combination such as Ctrl+C: holds the modifiers, presses and releases the key, then releases the modifiers. Sends one combination per call.
Parameters
combo: Text— Optional modifier symbols (^ for Ctrl, + for Shift, @ for Windows, the percent sign for Alt) followed by one letter or digit, or by a key name in braces such as {ENTER}, {F5} or {LEFT}, in any letter case. Example: '^c' is Ctrl+C.
Returns
true if the keystrokes were sent; false if Windows blocked them. A combo it does not understand stops the script with an error.
4 examples: Key combos, Type a signature, Uppercase the selected text, Search the web for the selection
KeyboardTypeText
KeyboardTypeText(text: Text) → Bool · Simple
Types text into the focused window character by character, in any language and including emoji, whatever the keyboard layout. Waits the Typing delay setting before each character.
Parameters
text: Text— The text to type. Each line break is sent as one Enter press. In a text expansion's script, the key that ended the trigger is typed after it.
Returns
true if every character was sent, or the text is empty; false if Windows blocked some of them.
3 examples: Launch a program, wait for its window, act on it, Today's date, and a timestamped file name, Type a signature
Macro
MacroClearTemporary
MacroClearTemporary() → Bool
Discards the macro recorded with MacroRecordTemporary.
Parameters
No parameters.
Returns
true if there was a recorded macro to discard; false if there was none.
MacroExpectFocusedWindow
MacroExpectFocusedWindow(exeName: Text, windowClass: Text) → Bool
Waits until the foreground window belongs to the given program and window class, up to the macro replay wait time in the settings (2 seconds by default). If it never matches, shows a notification and stops the script.
Parameters
exeName: Text— The program's file name, such as notepad.exe. Not case-sensitive; empty text matches any program.windowClass: Text— The top-level window's class name, such as Notepad. Not case-sensitive; empty text matches any class.
Returns
true when the window matches; false if the script was asked to stop while waiting.
MacroExpectWindowAt
MacroExpectWindowAt(x: Integer, y: Integer, exeName: Text, windowClass: Text) → Bool
Waits until the top-level window at a screen point belongs to the given program and window class, up to the macro replay wait time in the settings (2 seconds by default). If it never matches, it shows a notification and stops the script.
Parameters
x: Integer— Horizontal screen position to check, in virtual-screen pixels.y: Integer— Vertical screen position to check, in virtual-screen pixels.exeName: Text— The program's file name, such as notepad.exe. Not case-sensitive; empty text matches any program.windowClass: Text— The top-level window's class name, such as Notepad. Not case-sensitive; empty text matches any class.
Returns
true when the window matches; false if the script was asked to stop while waiting.
MacroGetTemporaryScript
MacroGetTemporaryScript() → Text
Returns the macro recorded with MacroRecordTemporary as Steps script text, so a script can save or inspect it.
Parameters
No parameters.
Returns
The last finished recording's Steps text, or empty text if nothing has been recorded or it was cleared. While a new recording is running, this still returns the previous one.
MacroPlayTemporary
MacroPlayTemporary(timeoutSeconds: Integer) → Bool
Plays back the macro recorded with MacroRecordTemporary and waits until it finishes or the timeout passes. The user's real mouse and keyboard input is held back during playback.
Parameters
timeoutSeconds: Integer— The longest time to wait, in seconds; 1 or more, or the script stops with an error. A macro still running after this keeps going, but real input is no longer held back.
Returns
true if the macro played to the end in time; false if nothing was recorded, a step or window check failed, playback was stopped, or it was still running at the timeout.
MacroRecordTemporary
MacroRecordTemporary() → Bool
Starts recording mouse and keyboard input into a temporary macro kept in memory; press Ctrl+Break to stop. Returns right away, before recording begins. A confirmation box may appear first.
Parameters
No parameters.
Returns
true if the recording request was sent; false if a recording is already running, starting or requested, or the engine has not finished starting.
Math
MathAbs
MathAbs(value: Any) → Any
Returns the absolute value of a number, that is, the number without its minus sign. Works on Integer and Real values.
Parameters
value: Any— The Integer or Real number.
Returns
The absolute value, of the same kind as value (Integer or Real); 0.0 for a Real that is NaN or infinite. A value that is not a number stops the action with an error.
2 examples: Clamp a value to a range, Which way did the stroke go?
MathAtan2
MathAtan2(y: Any, x: Any) → Real
Returns the angle, in radians, from the origin to the point (x, y). Screen y grows downward, so for a stroke angle in the usual math direction pass the vertical change negated.
Parameters
y: Any— The vertical coordinate of the point. Integer or Real. Note that y comes first.x: Any— The horizontal coordinate of the point. Integer or Real.
Returns
The angle in radians, from -pi to pi, as a Real; 0.0 if either argument is NaN or infinite. Arguments that are not numbers stop the action with an error.
MathCeil
MathCeil(value: Real) → Integer
Rounds a number up to the nearest whole number. MathCeil(2.1) is 3; MathCeil(-2.1) is -2.
Parameters
value: Real— The number to round up. An Integer is accepted as is.
Returns
The rounded value as an Integer. 0 if value is NaN or infinite; a value beyond the Integer range gives the largest or smallest Integer.
1 example: Rounding and Real math builtins
MathClamp
MathClamp(value: Any, min: Any, max: Any) → Any
Keeps a number inside a range: returns min if value is below it, max if value is above it, and value otherwise. Works on Integer and Real values.
Parameters
value: Any— The number to keep inside the range.min: Any— The lowest allowed value. Must not be greater than max.max: Any— The highest allowed value.
Returns
Whichever of value, min or max was chosen, keeping its own kind (Integer or Real); 0.0 if any argument is NaN or infinite. Non-numbers, or min greater than max, stop the action with an error.
1 example: Clamp a value to a range
MathCos
MathCos(radians: Real) → Real
Returns the cosine of an angle given in radians. To convert degrees, multiply by MathGetPi() and divide by 180.
Parameters
radians: Real— The angle in radians. An Integer is accepted as is.
Returns
The cosine, from -1 to 1, as a Real; 0.0 if radians is NaN or infinite.
1 example: Move the mouse in a circle
MathFloor
MathFloor(value: Real) → Integer
Rounds a number down to the nearest whole number. MathFloor(2.9) is 2; MathFloor(-2.1) is -3.
Parameters
value: Real— The number to round down. An Integer is accepted as is.
Returns
The rounded value as an Integer. 0 if value is NaN or infinite; a value beyond the Integer range gives the largest or smallest Integer.
1 example: Rounding and Real math builtins
MathGetE
MathGetE() → Real
Returns the mathematical constant e (about 2.71828), the base of natural logarithms.
Parameters
No parameters.
Returns
The value of e as a Real.
MathGetPi
MathGetPi() → Real
Returns the mathematical constant pi (about 3.14159). Use it to convert between degrees and radians.
Parameters
No parameters.
Returns
The value of pi as a Real.
1 example: Move the mouse in a circle
MathLog
MathLog(value: Real) → Real
Returns the natural logarithm (base e) of a number. Divide by MathLog(10.0) for a base 10 logarithm.
Parameters
value: Real— The number, greater than 0. An Integer is accepted as is.
Returns
The natural logarithm as a Real, or 0 if value is 0, negative, NaN or infinite.
MathMax
MathMax(a: Any, b: Any) → Any
Returns the larger of two numbers. Works on Integer and Real values.
Parameters
a: Any— The first number.b: Any— The second number.
Returns
Whichever of a or b is larger, keeping its own kind; a if they are equal; 0.0 if either is NaN or infinite. Arguments that are not numbers stop the action with an error.
MathMin
MathMin(a: Any, b: Any) → Any
Returns the smaller of two numbers. Works on Integer and Real values.
Parameters
a: Any— The first number.b: Any— The second number.
Returns
Whichever of a or b is smaller, keeping its own kind; a if they are equal; 0.0 if either is NaN or infinite. Arguments that are not numbers stop the action with an error.
1 example: Volume up with an on-screen display
MathMod
MathMod(value: Any, divisor: Any) → Any
Returns the remainder of dividing value by divisor. The result takes the divisor's sign, so MathMod(-30, 360) is 330: right for wrapping an angle or cycling an index.
Parameters
value: Any— The number to divide. Integer or Real.divisor: Any— The number to divide by. Integer or Real.
Returns
The remainder: an Integer when both arguments are Integer, otherwise a Real. 0 if divisor is 0 or either argument is NaN or infinite. Arguments that are not numbers stop the action with an error.
MathPow
MathPow(base: Real, exponent: Real) → Real
Raises a number to a power, such as a square or a cube. MathPow(2.0, 10.0) is 1024.
Parameters
base: Real— The number to raise. An Integer is accepted as is.exponent: Real— The power to raise it to. May be negative or fractional; 0.5 gives the square root.
Returns
The result as a Real, or 0 if an argument is NaN or infinite or there is no finite result, for example 0 to a negative power or a result too large to hold.
MathRandom
MathRandom(min: Integer, max: Integer) → Integer
Returns a random whole number between min and max, both included. MathRandom(1, 6) rolls a die.
Parameters
min: Integer— The lowest possible result.max: Integer— The highest possible result. Must not be less than min.
Returns
A random Integer from min to max. min greater than max stops the action with an error.
2 examples: while (true) with an exit flag, Random numbers and a coin flip
MathRound
MathRound(value: Real) → Integer
Rounds a number to the nearest whole number. Halves round away from zero: 2.5 becomes 3 and -2.5 becomes -3.
Parameters
value: Real— The number to round. To keep two decimals as a whole number, round value times 100.
Returns
The rounded value as an Integer. 0 if value is NaN or infinite; a value beyond the Integer range gives the largest or smallest Integer.
5 examples: Rounding and Real math builtins, Length of a gesture stroke, Move the mouse in a circle, Formatting a Real without six decimals, Volume up with an on-screen display
MathSin
MathSin(radians: Real) → Real
Returns the sine of an angle given in radians. To convert degrees, multiply by MathGetPi() and divide by 180.
Parameters
radians: Real— The angle in radians. An Integer is accepted as is.
Returns
The sine, from -1 to 1, as a Real; 0.0 if radians is NaN or infinite.
1 example: Move the mouse in a circle
MathSqrt
MathSqrt(value: Real) → Real
Returns the square root of a number. MathSqrt(dx * dx + dy * dy) is the distance between two points.
Parameters
value: Real— The number, 0 or greater. An Integer is accepted as is.
Returns
The square root as a Real, or 0 if value is negative, NaN or infinite.
2 examples: Rounding and Real math builtins, Length of a gesture stroke
MathTan
MathTan(radians: Real) → Real
Returns the tangent of an angle given in radians. Near a right angle the result becomes very large.
Parameters
radians: Real— The angle in radians. An Integer is accepted as is.
Returns
The tangent as a Real; 0.0 if radians is NaN or infinite.
Mouse
MouseButtonDown
MouseButtonDown(button: Integer) → Bool
Presses a mouse button at the current cursor position and keeps it down until MouseButtonUp. Combine with MouseMoveTo to script a drag.
Parameters
button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if the button press was sent; false if Windows blocked it. An unknown button stops the script with an error.
1 example: A scripted drag
MouseButtonUp
MouseButtonUp(button: Integer) → Bool
Releases a mouse button at the current cursor position, typically one pressed with MouseButtonDown.
Parameters
button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if the button release was sent; false if Windows blocked it. An unknown button stops the script with an error.
1 example: A scripted drag
MouseClick
MouseClick(x: Integer, y: Integer, button: Integer) → Bool · Simple
Moves the cursor to a screen point and clicks a mouse button there. The cursor stays at that point afterwards.
Parameters
x: Integer— Horizontal screen position to click, in pixels.y: Integer— Vertical screen position to click, in pixels.button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if the click was sent; false if the cursor could not be moved to the point, in which case nothing is clicked, or if Windows blocked the click. An unknown button stops the script with an error.
2 examples: Click somewhere, then put the cursor back, Shift-click
MouseClickAtClientPoint
MouseClickAtClientPoint(window: Window, x: Integer, y: Integer, button: Integer) → Bool
Clicks a mouse button at a point measured from the top-left corner of a window's client area (the inside, without title bar and borders). The cursor moves there and stays.
Parameters
window: Window— The window whose client area x and y are measured from.x: Integer— Distance from the client area's left edge, in that window's own pixels, which can differ from screen pixels for a window Windows scales for DPI.y: Integer— Distance from the client area's top edge, in that window's own pixels, which can differ from screen pixels for a window Windows scales for DPI.button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if the click was sent; false if the window is invalid or no longer exists or the cursor could not be moved to the point, in which case nothing is clicked, or if Windows blocked the click. An unknown button stops the script with an error.
1 example: Click a point inside a window
MouseDoubleClick
MouseDoubleClick(x: Integer, y: Integer, button: Integer) → Bool · Simple
Moves the cursor to a screen point and double-clicks a mouse button there. The cursor stays at that point afterwards.
Parameters
x: Integer— Horizontal screen position to double-click, in pixels.y: Integer— Vertical screen position to double-click, in pixels.button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if both clicks were sent; false if the cursor could not be moved to the point, in which case nothing is clicked, or if Windows blocked the clicks. An unknown button stops the script with an error.
MouseGetCursorX
MouseGetCursorX() → Integer
Returns the horizontal screen position of the mouse cursor.
Parameters
No parameters.
Returns
The cursor's x position in screen pixels; negative on a monitor left of the primary one.
8 examples: else-if chain, Move the mouse in a circle, Read the pixel color under the cursor, Snap a window into a 3×2 grid cell under the cursor, Describe what's under the cursor, Click somewhere, then put the cursor back, A scripted drag, Shift-click
MouseGetCursorY
MouseGetCursorY() → Integer
Returns the vertical screen position of the mouse cursor.
Parameters
No parameters.
Returns
The cursor's y position in screen pixels; negative on a monitor above the primary one.
8 examples: else-if chain, Move the mouse in a circle, Read the pixel color under the cursor, Snap a window into a 3×2 grid cell under the cursor, Describe what's under the cursor, Click somewhere, then put the cursor back, A scripted drag, Shift-click
MouseIsButtonDown
MouseIsButtonDown(button: Integer) → Bool
Checks whether a mouse button is held down at this moment.
Parameters
button: Integer— A MouseButton constant, such as MouseButton.Primary. Primary and Secondary follow the swap-buttons setting in Windows; Left and Right are the physical buttons.
Returns
true if the button is down; false if it is up. An unknown button stops the script with an error.
MouseLockToRect
MouseLockToRect(x: Integer, y: Integer, width: Integer, height: Integer) → Bool
Confines the mouse cursor to a screen rectangle. The lock outlives the script until MouseUnlock is called or another program changes it, so always unlock when done.
Parameters
x: Integer— Left edge of the rectangle, in screen pixels.y: Integer— Top edge of the rectangle, in screen pixels.width: Integer— Width of the rectangle, in pixels. Must be greater than 0.height: Integer— Height of the rectangle, in pixels. Must be greater than 0.
Returns
true if the cursor is now confined; false if width or height is not positive or Windows refused.
1 example: Confine the cursor to a window for 5 seconds
MouseMoveTo
MouseMoveTo(x: Integer, y: Integer) → Bool · Simple
Moves the mouse cursor to a screen point on any monitor, as if the user moved the mouse.
Parameters
x: Integer— Horizontal screen position, in pixels.y: Integer— Vertical screen position, in pixels.
Returns
true if the move was sent; false if Windows blocked it.
3 examples: Move the mouse in a circle, Click somewhere, then put the cursor back, A scripted drag
MouseScrollHorizontal
MouseScrollHorizontal(amount: Integer) → Bool · Simple
Turns the horizontal mouse wheel at the current cursor position. Use MouseMoveTo first to scroll somewhere else.
Parameters
amount: Integer— Wheel distance, where 120 is one notch: positive scrolls right, negative scrolls left. Smaller values scroll more finely in apps that support it.
Returns
true if the scroll was sent; false if Windows blocked it.
1 example: Scroll by notches
MouseScrollVertical
MouseScrollVertical(amount: Integer) → Bool · Simple
Turns the vertical mouse wheel at the current cursor position. Use MouseMoveTo first to scroll somewhere else.
Parameters
amount: Integer— Wheel distance, where 120 is one notch: positive scrolls up, negative scrolls down. Smaller values scroll more finely in apps that support it.
Returns
true if the scroll was sent; false if Windows blocked it.
1 example: Scroll by notches
MouseUnlock
MouseUnlock() → Bool
Frees the mouse cursor from any confinement, whether set by MouseLockToRect or by another program.
Parameters
No parameters.
Returns
true if the cursor is free; false if Windows refused.
1 example: Confine the cursor to a window for 5 seconds
Multimedia
MultimediaGetMute
MultimediaGetMute(endpoint: Integer) → Bool
Reports whether the default playback device or microphone chosen by endpoint is muted in Windows.
Parameters
endpoint: Integer— Which device to check: AudioEndpoint.Playback (default speakers or headphones), AudioEndpoint.Capture (default microphone) or AudioEndpoint.Communications (the microphone Windows uses for calls). Any other value stops the action with an error.
Returns
true if the device is muted; false if it is not muted or does not exist (for example, no microphone is connected).
1 example: Toggle the microphone mute
MultimediaGetVolume
MultimediaGetVolume(endpoint: Integer) → Real
Returns the master volume of the default playback device or microphone chosen by endpoint, as a Real from 0.0 to 1.0.
Parameters
endpoint: Integer— Which device to read: AudioEndpoint.Playback (default speakers or headphones), AudioEndpoint.Capture (default microphone) or AudioEndpoint.Communications (the microphone Windows uses for calls). Any other value stops the action with an error.
Returns
The volume from 0.0 (silent) to 1.0 (full), the same scale as MultimediaSetVolume; 0.0 if the device does not exist.
1 example: Volume up with an on-screen display
MultimediaPlayMp3File
MultimediaPlayMp3File(path: Text) → Bool · Simple
Starts playing an MP3 file and returns at once while it plays. Starting another MP3 stops the one still playing.
Parameters
path: Text— Full path of the .mp3 file, such as C:/Music/done.mp3.
Returns
true if playback started; false if the file is missing, Windows cannot open or play it within 10 seconds, or stop-all ended the wait.
MultimediaPlayWavFile
MultimediaPlayWavFile(path: Text) → Bool · Simple
Starts playing a .wav sound file and returns at once while it plays. Starting another WAV stops the one still playing. Only .wav files work; use MultimediaPlayMp3File for MP3.
Parameters
path: Text— Full path of the .wav file, such as C:/Windows/Media/chimes.wav.
Returns
true if the file exists and playback was started; false if there is no file at that path. A file that exists but is not a playable WAV returns true and plays nothing.
1 example: Play a sound
MultimediaSetMute
MultimediaSetMute(endpoint: Integer, muted: Bool) → Bool · Simple
Mutes or unmutes the default playback device or microphone chosen by endpoint, as the Windows volume mute button does.
Parameters
endpoint: Integer— Which device to change: AudioEndpoint.Playback (default speakers or headphones), AudioEndpoint.Capture (default microphone) or AudioEndpoint.Communications (the microphone Windows uses for calls). Any other value stops the action with an error.muted: Bool— true to mute the device; false to unmute it.
Returns
true if the mute state was set; false if the device does not exist or refused the change.
1 example: A toggle that survives between runs
MultimediaSetVolume
MultimediaSetVolume(endpoint: Integer, level: Real) → Bool · Simple
Sets the master volume of the default playback device or microphone chosen by endpoint to an exact level.
Parameters
endpoint: Integer— Which device to change: AudioEndpoint.Playback (default speakers or headphones), AudioEndpoint.Capture (default microphone) or AudioEndpoint.Communications (the microphone Windows uses for calls). Any other value stops the action with an error.level: Real— The new volume from 0.0 (silent) to 1.0 (full); 0.5 matches 50 on the Windows volume slider. Values outside 0.0 to 1.0 are clamped.
Returns
true if the volume was set; false if the device does not exist or refused the change.
2 examples: Volume up with an on-screen display, Turn an Arduino knob into a volume control
MultimediaToggleMute
MultimediaToggleMute(endpoint: Integer) → Bool · Simple
Mutes the default playback device or microphone chosen by endpoint if it is unmuted, or unmutes it if it is muted. Call MultimediaGetMute afterward to learn the new state.
Parameters
endpoint: Integer— Which device to toggle: AudioEndpoint.Playback (default speakers or headphones), AudioEndpoint.Capture (default microphone) or AudioEndpoint.Communications (the microphone Windows uses for calls). Any other value stops the action with an error.
Returns
true if the mute state was switched; false if the device does not exist or refused the change. This is not the new mute state.
1 example: Toggle the microphone mute
Plugin
PluginSendMessage
PluginSendMessage(pluginName: Text, message: Text, timeoutSeconds: Integer) → Text
Sends a text message to a running plugin that accepts commands and waits for its reply. A plugin handles one message at a time; messages sent while it is busy wait in a queue.
Parameters
pluginName: Text— The plugin's display name, matched exactly, including case.message: Text— The text to send. What it means is up to the plugin.timeoutSeconds: Integer— How long to wait for the reply, in seconds, from 0 to 10; any other value stops the script with an error. With 0 the call returns at once with empty text.
Returns
The plugin's reply, or empty text if it did not reply in time. No such running plugin, a full queue, or a message that is too long stops the script with an error.
1 example: Talk to a plugin
Region
RegionGetCellIndexAt
RegionGetCellIndexAt(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, pointX: Integer, pointY: Integer) → Integer
Splits a rectangle into a grid of columns and rows and returns which cell contains a point. Cells are numbered from 0, left to right, then top to bottom.
Parameters
rectX: Integer— Left edge of the rectangle to split, in pixels.rectY: Integer— Top edge of the rectangle to split, in pixels.rectWidth: Integer— Width of the rectangle, in pixels. Must be greater than 0.rectHeight: Integer— Height of the rectangle, in pixels. Must be greater than 0.columns: Integer— Number of columns in the grid. Must be greater than 0. Leftover pixels go one each to the first columns.rows: Integer— Number of rows in the grid. Must be greater than 0. Leftover pixels go one each to the first rows.pointX: Integer— Horizontal position of the point to look up, in the same pixels as rectX.pointY: Integer— Vertical position of the point to look up, in the same pixels as rectY.
Returns
The cell number (row times columns, plus column), or -1 if the point is outside the rectangle or rectWidth, rectHeight, columns or rows is not positive.
1 example: Snap a window into a 3×2 grid cell under the cursor
RegionGetHeight
RegionGetHeight(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer
Returns the height of one cell when a rectangle is split into a grid of columns and rows. Leftover pixels go one each to the first rows.
Parameters
rectX: Integer— Left edge of the rectangle to split, in pixels.rectY: Integer— Top edge of the rectangle to split, in pixels.rectWidth: Integer— Width of the rectangle, in pixels. Must be greater than 0.rectHeight: Integer— Height of the rectangle, in pixels. Must be greater than 0.columns: Integer— Number of columns in the grid. Must be greater than 0.rows: Integer— Number of rows in the grid. Must be greater than 0.index: Integer— Zero-based cell number, counted left to right, then top to bottom, from 0 to columns times rows minus 1.
Returns
The cell's height in pixels, or -1 if index is out of range or rectWidth, rectHeight, columns or rows is not positive.
1 example: Snap a window into a 3×2 grid cell under the cursor
RegionGetWidth
RegionGetWidth(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer
Returns the width of one cell when a rectangle is split into a grid of columns and rows. Leftover pixels go one each to the first columns.
Parameters
rectX: Integer— Left edge of the rectangle to split, in pixels.rectY: Integer— Top edge of the rectangle to split, in pixels.rectWidth: Integer— Width of the rectangle, in pixels. Must be greater than 0.rectHeight: Integer— Height of the rectangle, in pixels. Must be greater than 0.columns: Integer— Number of columns in the grid. Must be greater than 0.rows: Integer— Number of rows in the grid. Must be greater than 0.index: Integer— Zero-based cell number, counted left to right, then top to bottom, from 0 to columns times rows minus 1.
Returns
The cell's width in pixels, or -1 if index is out of range or rectWidth, rectHeight, columns or rows is not positive.
1 example: Snap a window into a 3×2 grid cell under the cursor
RegionGetX
RegionGetX(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer
Returns the left edge of one cell when a rectangle is split into a grid of columns and rows. Leftover pixels go one each to the first columns.
Parameters
rectX: Integer— Left edge of the rectangle to split, in pixels.rectY: Integer— Top edge of the rectangle to split, in pixels.rectWidth: Integer— Width of the rectangle, in pixels. Must be greater than 0.rectHeight: Integer— Height of the rectangle, in pixels. Must be greater than 0.columns: Integer— Number of columns in the grid. Must be greater than 0.rows: Integer— Number of rows in the grid. Must be greater than 0.index: Integer— Zero-based cell number, counted left to right, then top to bottom, from 0 to columns times rows minus 1.
Returns
The cell's left edge, or -1 if index is out of range or rectWidth, rectHeight, columns or rows is not positive. A real cell can also start at -1, so check index first.
1 example: Snap a window into a 3×2 grid cell under the cursor
RegionGetY
RegionGetY(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer
Returns the top edge of one cell when a rectangle is split into a grid of columns and rows. Leftover pixels go one each to the first rows.
Parameters
rectX: Integer— Left edge of the rectangle to split, in pixels.rectY: Integer— Top edge of the rectangle to split, in pixels.rectWidth: Integer— Width of the rectangle, in pixels. Must be greater than 0.rectHeight: Integer— Height of the rectangle, in pixels. Must be greater than 0.columns: Integer— Number of columns in the grid. Must be greater than 0.rows: Integer— Number of rows in the grid. Must be greater than 0.index: Integer— Zero-based cell number, counted left to right, then top to bottom, from 0 to columns times rows minus 1.
Returns
The cell's top edge, or -1 if index is out of range or rectWidth, rectHeight, columns or rows is not positive. A real cell can also start at -1, so check index first.
1 example: Snap a window into a 3×2 grid cell under the cursor
Serial
SerialClosePort
SerialClosePort(port: Text) → Bool
Closes a COM port opened with SerialOpenPort, freeing it for other programs such as the Arduino IDE. Received lines not yet read are discarded.
Parameters
port: Text— The port name passed to SerialOpenPort, such as COM3. Case does not matter.
Returns
true if the port was open and is now closed; false if it was not open, or a serial monitor holds it (use SerialMonitorDelete).
1 example: Ask a serial device a question
SerialEnumeratePorts
SerialEnumeratePorts() → Integer
Finds the serial (COM) ports on this computer, such as an Arduino, ESP32 or USB-to-serial adapter plugged in over USB, and returns how many there are. Read each name with SerialGetEnumeratedPortAt.
Parameters
No parameters.
Returns
The number of COM ports found, or 0 if there are none.
1 example: List the COM ports
SerialGetEnumeratedPortAt
SerialGetEnumeratedPortAt(index: Integer) → Text
Returns one port name, such as COM3, from the list made by the last SerialEnumeratePorts call in this script run. Device Manager shows which device is on which port.
Parameters
index: Integer— Position in the list, from 0 to the count minus 1. Names are sorted by number, so COM3 comes before COM10.
Returns
The port name, or empty text if index is out of range or SerialEnumeratePorts has not been called.
1 example: List the COM ports
SerialGetTextLine
SerialGetTextLine(port: Text, timeoutSeconds: Integer, baudRate: Integer) → Text
Waits for the next complete line from a COM port and returns it, such as a sensor reading, a barcode scan or a device's reply. Blocks the script for up to timeoutSeconds; stop-all ends the wait.
Parameters
port: Text— The port name, such as COM3. Open it first with SerialOpenPort to choose the settings and keep lines that arrive early; otherwise it opens at baudRate only for this wait.timeoutSeconds: Integer— Longest wait, in seconds. 0 waits until a line arrives or the script is stopped. A negative value stops the script with an error.baudRate: Integer— Speed in bits per second, used only when this call opens the port itself, for example 9600 or 115200; ignored for a port opened with SerialOpenPort. 0 or less stops the script with an error.
Returns
The line without its terminator, or empty text if no line arrived in time, the port could not be opened or the device was unplugged. Stops the script with an error if a serial monitor holds the port.
2 examples: Ask a serial device a question, Keep an Arduino's port open and send it commands
SerialMonitorCreate
SerialMonitorCreate(name: Text, port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text, script: Text) → Bool
Opens a COM port and runs a script for every line the device sends, for example to turn an Arduino button box or macro pad into shortcuts. The monitor keeps running after this script ends. Stop-all stops the script running for a line and drops waiting lines; the monitor keeps running.
Parameters
name: Text— A name for the monitor. Reusing the name of this port's current monitor replaces it; a name that already monitors another port stops the script with an error. Case does not matter.port: Text— The port name, such as COM3. Device Manager shows which port a board is on.baudRate: Integer— Speed in bits per second. It must match the device, for example the 9600 or 115200 in an Arduino sketch's Serial.begin.parity: Integer— A SerialParity constant. Most devices, including Arduino boards, use SerialParity.None.dataBits: Integer— Bits per character, as a plain number. Almost every device uses 8.stopBits: Integer— A SerialStopBits constant, usually SerialStopBits.One. Use the constant: the plain number 1 means one and a half stop bits.terminator: Text— The text that ends each line: removed from received lines and added to every line SerialWriteTextLine sends. Empty text means CR LF, which Arduino's Serial.println sends. Use '\n' for devices that end lines with LF only, or '\r' for CR only.script: Text— The script to run for each received line, as Text. It reads the line with ContextGetSerialTextLine. Lines run one at a time, in the order they arrived; up to 256 lines wait while the script runs, and beyond that the oldest are dropped.
Returns
true once the monitor is running; false if the port is missing, unplugged or in use by another program. Stops the script with an error if the port is open with SerialOpenPort or monitored under another name, or this name already monitors another port. Unplugging the device ends the monitor and logs a line to the console's System tab.
2 examples: Map a serial device's buttons to media keys, Turn an Arduino knob into a volume control
SerialMonitorDelete
SerialMonitorDelete(name: Text) → Bool
Stops a serial monitor created with SerialMonitorCreate and closes its COM port, so other programs can use the port again. Lines not yet handled are dropped; a script already running finishes.
Parameters
name: Text— The name given to SerialMonitorCreate. Case does not matter.
Returns
true if a monitor with that name was found and stopped; false if there was none.
SerialMonitorDeleteAll
SerialMonitorDeleteAll() → Bool
Stops every serial monitor and closes their COM ports. Ports opened with SerialOpenPort stay open.
Parameters
No parameters.
Returns
Always true.
SerialMonitorGetCount
SerialMonitorGetCount() → Integer
Returns how many serial monitors are running and takes a snapshot of their names for SerialMonitorGetEnumeratedNameAt.
Parameters
No parameters.
Returns
The number of running serial monitors, or 0 if there are none.
SerialMonitorGetEnumeratedNameAt
SerialMonitorGetEnumeratedNameAt(index: Integer) → Text
Returns one monitor name from the snapshot taken by the last SerialMonitorGetCount call in this script run.
Parameters
index: Integer— Position in the snapshot, from 0 to the count minus 1. The order has no meaning.
Returns
The monitor name, or empty text if index is out of range or SerialMonitorGetCount has not been called.
SerialOpenPort
SerialOpenPort(port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text) → Bool
Opens a COM port and keeps it open until SerialClosePort, collecting each received line for SerialGetTextLine. Opening turns on the DTR and RTS signals, which restarts many Arduino boards just as the Arduino IDE does, so open once and reuse it.
Parameters
port: Text— The port name, such as COM3. Device Manager or SerialEnumeratePorts shows it. Empty text stops the script with an error.baudRate: Integer— Speed in bits per second. It must match the device, for example the 9600 or 115200 in an Arduino sketch's Serial.begin.parity: Integer— A SerialParity constant. Most devices, including Arduino boards, use SerialParity.None.dataBits: Integer— Bits per character, as a plain number. Almost every device uses 8.stopBits: Integer— A SerialStopBits constant, usually SerialStopBits.One. Use the constant: the plain number 1 means one and a half stop bits.terminator: Text— The text that ends each line: removed from received lines and added to every line SerialWriteTextLine sends. Empty text means CR LF, which Arduino's Serial.println sends. Use '\n' for devices that end lines with LF only, or '\r' for CR only.
Returns
true if the port is open; false if it is missing, unplugged, in use by another program such as a serial monitor, or rejected the settings. Stops the script with an error if Input.Observer already has the port open or a serial monitor holds it.
2 examples: Ask a serial device a question, Keep an Arduino's port open and send it commands
SerialWriteTextLine
SerialWriteTextLine(port: Text, text: Text, baudRate: Integer) → Bool
Sends a line of text plus the port's line ending to a COM port, such as a command for an Arduino or a G-code line for a 3D printer. Works on a port opened with SerialOpenPort or held by a serial monitor, so a monitor's script can answer its device. A port that is not open is opened at baudRate, 8-N-1, just for this write.
Parameters
port: Text— The port name, such as COM3. Open it first with SerialOpenPort to choose the settings and to avoid restarting boards that reset when the port opens.text: Text— The line to send, encoded as UTF-8. Do not add a line ending: the terminator the port was opened with is added, or CR LF when this call opens the port itself.baudRate: Integer— Speed in bits per second, used only when this call opens the port itself, for example 9600 or 115200; ignored for a port that is already open or monitored. 0 or less stops the script with an error.
Returns
true if the line was sent; false if the port could not be opened or the write failed or timed out.
2 examples: Ask a serial device a question, Keep an Arduino's port open and send it commands
Shell
ShellEmptyRecycleBins
ShellEmptyRecycleBins() → Bool · Simple
Permanently deletes everything in the Recycle Bin on every drive, without asking for confirmation. This cannot be undone.
Parameters
No parameters.
Returns
true if the Recycle Bins were emptied or were already empty; false otherwise.
ShellEnumerateProcessIdsByExeRegex
ShellEnumerateProcessIdsByExeRegex(pattern: Text) → Integer
Finds every running process whose program file name, such as notepad.exe, matches a regular expression, and returns how many. Read each process ID with ShellGetEnumeratedProcessIdAt.
Parameters
pattern: Text— A regular expression, matched without regard to case against the file name only, not the full path. Use ^ and $ to match the whole name, such as ^notepad[.]exe$.
Returns
The number of matching processes, or 0 if none match. An invalid pattern stops the script with an error.
1 example: From process to window
ShellExpandEnvironmentVariables
ShellExpandEnvironmentVariables(text: Text) → Text
Replaces each environment variable in text, written as a name between two percent signs such as USERPROFILE or TEMP, with its value. Useful for building paths that work on any PC.
Parameters
text: Text— Text containing environment variable names between percent signs, such as a path in the user's profile folder.
Returns
The text with every known variable replaced; unknown variables are left as written. Empty text if the expansion fails.
8 examples: Today's date, and a timestamped file name, Screenshot the area you circled, Save a copied image to a file, Append to a log file, Count file types in a folder, Back up a file before editing it, Watch a folder, Expand environment variables
ShellGetEnumeratedProcessIdAt
ShellGetEnumeratedProcessIdAt(index: Integer) → Integer
Returns one process ID from the list made by the last ShellEnumerateProcessIdsByExeRegex call in this script run.
Parameters
index: Integer— Position in the list, from 0 to the count minus 1.
Returns
The process ID, or 0 if index is out of range or ShellEnumerateProcessIdsByExeRegex has not been called.
1 example: From process to window
ShellGetSystemMetricsByIndex
ShellGetSystemMetricsByIndex(index: Integer) → Integer
Returns a Windows system measurement or setting by its GetSystemMetrics index, such as 0 for the primary screen width or 80 for the number of monitors.
Parameters
index: Integer— A Windows SM_ index number, such as 0 (SM_CXSCREEN) or 1 (SM_CYSCREEN). There are no named constants for these.
Returns
The value Windows reports, often in pixels, or 0 for an unknown index.
ShellRun
ShellRun(command: Text) → Bool · Simple
Runs a program or opens a file, folder or web address, like typing it in the Windows Run box (Win+R). Does not wait for the program to finish.
Parameters
command: Text— A program name such as notepad.exe, a path or a web address, optionally followed by arguments. Put a path that contains spaces in single quotes when arguments follow it.
Returns
true if Windows started it; false if it could not be found or started. No Windows error box is shown on failure.
4 examples: while loop: wait for a window, with a timeout, Launch a program, wait for its window, act on it, Search the web for the selected text, Search the web for the selection
ShellRunOrActivate
ShellRunOrActivate(exeName: Text) → Bool · Simple
Brings a program's window to the front if the program is already running, or runs the command if not. Useful for a gesture that always takes you to the same program.
Parameters
exeName: Text— The program's file name, such as notepad or notepad.exe, or its full path, optionally followed by arguments used only when it has to be started. Running windows are matched by the file name of the first word, with .exe added when it has no extension; put a path that contains spaces in single quotes.
Returns
true if a window was brought to the front or the program was started; false if Windows refused to bring the window forward or the start failed.
1 example: Launch or switch to an app
ShellRunProgram
ShellRunProgram(path: Text, arguments: Text, verb: Any, windowStyle: Integer, waitForExit: Bool) → Bool
Runs a program or opens a file with a chosen action (verb) and window style, and can wait for it to close. Use ShellVerb.RunAs to run a program as administrator.
Parameters
path: Text— The program, document or folder to open, such as notepad.exe or a full file path.arguments: Text— Command-line arguments for the program, or empty text for none.verb: Any— A ShellVerb constant, such as ShellVerb.Open or ShellVerb.Print, or any verb the file type supports as Text. Empty text uses the default action.windowStyle: Integer— A WindowStyle constant: WindowStyle.Normal, WindowStyle.Minimized, WindowStyle.Maximized or WindowStyle.Hidden. Any other value stops the script with an error. Some programs ignore it.waitForExit: Bool— true to block the script until the program closes; stop-all ends the wait and leaves the program running. false to continue at once.
Returns
true if Windows started it (and, with waitForExit, it has closed); false if it could not start, the administrator prompt was declined, or stop-all ended the wait. No Windows error box is shown on failure.
2 examples: Run a program with a verb and window style, Run and wait for exit
ShellRunStoreApp
ShellRunStoreApp(packageName: Text) → Bool · Simple
Starts an installed Microsoft Store app by its package name, part of it, or its Start menu name, such as Microsoft.WindowsCalculator or Calculator. Ordinary desktop programs are not matched; use ShellRun for those.
Parameters
packageName: Text— The app's package family name or part of it, or its exact Start menu name, matched without regard to case. An exact package family name wins, then an exact Start menu name, then the first app whose package family name contains the text.
Returns
true if the app was started; false if packageName is empty, no installed Store app matches, or the start failed.
ShellShowToast
ShellShowToast(title: Text, message: Text) → Bool · Simple
Shows a Windows notification (toast) with a title and a message. Waits only until Windows accepts it, not until it is dismissed.
Parameters
title: Text— The first, bold line of the notification.message: Text— The text shown under the title.
Returns
true if the notification was shown; false if notifications are turned off in the General settings, Windows refused it, or stop-all ended the wait.
9 examples: Pin a window on top, Screenshot the area you circled, Save a copied image to a file, A toggle that survives between runs, A Windows notification, Toggle the microphone mute, Run and wait for exit, Cycle to the next gesture profile, Engine state
ShellTerminateProcess
ShellTerminateProcess(processId: Integer) → Bool
Ends a process immediately, like End task in Task Manager. Unsaved work in that program is lost.
Parameters
processId: Integer— The process ID, for example from WindowGetProcessId or ShellGetEnumeratedProcessIdAt. 0 or less, Input.Observer's own process and Windows system processes stop the script with an error.
Returns
true if the process was ended; false if it had already exited or Windows denied access, such as for a program running as administrator.
Snippet
SnippetExecuteScript
SnippetExecuteScript(name: Text) → Bool · Simple
Runs the snippet with this name and waits until it finishes. The snippet sees the caller's trigger context but has its own variables.
Parameters
name: Text— The snippet's name, matched exactly, including case.
Returns
true if the snippet ran to the end; false if no snippet has that name, or the snippet is empty, has an error, or was stopped.
1 example: Snippets as reusable functions
SnippetGetScript
SnippetGetScript(name: Text) → Text
Returns the script text of the snippet with this name without running it, for example to pass to TimerCreate.
Parameters
name: Text— The snippet's name, matched exactly, including case.
Returns
The snippet's script text, or empty text if no snippet has that name.
1 example: Timer script from a snippet, no escaping
Storage
StorageClearAll
StorageClearAll() → Bool
Removes every value stored with StorageSetValue, for all actions. Persistent values are not affected.
Parameters
No parameters.
Returns
Always true.
StorageClearAllPersistent
StorageClearAllPersistent() → Bool
Removes every persistent value and erases them from storage.toml, so none of them come back after a restart. Values stored with StorageSetValue are not affected.
Parameters
No parameters.
Returns
Always true.
StorageClearPersistentValue
StorageClearPersistentValue(key: Text) → Bool
Removes one persistent value and erases it from storage.toml. Nothing happens if the key is not stored.
Parameters
key: Text— The name of the value to remove. Upper and lower case count as different.
Returns
Always true, whether or not the key was stored.
StorageClearValue
StorageClearValue(key: Text) → Bool
Removes one value stored with StorageSetValue. Nothing happens if the key is not stored.
Parameters
key: Text— The name of the value to remove. Upper and lower case count as different.
Returns
Always true, whether or not the key was stored.
StorageGetPersistentValue
StorageGetPersistentValue(key: Text) → Any
Reads a value saved with StorageSetPersistentValue, including one saved before Input.Observer last restarted.
Parameters
key: Text— The name the value was saved under. Upper and lower case count as different.
Returns
The stored value with its kind (Bool, Integer, Real or Text), or Integer 0 if the key is not stored. Use StorageHasPersistentValue to tell a missing key from a stored 0.
1 example: A counter that survives a restart
StorageGetValue
StorageGetValue(key: Text) → Any
Reads a value stored with StorageSetValue by this or any other action since Input.Observer started.
Parameters
key: Text— The name the value was stored under. Upper and lower case count as different.
Returns
The stored value with its kind (Bool, Integer, Real, Text or Window), or Integer 0 if the key is not stored. Use StorageHasValue to tell a missing key from a stored 0.
5 examples: && and || evaluate both sides, A repeating timer that counts, A toggle that survives between runs, A list kept in Storage, Snippets as reusable functions
StorageHasPersistentValue
StorageHasPersistentValue(key: Text) → Bool
Checks whether a persistent value is stored under a name. Use it to tell a missing key from a stored 0, false or empty text.
Parameters
key: Text— The name to look for. Upper and lower case count as different.
Returns
true if a persistent value is stored under key; false if not.
StorageHasValue
StorageHasValue(key: Text) → Bool
Checks whether a value is stored under a name with StorageSetValue. Use it to tell a missing key from a stored 0, false or empty text.
Parameters
key: Text— The name to look for. Upper and lower case count as different.
Returns
true if a value is stored under key; false if not.
StorageSetPersistentValue
StorageSetPersistentValue(key: Text, value: Any) → Bool
Saves a value under a name that survives a restart, in storage.toml beside the configuration file. The file is plain text, never encrypted: do not keep passwords or other secrets there.
Parameters
key: Text— The name to save under, up to 256 characters. Upper and lower case count as different. Replaces any value already stored under it.value: Any— The value to save: a Bool, Integer, Real or Text (up to 32,768 characters). It comes back with the same kind. A Window cannot be saved.
Returns
true once the value is stored. false when storage.toml existed but could not be read at startup: saving is then off until the next start, and the value is kept only until Input.Observer exits. A window value, a key over 256 characters, Text over 32,768 characters or a new key past 1,024 stored values stops the action with an error.
1 example: A counter that survives a restart
StorageSetValue
StorageSetValue(key: Text, value: Any) → Bool
Stores a value under a name so later runs of this or any other action can read it. Values are kept until Input.Observer exits; use StorageSetPersistentValue to keep one across restarts.
Parameters
key: Text— The name to store under, up to 256 characters. Upper and lower case count as different. Replaces any value already stored under it, whatever its kind.value: Any— The value to store: a Bool, Integer, Real, Text (up to 32,768 characters) or Window. It comes back with the same kind.
Returns
true once the value is stored. A key over 256 characters, Text over 32,768 characters or a new key past 1,024 stored values stops the action with an error.
5 examples: && and || evaluate both sides, A repeating timer that counts, A toggle that survives between runs, A list kept in Storage, Snippets as reusable functions
String
StringContains
StringContains(text: Text, search: Text) → Bool
Checks whether text contains another piece of text anywhere. Upper and lower case must match; use StringToLower on both for a case-insensitive check.
Parameters
text: Text— The text to search in.search: Text— The text to look for.
Returns
true if search occurs in text, or if search is empty; false otherwise.
1 example: Case-insensitive comparisons
StringEndsWith
StringEndsWith(text: Text, suffix: Text) → Bool
Checks whether text ends with a given piece of text, such as a file extension. Upper and lower case must match.
Parameters
text: Text— The text to check.suffix: Text— The ending to look for, such as '.pdf'.
Returns
true if text ends with suffix, or if suffix is empty; false otherwise.
1 example: Count file types in a folder
StringFormat
StringFormat(format: Text, value0: Any, value1: Any) → Text
Builds text by replacing every {0} in format with value0 and every {1} with value1. This is how to turn a number, Bool or window into Text.
Parameters
format: Text— The text with {0} and {1} placeholders. There is no {2}; nest calls for more values. {0} is replaced first, so a {1} inside value0 is replaced too.value0: Any— The value for {0}, of any kind.value1: Any— The value for {1}, of any kind. Pass empty text if format has no {1}.
Returns
The format text with the placeholders replaced. A Real shows six decimals; true and false show as words.
50 examples: The five value kinds, Counting loops: up, down and by steps, Nested loops: a multiplication table, while (true) with an exit flag, Precedence surprises, && and || evaluate both sides, Equality across kinds, Mixed-type arithmetic falls back to 0, Comments, blank statements and blocks, Integer vs Real division, and dividing by zero, Remainder without %, Rounding and Real math builtins, Clamp a value to a range, Random numbers and a coin flip, Length of a gesture stroke, Formatting a Real without six decimals, Flag masks: set, clear, toggle, test, Read the pixel color under the cursor, Count the set bits, Shift edge cases, Swap two Integers, Key state bits, Formatting more than two values, Split and iterate, Nested splits: key=value pairs, Last index of: a file extension, Zero-pad a number, Count words on the clipboard, Text ordering is ordinal, Named constants vs raw numbers, List visible top-level windows, Minimize every window of one app, Close windows by title pattern, after confirming, Inspect a window's child controls, From process to window, Describe what's under the cursor, Everything the trigger context knows, Append to a log file, Read a file and count its lines, Count file types in a folder, A repeating timer that counts, A counter that survives a restart, A list kept in Storage, Volume up with an on-screen display, A live-updating display message, A Windows notification, List monitors, Engine state, Snippets as reusable functions, Keep an Arduino's port open and send it commands
StringFromNumber
StringFromNumber(number: Any, decimals: Integer, invariantCulture: Bool) → Text
Turns a number into text, either in the user's regional format with digit grouping for display, or in a fixed machine format for files and devices.
Parameters
number: Any— The Integer or Real to convert.decimals: Integer— How many digits after the decimal separator, 0 to 15, rounded; or -1 for as many as the value needs (none for an Integer).invariantCulture: Bool— true for machine text: a period as decimal point, no grouping, readable back with StringToNumber(text, true). false for the user's regional format.
Returns
The number as text, such as 1,234.50 or 1234.5. Empty text if a Real is not a finite number. A value that is not a number, or decimals out of range, stops the action with an error.
1 example: Read a number someone typed
StringGetIndexOf
StringGetIndexOf(text: Text, search: Text) → Integer
Finds where a piece of text first occurs inside another. Upper and lower case must match. Positions start at 0.
Parameters
text: Text— The text to search in.search: Text— The text to look for.
Returns
The 0-based position of the first occurrence, 0 if search is empty, or -1 if search does not occur in text.
1 example: && and || evaluate both sides
StringGetLength
StringGetLength(text: Text) → Integer
Returns the number of characters in text, counting spaces and line breaks. Positions used by StringGetSubstring count the same way.
Parameters
text: Text— The text to measure.
Returns
The character count, or 0 for empty text. Some emoji and rare characters count as 2.
3 examples: Last index of: a file extension, Zero-pad a number, Reverse Text
StringGetSplitPartAt
StringGetSplitPartAt(index: Integer) → Text
Returns one part from the most recent StringSplit call in this run of the script.
Parameters
index: Integer— The 0-based part number, from 0 to the count StringSplit returned minus 1.
Returns
The part's text, or empty text if index is out of range or StringSplit has not been called in this run.
6 examples: break and continue, Split and iterate, Nested splits: key=value pairs, Count words on the clipboard, Join clipboard lines into one line, Read a file and count its lines
StringGetSubstring
StringGetSubstring(text: Text, start: Integer, length: Integer) → Text
Returns part of text: up to length characters, beginning at position start. Positions start at 0.
Parameters
text: Text— The text to take the part from.start: Integer— The 0-based position of the first character to take. Must not be negative.length: Integer— The most characters to take. Must not be negative.
Returns
The requested part, shorter if text ends first, or empty text if start is at or past the end. A negative start or length stops the action with an error.
4 examples: && and || evaluate both sides, Integer to hex text, Last index of: a file extension, Reverse Text
StringIsNumber
StringIsNumber(text: Text, invariantCulture: Bool) → Bool
Checks whether text is a number that StringToNumber can read, such as what a user typed into UIShowInputBox. Spaces around the number are ignored.
Parameters
text: Text— The text to check.invariantCulture: Bool— true for machine text: a period as decimal point and no digit grouping. false for the user's regional format, as a person would type it; digit groups must then follow that format's group sizes.
Returns
true if text is a number in the chosen format; false otherwise, including for empty text.
2 examples: Read a number someone typed, Turn an Arduino knob into a volume control
StringRegexGetGroupAt
StringRegexGetGroupAt(index: Integer) → Text
Returns the whole match or one capture group from the most recent successful StringRegexMatch call in this run of the script.
Parameters
index: Integer— 0 for the whole match; 1 and up for the capture groups, in the order their opening parentheses appear. Named groups are numbered too.
Returns
The matched text, or empty text if index is out of range, the group took no part in the match, or the last StringRegexMatch found no match.
1 example: Pull a value out of copied text with a regex
StringRegexMatch
StringRegexMatch(text: Text, pattern: Text) → Bool
Checks whether a regular expression (PCRE2 syntax) matches anywhere in text, and remembers the match and its groups for StringRegexGetGroupAt.
Parameters
text: Text— The text to search.pattern: Text— The regular expression. Case-sensitive; start it with (?i) to ignore case. Character classes such as word and digit follow Unicode.
Returns
true if the pattern matches; false if not. An invalid pattern, or one that needs too many steps on this text, stops the action with an error.
1 example: Pull a value out of copied text with a regex
StringRegexReplace
StringRegexReplace(text: Text, pattern: Text, replacement: Text) → Text
Replaces every match of a regular expression (PCRE2 syntax) in text, with a replacement that can include the matched groups.
Parameters
text: Text— The text to change.pattern: Text— The regular expression. Case-sensitive; start it with (?i) to ignore case.replacement: Text— The text to put in place of each match. $1 or ${1} inserts group 1, ${name} a named group, $0 the whole match, and $$ a literal dollar sign.
Returns
The text with every match replaced, or text unchanged if nothing matches. An invalid pattern or replacement, too many steps, or a result over 16 million characters stops the action with an error.
1 example: Pull a value out of copied text with a regex
StringReplace
StringReplace(text: Text, search: Text, replacement: Text) → Text
Replaces every occurrence of a piece of text with another. Upper and lower case must match. The search is literal text, not a pattern.
Parameters
text: Text— The text to change.search: Text— The text to find. Must not be empty.replacement: Text— The text to put in its place. May be empty to remove every occurrence.
Returns
The text with every occurrence replaced, or text unchanged if search does not occur. An empty search stops the action with an error.
3 examples: Count words on the clipboard, Fill a template and paste it, Search the web for the selection
StringSplit
StringSplit(text: Text, delimiter: Text) → Integer
Splits text into parts at every occurrence of a delimiter and remembers the parts for StringGetSplitPartAt. Adjacent delimiters, or one at either end, give empty parts.
Parameters
text: Text— The text to split.delimiter: Text— The literal text to split at, such as ',' or a line break. Must not be empty.
Returns
The number of parts, at least 1. An empty delimiter stops the action with an error.
6 examples: break and continue, Split and iterate, Nested splits: key=value pairs, Count words on the clipboard, Join clipboard lines into one line, Read a file and count its lines
StringStartsWith
StringStartsWith(text: Text, prefix: Text) → Bool
Checks whether text begins with a given piece of text. Upper and lower case must match.
Parameters
text: Text— The text to check.prefix: Text— The beginning to look for.
Returns
true if text starts with prefix, or if prefix is empty; false otherwise.
2 examples: break and continue, Read a file and count its lines
StringToLower
StringToLower(text: Text) → Text
Converts text to lowercase, following the casing rules of the user's Windows regional format (for example the Turkish dotted and dotless i).
Parameters
text: Text— The text to convert.
Returns
The lowercase text, or text unchanged if Windows cannot convert it.
4 examples: Case-insensitive comparisons, Text ordering is ordinal, Let an unrecognized drawing through, Count file types in a folder
StringToNumber
StringToNumber(text: Text, invariantCulture: Bool) → Any
Reads a number from text, such as user input, a file or a serial device. Spaces around the number are ignored; an exponent such as 1.5e3 is allowed.
Parameters
text: Text— The text to read.invariantCulture: Bool— true for machine text: a period as decimal point and no digit grouping, so '1,5' is not a number. false for the user's regional format, as a person would type it; digit groups must then follow that format, so '1,234.5' reads in English (United States) but '1,5' does not.
Returns
An Integer if the text has no decimal separator or exponent and fits, otherwise a Real. 0 if the text is not a number; check with StringIsNumber first.
2 examples: Read a number someone typed, Turn an Arduino knob into a volume control
StringToUpper
StringToUpper(text: Text) → Text
Converts text to uppercase, following the casing rules of the user's Windows regional format (for example the Turkish dotted and dotless i).
Parameters
text: Text— The text to convert.
Returns
The uppercase text, or text unchanged if Windows cannot convert it.
2 examples: Uppercase the selected text, Back up a file before editing it
StringTrim
StringTrim(text: Text) → Text
Removes spaces, tabs, line breaks and other white space from the start and end of text. White space inside the text is kept.
Parameters
text: Text— The text to trim.
Returns
The trimmed text, or empty text if text was only white space.
6 examples: Count words on the clipboard, Join clipboard lines into one line, Search the web for the selected text, Search the web for the selection, Read a file and count its lines, Map a serial device's buttons to media keys
StringUrlEncode
StringUrlEncode(text: Text) → Text · Simple
Encodes text so it can go inside a web address, for example a search term built from the selected text. Encode only the value, not the whole address.
Parameters
text: Text— The text to encode, such as a search term.
Returns
The encoded text: letters, digits and - . _ ~ stay as they are; every other byte of the UTF-8 text becomes a percent escape with two hex digits. A space becomes percent 20, not a plus sign.
1 example: Search the web for the selected text
Style
StyleGetCurrent
StyleGetCurrent() → Text · Simple
Returns the key of the trail style the renderer plugin draws now, such as neonglow, or shuffle when Shuffle is selected.
Parameters
No parameters.
Returns
The style's key, the renderer's default style when nothing usable is selected, or empty text when no renderer is running or it has not reported its styles.
StyleNext
StyleNext() → Bool · Simple
Selects the next unlocked trail style in the renderer's list, wrapping around at the end. The new style is drawn from the next gesture.
Parameters
No parameters.
Returns
true if a style change was requested; false when no renderer is running or there is no other style to select.
StyleSet
StyleSet(key: Text) → Bool · Simple
Selects the renderer's trail style with this key, drawn from the next gesture. A draw button that has its own style keeps it.
Parameters
key: Text— The style's key, such as neonglow or auto; not case-sensitive. Use shuffle for a different style on each gesture.
Returns
true if the style change was requested; false if no renderer is running, no style has that key, or the style is locked.
System
SystemHibernate
SystemHibernate() → Bool · Simple
Hibernates the computer without asking. The script waits here and continues after the computer is turned back on. Does nothing if hibernation is turned off in Windows.
Parameters
No parameters.
Returns
true after the computer has hibernated and resumed; false if hibernation is not available or Windows refused.
SystemLock
SystemLock() → Bool · Simple
Locks the computer and shows the Windows sign-in screen, as Windows+L does. Apps keep running.
Parameters
No parameters.
Returns
true if Windows locked the computer; false if Windows refused, for example because a policy disables locking.
SystemMonitorOff
SystemMonitorOff() → Bool · Simple
Turns the monitors off. The next mouse move or key press turns them back on, so a script started by a gesture should call UtilityWait(500) first.
Parameters
No parameters.
Returns
true once the request was sent to Windows; false if it could not be sent.
SystemRestart
SystemRestart(force: Bool) → Bool · Simple
Restarts the computer without asking for confirmation; Windows closes the running apps first. Show UIShowMessageBox first if you want to confirm.
Parameters
force: Bool— false lets apps ask to save unsaved work (only apps that do not respond are closed by force); true closes every app at once and unsaved work is lost.
Returns
true if Windows accepted the restart request (it then proceeds on its own); false if Windows refused it.
SystemShutDown
SystemShutDown(force: Bool) → Bool · Simple
Shuts down and powers off the computer without asking for confirmation. Show UIShowMessageBox first if you want to confirm.
Parameters
force: Bool— false lets apps ask to save unsaved work (only apps that do not respond are closed by force); true closes every app at once and unsaved work is lost.
Returns
true if Windows accepted the shutdown request (it then proceeds on its own); false if Windows refused it.
SystemSignOut
SystemSignOut(force: Bool) → Bool · Simple
Signs the current user out of Windows without asking for confirmation, closing every app and Input.Observer with it.
Parameters
force: Bool— false lets apps ask to save unsaved work (only apps that do not respond are closed by force); true closes every app at once and unsaved work is lost.
Returns
true if Windows accepted the sign-out request (it then proceeds on its own); false if Windows refused it.
SystemSleep
SystemSleep() → Bool · Simple
Puts the computer to sleep without asking. The script waits here and continues after the computer wakes. On a Modern Standby computer this does nothing; use SystemMonitorOff there.
Parameters
No parameters.
Returns
true after the computer has slept and woken up; false if this computer has no sleep state a program can start, or Windows refused.
Timer
TimerCreate
TimerCreate(name: Text, startDelayMs: Integer, intervalMs: Integer, repeatCount: Integer, script: Text) → Bool
Creates a named timer that runs script text after a delay and then at a fixed interval, or replaces the timer with that name. Timers keep running after the script ends, until deleted or the engine exits.
Parameters
name: Text— A name for the timer, used by TimerDelete. Case-sensitive; an existing timer with this name is replaced.startDelayMs: Integer— Delay before the first run, in milliseconds; 0 or more.intervalMs: Integer— Time between runs, in milliseconds; 1 or more. A run does not wait for the previous one to finish.repeatCount: Integer— How many times to run in total; 0 repeats until the timer is deleted.script: Text— The script text to run on each tick. It runs on its own, with no trigger context and none of this script's variables.
Returns
true once the timer is set. A negative startDelayMs or repeatCount, or an intervalMs below 1, stops the script with an error.
2 examples: A repeating timer that counts, Timer script from a snippet, no escaping
TimerDelete
TimerDelete(name: Text) → Bool
Removes the timer with this name so it does not run again.
Parameters
name: Text— The timer's name, as given to TimerCreate. Case-sensitive.
Returns
true if the timer existed and was removed; false if there was no timer with that name.
1 example: List and stop timers
TimerDeleteAll
TimerDeleteAll() → Bool
Removes every timer created with TimerCreate, so none of them run again.
Parameters
No parameters.
Returns
Always true.
1 example: List and stop timers
TimerEnumerateAll
TimerEnumerateAll() → Integer
Takes a list of the names of all current timers and returns how many there are. Read each name with TimerGetEnumeratedNameAt.
Parameters
No parameters.
Returns
The number of timers, or 0 if there are none.
1 example: List and stop timers
TimerGetEnumeratedNameAt
TimerGetEnumeratedNameAt(index: Integer) → Text
Returns one timer name from the list TimerEnumerateAll last took in this script.
Parameters
index: Integer— Zero-based position in the list, from 0 to the count minus 1. The order has no meaning.
Returns
The timer's name, or empty text if index is out of range or TimerEnumerateAll has not been called.
1 example: List and stop timers
Tray
TrayMinimizeWindow
TrayMinimizeWindow(window: Window) → Bool
Hides a window and shows a tray icon for it with the window's own icon and title. Clicking the icon restores the window where it was. A control's top-level window is the one hidden.
Parameters
window: Window— The window to hide, such as ContextGetWindow().
Returns
true if the request was accepted; false for a null window or one that no longer exists.
1 example: Hide a window in the tray
TrayRestoreAllWindows
TrayRestoreAllWindows() → Bool
Restores every window hidden with TrayMinimizeWindow and removes their tray icons.
Parameters
No parameters.
Returns
true if the request was sent; false if the engine has not finished starting.
UI
UIClearPrintLog
UIClearPrintLog() → Bool
Clears the User tab of the diagnostic console, where UtilityPrint output appears, including output saved while the console was closed.
Parameters
No parameters.
Returns
Always true.
UICloseDisplayMessage
UICloseDisplayMessage(sessionId: Integer) → Bool
Closes one on-screen message opened by UIShowDisplayMessage. Does nothing if that message has already closed.
Parameters
sessionId: Integer— The id UIShowDisplayMessage returned for the message to close.
Returns
Always true, including when the message had already closed.
1 example: A live-updating display message
UIGetCulture
UIGetCulture() → Text
Returns the language and region Input.Observer uses for its own text (tray menu, messages, error text), as set by UISetCulture, the language setting, or Windows.
Parameters
No parameters.
Returns
The culture name as it was set, such as en-US or es-ES, even when another region's translation stands in for it.
UISetCulture
UISetCulture(culture: Text) → Bool
Switches the language Input.Observer uses for its own text (tray menu, messages, error text) until it exits or the language setting changes. Does not change the settings window or the saved setting.
Parameters
culture: Text— A culture name such as en-US, de-DE or es-MX.
Returns
true if the culture was applied; false, and the language stays as it was, if culture is not a culture Windows knows or Input.Observer has no translation in its language. Another region of a translated language, such as es-ES, is accepted.
UIShowConsole
UIShowConsole() → Bool
Opens the diagnostic console, or brings it to the front if it is already open, and waits until it is open. If the configuration is password-protected, waits while the password is asked for. Only the console's own close button closes it.
Parameters
No parameters.
Returns
true once the console is open; false if it did not open, for example because the password prompt was cancelled or the console's saved state can't be read.
UIShowDisplayMessage
UIShowDisplayMessage(title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Integer · Simple
Shows a panel with a title line and a message line at a fixed place on the screen, and returns at once. Several can be open together; keep the returned id to update or close this one.
Parameters
title: Text— Text of the top line, drawn with the title font. Empty text leaves the line out.message: Text— Text of the second line, drawn with the message font. Long text wraps onto more lines. Empty text leaves the line out.durationMs: Integer— How long the panel stays, in milliseconds. 0 or less keeps it until UICloseDisplayMessage closes it (the built-in panel also closes on a double-click).opacity: Real— How solid the panel is, from 0.05 (almost invisible) to 1.0 (fully opaque). Values outside that range are clamped.location: Any— Where to show it: a Location constant such as Location.BottomCenter (placed inside the screen area not covered by the taskbar), or Text 'x,y' with no spaces giving the panel's top-left corner in screen pixels, such as '100,200'. Anything else stops the action with an error.titleFontFamily: Text— Font name for the title line, such as Segoe UI.titleFontSizePt: Integer— Title font size in points. Values below 1 count as 1.titleBold: Bool— true to draw the title line in bold.titleItalic: Bool— true to draw the title line in italics.messageFontFamily: Text— Font name for the message line, such as Segoe UI.messageFontSizePt: Integer— Message font size in points. Values below 1 count as 1.messageBold: Bool— true to draw the message line in bold.messageItalic: Bool— true to draw the message line in italics.foreColor: Text— Text color for both lines: a color name such as white or black, '#RRGGBB', or 'R,G,B' with each number 0 to 255 and no spaces. Anything else stops the action with an error.backColor: Text— Background color, in the same forms as foreColor, such as '#F7F7F5'. Use opacity, not the color, to make the panel see-through.paddingPx: Integer— Empty space around the text, in pixels at 100 percent display scaling; it grows with the display scale. Values below 0 count as 0.usePrimaryScreen: Bool— true to place a Location on the primary monitor; false to use the monitor the mouse pointer is on now. Ignored for an 'x,y' location.titleAlign: Integer— How the title line is aligned: TextAlign.Left, TextAlign.Center or TextAlign.Right. Any other value stops the action with an error.messageAlign: Integer— How the message line is aligned: TextAlign.Left, TextAlign.Center or TextAlign.Right. Any other value stops the action with an error.
Returns
The message's session id, always greater than 0, for UIUpdateDisplayMessage and UICloseDisplayMessage. An id is returned even when messages are turned off in settings and nothing appears.
2 examples: Volume up with an on-screen display, A live-updating display message
UIShowInputBox
UIShowInputBox(prompt: Text, title: Text, defaultText: Text) → Text · Simple
Shows a box that asks the user to type one line of text, with OK and Cancel buttons. Blocks the script until the box closes, then returns focus to the window that had it.
Parameters
prompt: Text— The question shown above the text field. Text longer than 2000 characters is cut.title: Text— Title shown in the box's title bar.defaultText: Text— Text already in the field when the box opens, selected so typing replaces it. Use empty text for an empty field.
Returns
The text typed when the user clicks OK (up to 4096 characters), or empty text on Cancel, Esc or the close button. An empty OK also returns empty text.
2 examples: Read a number someone typed, One gesture, several choices
UIShowMenu
UIShowMenu(items: Text) → Integer · Simple
Shows a popup menu at the mouse pointer, so one gesture or hotkey can offer several choices. Blocks the script until the user picks an item or dismisses the menu.
Parameters
items: Text— The menu items, one per line. A line holding only - is a separator; blank lines are skipped. 1 to 100 items, or the action stops with an error; an item longer than 260 characters is cut. Put & before a letter to make it the item's shortcut key; && shows a single &.
Returns
The 0-based position of the chosen item, counting items only (not separators), or -1 if the menu was dismissed or could not be shown.
1 example: One gesture, several choices
UIShowMessageBox
UIShowMessageBox(message: Text, title: Text, buttons: Text, icon: Text) → Text · Simple
Shows a standard Windows message box in front of other windows and waits for the user to press a button. Blocks the script until the box closes.
Parameters
message: Text— The message text shown in the box.title: Text— Title shown in the box's title bar.buttons: Text— Which buttons to show, written exactly: OK, OKCancel, YesNo, YesNoCancel, RetryCancel or AbortRetryIgnore. Anything else stops the action with an error.icon: Text— Which icon to show, written exactly: None, Information, Warning, Error or Question. Anything else stops the action with an error.
Returns
The button pressed: OK, Cancel, Yes, No, Retry, Abort or Ignore (closing the box with Esc or its close button returns Cancel when there is a Cancel button). Empty text if the box could not be shown.
3 examples: Read a number someone typed, Close windows by title pattern, after confirming, Ask a question
UIShowSettings
UIShowSettings() → Bool · Simple
Opens the Input.Observer settings window, or brings it to the front if it is already open. Returns without waiting for the window to finish loading.
Parameters
No parameters.
Returns
true if the settings window was brought forward or started; false if Input.Observer.UI.exe is missing, could not be started, or the engine did not respond within 3 seconds.
UIUpdateDisplayMessage
UIUpdateDisplayMessage(sessionId: Integer, title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Bool
Replaces everything about an open UIShowDisplayMessage panel (text, position, fonts, colors and duration) with new values. The duration starts again from this call.
Parameters
sessionId: Integer— The id UIShowDisplayMessage returned for the message to change.title: Text— New text of the top line, drawn with the title font. Empty text leaves the line out.message: Text— New text of the second line, drawn with the message font. Long text wraps onto more lines. Empty text leaves the line out.durationMs: Integer— How long the panel stays from now, in milliseconds. 0 or less keeps it until UICloseDisplayMessage closes it (the built-in panel also closes on a double-click).opacity: Real— How solid the panel is, from 0.05 (almost invisible) to 1.0 (fully opaque). Values outside that range are clamped.location: Any— Where to show it: a Location constant such as Location.BottomCenter (placed inside the screen area not covered by the taskbar), or Text 'x,y' with no spaces giving the panel's top-left corner in screen pixels, such as '100,200'. Anything else stops the action with an error.titleFontFamily: Text— Font name for the title line, such as Segoe UI.titleFontSizePt: Integer— Title font size in points. Values below 1 count as 1.titleBold: Bool— true to draw the title line in bold.titleItalic: Bool— true to draw the title line in italics.messageFontFamily: Text— Font name for the message line, such as Segoe UI.messageFontSizePt: Integer— Message font size in points. Values below 1 count as 1.messageBold: Bool— true to draw the message line in bold.messageItalic: Bool— true to draw the message line in italics.foreColor: Text— Text color for both lines: a color name such as white or black, '#RRGGBB', or 'R,G,B' with each number 0 to 255 and no spaces. Anything else stops the action with an error.backColor: Text— Background color, in the same forms as foreColor, such as '#F7F7F5'. Use opacity, not the color, to make the panel see-through.paddingPx: Integer— Empty space around the text, in pixels at 100 percent display scaling; it grows with the display scale. Values below 0 count as 0.usePrimaryScreen: Bool— true to place a Location on the primary monitor; false to use the monitor the mouse pointer is on now. Ignored for an 'x,y' location.titleAlign: Integer— How the title line is aligned: TextAlign.Left, TextAlign.Center or TextAlign.Right. Any other value stops the action with an error.messageAlign: Integer— How the message line is aligned: TextAlign.Left, TextAlign.Center or TextAlign.Right. Any other value stops the action with an error.
Returns
Always true, including when the message had already closed (the call then does nothing).
1 example: A live-updating display message
Utility
UtilityGetTickCount
UtilityGetTickCount() → Integer
Returns the number of milliseconds since Windows started. Subtract two readings to measure elapsed time, for example to detect a double trigger. It is not a clock; use DateTimeGetNow for the time of day.
Parameters
No parameters.
Returns
Milliseconds since Windows started, as an Integer.
UtilityLockAcquire
UtilityLockAcquire(name: Text, timeoutSeconds: Integer) → Integer
Takes a named lock so only one action at a time runs a section of script. Blocks the script until the lock is free or timeoutSeconds passes. The lock is released automatically when the script ends.
Parameters
name: Text— The lock's name, 1 to 255 characters, shared by all actions; upper and lower case are the same. Taking a lock this script already holds again is allowed and needs one more UtilityLockRelease.timeoutSeconds: Integer— The longest time to wait, in seconds. 0, or more than 24 days, waits until the lock is free or the action is stopped. A negative value stops the action with an error.
Returns
LockResult.Acquired, LockResult.TimedOut (also when the action is stopped while waiting), or LockResult.Pinned at once if the lock is pinned.
1 example: Let only one action run a section at a time
UtilityLockAcquirePinned
UtilityLockAcquirePinned(name: Text, timeoutSeconds: Integer) → Integer
Takes a named lock and pins it, so it stays taken after the script ends. Only UtilityLockRelease from this same script run, or a configuration reload, frees it. Blocks like UtilityLockAcquire.
Parameters
name: Text— The lock's name, 1 to 255 characters, shared by all actions; upper and lower case are the same. A lock this script already holds becomes pinned.timeoutSeconds: Integer— The longest time to wait, in seconds. 0, or more than 24 days, waits until the lock is free or the action is stopped. A negative value stops the action with an error.
Returns
LockResult.Acquired, LockResult.TimedOut (also when the action is stopped while waiting), or LockResult.Pinned at once if the lock is already pinned.
UtilityLockGetState
UtilityLockGetState(name: Text) → Integer
Reports whether a named lock is free, held by this script, held by another action, or pinned. Never waits.
Parameters
name: Text— The lock's name, 1 to 255 characters; upper and lower case are the same.
Returns
LockState.Free, LockState.HeldByMe, LockState.HeldByOther or LockState.Pinned. A pinned lock reports LockState.Pinned even to the script that pinned it.
UtilityLockRelease
UtilityLockRelease(name: Text) → Bool
Releases a named lock this script holds, or removes its pin. A lock taken several times is freed after the same number of releases.
Parameters
name: Text— The lock's name, 1 to 255 characters; upper and lower case are the same.
Returns
true if this script held the lock; false, doing nothing, if nobody holds it or another action does.
1 example: Let only one action run a section at a time
UtilityPrint
UtilityPrint(text: Text) → Bool
Writes a line of text to the User section of the diagnostic console, or to the Script section's output when the script runs from there. Lines printed while the console is closed appear when it next opens.
Parameters
text: Text— The text to write. Turn a number into Text first with StringFormat or StringFromNumber.
Returns
Always true.
70 examples: Hello, console, The five value kinds, Truthiness of every kind, else-if chain, Counting loops: up, down and by steps, Nested loops: a multiplication table, while loop: wait for a window, with a timeout, while (true) with an exit flag, break and continue, Precedence surprises, && and || evaluate both sides, Equality across kinds, Mixed-type arithmetic falls back to 0, Comments, blank statements and blocks, Integer vs Real division, and dividing by zero, Remainder without %, Rounding and Real math builtins, Clamp a value to a range, Random numbers and a coin flip, Length of a gesture stroke, Formatting a Real without six decimals, Flag masks: set, clear, toggle, test, Read the pixel color under the cursor, Integer to hex text, Count the set bits, Shift edge cases, Swap two Integers, Key state bits, String escapes and Windows paths, Formatting more than two values, Split and iterate, Nested splits: key=value pairs, Last index of: a file extension, Read a number someone typed, Launch a program, wait for its window, act on it, Pull a value out of copied text with a regex, Zero-pad a number, Reverse Text, Count words on the clipboard, Case-insensitive comparisons, Text ordering is ordinal, Today's date, and a timestamped file name, Named constants vs raw numbers, List visible top-level windows, Minimize every window of one app, Inspect a window's child controls, From process to window, Describe what's under the cursor, Everything the trigger context knows, Which way did the stroke go?, Branch on the stroke button, Save a copied image to a file, Read a file and count its lines, Count file types in a folder, Watch a folder, A repeating timer that counts, List and stop timers, A counter that survives a restart, A list kept in Storage, Let only one action run a section at a time, Ask a question, Expand environment variables, Hand off to AutoHotkey, List monitors, Engine state, Snippets as reusable functions, Talk to a plugin, Ask a serial device a question, List the COM ports, Keep an Arduino's port open and send it commands
UtilityWait
UtilityWait(milliseconds: Integer) → Bool · Simple
Pauses the script for a number of milliseconds, for example to let a window or the clipboard catch up. The wait ends early if the action is stopped.
Parameters
milliseconds: Integer— How long to wait, in milliseconds, from 0 to 60000 (one minute). Larger values wait one minute; negative values do not wait.
Returns
Always true.
10 examples: while loop: wait for a window, with a timeout, Move the mouse in a circle, Fill a template and paste it, Click somewhere, then put the cursor back, A scripted drag, Confine the cursor to a window for 5 seconds, Media keys, Uppercase the selected text, Search the web for the selection, A live-updating display message
Window
WindowCenterToScreen
WindowCenterToScreen(window: Window) → Bool · Simple
Moves a window so it is centered in the work area (the screen minus the taskbar) of the monitor it is on, keeping its size.
Parameters
window: Window— The window to center.
Returns
true if the window moved; false if the window is null or closed, or refused to move.
2 examples: while loop: wait for a window, with a timeout, Remember and restore a window's position
WindowClipToScreen
WindowClipToScreen(window: Window) → Bool
Shrinks and moves a window just enough that no edge sticks out past the work area (the screen minus the taskbar) of the monitor it is on. A window entirely outside the work area is first moved onto it at its current size.
Parameters
window: Window— The window to clip to the work area.
Returns
true if the window was placed, including when it was already inside the work area; false if the window is null or closed, or refused the change.
WindowClose
WindowClose(window: Window) → Bool · Simple
Asks a window to close, as if the user clicked its close button. The program may ask to save changes or refuse; use WindowWaitClose to wait until it is gone.
Parameters
window: Window— The window to close.
Returns
true if the close request was sent, which does not mean the window has closed; false if the window is null or closed, or belongs to a program running with higher rights, such as as administrator.
3 examples: Close windows by title pattern, after confirming, Branch on the stroke button, Change behavior while Ctrl is held
WindowContainsTitle
WindowContainsTitle(window: Window, text: Text) → Bool
Checks whether a window's title contains some text, ignoring letter case.
Parameters
window: Window— The window whose title to check.text: Text— The text to look for anywhere in the title. Letter case is ignored.
Returns
true if the title contains text, and always true when text is empty; otherwise false, including for a null or closed window.
WindowControlFromPoint
WindowControlFromPoint(x: Integer, y: Integer) → Window
Returns the innermost window at a screen point, such as a button, text box or other control inside a program's window. Hidden and disabled windows are skipped.
Parameters
x: Integer— Horizontal screen position, in virtual-screen pixels.y: Integer— Vertical screen position, in virtual-screen pixels.
Returns
The control or window under the point, or a null window if there is none.
1 example: Describe what's under the cursor
WindowEnsureVisible
WindowEnsureVisible(window: Window) → Bool
Slides a window fully onto the work area of the monitor it is on, without resizing it. A window larger than the work area is lined up with the work area's top-left corner.
Parameters
window: Window— The window to bring fully onto the screen.
Returns
true if the window was placed, including when it was already fully visible; false if the window is null or closed, or refused to move.
WindowFindAllByModuleRegex
WindowFindAllByModuleRegex(pattern: Text) → Integer
Finds every top-level window, hidden ones included, whose program file path matches a regular expression, and keeps the list for WindowGetEnumeratedAt. Replaces any earlier window list.
Parameters
pattern: Text— A regular expression matched, ignoring letter case, against the full path of the program that owns each window, such as 'notepad[.]exe$'.
Returns
The number of matching windows, or 0 if none match. An invalid pattern stops the action with an error.
1 example: Minimize every window of one app
WindowFindAllByTitleRegex
WindowFindAllByTitleRegex(pattern: Text) → Integer
Finds every top-level window, hidden ones included, whose title matches a regular expression, and keeps the list for WindowGetEnumeratedAt. Replaces any earlier window list.
Parameters
pattern: Text— A regular expression matched against each window's title, ignoring letter case. It matches anywhere in the title unless anchored with ^ or $.
Returns
The number of matching windows, or 0 if none match. An invalid pattern stops the action with an error.
1 example: Close windows by title pattern, after confirming
WindowFindByClassName
WindowFindByClassName(className: Text) → Window
Finds the frontmost visible top-level window whose class name contains the given text, ignoring letter case.
Parameters
className: Text— Text to look for in the class name, such as 'Notepad'. Part of a name matches; empty text matches the frontmost visible window.
Returns
The window found, or a null window if no visible top-level window matches.
WindowFindByTitle
WindowFindByTitle(title: Text) → Window
Finds the frontmost visible top-level window whose title contains the given text, ignoring letter case.
Parameters
title: Text— Text to look for anywhere in the title. Letter case is ignored; empty text matches the frontmost visible window.
Returns
The window found, or a null window if no visible top-level window matches.
4 examples: Truthiness of every kind, while loop: wait for a window, with a timeout, Equality across kinds, Click a point inside a window
WindowFitToScreen
WindowFitToScreen(window: Window) → Bool · Simple
Resizes and moves a window so its visible edges fill the work area (the screen minus the taskbar) of the monitor it is on, without maximizing it.
Parameters
window: Window— The window to fit to the work area.
Returns
true if the window was resized; false if the window is null or closed, or refused the change.
WindowFromPoint
WindowFromPoint(x: Integer, y: Integer) → Window
Returns the top-level window at a screen point, such as the program window under the mouse, rather than the control inside it.
Parameters
x: Integer— Horizontal screen position, in virtual-screen pixels.y: Integer— Vertical screen position, in virtual-screen pixels.
Returns
The top-level window under the point, or a null window if there is none.
WindowFromProcessId
WindowFromProcessId(processId: Integer) → Window
Returns the main window of a running program: the frontmost visible top-level window owned by that process.
Parameters
processId: Integer— The process ID, as returned by WindowGetProcessId or ShellGetEnumeratedProcessIdAt.
Returns
The window, or a null window if the process has no visible top-level window or processId is 0.
1 example: From process to window
WindowGetActive
WindowGetActive() → Window
Returns the foreground window: the top-level window the user is currently working in.
Parameters
No parameters.
Returns
The active window, or a null window if no window is active at that moment, for example while focus is changing.
4 examples: The five value kinds, Formatting more than two values, Case-insensitive comparisons, Snap the active window to the left half of its monitor
WindowGetAllChildren
WindowGetAllChildren(window: Window, directOnly: Bool) → Integer
Lists the child windows (controls) inside a window and keeps the list for WindowGetEnumeratedAt. Replaces any earlier window list.
Parameters
window: Window— The window whose child windows to list.directOnly: Bool— true for only the window's immediate children; false for all descendants at every depth.
Returns
The number of child windows found, or 0 if there are none or the window is null.
1 example: Inspect a window's child controls
WindowGetAllProps
WindowGetAllProps(window: Window) → Integer
Lists every property stored on a window, by this engine, the program itself or other software, and keeps the list for WindowGetEnumeratedPropNameAt and WindowGetEnumeratedPropValueAt.
Parameters
window: Window— The window whose properties to list.
Returns
The number of properties found, or 0 if there are none or the window is null.
WindowGetAllTopLevel
WindowGetAllTopLevel() → Integer
Lists every top-level window on the desktop, front to back, including hidden and cloaked ones, and keeps the list for WindowGetEnumeratedAt. Replaces any earlier window list.
Parameters
No parameters.
Returns
The number of top-level windows found.
1 example: List visible top-level windows
WindowGetAlpha
WindowGetAlpha(window: Window) → Integer
Returns a window's transparency level, as set by WindowSetAlpha or by the program itself.
Parameters
window: Window— The window to read.
Returns
A value from 0 (fully transparent) to 255 (fully opaque). 255 for a window with no transparency set, and for a null or closed window.
1 example: Cycle window transparency
WindowGetClassName
WindowGetClassName(window: Window) → Text
Returns a window's class name, the type name Windows uses for it, such as 'Notepad' or 'Button'. Useful for recognizing windows whose titles change.
Parameters
window: Window— The window to read.
Returns
The class name, or empty text if the window is null or closed.
2 examples: Inspect a window's child controls, Describe what's under the cursor
WindowGetControlText
WindowGetControlText(window: Window) → Text
Reads the text of a control in any program, such as a text box, status bar or dialog message. Works with classic Windows controls only. Blocks the script for up to 2 seconds if the program does not respond.
Parameters
window: Window— The control or window to read, for example from WindowControlFromPoint or WindowGetEnumeratedAt.
Returns
The control's text, up to about one million characters, or empty text if it has none, the window is null or closed, or the program did not respond. Another program's password box gives empty text.
WindowGetDpi
WindowGetDpi(window: Window) → Integer
Returns the DPI of the monitor a window is on: 96 at 100 percent display scaling, 144 at 150 percent.
Parameters
window: Window— The window to check.
Returns
The DPI, or 0 if the window is null or closed.
WindowGetEnabled
WindowGetEnabled(window: Window) → Bool
Checks whether a window accepts mouse and keyboard input. A disabled window or control is usually shown grayed out.
Parameters
window: Window— The window to check.
Returns
true if the window is enabled; false if it is disabled, null or closed.
WindowGetEnumeratedAt
WindowGetEnumeratedAt(index: Integer) → Window
Returns one window from the list built by the most recent WindowGetAllTopLevel, WindowGetAllChildren, WindowFindAllByTitleRegex or WindowFindAllByModuleRegex call.
Parameters
index: Integer— Position in the list, from 0 up to the count the listing call returned minus 1.
Returns
The window at that position, or a null window if index is out of range.
4 examples: List visible top-level windows, Minimize every window of one app, Close windows by title pattern, after confirming, Inspect a window's child controls
WindowGetEnumeratedPropNameAt
WindowGetEnumeratedPropNameAt(index: Integer) → Text
Returns the name of one property from the list built by the most recent WindowGetAllProps call.
Parameters
index: Integer— Position in the list, from 0 up to the count WindowGetAllProps returned minus 1.
Returns
The property name, or empty text if index is out of range.
WindowGetEnumeratedPropValueAt
WindowGetEnumeratedPropValueAt(index: Integer) → Integer
Returns the raw integer value of one property from the list built by the most recent WindowGetAllProps call. A property set with WindowSetPropertyText shows an internal number here, not its text.
Parameters
index: Integer— Position in the list, from 0 up to the count WindowGetAllProps returned minus 1.
Returns
The property's value, or 0 if index is out of range.
WindowGetExecutableFolder
WindowGetExecutableFolder(window: Window) → Text
Returns the folder that contains the program owning a window, without the file name and without a trailing separator. Use WindowGetExecutableName for the file name, or WindowGetExecutableFullPath for both.
Parameters
window: Window— The window whose program to locate.
Returns
The folder path, or empty text if the window is null or closed or the program cannot be queried.
WindowGetExecutableFullPath
WindowGetExecutableFullPath(window: Window) → Text
Returns the full path of the program that owns a window, folder and file name together, such as the path of notepad.exe in the Windows folder. Use WindowGetExecutableFolder or WindowGetExecutableName for one part.
Parameters
window: Window— The window whose program to locate.
Returns
The full path, or empty text if the window is null or closed or the program cannot be queried.
WindowGetExecutableName
WindowGetExecutableName(window: Window) → Text
Returns the file name of the program that owns a window, such as 'notepad.exe'.
Parameters
window: Window— The window whose program to identify.
Returns
The program's file name, or empty text if the window is null or closed or the program cannot be queried.
2 examples: Case-insensitive comparisons, List visible top-level windows
WindowGetHeight
WindowGetHeight(window: Window) → Integer
Returns a window's visible height, excluding the invisible resize border Windows adds around most windows.
Parameters
window: Window— The window to measure.
Returns
The height in pixels, or 0 if the window is null or closed.
3 examples: Formatting more than two values, Snap the active window to the left half of its monitor, Confine the cursor to a window for 5 seconds
WindowGetLastFocus
WindowGetLastFocus() → Window
Returns the window or control that most recently received keyboard focus anywhere on the desktop. Often a control such as a text box rather than its top-level window.
Parameters
No parameters.
Returns
The last focused window or control, or a null window if focus has not changed since the engine started.
WindowGetMovableAncestor
WindowGetMovableAncestor(window: Window) → Window
Returns the nearest window that can be dragged: the window itself or the first parent above it that has a system menu. Turns a control under the mouse into the window to move.
Parameters
window: Window— The window or control to start from.
Returns
The window itself or the first parent with a system menu, or a null window if none has one or the window is null.
WindowGetParent
WindowGetParent(window: Window) → Window
Returns the window that contains a control. For a pop-up window such as a dialog, this can be the window that owns it.
Parameters
window: Window— The window or control whose parent to get.
Returns
The parent or owner window, or a null window if there is none or the window is null or closed.
WindowGetProcessId
WindowGetProcessId(window: Window) → Integer
Returns the ID of the process (the running program) that owns a window, the same number Task Manager shows.
Parameters
window: Window— The window whose process to identify.
Returns
The process ID, or 0 if the window is null or closed.
WindowGetPropertyInteger
WindowGetPropertyInteger(window: Window, name: Text) → Integer
Reads a named integer stored on a window, for example one stored earlier with WindowSetPropertyInteger to remember something about that window.
Parameters
window: Window— The window to read from.name: Text— The property name.
Returns
The stored value, or 0 if the property does not exist or the window is null. A stored 0 looks the same as a missing property.
2 examples: Pin a window on top, Remember and restore a window's position
WindowGetPropertyText
WindowGetPropertyText(window: Window, name: Text) → Text
Reads a named text value this engine stored on a window with WindowSetPropertyText.
Parameters
window: Window— The window to read from.name: Text— The property name.
Returns
The stored text, or empty text if the property does not exist, was not stored as text by this engine, has been overwritten since, or the window is null.
WindowGetRoot
WindowGetRoot(window: Window) → Window
Returns the top-level window that contains a window or control, such as the program window around a button.
Parameters
window: Window— The window or control to start from.
Returns
The top-level window, which is the window itself if it is already top-level; a null window if the window is null or closed.
1 example: Describe what's under the cursor
WindowGetTitle
WindowGetTitle(window: Window) → Text
Returns the text in a window's title bar. For controls in other programs this is usually empty; use WindowGetControlText for those.
Parameters
window: Window— The window to read.
Returns
The title, or empty text if the window has none or is null or closed.
9 examples: Case-insensitive comparisons, One gesture, several choices, Pin a window on top, List visible top-level windows, Inspect a window's child controls, From process to window, Describe what's under the cursor, Everything the trigger context knows, A list kept in Storage
WindowGetVisible
WindowGetVisible(window: Window) → Bool
Checks whether a window is set to be shown. A visible window can still be minimized, covered by other windows, off screen or on another virtual desktop.
Parameters
window: Window— The window to check.
Returns
true if the window and all its parents are shown; false if it is hidden, null or closed.
1 example: List visible top-level windows
WindowGetWidth
WindowGetWidth(window: Window) → Integer
Returns a window's visible width, excluding the invisible resize border Windows adds around most windows.
Parameters
window: Window— The window to measure.
Returns
The width in pixels, or 0 if the window is null or closed.
3 examples: Formatting more than two values, Snap the active window to the left half of its monitor, Confine the cursor to a window for 5 seconds
WindowGetX
WindowGetX(window: Window) → Integer
Returns the screen position of a window's visible left edge, excluding the invisible resize border. For a minimized window this is an off-screen parking position.
Parameters
window: Window— The window to locate.
Returns
The left edge, in virtual-screen pixels, or 0 if the window is null or closed.
4 examples: Formatting more than two values, Snap the active window to the left half of its monitor, Remember and restore a window's position, Confine the cursor to a window for 5 seconds
WindowGetY
WindowGetY(window: Window) → Integer
Returns the screen position of a window's visible top edge, excluding the invisible resize border. For a minimized window this is an off-screen parking position.
Parameters
window: Window— The window to locate.
Returns
The top edge, in virtual-screen pixels, or 0 if the window is null or closed.
4 examples: Formatting more than two values, Snap the active window to the left half of its monitor, Remember and restore a window's position, Confine the cursor to a window for 5 seconds
WindowHide
WindowHide(window: Window) → Bool
Hides a window completely, taskbar button included. The engine shows it again when it exits, and the tray menu's Show Hidden Windows brings it back at any time.
Parameters
window: Window— The window to hide.
Returns
true if the window was hidden or was already hidden; false if it is null or closed, is the desktop, the taskbar or one of this engine's own windows, or 256 hidden windows are already tracked.
WindowIsCloaked
WindowIsCloaked(window: Window) → Bool
Checks whether Windows keeps a window out of sight even though it counts as shown, for example a window on another virtual desktop or a suspended Store app. Useful to skip such windows in a list.
Parameters
window: Window— The window to check.
Returns
true if the window is cloaked; false if it is not, or the window is null or closed.
1 example: List visible top-level windows
WindowIsMaximized
WindowIsMaximized(window: Window) → Bool
Checks whether a window is maximized, for example before deciding whether to call WindowRestore or WindowMaximize.
Parameters
window: Window— The window to check.
Returns
true if the window is maximized; false if it is not, or the window is null or closed.
1 example: Toggle maximize for the gesture's window
WindowIsMinimized
WindowIsMinimized(window: Window) → Bool
Checks whether a window is minimized to the taskbar, for example before deciding whether to call WindowRestore.
Parameters
window: Window— The window to check.
Returns
true if the window is minimized; false if it is not, or the window is null or closed.
WindowMapClientPointToScreenX
WindowMapClientPointToScreenX(window: Window, x: Integer, y: Integer) → Integer
Converts a point in a window's client area (the inside of the window, below the title bar and within the borders) to a screen position and returns its horizontal part.
Parameters
window: Window— The window whose client area the point is in.x: Integer— Horizontal position from the left edge of the client area, in pixels.y: Integer— Vertical position from the top edge of the client area, in pixels.
Returns
The screen X position, in virtual-screen pixels, or 0 if the window is null or closed.
WindowMapClientPointToScreenY
WindowMapClientPointToScreenY(window: Window, x: Integer, y: Integer) → Integer
Converts a point in a window's client area (the inside of the window, below the title bar and within the borders) to a screen position and returns its vertical part.
Parameters
window: Window— The window whose client area the point is in.x: Integer— Horizontal position from the left edge of the client area, in pixels.y: Integer— Vertical position from the top edge of the client area, in pixels.
Returns
The screen Y position, in virtual-screen pixels, or 0 if the window is null or closed.
WindowMapScreenPointToClientX
WindowMapScreenPointToClientX(window: Window, x: Integer, y: Integer) → Integer
Converts a screen position to a point relative to a window's client area (the inside of the window, below the title bar and within the borders) and returns its horizontal part.
Parameters
window: Window— The window whose client area to measure from.x: Integer— Horizontal screen position, in virtual-screen pixels.y: Integer— Vertical screen position, in virtual-screen pixels.
Returns
The X position from the client area's left edge, in pixels; negative if the point is left of it. 0 if the window is null or closed.
1 example: Describe what's under the cursor
WindowMapScreenPointToClientY
WindowMapScreenPointToClientY(window: Window, x: Integer, y: Integer) → Integer
Converts a screen position to a point relative to a window's client area (the inside of the window, below the title bar and within the borders) and returns its vertical part.
Parameters
window: Window— The window whose client area to measure from.x: Integer— Horizontal screen position, in virtual-screen pixels.y: Integer— Vertical screen position, in virtual-screen pixels.
Returns
The Y position from the client area's top edge, in pixels; negative if the point is above it. 0 if the window is null or closed.
1 example: Describe what's under the cursor
WindowMaximize
WindowMaximize(window: Window) → Bool · Simple
Maximizes a window so it fills the monitor it is on, and activates it. A window hidden with WindowHide is shown and no longer tracked as hidden.
Parameters
window: Window— The window to maximize.
Returns
true if the window is maximized afterwards; false if the window is null or closed, or did not maximize.
2 examples: One gesture, several choices, Toggle maximize for the gesture's window
WindowMinimize
WindowMinimize(window: Window) → Bool · Simple
Minimizes a window to the taskbar. Windows then activates the next window. A window hidden with WindowHide is shown minimized and no longer tracked as hidden.
Parameters
window: Window— The window to minimize.
Returns
true if the window is minimized afterwards; false if the window is null or closed, or did not minimize.
4 examples: One gesture, several choices, Minimize every window of one app, Branch on the stroke button, Change behavior while Ctrl is held
WindowMoveTo
WindowMoveTo(window: Window, x: Integer, y: Integer) → Bool
Moves a window so its visible top-left corner is at a screen position, keeping its size. Uses the same coordinates as WindowGetX and WindowGetY; a maximized window is not restored first.
Parameters
window: Window— The window to move.x: Integer— New left edge of the visible frame, in virtual-screen pixels.y: Integer— New top edge of the visible frame, in virtual-screen pixels.
Returns
true if the window moved; false if the window is null or closed, or refused to move.
3 examples: Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor, Remember and restore a window's position
WindowRemoveProp
WindowRemoveProp(window: Window, name: Text) → Integer
Removes a named property from a window, whether it was stored with WindowSetPropertyInteger, WindowSetPropertyText or by other software.
Parameters
window: Window— The window to remove the property from.name: Text— The property name.
Returns
The removed property's raw value, or 0 if it did not exist or the window is null. For a text property this is an internal number, not the text.
2 examples: Pin a window on top, Remember and restore a window's position
WindowResizeTo
WindowResizeTo(window: Window, width: Integer, height: Integer) → Bool
Resizes a window's visible frame, keeping its top-left corner in place. Uses the same size as WindowGetWidth and WindowGetHeight; a maximized window is not restored first.
Parameters
window: Window— The window to resize.width: Integer— New visible width, in pixels.height: Integer— New visible height, in pixels.
Returns
true if the window was resized; false if the window is null or closed, or refused the change.
2 examples: Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
WindowRestore
WindowRestore(window: Window) → Bool · Simple
Returns a minimized or maximized window to its normal size and position, and activates it. A window hidden with WindowHide is shown and no longer tracked as hidden.
Parameters
window: Window— The window to restore.
Returns
true if the window ends at its normal size, neither minimized nor maximized; false if the window is null or closed, or did not get there. A minimized window that was maximized before returns to maximized, which counts as false.
3 examples: Toggle maximize for the gesture's window, Snap the active window to the left half of its monitor, Snap a window into a 3×2 grid cell under the cursor
WindowSendToBottom
WindowSendToBottom(window: Window) → Bool · Simple
Moves a window behind all other windows without activating it. A window that was always on top loses that setting.
Parameters
window: Window— The window to send to the back.
Returns
true if the window was moved to the back; false if the window is null or closed, or refused the change.
WindowSendToMonitorAt
WindowSendToMonitorAt(window: Window, x: Integer, y: Integer, mouseFollows: Bool) → Bool
Moves a window to the monitor that contains a screen point, keeping its size and its position relative to the work area. A maximized window ends up maximized on the new monitor; if that activates it, the window that was active before gets the focus back when Windows allows.
Parameters
window: Window— The window to move.x: Integer— Horizontal position of any point on the target monitor, in virtual-screen pixels. A point off every monitor picks the nearest monitor.y: Integer— Vertical position of any point on the target monitor, in virtual-screen pixels.mouseFollows: Bool— true to move the mouse pointer to the same relative spot on the new monitor when the window moves; false to leave it where it is.
Returns
true if the window moved; false if the window is null or closed, or refused to move.
WindowSendToMonitorIndex
WindowSendToMonitorIndex(window: Window, index: Integer, mouseFollows: Bool) → Bool
Moves a window to a monitor chosen by its position in the list from the most recent DisplayMonitorEnumeratedAll call, keeping its size and relative position. A maximized window stays maximized; if maximizing it again activates it, the window that was active before gets the focus back when Windows allows.
Parameters
window: Window— The window to move.index: Integer— Position in the monitor list, starting at 0. Monitors are ordered left to right, then top to bottom.mouseFollows: Bool— true to move the mouse pointer to the same relative spot on the new monitor when the window moves; false to leave it where it is.
Returns
true if the window moved; false if the window is null or closed, index is out of range or DisplayMonitorEnumeratedAll has not run in this script, or the window refused to move.
1 example: Send a window to a specific monitor
WindowSendToMonitorName
WindowSendToMonitorName(window: Window, name: Text, mouseFollows: Bool) → Bool
Moves a window to the monitor with a given device path or friendly name, keeping its size and relative position. A maximized window stays maximized; if maximizing it again activates it, the window that was active before gets the focus back when Windows allows. Useful for layouts that survive docking and undocking.
Parameters
window: Window— The window to move.name: Text— The monitor's device path or friendly name, as returned by DisplayMonitorGetDevicePathFromPoint or DisplayMonitorGetFriendlyNameFromPoint. The device path is the reliable choice. Letter case is ignored.mouseFollows: Bool— true to move the mouse pointer to the same relative spot on the new monitor when the window moves; false to leave it where it is.
Returns
true if the window moved; false if no connected monitor has that name, the window is null or closed, or the window refused to move.
WindowSendToNextScreen
WindowSendToNextScreen(window: Window, mouseFollows: Bool) → Bool · Simple
Moves a window to the next monitor, going left to right then top to bottom and wrapping from the last to the first, keeping its size and relative position. A maximized window stays maximized; if maximizing it again activates it, the window that was active before gets the focus back when Windows allows.
Parameters
window: Window— The window to move.mouseFollows: Bool— true to move the mouse pointer to the same relative spot on the new monitor when the window moves; false to leave it where it is.
Returns
true if the window moved, including when there is only one monitor; false if the window is null or closed, or refused to move.
2 examples: Throw a window to the next monitor, Send a window to a specific monitor
WindowSendToPreviousScreen
WindowSendToPreviousScreen(window: Window, mouseFollows: Bool) → Bool · Simple
Moves a window to the previous monitor, going right to left then bottom to top and wrapping from the first to the last, keeping its size and relative position. A maximized window stays maximized; if maximizing it again activates it, the window that was active before gets the focus back when Windows allows.
Parameters
window: Window— The window to move.mouseFollows: Bool— true to move the mouse pointer to the same relative spot on the new monitor when the window moves; false to leave it where it is.
Returns
true if the window moved, including when there is only one monitor; false if the window is null or closed, or refused to move.
WindowSetActive
WindowSetActive(window: Window) → Bool
Brings a window to the front and gives it keyboard focus, restoring it first if minimized and showing it if hidden. A window hidden with WindowHide is no longer tracked as hidden. Windows may refuse and flash its taskbar button instead.
Parameters
window: Window— The window to activate.
Returns
true if the window became the foreground window; false if Windows refused, or the window is null or closed.
2 examples: Launch a program, wait for its window, act on it, Click a point inside a window
WindowSetAlpha
WindowSetAlpha(window: Window, alpha: Integer) → Bool
Sets how transparent a window is, from fully transparent to fully opaque. At 255 the window stops being a layered window, which also removes any transparency the program set itself. Windows of programs running as administrator cannot be changed unless the engine is too.
Parameters
window: Window— The window to change.alpha: Integer— Opacity from 0 (fully transparent) to 255 (fully opaque). Values outside that range are clamped to it.
Returns
true if the transparency was applied; false if the window is null or closed, or the change was refused.
1 example: Cycle window transparency
WindowSetBounds
WindowSetBounds(window: Window, x: Integer, y: Integer, width: Integer, height: Integer) → Bool
Moves and resizes a window in one step, using the same visible-frame coordinates as WindowGetX, WindowGetY, WindowGetWidth and WindowGetHeight. Avoids the flicker of WindowMoveTo followed by WindowResizeTo.
Parameters
window: Window— The window to move and resize.x: Integer— New left edge of the visible frame, in virtual-screen pixels.y: Integer— New top edge of the visible frame, in virtual-screen pixels.width: Integer— New visible width, in pixels.height: Integer— New visible height, in pixels.
Returns
true if the change was applied; false if the window is null or closed, or refused the change.
WindowSetEnabled
WindowSetEnabled(window: Window, enabled: Bool) → Bool
Enables or disables a window or control. A disabled window ignores mouse clicks and key presses until it is enabled again.
Parameters
window: Window— The window or control to change.enabled: Bool— true to enable the window; false to disable it.
Returns
true once the request is made; false if the window is null or closed.
WindowSetPropertyInteger
WindowSetPropertyInteger(window: Window, name: Text, value: Integer) → Bool
Stores a named integer on a window, for example to remember something about that window between actions. The engine removes the properties it stored when it exits.
Parameters
window: Window— The window to store the value on.name: Text— The property name. Choose a distinctive name so it does not clash with properties the program uses itself.value: Integer— The integer to store.
Returns
true if the value was stored; false if the window is null or closed.
2 examples: Pin a window on top, Remember and restore a window's position
WindowSetPropertyText
WindowSetPropertyText(window: Window, name: Text, value: Text) → Bool
Stores a named text value on a window, read back with WindowGetPropertyText. The engine keeps the text exactly as given, letter case included, and it may be empty. The engine removes the properties it stored when it exits.
Parameters
window: Window— The window to store the text on.name: Text— The property name. Choose a distinctive name so it does not clash with properties the program uses itself.value: Text— The text to store, at most 1024 characters.
Returns
true if the text was stored; false if the window is null or closed, 512 text values are already stored, or the property could not be set. Text over 1024 characters stops the action with an error.
WindowSetTitle
WindowSetTitle(window: Window, title: Text) → Bool
Changes the text in a window's title bar. The program may change it back at any time. A program that does not respond within 1 second is left unchanged.
Parameters
window: Window— The window to rename.title: Text— The new title text.
Returns
true if the title was set; false if the window is null or closed, did not respond within 1 second, or the program refused.
1 example: One gesture, several choices
WindowSetTopmost
WindowSetTopmost(window: Window, topmost: Bool) → Bool · Simple
Keeps a window on top of all normal windows, or returns it to normal stacking, without activating it.
Parameters
window: Window— The window to change.topmost: Bool— true to keep the window always on top; false to return it to normal stacking.
Returns
true if the change was applied; false if the window is null or closed, or belongs to a program running with higher rights.
1 example: Pin a window on top
WindowShow
WindowShow(window: Window) → Bool
Shows a hidden window again, such as one hidden with WindowHide, in its current size and position. The engine stops tracking it as hidden.
Parameters
window: Window— The window to show.
Returns
true if the show request was made; false if the window is null or closed.
WindowToggleTopmost
WindowToggleTopmost(window: Window) → Bool · Simple
Switches a window between always on top and normal stacking, without activating it.
Parameters
window: Window— The window to change.
Returns
true if the change was applied; false if the window is null or closed, or refused the change. It does not tell which state the window is in now.
WindowWaitClose
WindowWaitClose(window: Window, timeoutMs: Integer) → Bool
Waits until a window closes, checking every 50 milliseconds. Blocks the script for up to timeoutMs; stopping all actions ends the wait early.
Parameters
window: Window— The window to wait for.timeoutMs: Integer— Longest time to wait, in milliseconds, from 0 to 60000. Larger values count as 60000; 0 checks once without waiting.
Returns
true once the window is closed, at once if it is already closed or null; false if it is still open when the time runs out or the wait is stopped.
1 example: Launch a program, wait for its window, act on it
WindowWaitFor
WindowWaitFor(pattern: Text, timeoutMs: Integer) → Window
Waits until a visible top-level window whose title matches a regular expression appears, checking every 50 milliseconds. Blocks the script for up to timeoutMs; useful right after starting a program.
Parameters
pattern: Text— A regular expression matched against window titles, ignoring letter case, such as 'Notepad$'. It matches anywhere in the title unless anchored with ^ or $.timeoutMs: Integer— Longest time to wait, in milliseconds, from 0 to 60000. Larger values count as 60000; 0 checks once without waiting.
Returns
The frontmost matching window, or a null window if none appeared in time or the wait was stopped. An invalid pattern stops the action with an error.