Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Text application properties

Updated on October 19, 2022

The Text adapter has the following properties, methods, and events. Design properties are accessed from the Properties Grid.


AdvancedConfigurationAdvanced options that should only be used when directed by Support.
ApiTypeSets the high-level language API used to communicate with the DLL. Options are:
  • 16-bit WinHllapi
  • 32-bit WinHllapi
  • 16-bit EHllapi
  • 32-bit EHllapi
ApplyTimeoutToAllControlsSpecifies if the ControlTimeout value should be used for all controls.
CodePageSets the code page conversion table for the language. Can be left blank.
ControlTimeoutSpecifies the amount of time in milliseconds to wait before timing out, if ApplyTimeoutToAllControls is set to True.
CredentialsSet the application credentials for assisted sign-on. Click the More menu to open the Credential Collection Editor and add credential properties.
DelayBeforeScreenCopyThe amount of settle time, in milliseconds, to wait until the presentation space has stopped updating. This property should only be modified under direction of Pega Support.
DllNameUse this property to define the full path and WHLAPI32.DLL file for host adapter.
DoWinHllapiCleanupOnShutdownAllows de-registering from WinHllapi implementation on shutdown. For some emulators (Reflection, for one), this must be set to False when supporting multiple sessions.
EnhancedHllapiControls whether to use the enhanced Hllapi interface. Most emulators use the standard interface.
ExcludedProcessesUse this property to identify processes that are not required by your project. For more information, see Excluding processes in projects.

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.
FriendlyNameThe friendly name of the application that displays for users in StartMyDay.
FullNameGets the fully qualified name of the application.

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.

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

Use this property to control whether an RPA robot receives new work from Robot Manager. If set to True, which is the default, the property indicates that the application is loaded, logged into, and ready for the robot to begin its work.

The heartbeat messages from the robot communicate a Ready/NotReady status to Robot Manager.

If an application fails when processing robot work assignments, change its ReadyForRobotWork value to False and use the ReasonRobotNotReady property to describe the failure.

For example, in Robot Manager you would see a message similar to the following example if ReadyForRobotWork is set to False and ReasonRobotNotReady is set to “Cannot access applications.”:

Robot not ready. Cannot access applications.

If at least one application in the loaded solution is set to not ready, then the robot is not ready and does not request new work assignments from Robot Manager.

ReasonAdapterNotReadyUse this property to display a message that describes why the robot could not perform the work.

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.

ScreenDefinitionUse this property to specify the screen definition of the emulator.
SensitiveSet to true if this control has sensitive values that should be masked in design blocks and logs. For more information, see Sensitive data.

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.

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

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).

ShowHiddenFieldsControls whether hidden fields are shown during interrogation and runtime.

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.


Use this property to specify how this adapter participates in Start My Day functionality. For instance, choose Automatic if you want the adapter to start automatically or Manual if you want the user to start the adapter. The default is None, which indicates the adapter does not participate in Start My Day functionality.

When you choose Automatic or Manual, the StartOnProjectStart property is updated to reflect your choice.


Indicates which controls are used by the StartMyDay component to locate the application using the following methods:

  • OrganizeApplication
  • GetApplicationPositionAndSize
  • SetApplicationPositionAndSize

The system lists eligible interrogated controls in the Collection dialog. Select all windows, web pages, or screens that are required to locate the application for the StartMyDay component.

Note: If there is no matching StartMyDayControl available when an Organizing method is called, the application is not affected.

StartOnProjectStartSets whether or not the selected application should start when the project runs.

Set to True to prevent an application from creating top-most windows or bringing windows into the foreground when it is not the active application. The default is False.

For example, when automating a Windows application in the background, the application may create top most windows that show over the top of foreground windows disrupting user activity.

Setting this property to True prevents the application from creating new topmost windows, converting existing windows to topmost, and bringing windows into the foreground.


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:


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

UniqueIdIndicates the unique identifier of the adapter object.
UnprotectedHighThe designated color that the emulator uses to display high level unprotected data.
UnprotectedNormalThe designated color that the emulator uses to display regular unprotected data.
UpdateScreenOnKeyPressWhen set to True, Robot Studio generates a presentation change notification for every key press.

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.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us