SetTitleMatchMode

Homepage
Command List

Sets the matching behavior of the WinTitle parameter in commands such as WinWait.

SetTitleMatchMode, MatchMode
SetTitleMatchMode, Fast|Slow

Parameters

MatchMode

One of the following digits or the word RegEx:

1: A window's title must start with the specified WinTitle to be a match.
2: A window's title can contain WinTitle anywhere inside it to be a match.
3: A window's title must exactly match WinTitle to be a match.

RegEx (v1.0.45+): Changes WinTitle, WinText, ExcludeTitle, and ExcludeText to be regular expressions. Do not enclose such expressions in quotes when using them with commands. For example: WinActivate Untitled.*Notepad. RegEx also applies to ahk_group and ahk_class; for example, ahk_class IEFrame searches for any window whose class name contains IEFrame anywhere (this is because by default, regular expressions find a match anywhere in the target string). Note: For WinText, each text element (i.e. each control's text) is matched against the RegEx separately. Therefore, it is not possible to have a match span more than one text element.

The modes above also affect ExcludeTitle in the same way as WinTitle. For example, mode 3 requires that a window's title exactly match ExcludeTitle for that window to be excluded.

Fast|Slow

Fast: This is the default behavior. Performance may be substantially better than Slow, but certain WinText elements for some types of windows may not be "seen" by the various window commands.

Slow: Can be much slower, but all possible WinText is retrieved from every window as a windowing command searches through them for a match. Window Spy reveals which parts of a Window's text (if any) require the slow mode.

Remarks

This command affects the behavior of all windowing commands, e.g. IfWinExist and WinActivate.

If unspecified, TitleMatchMode defaults to 1 and fast.

Generally, the slow mode should be used only if the target window cannot be uniquely identified by its title and fast-mode text. This is because the slow mode can be extremely slow if there are any application windows that are busy or "not responding".

The customized version of Window Spy distributed with AutoHotkey reports slow text in a separate section so that its easy to determine whether the slow mode is needed.

If you wish to change both attributes, run the command twice as in this example:
SetTitleMatchMode, 2
SetTitleMatchMode, slow

The built-in variables A_TitleMatchMode and A_TitleMatchModeSpeed contain the current settings.

Regardless of the current TitleMatchMode, WinTitle, WinText, ExcludeTitle and ExcludeText are case sensitive. The only exception is the case-insensitive option of the RegEx mode; for example: i)untitled - notepad

Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off fresh with the default setting for this command. That default may be changed by using this command in the auto-execute section (top part of the script).

Related

SetWinDelay, IfWinExist, WinActivate, RegExMatch()

Example

SetTitleMatchMode 2
; OR:
SetTitleMatchMode RegEx

SetTitleMatchMode Slow  ; Slow/Fast can be set independently of all the other modes.

Homepage  |  Command List