HotIf / HotIfWin

Specifies the criteria for subsequently created or modified hotkey variants.

Contents:

HotIf

HotIf "Expression"
HotIf Function

Parameters

(parameter omitted)

Sets blank criteria (turns off context-sensitivity).

"Expression"

Type: String

Sets the criteria to an existing #HotIf expression. Expression is usually written as a quoted string, but can also be a variable or expression which returns text matching a #HotIf expression. Although this function is unable to create new expressions, it can create new hotkeys using an existing expression. See #HotIf example 5.

Note: The HotIf function uses the string that you pass to it, not the original source code. Escape sequences are resolved when the script loads, so only the resulting characters are considered; for example, HotIf 'x = "`t"' and HotIf 'x = "' A_Tab '"' both correspond to #HotIf x = "`t".

Function

Type: Function Object

Sets the criteria to a given function object. Subsequently-created hotkeys will only execute if calling the given function object yields a non-zero number. This is like HotIf "Expression", except that each hotkey can have many variants (one per object). Function must be an object with a call method taking one parameter, the name of the hotkey.

Once passed to the HotIf function, the object will never be deleted (but memory will be reclaimed by the OS when the process exits).

The "three-key combination" Hotkey example uses this mode of HotIf.

HotIfWin...

HotIfWinActive WinTitle, WinText
HotIfWinExist WinTitle, WinText
HotIfWinNotActive WinTitle, WinText
HotIfWinNotExist WinTitle, WinText

Parameters

(all parameters omitted)

Sets blank criteria (turns off context-sensitivity).

WinTitle, WinText

Type: String

Specifies the window title and other criteria that should be used to identify a window. Depending on which function is called, affected hotkeys and hotstrings are active only while a matching window is active, exists, is not active, or does not exist.

Since the parameters are evaluated before the function is called, any variable reference becomes permanent at that moment. In other words, subsequent changes to the contents of the variable are not seen by existing hotkeys.

WinTitle and WinText have the same meaning as for WinActive or WinExist, but only strings can be used, and they are evaluated according to the default settings for SetTitleMatchMode and DetectHiddenWindows as set by the auto-execute thread. See WinTitle for details.

Error Handling

An exception is thrown if HotIf's parameter is invalid, such as if it does not match an existing expression and is not a valid callback function.

General Remarks

HotIf allows context-sensitive hotkeys to be created and modified while the script is running (by contrast, the #HotIf directive is positional and takes effect before the script begins executing). For example:

HotIfWinActive "ahk_class Notepad"
Hotkey "^!e", MyFuncForNotepad  ; Creates a hotkey that works only in Notepad.

Using HotIf puts context sensitivity into effect for all subsequently created hotkeys in the current thread, and affects which hotkey variants the Hotkey function modifies. Only the most recent call to any of the HotIf functions in the current thread will be in effect.

To turn off context sensitivity (such as to make subsequently-created hotkeys work in all windows), call any HotIf function but omit the parameters. For example: HotIf or HotIfWinActive.

Before HotIf is used in a hotkey or hotstring thread, the Hotkey and Hotstring functions default to the same context as the hotkey or hotstring that launched the thread. In other words, Hotkey A_ThisHotkey, "Off" turns off the current hotkey even if it is context-sensitive. All other threads default to creating or modifying global hotkeys, unless that default is overridden by using HotIf during script startup.

When a mouse or keyboard hotkey is disabled via a HotIf function or directive, it performs its native function; that is, it passes through to the active window as though there is no such hotkey. However, joystick hotkeys always pass through, whether they are disabled or not.

Hotkey (function), Hotkeys (general), #HotIf, Threads

Examples

See Hotkey for examples.