Screen Element Assets
(Available from version 7.0 onwards.)
This section presents screen element assets, including methods, properties, and events.
To learn about capturing and managing screen elements, see Screen Elements.
To learn about the elements for IBA screen elements, see Using IBA Assets.
Each screen elements has its own methods, properties, and events. These are visible in the Assets Panel, for example:
If an element in the screen element hierarchy has sub-elements indented below it, its own methods, properties, and events are listed in the Items folder below it.
The methods, properties, and events of the iexplore process are listed under Items.
Many of the methods, properties, and events are common to many types of screen elements, while some screen elements have their own particular assets.
This topic provides details about all available methods, properties, and events for screen elements.
Methods
Listed below are all methods provided for screen elements captured using all connector types. Not all methods are relevant for all connector types, or for all screen element types captured with a particular connector.
If multiple instances of a screen element are open, use this method to lock onto one specific instance. Any method you apply afterward will be applied to the same specific instance, until the Unlock Active Instance method is used. When applying this method, the screen element itself and all its parent screen elements in the hierarchy are locked.
Note: This method overrides the Has Multi Instances option selected. For example, if the option is set to Last Focused, normally any method applied to the screen element will be applied to the instance that was last in focus. However, if the Activate and Lock Instance method has been applied, any method applied to the screen element will be applied to the instance that was activated and locked.
Example
-
If you have multiple instances of a CRM application open, and at the beginning of each interaction you want to connect to a single relevant instance and stay connected to that instance until the interaction is complete, use the Activate And Lock Instance function at the beginning of the interaction. Use the Unlock Active Instance function to unlock the active instance when the interaction is complete.
Demonstration
In the example below, the text Hello is written into a Notepad window.
Because the Last Focused multi-instance option was selected, the text will be entered into whichever instance was last in focus.
Below you can see that when the workflow is run the text is written into whichever instance of Notepad was last in focus.
We'll now activate and lock an instance of Notepad before writing the text into Notepad.
Below you can see that when the workflow is run the text is now always written to the same instance of Notepad, regardless of which one was last in focus.
Activates a context menu item. For this function, you need to define the value of the Item Path parameter as a text list.
Activates the default action of the child object, if a default action is defined. For this function, you need to define the value of the Child Control Text parameter as a text list.
Attaches to the process.
Moves the screen element to the top of the stacking order thereby bringing the object to the front.
For example, if a window is currently not visible because it is hidden by other applications, this method will display the window on top of the other applications.
If the window is currently minimized, this method will not restore the window and the window will not be displayed.
Removes all row, column, and cell selections.
Clicks the screen element.
Clicks on the cell at the specified column and row. You can specify to execute this function asynchronously, so that it does not block continuous connectivity and recognition.
Clicks the menu item specified by the path. You can specify to execute this function asynchronously, so that it does not block continuous connectivity and recognition.
Clicks the menu item using an index number to indicate the menu or sub-menu item.
Clicks the menu item using the name of the menu (such as File, Save, Exit, etc.).
In the menu below, File is the first index item in the menu, and Exit is third sub-index item.
Clicks on the item in a list specified by the index path.
Clicks on the node in the data structure specified by the index path.
This function allows you to select a specified point in a physical element.
Clicks on the row in the list view specified by the row number.
Clicks a specified button within a popup window.
Clicks on the tab specified by the index number.
Closes a window screen element.
If the window includes unsaved changes, for example, if a Notepad window includes text that has not been saved, the window will not close. Instead, the Save dialog will be displayed just as if a human agent attempted to close the window.
Closes the currently selected tab.
Collapses the tree to the node specified by the index path.
Collapses all the nodes in the SAP GUI tree.
Removes the specified column from the collection of the selected columns. (For SAP GUI Grid)
Detaches from the process.
This function performs the default action specified for element in the application.
Executes the action defined for radio button.
Executes the performed action defined for the button.
Double-clicks on the cell at the specified column and row. You can specify to execute this function asynchronously, so that it does not block continuous connectivity and recognition.
Simulates a double-click on the specified item.
Double-clicks on the item in a list specified by the index path.
This function allows you to double-click a specified point in a physical element.
Double-clicks on the row in the list view specified by the row number.
Emulates the text entered from the keyboard. For this function, you need to specify the value of the Text parameter by defining the text that you want to emulate.
You need to verify that the object is in focus before invoking the Emulate Keyboard function.
Emulates a left-click on the screen element.
Emulates a right-click on the screen element.
Emulates inputting a value into an HTML input element. The emulation occurs even if the application window is minimized.
Emulates inputting a value into an HTML input element using AutoComplete. Accepts two parameters: string, index.
Example:
If your dropdown element offers two strings beginning with 'ma' - 'mall' and 'map', and you want to simulate entering 'mall', you would supply ('ma', 1) as parameters.
Ensures that the row in the list view specified by the row number is visible.
Ensures that the node specified by the index path is visible.
LIMITATION:
From time to time, upon a successful function call, the function may fail to return a successful result. To clarify this, you can check the returned value in your Java application.
Runs the script defined in the script parameter on the selected screen element.
Executes the add-on function defined in the Name parameter on the selected screen element.
Executes a command on the selected screen element. For this function, you need to specify the Method, Class, and Assembly of the command you want to execute.
Executes a JavaScript script on the screen element.
Executes a NativeScript script on the screen element.
Executes JavaScript on the targeted web document or screen element. In some cases, Execute Script Async is recommended as it does not block continuous connectivity and recognition.
Example: Screen element
element is a local variable mapped to the screen element.
Executing element.value='123' assigns the string '123' to the target element.
Executes scripts on the current web document without blocking continuous connectivity and recognition.
Example 1
Assuming function myFunction(){console.log("Hello!")} is implemented in the DOM with which you are working, the following script can be executed:
scriptElem = document.createElement('script');
scriptElem.type = 'text/javascript';
scriptElem.appendChild(document.createTextNode('myFunction();'));
document.body.appendChild(scriptElem);
Example 2
//Simulate click event
var clickEvent = new Event("click");
button.dispatchEvent(clickEvent);
Example 3
//Mouse down event
var mouseEvent = document.createEvent('MouseEvents');
mouseEvent.initEvent('mousedown', true, true);
button.dispatchEvent(mouseEvent);
Runs JavaScript or an expression (on a tab) that returns a result. The return value is text.
Runs JavaScript or an expression (on a tab) that returns a result. The return value is text.
Runs JavaScript or an expression (on a tab) that returns a result or times out. The return value is text.
Executes JavaScript and returns a result if applicable. The return type is text.
Example: Screen Element
element is a local variable mapped to the screen element.
Executing element.value on a target element with the value '123' returns the string '123'.
Example: Document
document.URL
document.body.outerHTML
function ExampleFunc () {return document.body.outerHTML;} ExapmleFunc ();
Expands the tree so that the node specified by the path is visible.
Expands all nodes in the SAP GUI tree.
Find specified text in the DataWindow object’s cell.
Finds the paths of all the children of the node specified by the index path or the item name.
Finds the path to the first child of the node specified by the index path or the item name.
Simulates an event by a given name.
Examples of event names include: blur, focus, focusin, focusout, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error, and contextmenu.
Example
If you need to set the value of a combo-box, set the required value of the combo-box and then invoke the Fire Event function for the change event.
Simulates an event (asynchronously) by a given name.
Use this function to fire an event on a screen element.
For example, to automate hovering over a screen element, fire the mouseover event.
The workflow below fires a mouseover event to hover of a video thumbnail.
When the workflow is run, the web site behaves as if a user had hovered their cursor over the video thumbnail.
For a full list of events, see online resources such as https://developer.mozilla.org/en-US/docs/Web/API/Element.
Calls to this function do not block continuous connectivity and recognition. For example, if you simulate a click event on the HTML Button screen element and the result of this action is a pop-up window, this window is recognized, unlike the call to the Fire Event function.
Example
Executes JavaScript on the current web document.
Returns a list of all matching screen elements for the given name.
Returns all matching screen elements for the given selector that is contained in the parent on which the function was invoked.
Returns a collection of all nodes in the SAP GUI tree.
Returns a list of List of Text.
Returns a textual value of an attribute of the screen element by its name. Before you run the function, you must define the attrName parameter.
Example
The Google Search button shown has an attribute called value. Note that its value is Google Search.
The workflow below writes the value of the attribute value to the text variable Text.
When the workflow is run, the value of Text is set to Google Search, as expected.
Returns the type of the specified cell. Possible values are: "Normal", "Button", "Checkbox", "ValueList". (For SAP GUI Grid)
Gets the text value in the cell at the specified row and column. (1-based index)
Retrieves a list of rows with values from the specified range of cells.
Get the screen element rectangle of the cell at the specified column and row.
Gets the text value in the cell at the specified column and row.
Gets text by row/column.
Get all the children of the node in the tree specified by the index path.
Returns the number of children of the selected screen element.
Returns the number of children of the selected element in the class defined by the ClassName parameter.
Returns the class name of the selected screen element.
Gets the name of the column specified by the column number.
Returns the screen element for the given Id.
Returns the enumerating physical object. You can use it with every screen element that has an enumerator as a control (process is excluded because it doesn’t have an enumerator and usually top level window is excluded because its enumerator is the process).
Gets the checked state of the menu item specified by the index path.
Gets the enabled state of the menu item specified by the index path.
Gets the text value of the menu item specified by the index path.
Returns the first matching screen element for the given name.
Returns the first matching screen element for the given selector that is contained in the parent on which the function was invoked.
Examples
Examples of selectors:
Selector |
Description |
---|---|
* |
Returns all elements. |
input | Returns all elements with the tag input. |
.container |
Returns all elements with the class name container. |
#firstName | Returns element with theID firstName. |
input[value=’17’] | Returns input elements that have an attribute value set to 17. |
Returns the first recognized physical object of the screen element from the process defined by the Process ID parameter.
Returns the first recognized instance of the screen element whose enumerator (parent) has the given Window Handle value. The returned type is IPhysicalObject.
Returns the instances of all recognized physical objects. If Multiple Instances is enabled, multiple instances maybe returned, for example, multiple browser tabs all opened to the same URL.
The returned type is a list of IPhysicalObject.
Gets the item in a list box.
Gets the list of items from a list box.
Get the screen element rectangle of the item, specified by the index path.
Gets the text of the item, for example, the text in the combo box or list box, specified by the index path.
Gets the number of rows in the grid
Gets row text by row number (returns List of Text for text in each column).
Gets the number of rows.
Returns the collection of rows that match specified text in the cell.
Gets the value of a property specified by the propName parameter. The value of this parameter is case-sensitive.
Returns the numbers of the selected rows (1 based index). (For SAP GUI Grid)
Gets the active tab by tab name in the application.
Returns the tab info.
Returns the text from a document, for example, an HTML document.
Gets the text color of the selected screen element.
Gets the cell text for the specified row (1 based index). The parameter of the function is Row of the Number type.
Gets the URL of the web page in the browser.
Gets the name of the selected item in a combo box.
Returns the visibility state ('True' or 'False') of the matching Physical Objects by the given selector.
Highlights all the cells in the table.
Executes JavaScript on the current HTML Document.
Checks if the cell at the specified column and row is selected.
Checks if the node in tree specified by the index path is visible.
Checks if the row in the list view specified by the row number is visible.
Finds the screen element and highlights it, as is the case when you click Locate in the Edit Screen Element window. Nothing happens if the screen element does not exist.
Example
The workflow below locates the Google Search button.
When the workflow is run, the Google Search button is highlighted.
Writes the screen elements tree to the RTClient log file.
Get the names of all the nodes in a specified index path.
Navigates to the given URL.
Get the index path to the specified nodes.
Emulates manually pressing a button. Pressing a button always causes server communication to occur, rendering all references to elements below the window level invalid.
Emulates pressing a button placed in a given cell, and raises an exception if the cell does not contain a button, or does not exist. Relevant for SAP GUI Grid.
Emulates a click on the header of the column if the parameter identifies a valid column, and raises an exception otherwise. Relevant for SAP GUI Grid.
Emulates pressing the Enter key.
Emulates pressing the F1 key.
Emulates pressing the F4 key.
Recognizes all the children of the process.
Recognizes the children of the screen element.
Refreshes the screen element. For Win32 and HTML objects, acts as Destroy and Refresh.
Right-clicks the screen element.
Right-clicks on the cell at the specified column and row. You can specify to execute this function asynchronously, so that it does not block continuous connectivity and recognition.
Right-clicks on the item in the list specified by the index path.
This function allows you to right-click a specified point in a physical element.
Runs the JavaScript inside the WPF Chromium Control (inside the web page in Chromium browser). Use the Script Text parameter to specify the script. The function can return the text value as a result of running the script.
To interact with an HTML object through JavaScript, you must identify the object by its ID or name:
document.getElementById("<id_field>") or document. getElementsByName("<name_ field >")[0]
You can find the HTML object properties on the web page in the HTML code. Run the Get HTML function to get all HTML or find an object by using a tool (for example, Developer Tools in IE).
-
Get the value of a text field:
object.value;
-
Set the value of a text field:
object.value =”<your value>”;
-
Click on object:
object click();
-
Disable object:
object disabled = "true";
-
Select radio button:
object.checked = "true"; or clear radio button: object.checked = "";
Points to undocumented internal functions. Recommended for advanced users in special cases for testing purposes. (For SAP GUI frame)
Selects the whole grid content (all rows and all columns). (For SAP GUI Grid)
Adds the specified column to the collection of the selected columns. (For SAP GUI Grid)
Selects the node in the tree specified by the index path.
Selects the item in a list box by index.
Selects the item in a list box by name.
Executes a keyboard emulation script on the screen element.
Sets a textual value of an attribute of the screen element by its name.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
attrName | text | The name of the attribute to set |
attrValue |
text |
The value to set for the attribute |
case sensitive |
Boolean |
Whether the attribute name is case sensitive or not |
Example
The Google text field has an attribute maxlength which limits the number of characters than can be entered. By default, it is set to 2048.
The workflow below changes the value of maxlength from 2048 to 7.
After the workflow is run, only 7 characters can be entered.
Sets a text value in the cell at the specified row and column. (1-based index)
Sets text by row/column.
Set specified cell as current cell. (For SAP GUI Grid)
Sets the focus to the captured screen element.
Example
The workflow below sets the focus to the Google text field.
When the workflow is run, the focus shifts to the text field, as can be seen by the presence of the text cursor.
Sets the checked state of the menu item specified by the index path.
Sets the enabled state of the menu item specified by the index path.
Sets the text value of the menu item specified by the index path.
Sets the text for the popup or alert.
Sets the value of a property,
Parameter |
Input Type |
Description |
---|---|---|
propName | text | The name of the object’s attribute. The value of this parameter is case-sensitive. |
propValue |
text |
The value of the object’s attribute. |
Sets the item in the combo box by index.
Sets the item in the combo box by name
Sets the selected item in the SAP GUI tree.
Sets the active tab by tab name in the application.
Scrolls to the captured element.
Example
Scroll to an HTML element in a web page.
Scrolls up or down specified number of pages.
Opens the context menu of a SAP object.
Starts recording a script of actions in the SAP session to the specified file by its name (do not provide path). Path for recorded file is: C:\Users\{current user}\AppData\Roaming\SAP\SAPGUI\. It is an undocumented function by SAP. To be used by advanced users only.
Unlocks the active instance locked by the Activate And Lock Instance function, and therefore must be applied to the same screen element that was locked.
Unregisters an event by the name that was registered with the Register Event by Name function.
Validates the children of the screen element.
Displays a red frame around a SAP object if the parameter is True. The frame will be removed if the parameter is False.
Properties
Listed below are all properties provided for screen elements captured using all connector types. Not all properties are relevant for all connector types, or for all screen element types captured with a particular connector.
The rectangle outlines the area where the cursor is currently hovering, which is captured as the screen element.
For a label:
Gets the position of caret on a label that can't be seen in the application. It is possible to change its position and invoke functions based on the caret position.
For a text field:
Gets the position of the caret within a text field, that may be checked by the ABAP application to determine which word the caret is in. Among other things, this may be useful for context-sensitive help.
(For SAP GUI Grid)
Indicates whether a screen element is changeable if it is neither disabled nor read-only.
Sets the checked state of a checkbox.
Indicates the class name of window. For example, SAP_FRONTEND_SESSION.
This property is True if the object is a container and therefore has no children property.
Returns the number of columns in a grid.
Indicates whether a screen element exists.
Indicates whether the screen element is in focus.
Gets the height of a SAP object.
This property is True if only numbers and special characters may be written into the text field.
Indicates whether a text field uses hidden text for passwords.
Indicates the modified state of the screen element's state as changed by the user, before this change is sent to the SAP system.
SAP element name.
The unique process ID.
Returns the number of rows in a grid.
The SAP interface handle.
Gets a unique textual identifier for the SAP object. This is achieved through a URL-like formatting, starting at the GUIApplication object and drilling down to the respective object. For example, Id of the text field in transaction se32 is /app/con[0]/ses[0]/wnd[0]/usr/ctxtRS32M-PROGRAMM
Gets the left screen coordinate of a SAP object.
Gets or sets the selected state of a radio button.
Gets or sets the selected item in combo box
Gets the top screen coordinate of a SAP object
The value of this property very much depends on the type of the object. This is straightforward for text fields or menu items, on the other hand this property is empty for toolbar buttons and is the class id for shells. You can read the text property of a label, but you can't change it, whereas you can only set the text property of a password field, but not read it.
Gets a long value that can alternatively be used to identify an object's type. For example, 31 is Text Field. These values can be taken from the type library in sapfewse.ocx.
Gets the width of a SAP object.
The window handle of the SAP object.
Events
Listed below are all events provided for screen elements captured using all connector types. Not all events are relevant for all connector types, or for all screen element types captured with a particular connector.
Event is fired when a specified popup has been closed.
Event is fired when a specified popup has been opened.
Event is fired when SAP session is activated.
Event is fired when SAP session changes.
The event is fired when SAP GUI is about to display a context menu. There are currently the following limitations documented at SAP:
-
Only context menus of controls of type GuiShell are supported.
-
The event is not fired for "cashed" context menus, which are not retrieved from the server when being opened.
This event is raised before a session is destroyed.
Event is fired if a run-time error occurs during the execution of a script in the current session.
The event is fired when the focus state of the current SAP session is modified.
The event is only raised when elementVisualizationMode is set to True, which turns on the hit test mode of SAP GUI. If on this mode a SAP GUI component is identified, the event is raised. The parameters of this event are:
-
The Id of the component that was hit.
-
A description of an inner object of the component if an inner object was hit.