Property

Description

API Type

Use this property to select the API type that is appropriate for the emulator.

• StandardWinHllapi  – The HLLAPI API with Windows extensions, using 16-bit data alignment. This is the default.

• EnhancedWinHllapi  – The HLLAPI API with Windows extensions, using 32-bit data alignment.

• StandardEHllapi  – The HLLAPI API without Windows extensions, using 16-bit data alignment.

• EnhancedEHllapi  – The HLLAPI API without Windows extensions, using 32-bit data alignment.

Context

Indicates the context in which the adapter is loaded. Contexts generally apply to solutions running in a Citrix environment. For more information, see Citrix - Project Items in Solutions.

DelayBeforeScreenCopy

Only modify this setting under direction of Pega Support.

The amount of settle time, in milliseconds, to wait until the presentation space has stopped updating.  

DesignTime

Use this property to get a value indicating if the control is a design time control. (Boolean)

DllName

Use this property to define the full path and WHLAPI32.DLL file for host adapter.

Name

Use this property to get or set the reusable design component name.

ExcludedProcesses

Use this property to identify processes that are not required by your project. For more information, see Excluding Processes for Use in Projects.

Extender

Lets you specify an extender class that you have implemented in a separate .DLL file. Adapter extender classes implement IAdapterExtender and can contribute properties, methods, and events to an adapter.

FastFieldQuery

Only modify this setting under the direction of Pega Support. This setting determines how fields are queried when the screen is updated.

• Set to True to query unprotected (data entry) fields. Only when a host has screens with a large number of protected fields should this field be set to True. When set to True, the screen image in the Designer does not show different colors for different protected field attributes.

• Set to False to query all fields.

FullName

Use this property to get the fully qualified name of the adapter item.

IsRunning

Use this property to get a value that indicates whether the application is running.

IsStartStoppable

If set to False, Robot Studio only lets the adapter run once, and then never again until the project is restarted. In this case the adapter cannot be restarted using the Start method.

The default is True, which indicates the adapter can be restarted while the project is running. Typically, you accept the default so the adapter can be restarted.

MatchedScreenCount

Use this property to get a count of matched partial screens after a screen update.

MonitoredEvents

Use this property to specify the target types and corresponding events for which event notifications are generated. Browse this property to open the Configure Monitored Events window for selection of the target types and events associated with each selected target type for which notifications are generated.

MonitorEventsMode

Use this property to specify the types of application controls for which event notifications are generated. Your options are:

• None – No event notifications are generated for the adapter.

• Interrogated Controls – Event notifications are generated only for controls which have been interrogated at design time.  For this mode, you must interrogate the application's controls for which you want to generate event notifications and then use the MonitoredEvents property to select the controls (target types) and corresponding events for which event notifications will be generated.

• All Controls – Event notifications are generated for any application control matching the selected target types and corresponding events. For this mode, you do not need to interrogate individual controls in the application. It is only necessary to interrogate the main application window to allow Robot Studio to integrate the application, and complete the MonitoredEvents property to select the controls (target types) and corresponding events for which event notifications are generated.

Name

Use this property to get or set the name assigned to the adapter.

ProtectedHigh

Use this property to specify the color that the emulator uses to display fields that are highly protected.

ProtectedNormal

Use this property to specify the color that the emulator uses to display fields that are protected at a normal level.

RefreshTimeout

Use this property to define the maximum amount of time to wait for a screen text changed event to occur after setting a region of text. This includes the amount of time it takes to get notified that the screen has changed, the time it takes for the screen to be in a ready state, and the time it takes to read the screen and identify that the current screen differs from the previous screen. The default is 5000 milliseconds.

For most emulators that support asynchronous communication, the screen changed notification occurs immediately and the screen is already in a ready state to be read. For these emulators, the screen changed notification occurs immediately and this property is not relevant.

For Rocket BlueZone emulator versions that support asynchronous communication (6.1.4 and later), the screen is not in a ready state after receiving the screen changed notification and Robot Studio waits 200 milliseconds before it checks to see if the screen is in a ready state.

For non-asynchronous emulators, Robot Studio uses a polling mechanism to read the screen approximately every second. The amount of time it takes to process a screen text changed event depends on the timing of the polling cycle and could take up to a full second to occur. Also note that this timeout interval is applicable to every region of text. A delay would be compounded if there are many regions getting updated on a screen at one time in an automation.

One strategy often used is to set this property low, update several regions in an automation, and have the automation wait for the screen to be updated before continuing.

ScreenDefinition

Use this property to specify the screen definition of the emulator.

SerializeWinhllapiAccess

Use this property to control whether the commands sent to the emulator occur on the same thread. The default is True, which forces all calls to the emulator to occur on the same thread. Most emulators require this property to be set to True to function properly.

Emulators such as Rumba, however, require that this property be set to False or the emulator locks up when started.

The Rocket Terminal (formerly Rocket BlueZone) emulator works with either setting. However, due to a limitation on how long it takes the emulator to process certain functions, having all calls to the emulator on the same thread can cause a second command to be sent to the emulator before it finishes processing the first command. For older versions of BlueZone, set this option to False so the calls occur on different threads. Studio locks the multiple threads and forces the calls to be processed individually.

Note:  Newer versions of the Rocket Terminal emulator may require you to set this property to True.

SetRegionTextWithSendkey

Use this property to control how text is copied to the screen when you set the region’s Text property.

The default is False, which tells the system to copy the contents of the Text property into the region on the screen. Most emulators support this method of directly entering data into a specific location on the screen.

If your emulator does not support this method, enter True. When you enter True, the system updates the screen by automatically setting the cursor position and sending text to the host using a WinHillapi function (in the same way that the SendKeyToHost method works).

SessionID

The short name set up in the emulator for the session.

ShowWinHllapiHostWindow

This setting should only be modified under direction of Pega Support.

Determines whether the user interface for the Studio WinHLLAPI host executable is displayed when the adapter is started. This application is not the emulator, but a Studio executable that hosts the WinHLLAPI.dll file and allows the Text adapter to call functions on it. Normally, it is not visible when launched, but when debugging a problem, it can be useful to have it visible.

StartOnProjectStart

Sets whether or not the selected adapter should start when the project runs. For more information, see StartMethod Property and StartOnProjectStart.

This

A reference to the text adapter object.

TrimRegionText

build 19.1.38 or later

Enter False if you want Robot Studio to leave leading and trailing white spaces for the Text property of a region or field. The default is True, which automatically trims leading and trailing white spaces. 

For example, you might set this property to False if you need to count positions in a text field to then extract content based on that character count. If the text in the field looked like this:

    hello

With the property set to True, the system returns "hello". With the property set to False, the system returns "    hello."

UniqueId

Indicates the unique identifier of the adapter object.

UnprotectedHigh

The designated color that the emulator uses to display high level unprotected data.

UnprotectedNormal

The designated color that the emulator uses to display regular unprotected data.

UpdateScreenOnKeyPress

When set to True, Robot Studio generates a presentation change notification for every key press.

UseExtendedFunctions

Controls whether asynchronous screen text changed and keystroke intercepts occur. The default is True, which means Robot Studio expects the emulator to send a Windows message that indicates that the screen has been updated.

If this behavior is not supported, it will be obvious during interrogation because updates to the emulator screen will not be reflected on the Designer window.

Set this property to False to tell Robot Studio to poll the screen approximately once every second. This is much slower because the time it takes to read the screen depends on the polling interval. The slower speed is also obvious during interrogation because there is a significant delay between the time the emulator screen is updated and the corresponding changes appear on the Designer window.

Method

Description

Parameters

Return type

Focus

Places focus on the main window of the target application.

None

Void

Hide

Hides all processes currently running in this adapter.

None

Void

Maximize

Maximizes the main window of the target application.

None

Void

Minimize

Minimizes the main window of the target application.

None

Void

RematchChildren

Refreshes matching on all objects under the adapter. Set the detach property to True to unmatch all targets before attempting to rematch.

Boolean detach

Void

ResetState

Resets all component properties to their initial values.

None

Void

Restore

Restores the main window of the target application.

None

Void

SendControlSequence (1 Param)

Sends the appropriate control sequence data. Control sequences consist of text data plus optional binary data expressed with an octal escape sequence. The octal number must contain three digits, including leading zeros, for example,  ABCD\007.

This sends the letters ‘ABCD’ followed by 7 (BELL).  Note, this is not the character 7 (which is 55 in ASCII).

controlSequence

Void

SendKeyStringToHost (1 Param)

Sends the key string data to the host application.

StringKeys

Void

SendKeyStringToHost

PlusEnter (1 Param)

Sends the key string data plus an Enter key to the host application.

Strings

Void

SendKeyToHost (1 Param, 2 Param)

Sends the keystroke to the host application.

(Keys), (Char), (Host Keys), (Keys Key, Int32 Repeal Count), (Char key, Int32 Repeal Count), (Host32Key, Int32 Repeal Count)

Void

Show

Shows all processes currently running in this adapter.

None

Void

ShowHiddenFields

Set this property to True if you want hidden fields, such as those that show passwords or other sensitive information, to appear. The default is False, which hides this information.

Note: The ShowHiddenFields property for Text adapters is not supported by all emulators. For example, it is not supported by Reflection or Call.

None

Void

Start

Starts the application.

None

Void

Stop

Stops the associated process (and all child processes) using StopMethod.

None

Void

Event

Description

Started

Occurs when the host application is started.

Starting

Occurs when the host application is starting.

Stopped

Occurs when the host application exits.

Stopping

Occurs before the Stop is called on the host application.

Terminated

Occurs when the host application is terminated.