Steps, Script and AutoHotkey
What an action does can be written three ways. Written as, on the What it does card of the Actions page, chooses which one runs.
| Mode | What it is | Choose it when |
|---|---|---|
| Steps | A list of steps you pick and fill in, one row each. No code to type. | You want to build the action without writing code. Most actions fit: send keys, type text, move or close windows, wait, ask a question. |
| Script | Input.Observer's own script language, typed in a code editor. | You need arithmetic, building text from pieces, loops that count with a variable, or anything Steps can't express. |
| AutoHotkey | An AutoHotkey v2 script, run by AutoHotkey itself. | You already have AutoHotkey code, or need something only AutoHotkey does. |
Steps and Script run inside Input.Observer and call the same builtins: Steps is a visual way to write what a script would. See Steps and the Script language reference.
Each mode keeps its own content
An action holds a Steps body, a Script body and an AutoHotkey body side by side. Switching Written as ① changes which one runs. It never deletes the others, so you can switch back.
If the mode you select is empty while another mode has content, a notice under the switch says that running the action does nothing, and offers a button to use the mode that has content.
Switching from Steps to Script
When you switch from Steps to Script while the action has steps and its Script body is empty, Input.Observer offers to translate the steps: Convert steps to a script? Choose Convert to put the translation in the Script editor.
- The steps stay as they are. Switching back to Steps shows them unchanged.
- Nothing converts back. A script can't be turned into steps.
- Steps that use Repeat while…, Repeat until…, Exit the loop or Stop the steps are not offered for translation, because Script has no matching statements. You can still switch; the Script body just starts empty.
- AutoHotkey is never converted to or from.
- When the steps are a recording from the Recorder page, the dialog also says that the script ignores Replay speed and Replay mouse path detail: its waits run at recorded speed and every recorded mouse move replays (Recorder settings).
From Steps to Script shows what each kind of step becomes.
AutoHotkey
AutoHotkey is a separate program that Input.Observer starts when an AutoHotkey action runs. It is not included; you install AutoHotkey v2 yourself and tell Input.Observer where it is.
- Install AutoHotkey v2.
- On the General page, turn on Enable AutoHotkey and set AutoHotkey executable to its
program file, such as
AutoHotkey64.exe. - AutoHotkey now appears under Written as. Apply your changes so the engine uses the new setting.
The rules:
- AutoHotkey is offered under Written as only while Enable AutoHotkey is on, or when the action already runs as AutoHotkey. An AutoHotkey action with AutoHotkey turned off does nothing, and the page says so.
- Use a normal AutoHotkey build. The builds with
_UIAin their name, such asAutoHotkey64_UIA.exe, can't run scripts from Input.Observer. - When AutoHotkey is turned on but its program can't be found at startup or when the configuration is reloaded, Input.Observer asks you to Browse for the AutoHotkey executable or Leave as-is.
- Each run starts a new AutoHotkey process with your script. It can't call Input.Observer's builtins. With Wait for it to finish on, the action runs until the script ends by itself, and the stop-all-actions hotkey ends it (Scripts that keep running).
- Before your script, Input.Observer sets variables that describe the trigger, such as
IO_ActionName,IO_TriggerKindand the gesture's or hotkey's window (AutoHotkey variables). The editor's Variables available here list shows the ones the action's triggers provide; click one to insert it. - What the script writes to its standard output appears in the diagnostic console, starting with
AHK:(The diagnostic console).
A Steps or Script action can also run a piece of AutoHotkey code with the AutoHotkeyExecuteScript
builtin, which waits for it to finish, or start one with AutoHotkeyStartScript, which doesn't. The
same setting and executable apply.
Scripts that keep running
An AutoHotkey script with hotkeys, hotstrings or a timer keeps running after its last line. To start one like that from Input.Observer, turn off Wait for it to finish under the AutoHotkey editor. The switch is there wherever an AutoHotkey body is: actions, Before and after scripts, global events and snippets.
| Wait for it to finish on | Wait for it to finish off | |
|---|---|---|
| The action | Runs until the script ends | Is done as soon as AutoHotkey starts |
| What the script writes | Appears in the diagnostic console, starting with AHK: | Is not shown |
| A syntax error | Appears in the diagnostic console | AutoHotkey shows its own error box |
| The stop-all-actions hotkey | Ends the script | Leaves it running |
| Saving settings or Reload Config | Ends the script, with the other running actions | Leaves it running, unless the Config loaded event started it |
| Input.Observer exits | Ends the script | Ends the script |
A script that Config loaded started ends when the settings are saved or reloaded, because that event then runs again and starts a fresh copy. Without that, each save would leave one more copy running. To keep one copy of a script running all session, put it in Config loaded with Wait for it to finish off.
AutoHotkeyStartScript works the same way as the switch turned off, and returns the process id of the
AutoHotkey it started.
AutoHotkey variables
Every AutoHotkey run starts with a few lines Input.Observer adds ahead of your script, setting IO_
variables from what triggered the action. This applies to an action written as AutoHotkey and to
code run with AutoHotkeyExecuteScript or AutoHotkeyStartScript, which gets the variables of the
action that called it.
Every run sets these three:
| Variable | Holds |
|---|---|
IO_ActionName | The action's name. For a global event, Global_Event_ followed by the event's name in the configuration file, such as Global_Event_release or Global_Event_foreground_changed. Empty when nothing triggered the run, such as a script run from the console. |
IO_AppGroupName | The name of the app group the action was found in, such as Global. Empty for a global event. |
IO_TriggerKind | What triggered the run: Gesture, Hotkey, TextExpansion, MouseButton (a button chord trigger, or a mouse-button or Draw button released global event), Wheel (a wheel trigger or a wheel global event), or None. |
The rest depend on the trigger, and only that trigger's are set:
| Trigger | Variable | Holds |
|---|---|---|
| Gesture | IO_GestureWindow | The window the gesture started over |
IO_GestureButton | The draw button: left, right, middle, x1 or x2, or key for the draw key | |
IO_GestureStartX, IO_GestureStartY | Where the stroke started | |
IO_GestureEndX, IO_GestureEndY | Where it ended | |
IO_GestureBoundsLeft, IO_GestureBoundsTop, IO_GestureBoundsRight, IO_GestureBoundsBottom | The rectangle around the whole stroke | |
IO_GesturePoints | Every point of the stroke in drawing order, as an array of [x, y] arrays | |
| Hotkey | IO_HotkeyWindow | The window in front when the hotkey was pressed |
IO_HotkeyVkCode | The final key's Windows virtual-key code, such as 75 for K | |
IO_HotkeyModifiers | The modifier keys of the combination, added together: Ctrl 1, Shift 2, Alt 4, Win 8 (Ctrl+Alt is 5) | |
| Text expansion | IO_TextExpansionWindow | The window you typed in |
IO_TextExpansionPattern | The abbreviation you typed | |
| Mouse-button event | IO_MouseWindow | The window under the pointer |
IO_MouseButton | The button: left, right, middle, x1 or x2; for Draw button released after a gesture drawn with the draw key, key | |
IO_MouseX, IO_MouseY | Where the pointer was | |
| Wheel trigger or wheel event | IO_WheelWindow | For a wheel trigger, the window you pressed the draw button over; for a wheel event, the window under the pointer |
IO_WheelDelta | How far the wheel turned, as Windows reports it: 120 for one notch of an ordinary wheel (smooth-scrolling wheels and touchpads send smaller steps), positive away from you (or to the right), negative toward you (or to the left). A wheel trigger always gets 120 or -120 | |
IO_WheelHorizontal | true for a sideways wheel turn, false for an ordinary one | |
IO_WheelX, IO_WheelY | Where the pointer was | |
IO_WheelButton | For a wheel trigger, the draw button you held: left, right, middle, x1 or x2, or key for the draw key. Empty for a wheel event |
- Windows are window handles, numbers AutoHotkey reads as a window id:
"ahk_id " IO_GestureWindownames the window inWinActivate,WinGetTitleand the other window functions. - Positions are screen coordinates in physical pixels, from the top-left corner of the main
monitor. Set
CoordMode "Mouse", "Screen"before using them with AutoHotkey's mouse functions, which otherwise work relative to the active window. - Text arrives exactly as it was; quotes, backticks and line breaks in an action or group name are escaped for you.
- A variable the trigger doesn't provide isn't set at all, and AutoHotkey stops the script when it
reads an unset variable. An action with several kinds of trigger, or a snippet called from different
actions, should check
IO_TriggerKindfirst, or useIsSet(IO_GestureWindow).
For example, an action that runs from a gesture or a hotkey, bringing the window it was used on to the front and showing its title:
CoordMode "Mouse", "Screen"
win := IO_TriggerKind = "Gesture" ? IO_GestureWindow : IO_HotkeyWindow
WinActivate "ahk_id " win
MsgBox WinGetTitle("ahk_id " win), IO_ActionName
Plugin script engines
A plugin can add a script engine of its own. It then appears under Written as with the plugin's name, and the text you type there goes to the plugin exactly as written; Input.Observer doesn't check it. See Plugins.
- No registered plugin provides the engine, for example because the plugin was removed: Written as marks the engine as not registered, and a warning under it says the script is skipped when it runs. The action then does nothing, and no message says so.
- The plugin is registered but can't take the run, for example because it is disabled, stopped or restarting: the action doesn't run and isn't retried later. A line in the console's System section names the plugin and the engine (Console), and a Windows notification names the action and the plugin. The notification appears only while Windows notifications is on (General settings).
In Simple mode
Simple mode shows Written as only for an action that already has a script or an AutoHotkey body. For any other action the card shows the steps directly. To write a new action as a script, switch the window to Advanced mode (The configuration window).