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 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 they have implemented in a separate DLL file. Adapter extender classes implement IAdapterExtender and are able to contribute properties, methods, and events to an adapter.

FastFieldQuery

Only modify this setting under the direction of 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, 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. We recommend you accept the default.

MatchedScreenCount

Use this property in version 8.0.1082 and later 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 dialog 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 Studio  to integrate the application, and complete the MonitoredEvents property to select the controls (target types) and corresponding events for which event notifications will be 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 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 Studio waits 200 milliseconds before it again checks to see if the screen is in a ready state.

For non-asynchronous emulators, 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 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 will lock up when started.

The BlueZone emulator will work with either setting, however, due to a limitation on how long it takes BlueZone 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 has finished processing the first command. For this reason, for BlueZone set this option to False so the calls occur on different threads. Studio locks the multiple threads and force the calls to be processed individually.

SetRegionTextWithSendkey
8.0.1037 and later

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

UniqueId

Indicates the unique identifier of the adapter object.

UnprotectedHigh

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

UnprotectedNormal

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

UpdateScreenOnKeyPress

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

UseExtendedFunctions

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

If this 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 Studio to poll the screen approximately once every second. This is much slower since the time it takes to read the screen depends on the polling interval. This 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.

Note:  Avoid using this method when automating applications because some applications and controls must be on an active desktop and visible.

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. Here is an 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 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 which show passwords or other sensitive information, to appear. The default is False which hides this information.

Note: The ShowHiddenFields property for TextAdapters may not be 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 application is terminated.