Window Titles and Text Advanced

Revision as of 08:31, 19 October 2013

Description

Sputnik operates in one of five "Window matching" modes.

The modes are set with the Opt() function using the WinTitleMatchMode and WinTextMatchMode option.

Remarks

Mode 1 (default)

@MatchModeLeft

Matches partial titles from the start.

In this mode the a window titled Untitled - Notepad would be matched by "Untitled - Notepad", "Untitled", "Un", etc.

e.g.

WinWait("Untitled");

Mode 2

@MatchModeRight

Matches partial titles from the end.

In this mode the a window titled Untitled - Notepad would be matched by "Untitled - Notepad", "Notepad", "pad", etc.

e.g.

WinWait("pad");

Mode 3

@MatchModePartial

Matches any sub-string in the title.

In this mode a window titled Untitled - Notepad would be matched by "Untitled - Notepad", "Untitled", "Notepad", "pad", "d - N", etc.

e.g.

WinWait("Notepad");

Mode 4

@MatchModeFull

Exact title match.

In this mode a window titled Untitled - Notepad would only be matched by "Untitled - Notepad"

e.g.

WinWait("Untitled - Notepad");

Mode 5

@MatchModeAdvanced

Advanced mode.

Must be replaced with Advanced Window Descriptions which does not need any mode to be set.

Advanced Window Descriptions

A special description can be used as the window title parameter.

This description can be used to identify a window by the following properties:

• TITLE - Window title
• TITLERX - Match Window title using a regular expression (Can be used on Title or Text params or both params to match the the given text of each param)
• TEXT - Window text
• TEXTRX - Match Window text using a regular expression (Can be used on Title or Text params or both params to match the the given text of each param)
• CLASS - The internal window class name
• CLASSRX - Match class using a regular expression (Can be used on Title or Text params or both params to match the the given text of each param)
• ACTIVE - Currently active window
• NOTACTIVE - This will not count the current active window in the search
• INSTANCE - The 1-based instance when all given properties match

One or more properties are used in the title parameter of a window command in the format:

[PROPERTY1=Value1; PROPERTY2=Value2]

Note : if a Value must contain a ";" it must be doubled.

e.g. Wait a window of classname "Notepad"

WinWaitActive("[CLASS=Notepad]", "");

e.g. Close the currently active window

WinClose("[ACTIVE]", "");

e.g. Wait for the 2nd instance of a window with title "My Window" and classname "My Class"

WinWait("[TITLE=My Window; CLASS=My Class; INSTANCE=2]", "");

e.g. Wait for the 2nd instance of a notepad

WinWait("[class=Notepad;INSTANCE=2]");

e.g. List windows matching a classname defined by a regular expression

WinList("[CLASSRX=#\d+]")

e.g. Use a ; in the title, text or a regex by placing it as ;;

WinList("[CLASSRX=#;;\d+]")

Window Handles / HWNDs

The SV datatype in Sputnik supports window handles (HWNDs) as IntPtr. A window handle is a special value that windows assigns to a window each time it is created. When you have a handle you may use it in place of the title parameter in any of the function calls that use the title/text convention. The advantage of using window handles is that if you have multiple copies of an application open - which have the same title/text - you can uniquely identify them when using handles. When you use a window handle for the title parameter then the text parameter is completely ignored.

Various functions such as WinGetHandle and WinList etc return these handles.

Note: Window handles will work no matter what WinTitleMatchMode/WinTextMatchMode is currently in use.