Child Windows

Child Windows

Child Windows

Child window commands are responsible for triggering behaviour when a dialog (child window) of the monitored process opens.


WhenWindow

Waits until a window (dialog box) child of the target app, whose caption matches the parameter value and the optional control matching options, comes to the foreground. When it does the script within the conditional statement block is executed.

If a timeout is specified and the window is not detected before the timeout expires then the script is terminated and follows the OnError settings.

See separate entries for the other parameters.
WhenWindow only works on windows belonging to the process being scripted. (The one identified by the WaitProcess command.)
It is possible to use a WhenWindow on the main window of an application but this may interfere with the normal running of the application, so should be used carefully.

Syntax Diagram


Parameters

Refer to the syntax diagrams for the valid combinations and positioning of the parameters.

windowCaption

String literal, used to match the value against the foreground window’s title.

  • Case insensitive

  • May be a regex

Sample Matching

Assume foreground window’s title is “Starting Payroll App”.

  • “Payroll” - matches (value contained in title)

  • “payroll” - matches (value contained in title)

  • “^payroll” - regex - no match (caption does not start with title)

  • “payroll app$” - regex - matches (caption ends with title)

controlSelectOptions

See ControlSelectOptions

FirstTime / EveryTime

Parameter

Meaning

FirstTime

Default option if none is specified. The code block is executed only on the first time the window instance comes to the foreground.

EveryTime

The code block is executed every time the window instance comes to the foreground.

Poll

The Poll option causes the desktop client to periodically check if the foreground window is the one it is looking for. Normally this is automatic, but some applications don’t behave as expected and this may resolve the issue.

Examples

If a window with caption “Hello World” comes to the foreground then the script within the { }s is executed.

WhenWindow "Hello World"
{
  // More script
}

The following example is triggered when a window with the caption “About ACME CMS” comes to the foreground and one of the text fields on the window contains the username used to log into the app.

WhenWindow "About ACME CMS" ControlStatic bmUsername
{
  // Select the button that has the user's name as its caption
  SelectControl ControlButton EndsWith bmUsername

  // Press the button
  SendKeys ENTER
}

Application Notes

  • WhenWindow only works on windows belonging to the process being scripted. (The one identified by the WaitProcess command.)

  • It is possible to use a WhenWindow on the main window of an application but this may interfere with the normal running of the application, so should be used carefully. It is more likely that the WhenVaultLaunch command should be used instead.


ControlSelectOptions

The Control Select Options allow for finer level control over matching of a window (in a WhenWindow command) or in selecting a control (in the SelectControl command).

This is achieved by defining a pattern that identifies a specific control within the target window.

Syntax Diagram


Parameters

Refer to the syntax diagrams for the valid combinations and positioning of the parameters.

Parameter: ControlClass (Mandatory)

The type of control. Valid values are:

  • ControlButton

  • ControlComboBox

  • ControlEdit

  • ControlListBox

  • ControlMdiClient

  • ControlScrollBar

  • ControlStatic (text labels)

One way to identify the type of a control is to use a tool like WinSpy that shows the underlying windows control’s class name.

The screen grabs below show WinSpy identifying button, edit and label (static) controls.

Parameter: Control Content Pattern (Optional)

The string value to be matched against the control’s content.

Parameter: String Match (Optional)

How the control content pattern is to be matched to the control’s text.

These are all case insensitive.

Default value is Contains.

  • StartsWith The control’s text must start with the value.

  • Contains The control’s text must contain the value.

  • EndsWith The control’s text must end with the value.

  • Regex The control content pattern is treated as a regex and an IsMatch performed between it and the control’s text.

Parameter: Index (Optional)

Matches the n’th control that satisfies all the above filter criteria.

First matching control’s index is 1.

Default value is 1.

The actual order of a window’s controls does not necessarily reflect the visual ordering.

If no control content pattern is specified then the index will simply allow the n’th instance of a specific control to be matched.

Parameter: Control ID (Optional)

Matches against the specified control class if a control of that type has the supplied ID. The Control ID is assumed to be unique to a search, so the first time a match is found it is selected.

Specified as a 32 bit hexadecimal number in the format 0x[0-9, a-f, A-F]

  • E.g. 0x120F or 0x120f

Default value is to not use the control ID.

Control IDs may change between program runs depending upon how the target program was developed. You need to check that they are constant before trying to use them.

Application Notes

The following table summarises the effect of using the above parameters in combination.

Class

Content Pattern

Index

Result

Specified

Not Specified

Default

Selects the first control of the control class type

Specified

Not Specified

Specified

Selects the index(th) control of the control class type

Specified

Specified

Default

Selects the first control that matches the type and content

Specified

Specified

Specified

Selects the index(th) control that matches the type and content


    • Related Articles

    • Desktop Scripting

      Structure of a Script A Desktop DSL Script has the following functional sections (not all are required for all apps): Error Directive Determines the impact of errors on the script run. Process Start and Identification Ensures the correct windows ...

    • Main Window Commands

      Main window commands are responsible for interacting with the primary window of an application, or the application itself rather than the current child window. BringToForeground The BringToForeground command is used to bring the main application into ...

    • Desktop Scripting Overview

      Purpose The My1Login Desktop Scripting language is a Domain Specific Language (Desktop DSL), targeted at controlling and responding to Windows desktop applications, with the aim of injecting user credentials that are stored in the My1Login system. It ...

    • Working With the OS Environment

      Working With the OS Environment 32 bit Apps on 64 & 32 bit Windows Specifying the bmAppPath for a 32 bit process should use the “Program Files (x86)” folder if the script is to be run on 64 bit versions of windows. At runtime the bmAppPath will be ...

    • Error Directive, Alerting & Logging Commands

      OnError Controls the processing of a script in the event of a runtime error. Multiple OnError commands may be used to control behaviour at different points in the script. Syntax Diagram Parameters Terminate - stop script execution Continue - continue ...