http://www.itpsap.

com/blog/2012/04/15/sap-controls-technology-part-1/

Controls Technology What Every ABAP Developer Needs to Know

In this months blog I will begin to take a look at the SAP Controls Technology and how we can use this advanced control technology in our development. Lets start out by defining a control of the Controls Technology. Controls are independent binary software components that are installed on a local PC (the presentation server). When you install a local SAP GUI on your machine, the system also installs the appropriate controls. The SAP GUI functions as a container for controls at the front-end. Controls can either replace or work alongside classical ABAP components, and can either be ActiveX controls or JavaBeans. Typical examples of Controls Technology controls are: - Picture controls, which allow you to display any picture (.BMP, .JPG, or .GIF format) on the SAP R/3 screen - Tree controls, which are used to display and work with a tree structure - Text-edit controls, which allow you to implement editors for viewing and maintaining texts - HTML viewer controls, which allow you to display HTML pages and graphics in your transactions Lets take a look at the transaction SE80 below

Figure 1 above shows the Object Navigator(SE80), which is used to display the contents of an ABAP program. Tree and textedit controls were used from the Controls Technology to design this interface. On the left, you can see the tree control, which allows you to navigate quickly through the various components of a program. On the right is the textedit control, which allows you to implement the functionality that a typical ABAP Editor provides. Starting as far back as Release 4.5,

these types of Controls Technology controls came with the SAP GUI, and you could access them through ABAP Object classes. What does an ABAP developer need to know to take advantage of the Controls Technology, and whats the best way to get started? Thats what this blog series will address. I am assuming the reader has practical ABAP experience and a basic understanding of ABAP Objects.

Controls Technology: Some Brief Background

Lets review some of the technical aspects of controls technology: -The SAP Control Framework -The Automation Queue, and the issues surrounding flushing it -Event handling -Error handling Including Controls Technology controls on the front-end establishes a client/server relationship between the application server and the controls on the presentation server. The application server (the automation client) drives the controls (automation server) at the presentation server by calling functions (methods) that they provide. Take a look at the diagram below.

The application logic runs on the application server. The application server transfers methods to the front-end by means of a Remote Function Call (RFC) and then executes them. The communication between the control and the application logic (on the application server) is administered by the SAP Control Framework ABAP Objects are used to implement controls in programs. Each control has a global wrapper class in ABAP Objects. The table below summarizes the most common controls and their respective wrapper classes.

In order to work with Controls Technology controls on your screen, you simply create objects of these wrapper classes, call their methods, and react on their events. The real art of controls programming lies in selecting the control that best fulfills your requirements and then calling th e appropriate methods that its wrapper class provides. Each wrapper class provides us with methods to modify the control properties, and thus influence the behavior of the control. For example, the class CL_GUI_PICTURE_CONTROL provides the method load_picture_from_url, which enables us to display a picture on the screen. The user of an application program triggers control events by performing specific actions (for example, double-clicking). You can decide which events you want to catch in your ABAP program and then register these events for the relevant control. For example, the class CL_GUI_SIMPLE_TREE provides us with the NODE_DOUBLE_CLICK event to notify the program that a tree node has been doubleclicked. A triggered event is then transferred from the SAP GUI to the application server. In response to this event, you can then influence the behavior of the control with additional method calls. For example, when the user tries to expand a tree node by clicking or double-clicking on it, you can add further nodes to the tree by calling the method CL_GUI_SIMPLE_TREE=>add_nodes.

Navigating Through the Control Classes in the Controls Technology

All controls in the Controls Technology are encapsulated in a wrapper class. A wrapper class is a global ABAP Objects class that encapsulates the complete functionality of the control, making it easy for developers to reuse the functions that they provide. Before coding, its always a good idea to become familiarized with the structure of the wrapper class. To do this you could use SE24 (Class Editor), or an easier tool would be SE80 (the Object Navigator). 1. Enter transaction code SE80 (Object Navigator) in the command field. 2. Enter the name of the class in the Class input field on the Object Navigator initial screen and choose Display. 3. A tree structure appears for the class you have chosen. You can see from the figure below, that I have called up the CL_GUI_SIMPLE_TREE wrapper class. You can see the expanded wrapper class and its sub-objects. I clicked on the Methods node, and then double-clicked on NODE_SET_TEXT to view the source code of that particular method. You can click on the root node to view all the sub-objects of the wrapper class, and then go further and expand the child nodes to view the list of items in that particular category.

Typically, the Object Navigator provides you with the following information: Superclasses: Under the superclasses category, you will find the complete inheritance hierarchy, which lets you see all the classes from which the control has been derived e.g., the class CL_GUI_SIMPLE_TREE is derived from the class CL_TREE_CONTROL_BASE, which is further derived from the class CL_GUI_CONTROL, and so on. The interface of the class CL_GUI_SIMPLE_TREE also includes the public methods of the classes CL_TREE_CONTROL_BASE and CL_GUI_CONTROL. Attributes: This is the set of data that the class encapsulates. Attributes may be properties of a control, establishing things like the shape, size, or position of an element on the screen. They may be static (defined for all objects), private, or public. Event IDs of specific events (e.g., click, double-click) are also included in attributes. For example, the class CL_GUI_SIMPLE_TREE has the attributes WS_VISIBLE and EVENTID_NODE_DOUBLE_CLICK. Methods: These are operations that can be performed on a control. There may be methods to change the appearance of a control, to set values of its attributes, etc. One special method, the constructor, allows you to create (or construct, as its name implies) objects. For example, class CL_GUI_SIMPLE_TREE gives us methods like GET_WIDTH, COLLAPSE_ALL_NODES, and so on. Events: The events that are listed by the Object Navigator tell you what specific events the control may be able to respond to. All events have a meaningful name. The class CL_GUI_SIMPLE_TREE, for example, has events RIGHT_CLICK and NODE_DOUBLE_CLICK.

Containers in Controls Technology Linking Controls with Containers

Every control that needs to be displayed on the screen must be linked to a container, which is linked to a screen area. A container in the Controls Technology has the following features: -It provides a physical area where the controls can be displayed. -It manages controls in a logical collection. -It behaves like the parent of the control within it.

-It can contain other controls (for example, a tree control, a picture control, an HTML viewer control, and so on). Remember, a container is also a control inside the Controls Technology. -All controls in the Controls Technology live in a container. (The lifetime of a container should always be greater than the lifetime of the controls within it.) -If a parent is not visible, its children are also not visible. -The default size of a control is the same as the size of its container. It can be changed at the time the control is instantiated. -Containers can be nested, thus you can place one container within another container. SAP provides you with five kinds of containers for use in the Control Technology. The table below lists the SAP-provided containers, along with their wrapper classes.

Containers are instances of special global control classes. Each kind of container is wrapped in a separate class of ABAP Objects. Like other control classes of the Control Technology, container classes are derived from the class CL_GUI_CONTROL. You choose the container that best suits the type of functionality you would like to implement. Linking a control to a container on a screen involves a few easy steps. Suppose we want to place a tree control on the screen. In order to do this, we must first create a custom container, then link it to accommodate the tree control. Take a look at the following steps: 1. Create a screen on which to place the control. Create a screen area CONT for your custom container control using the Screen Painter. 2. We then need to define a reference variable for the container in which to place our control: DATA: mycontainer TYPE REF TO cl_gui_custom_container.

and then define a reference variable for the tree control: DATA: mytree TYPE REF TO cl_gui_simple_tree. 3. The classes of containers provide constructors for creating the container objects. The constructors are called by using the CREATE OBJECT statement as follows: CREATE OBJECT mycontainer EXPORTING container_name = CONT EXCEPTIONS cntl_error = 1 cntl_system_error = 2 create_error = 3 lifetime_error = 4 lifetime_dynpro_dynpro_link = 5. The above code creates a container for one tree control, and the container is linked to our control with the name CONT on the dynpro (exporting parameter container_name). 4. Finally, we create a tree control object and place it in the container that we have just defined. We use the constructor that the class CL_GUI_SIMPLE_TREE provides us: CREATE OBJECT mytree EXPORTING parent = mycontainer EXCEPTIONS cntl_error = 1 cntl_system_error = 2 create_error = 3 lifetime_error = 4 lifetime_dynpro_dynpro_link = 5. We have successfully created a screen, added a customer container screen control, created an object for the controls container referencing the screen area, and finally created an object for the tree control and linked it back to the container. That was a brief overview of the Controls Technology Framework. In the next blog we can look closer at the Automation Controller, and Automation Queue.

The Controls Technology Framework,Automation Controller, and Automation Queue

In this months blog I will continue to take a look at the SAP Controls Technology and how we can use it in our development. There is constant communication passed between controls on the SAP GUI and the application that resides on the application server. The SAP Controls TechnologyFramework and the Automation Controller are the vehicles by which these communications take place. The Controls Technology Framework resides on the application server (the back-end), and the Automation Controller sits on the presentation server (the front-end). The integral component that optimizes the communication between the two is the Automation Queue.

Lets take a closer look at the benefits this architecture offers by examining how the SAP Controls Technology Framework enables integration and use of your controls through ABAP OO methods, and how the Automation Queue provides a buffer to the Automation Controller to help avoid decreased system performance.

The SAP Controls Technology Framework ABAP OO Methods

The Controls Technology Framework supports all the controls that are implemented within the SAP GUI. It encapsulates all available controls in global wrapper classes of ABAP Objects, and even maintains a list of the control instances you have created. To work with controls on your screen, you simply create objects of these wrapper classes, call their methods, and react on their events.Therefore, when integrating a control into your program, you are actually just calling delivered methods of the Controls Technology Framework. The controls at the front-end are utilized by using the methods of the Controls Technology Framework classes CL_GUI_CFW, CL_GUI_OBJECT, and CL_GUI_CONTROL.

The SAP Controls Technology Framework offers you classes for:

- Creating, initializing, and positioning controls to be displayed on the front-end or Presentation Layer - Making a control visible or invisible - Checking whether a control is still active or has been destroyed - Querying a control to retrieve information regarding its height or width - Enabling the possibility to implement user interaction in the program by using events (examples of events are click, double-click, drag and drop, and so on) - Buffering control methods in a queue and transferring them to the front-end for execution - Destroying controls at the front-end and freeing the memory they occupy Lets take a closer look at each of these classes in turn

The CL_GUI_CFW Class

The CL_GUI_CFW class contains only static methods, which apply collectively to all the controls that exist at the front-end. The two most commonly used methods are dispatch and flush:

The dispatch method

In the case of certain events (application events) the event handler method is not called before the PAI (Process After Input) event. If you wish to call the event handler within the PAI event, the dispatch method is used: CALL METHOD cl_gui_cfw=>dispatch IMPORTING return_code = return_code. The value of return_code indicates whether or not the call was successful. If you do not call this method in your program (explicit), the system calls this method automatically after the end of the PAI event (implicit).

The flush method

This method is used to force synchronization of the Automation Queue. All the buffered methods in the queue are then transferred to the front-end via RFC for execution: CALL METHOD cl_gui_cfw=>flush EXCEPTIONS cntl_system_error = 1 cntl_error = 2.

If there is any error, an exception is triggered. If you do not call this method in your program (explicit), the system calls this method itself after the end of the PAI event (implicit).

The CL_GUI_OBJECT Class

The CL_GUI_OBJECT class is the superclass of all control wrapper classes. The commonly used methods are is_valid and free:

The is_valid method

This method informs you whether or not a control for an object reference still exists at the front-end. Suppose you want to find out whether or not the variable my_control has the object reference of an instantiated control. In that case, you use the following code:

CALL METHOD my_control->is_valid IMPORTING result = result. If the value of result is 1, then the control is active. A value of zero means it is inactive.

The free method

This method is used to destroy a control at the front-end. The method also deletes the entry of the control from the Controls Technology Framework system table. You should also initialize the object reference after this method call: CALL METHOD my_control->free EXCEPTIONS cntl_error =1

cntl_system_error = 2. Free my_control.

The CL_GUI_CONTROL Class

The CL_GUI_CONTROL class is inherited from the superclass CL_GUI_OBJECT. All control classes are then inherited from this class. It contains the following methods for setting attributes of the control and implementing event handling:

The constructor method

This method is called by the control wrapper when you instantiate a control by the CREATE OBJECT statement.

The set_registered_events method

This method is used to register the events of the control (this will be covered in more detail in the upcoming blog, Part 3, on event handling): CALL METHOD my_control->set_registered_events EXPORTING events = it_events EXCEPTIONS cntl_error cntl_system_error =1 =2

illegal_event_combination = 3. The table it_events contains a list of the events that you want to register, and is based on the DDIC structure CNTL_SIMPLE_EVENT.

The get_registered_events method

This method returns a list of all events registered for a control: CALL METHOD my_control->get_registered_events IMPORTING events = it_events EXCEPTIONS cntl_error = 1. Again, the it_table events should be based on the DDIC structure CNTL_SIMPLE_EVENT.

The set_visible method

Use this method to make a control visible or invisible: CALL METHOD my_control->set_visible EXPORTING visible = visible EXCEPTIONS cntl_error =1

cntl_system_error = 2. If the value of the variable visible is equal to X, the control becomes visible. When it is equal to space ( ), then it becomes invisible.

The is_alive method

If a control is already destroyed and you try to destroy it again, an error will occur. To avoid this we can determine the state of a control using the following code: CALL METHOD my_control->is_alive RETURNING state = state. If the control is active and visible, then the value of state will be equal to the attribute state_alive of the control.

How the Automation Queue provides a buffer to the Automation Controller to help avoid decreased system performance.
Each control class method, if called immediately from your ABAP program, could open a separate Remote Function Call (RFC) connection between the application server and the front-end. Too many RFC calls can result in poor system performance and excessive consumption of system resources. To avoid this, the Controls Technology Framework methods are not executed when they are called. They are instead inserted into a buffer called the Automation Queue before being sent for execution to the Automation Controller (the presentation server) at defined synchronization points. Automatic synchronization occurs at the end of the PBO (Process Before Output) event. Synchronization can also be forced by calling the static method CL_GUI_CFW=>FLUSH. The Automation Queue follows a FIFO (First In, First Out) principle. At synchronization, the methods that are called first are executed first. For every internal session, there is a separate Automation Queue to handle its controls (see below).

At synchronization, the Automation Queue passes its contents (methods m1, m2, and m3, in that order) to the front-end. The methods are executed at the front-end and the results are returned to the back-end. That was a brief overview of the Controls Technology Frameworks use of the Automation Controller, an d Automation Queue. We also explored the OO Class structure and commonly used methods in ABAP development. In the next blog we can look closer at the Events and Error Handling.

The Controls Technology Framework, Event and Error Handling

In this final blog of the series on the Controls Technology Framework, I will continue to take a look at the SAP Controls Technology and how we can use it in our development. I will focus on Events and their respective handling techniques along with errors.

Event Handling in the Controls Technology Framework

Events are used to implement user interaction within a program. The user triggers control events by performing specific actions (e.g., double-clicking). For a complete list of events relevant to a particular control, refer to the control class documentation or the Object Navigator (transaction SE80). There are two kinds of events: System events: A system event is triggered before any automatic field checks (e.g., required fields) have taken place on the screen, and before any field transports. The PAI and PBO events are not triggered. By default, an event is a system event. The event handler method is called automatically before the PAI event. Application events: An application event triggers the normal PAI event. Consequently, all field checks and field transports have taken place. If you want the event handler method to be called at a particular point in your application program, you must call the static method CL_GUI_CFW=>DISPATCH in a PAI module. The dispatch method calls the event handler method that is defined and registered for that event. After the event handler method is called, normal PAI event processing continues. There are advantages and disadvantages to employing both types of events. Below is a summary

For performance reasons, the frontend must not pass all events to the application server, and it must be clear at runtime whether an event must take place as a system or an application event. This is necessary so that the point of time at which the event handler is triggered (either before the PAI event and screen field transports, or after) can be determined. For this purpose, the information regarding events is stored in special internal tables, both on the application server and the presentation server. The table at the frontend is managed by the Automation Controller; the tables at the backend are administered by the Controls Technology Framework. Loo at the diagram below to get an idea of how the Automation Controller and the Control Framework handle an event.

When an event is triggered by the user at the frontend, the Automation Controller checks whether the event is registered or not. If the event is not registered, the Automation Controller ignores it. Otherwise, it generates an OK_CODE that is passed to the Controls Technology Framework. The Controls Technology Framework then calls the event handler method. For the system event, the handler method is called directly. In the case of an application event, you must call the static method CL_GUI_CFW=>DISPATCH within the PAI module. The event handling of controls involves three steps:

1. Register the events. You need to construct the event tables using a special ABAP Objects Controls Technology Framework method (control-> set_registered_events). The table has a type based on the cntl_simple_events structure. Define an internal table (type cntl_simple_events) and a corresponding work area (type cntl_simple_event): DATA events TYPE cntl_simple_events. DATA event TYPE cntl_simple_event. Now fill the event table with the relevant events. To do this, you need the event ID (event_id field). You can find this information in the Object Navigator by looking at the attributes of the control class CL_GUI_SIMPLE_TREE. You must also decide whether the event is to be a system event (appl_event = ) or an application event (appl_event = X): event-eventid = event_id.

event-appl_event = appl_event. APPEND event TO events. Finally you must now send the event table to the frontend so that it knows which events it has to direct to the backend:

CALL METHOD my_control-> set_registered_events events = events. 2. Define the event handler methods. To react to the events of our control, we must now specify a handler method for it. This can be either an instance method or a static method. However, it must be defined in a local class. Suppose we want to catch the event NODE_DOUBLE_CLICK in a simple tree control. We would define a class whose definition is as follows: Class handler_class definition. Public-section. Class-methods my_method For event NODE_DOUBLE_CLICK of CL_GUI_SIMPLE_TREE Importing node_key sender. Endclass. You can then implement the handler. The methods sender parameter is always imported, which contains information regarding the control that fired the event. You can also import additional parameters in our case, we have imported the node that fired the event. 3. Register the handler methods for the events. This is done via the following line of code. SET HANDLER for handler_class=>my_method for my_control. The variable my_control is the reference variable of the tree object. In the case of a system event, the handler method that you define for the event is called automatically by the system. Since the PBO and PAI events are not called, you can use the method set_new_ok_code to set a new value for the OK_CODE field. This then triggers the PAI and PBO modules. Calling the method set_new_ok_code also carries out normal field transport. To process an application event, you must call the static method CL_GUI_CFW=>DISPATCH within a PAI module. You cannot trigger the handler method for a second time by calling the dispatch method twice. Keep it simple. Use the application event when you use other screen components e.g., input/output fields along with the controls since only in this case will you want the event handler to access the latest values of the screen fields. If you use only the controls and no old screen components, a system event will suffice.

Error Handling (Debugging) in the Controls Technology Framework

The majority of errors in controls technology programming occur during synchronization of the Automation Queue. This raises the exception CNTL_ERROR. The exception only indicates that a method call was unsuccessful, and since there may be many control methods called from a program, it is difficult to figure out which method raised the exception. It is up to the developer to find out where the error occurred and which control fired the exception. When a method in the queue gives an exception, the methods that follow it are also not executed. Lets look at a simple example of the type of error that can occur. SAP offers the method CL_GUI_SIMPLE_TREE >add_nodes for adding nodes to the simple tree. If you attempt to add two nodes with the same node key (which has to be unique) to the tree structure, a CNTL_ERROR exception is triggered. This error is not apparent until the Automation Queue is synchronized. The steps involved in error handling are: 1. Run the program in the ABAP Debugger by entering the name of the program in the ABAP Editor (transaction SE38) and selecting Program Execute Debugging. 2. In the debugger settings, select the option Automation Controller: Always process requests synchronously. Selecting this option synchronizes the Automation Queue after each method call.

3. Step through the individual methods. You will find that the value of SY-SUBRC has been set in the method(s) where an exception has been triggered. Otherwise a short dump occurs Now that you have a basic technical understanding of controls technology framework, you are ready to take the next step and actually integrate a control maybe a tree control into an ABAP program. Controls technology has become a valuable tool for ABAP developers. It provides a great deal of functionality, and an efficient way to build interactive and user-friendly interfaces that benefit your end users without requiring you to start from scratch, an advantage every time-strapped programmer can appreciate.