Table of Contents

Activate Commands

Choosing an Activate Caption Property

Window captions (or you may call them window titles) can often have workflow specific information, Test vs Prod, a patient identifier, some specific exception text. One main use for an Activate command is to ask "Hey does this window exist?". This means you often need to pattern match using wildcards.

To help understand what you need to use for a wildcard lets use an example caption of:

Editing Patient Fred - OurEMR

You could use:

Editing Patient
Editing  [but be careful as this could be not unique enough!]
Editing Patient* [the trailing* is not manditory as the above showed but is a good practice!]
*Patient* [the trailing* is manditory!]

Importance of the Foreground Window

The application you are automating needs to be the foreground window while it is being automated, or when you are testing automation commands.

If you read Microsoft's documentation on the various ways of changing the foreground window programmatically, you will see that the Windows operating system tries to prevent one process to steal focus (switching the foreground window) from a user, as that would be annoying. This behavior is controlled by a registry setting - ForegroundLockTimeout. Using C.MachineSettings.ImproveActivateSet to verify / set ForegroundLockTimeout to 0. This allows LGI RPA to attempt to bring a window to the foreground.

The Microsoft Win32 API method used by Activate commands is SwitchToThisWindow.

Activate commands all activate a window handle as that's what the Win32 API method uses. However, the commands themselves accept a window caption. Captions are evaluated using a Like operator, therefore you must pass either the entire caption or more commonly use wildcards (*). Note that the caption you see may not be exactly what is the true caption. It is a good idea to verify what the caption should be using the VBA immediate window:

wait 3:?GetForegroundCaption()

Now if you just pasted that command into the Immedate window and ran it - in three seconds you'd get an output that looks like this:

Microsoft Visual Basic for Applications - ... [running] - [Automations (Code)]

That is because VBA is the foreground window. It is a common misconception, that executing a command in VBA magically goes to the desired window; for example here you would magically get the caption to the window you wanted. This is not the case. It is always up to you to make sure the window you want is in the foreground, when debugging, using the Immediate window, and of course during automation execution.

Activate Commands

There are several options within WorkStation.WindowUtilities. In VBA use C.WindowUtilities.

Function Activate_(captionLike As String, [timeout As Long = 5000]) As Boolean
    Member of WorkStation.WindowUtilities

Returns false if the caption does not exist within the specified timeout interval.

Function ActivateGetPID(captionLike As String, [timeout As Long = 5000], [altTab As Boolean = True]) As Long
    Member of WorkStation.WindowUtilities

Returns the process id (PID) of the application with the specified caption, or returns 0 if the caption does not exist within the specified timeout interval. Storing the PID allows easily closing the application using

C.Utilities.ClosePID storedPID

Function ClosePID(PID As Long) As Boolean
    Member of WorkStation.Utilities

Function ActivatePosition(captionLike As String, x As Long, y As Long, Width As Long, Height As Long, [timeout As Long = 5000], [altTab As Boolean = True]) As Long
    Member of WorkStation.WindowUtilities

Has the same PID behavior as ActivateGetPID, but also positions and sizes the window. Use hotkey:

Ctrl+Alt+W

To learn an C.ActivatePosition command for the foreground window populated with caption, position and size values. Note that X and Y values<=0 will be set 1 to prevent inadvertent issues.

There are also Activate commands that support a window handle. These methods will be named with hWnd in the name.

Legacy Activate command

Sub Activate(sCaption As String, [Wait As Boolean = False], [SwitchDelay As Long])
    Member of BostonWorkStation70.BostonWorkStation

Long time users will know this command well. And there is no reason to convert existing code unless the return values are useful, the embedded timeout scheme is more convenient or it would have been easier to pass a handle. They all use the same tricks to force the window to the foreground.

This method does not return a value and wait is set to true, requires setting this property prior to calling Activate to prevent it hanging forever if the caption is not found.

Property Timeout As Double
    Member of BostonWorkStation70.BostonWorkStation