Purpose
Understand the GuiXT Native Control Interface

SAP GUI screen elements such as input fields, radiobuttons, checkboxes or tables can easily be handled in GuiXT scripts. For a set of special SAP GUI controls, namely the ALV Grid Control, the Tree Control and the Toolbar Control, together with a few seldomly used controls (HTML Viewer, Picture Control), the direct access via GuiXT script is not possible.

We recommend you call up SAP GUI scripting in order to handle these controls. Use the GuiXT commands ApplyGUIScript, CallVBSAsync, CallJSAsync or CallVBAsync to execute SAP GUI scripting commands in exit routines that you implement with VBScript, JavaScript or VB.NET.

There are cases where SAP GUI scripting cannot be used or is too complicated to use. For such cases, GuiXT allows us to apply common Windows means (ActiveX technology) to communicate with the special controls. In most cases you do not need to program any exit function, since the GuiXT Controls component (guinet.dll) already includes useful functions for many practical needs.

The technical background and typical examples are provided in the present and the following articles.

1. Technical background: SAP control framework
SAP GUI receives all information about the normal screen elements from the SAP application server via a special protocol, the so-called "diag" protocol. GuiXT is implemented as an exit function which is called up by SAP GUI for each "diag" protocol record. GuiXT changes the content of the screen description in the "diag" protocol record while executing your GuiXT script.

Special UI controls such as the ALV Grid Control or the Tree Control are not part of the "diag" protocol. Instead, SAP uses the following "control framework" technology:

  • Each UI control is implemented as a separate Windows ActiveX component (.ocx file)
  • The SAP GUI automation controller communicates with the ActiveX components via OLE automation
  • On the application server, there is an ABAP class for each control type allowing the ABAP programmer to deal with the UI control via ABAP OO means.
  • The communication between the ABAP object on the application server and the UI control on the frontend takes place in a separate channel which cannot be influenced by GuiXT

For example, the ABAP class for the ALV Grid View control is "CL_GUI_ALV_GRID_BASE" (transaction SE24). The constructor method in this class sets the technical ActiveX identification "SAPGUI.GridViewCtrl.1" which links to the implementation file "GridView.ocx" on the frontend PC.

2. Native Control Interface in GuiXT Controls

With GuiXT Controls you can call up VB.NET functions in your script, either in a synchronous way with the command CallVB or asynchronously with CallVBAsync. The native control interface now allows us to request an object reference to a SAP GUI control so that we can read and change the control's properties or call up its methods.

In almost all cases you need to work asynchronously, i.e. with CallVBAsync, since the controls are built up by SAP GUI after calling the GuiXT exit for a screen; they do not yet exist at the time when your script is running.

Example:

In transaction IH08 (Equipment list) we want to add a grid title showing how many items of equipment have been selected.

GuiXT script:

 

VB.NET function SetTitle_IH08:

Result

:

If the grid title looks a little bit too large, you can change its size in your VB function with

resulting in

Here GRIDVIEWLib is the "type library" of the ALV Grid AxtiveX component.

General hint for the Native Control Interface:
Please observe that properties and methods of the ActiveX control can be changed by SAP without any notice, invalidating your program.

This is not very likely, since SAP itself uses the ActiveX interface and needs the controls working for older SAP releases. And each GuiXT script already relies on field labels and technical field names that theoretically can change, but practically are quite stable from release to release.

3. Automating user actions in the controls

The ActiveX control interfaces contain many methods that correspond to user actions, for example you can click a button in a toolbar control. When you do this in your VB.NET function, it will not work in most cases when you do it with a straight method call. For example, you want to click the "Open project" button in the project builder transaction CJ20N in an InputScript. The button is implemented within a special toolbar control in this transaction:

 

InputScript:

 

VB function "clickbutton":

 

The button click does not work and you receive the following error popup instead:

 

The ActiveX control does not accept such method calls from your VB program, since internally your  method call can interfere with user actions; this is not synchonized. GuiXT provides the means to call the method in the same context as the control receives the UI action message, thereby avoiding the problem of parallel actions.

To use this technology, simply replace the method call

with

And voilą - this gives the desired result:

 

4. Predefined funtions

Handling the native controls is not always easy. Namely the Tree Control and the ALV Grid Control have the unpleasant (for our purposes) property that the content of large trees and large grids is typically loaded only partially at the beginning of the transaction. Further internal requests are  made when the user scrolls to a not yet loaded row or clicks a tree node whose subtree is not yet loaded.

Both with SAP GUI scripting and with native scripting you simply receive an empty grid cell content, since the access via scripting does not trigger the lazy loading.

To avoid difficulties of this kind we suggest you use the functions aleady built into the GuiXT Controls "guinet.dll". These functions, for example, will trigger the loading of a subtree when you request a click on a particular node.

The built-in functions are listed in the next article. Most of the subsequent samples need the built-in functions only, without requiring your own VB programming. In the preceding example (toolbar button click) you use the "toolbarcontrol.clickbutton" function of the guinet.dll:

Screen saplcnpb_m.1000
 
 CallVBAsync guinet.toolbarcontrol.clickbutton "OPEN"
  
Enter

Example Tree Control:

In transaction SPRO we want to add a couple of "Quick links" which immediately open a particular path in SAP Reference IMG:

 

GuiXT script:

Box (16,1) (23,78) "Quick IMG links"

Pushbutton (18,2) "Value Contract" process="img_navigate.txt" size=(2,16)
using PATH = "SAP Customizing Implementation Guide\Sales and Distribution\Sales\Sales Documents\Contracts\Value Contract"

// add more quick link buttons here ...

InputScript "img_navigate.txt"

Parameter PATH // path to navigate to

// to SAP Reference IMG
Enter
"/5" // toSAP Reference IMG

Screen SAPLSHI01.0200
  CallVBAsync guinet.treecontrol.SelectNodeByPath "&U[PATH]"
  Enter

When we press our "quick link" button we reach the desired tree node without any of our own navigation steps:

 

Components
Controls