UseWindow
Windows management function.
The UseWindow function specifies the window to which subsequent keyboard, mouse and menu actions are directed.
Usage
UseWindow is used to bring to foreground/front the specified window so that it may receive keystrokes, mouse clicks and other interactive actions. It includes an automatic synchronization : the next step in the script is processed only when the specified window has been found and ready for receiving user actions.
Syntax
UseWindow(<window_name> [,<instance>[,NoActivate]])
or
ret=UseWindow(<window_name> [,<instance>[,NoActivate]])Parameters
<window_name>, string. window name (see this topic) of the window to which script actions will be directed. You can use the SPY tool to manually determine the caption of a window. During Recording mode they will be inserted automatically. The window name can be truncated, for example "NOTEPAD.EXE|Edit|Untitled - Notepad" can be truncated in "NOTEPAD.EXE|Edit|" ; UseWindow function will search for any Edit window in Notepad whatever document name is.
<instance>, optional parameter, instance number of the window.
WinTask will try to find the window defined by UseWindow for a period of time defined by the system variable #ActionTimeout. Once the window is found, WinTask makes it active and sends all actions to it. If #UseExact is not set to 1, if a window with an approaching name is found, WinTask makes it active and sends all actions to it.
The keyword NoActivate prevents the window from being activated ; this keyword is generated automatically when Low level Recording mode is used. In this case, the statements following UseWindow will activate the window - thus it is not necessary to activate it beforehand.
Return value
Ret, numeric return code. When the <window_name> has been found and can be activated, the function returns 0, otherwise use this return code for Error Handling. At replay, the default behavior when the window is not found is to display an error message and script execution stops. If #IgnoreErrors=1, the execution is not stopped and you have to test the return code if you want to avoid strange issues (for example sending keys to a window which is not the one you expect as the previous UseWindow has failed and you are not aware of that as #IgnoreErrors=1).
Remarks
Note that in Recording mode, a UseWindow is generated each time the target window changes.
During execution, if the target window is minimized, it is automatically restored and activated.
If #ActionTimeout has been set to a value lower or equal than 10, the exact window name search is used.
See also
Examples
UseWindow("NOTEPAD.EXE|Edit|Untitled - Notepad", 1)
Result = UseWindow(win$)
UseWindow("NOTEPAD.EXE|Edit|Untitled - Notepad", 1)
'Child window NOTEPAD , file "Untitled" opened, instance 1
UseWindow("NOTEPAD.EXE|Edit|Untitled - Notepad")
'Child window NOTEPAD , file "Untitled" opened, first instance found
UseWindow("NOTEPAD.EXE|Edit",1)
'Child window NOTEPAD , any file opened, instance 1