Screen Element Functionality Reference

Locks a specific screen element and makes it the active element. When applying this function, the screen element itself and all its parent screen elements in the hierarchy are locked.

Examples

• If you have multiple instances of a CRM application, 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.

• Locks a specific Generic HTML Document and make it the active document.

  Note: Using this function will disable (overwrite) any selected Has multi instances options.

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.

Moves the screen element to the top of the stacking order, thereby bringing the object to the front.

Removes all row, column, and cell selections.

Clicks the screen element. In some cases, the function includes the Async parameter.

Clicks a captured cell in a table. Applicable to an HTML Table.

Click Menu Item by Index

Clicks the menu item using an index number to indicate the menu or sub-menu item.

Click Menu Item by Path

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 a button on a notification bar. This function is used together with the Wait for Notification Bar Async function, which waits for the notification bar to be displayed.

This function was added in version 7.3, and is only available for HTML Document screen elements captured using the Web Connector for IE.

For details on using this function, see Using Notification Bar Functions.

Returns

Returns a boolean value of True if the button was clicked; otherwise returns False.

This function allows you to select a specified point in a physical element.

Collapses all the nodes in the SAP GUI tree.

Removes the specified column from the collection of the selected columns. (For SAP GUI Grid)

Validates all objects from the selected element downward in the hierarchy. The process destroys any objects that no longer exist (i.e. they are removed from the hierarchy) and attempts to recognize new objects and their children objects.

This function performs the default action specified for element in the application.

Double-clicks on the selected screen element. In some cases, the function includes the Async parameter.

Double-clicks the cell using row and column coordinates.

Simulates a double-click on the specified item.

This function allows you to double-click a specified point in a physical element.

Emulates text entered from the keyboard. This function can include the following parameters:

Emulates a left mouse click on the screen element.

Emulates a double mouse click on the screen element.

Emulates a right mouse click on the screen element.

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 JavaScript on a .Net or WPF screen element. See Using the Sample Execute JavaScript Project.

Executes scripts on the current web document. In some cases, ExeScript Async is recommended as it does not block continuous connectivity and recognition.

Executes scripts on the current web document without blocking continuous connectivity and recognition.

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.

Runs JavaScript or an expression that returns a result. The return value is text.

Example

2+2

document.URL

document.body.outerHTML

"printresult"

function ExampleFunc () {return document.body.outerHTML;} ExapmleFunc ();

Expands all nodes in the SAP GUI tree.

Find specified text in the DataWindow object’s cell.

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 theninvoke the Fire Event function for the change event.

Simulates an event (asynchronously) by a given name.

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

Examples of a parameter name for an HTML element can be any existing attribute of the HTML element according to Web API, such as role, title, style, id, type, name.

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.

Gets text by row/column.

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.

Returns the entire HTML Table (as a DataTable).

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

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:

Gets the HTML code from the page.

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.

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.

Executes JavaScript on the current HTML Document.

Locates the screen element.

Writes the screen elements tree to the log file.

Navigates to the given URL.

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 the children of the screen element.

Refreshes the screen element. For Win32 and HTML objects, acts as Destroy and Refresh.

Registers an event by a given name.

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 item in a list box by index.

Selects the item in a list box by name.

Sets a textual value of an attribute of the screen element by its name.

Example

Attribute names for an HTML screen element can be any existing attribute of the HTML element according to Web APIs, such as role, title, style, ID, type, name.

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

Set the focus to an HTML element in a web page.

Sets the value of a property,

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.

Waits 45 seconds asynchronously for a notification bar to appear in an Internet Explorer tab, and triggers a Notification Bar Event. This function does not use any parameters. If the notification bar appears within the waiting period, you can use the Click Notification Bar Button by Name function to click a button on the notification bar.

If you invoke the function again during the waiting period, the timer is reset. The Notification Bar Event is not fired in this case.

This function was added in version 7.3, and is only available for HTML Document screen elements captured using the Web Connector for IE.

For details on using this function, see Using Notification Bar Functions.

Returns

Returns a boolean value of True when the function is run and begins waiting for the notification bar.

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.

Is Password

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.

This event is fired when the Wait for Notification Bar Async function stops waiting for a notification bar. The Status parameter indicates why the function stopped waiting for the notification bar, and, if the notification bar appeared, the Message parameter shows the notification bar text.

For details on using this event, see Using Notification Bar Functions.

This event was added in version 7.3.

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