Start of Content Area

Custom Controls  Locate the document in its SAP Library structure

A custom control is an area on a screen. You create them in the Screen Painter, and, like all other screen objects, they have a unique name. You use custom controls to embed controls. Controls are software components of the presentation server. Depending on the used SAP GUI, these are either ActiveX Controls or JavaBeans. They allow you to perform tasks, such as editing texts, locally on the presentation server. The control is driven by the application logic, which still runs on the application server.

The SAP Control Framework

The controls on the presentation server and the ABAP application programs on the application server communicate using the SAP Control Framework. The SAP Control Framework is programmed in ABAP Objects . It contains global classes that can be found in the class library under Basis Frontend Services. These classes encapsulate the communication between the application server and presentation server, which is implemented using Remote Function Call.

All application controls are encapsulated in a global class. You can find the SAP Basis controls in the Class Browser under Basis Frontend Services or Basis Component Integration. Programs that use controls on a screen work with the methods and events of the global classes that encapsulates them.

Container Controls

Before you can work with a custom control on a screen, you must assign a SAP Container Control to it. Container controls are instances of special global classes from the SAP Control Framework. The global class for custom controls is called CL_GUI_CUSTOM_CONTAINER. To link a custom control to a container control, pass the custom control name to the constructor of the container control when you instantiate it using CREATE OBJECT.

As well as using custom containers, you can link controls to a screen using a SAP Docking Container. This is encapsulated in the global class CL_GUI_DOCKING_CONTAINER. The SAP Docking Container does not place the control within a screen. Instead, it attaches it to one of the four edges. You can nest containers. For example, you can use the SAP Splitter Container (classes CL_GUI_EASY_SPLITTER_CONTAINER or CL_GUI_SPLITTER_CONTAINER) within other containers. This allows you to split a custom control or docking control into more than one area, allowing you to embed more than one control.

This graphic is explained in the accompanying text

Application Controls

You must also create instances for the application controls that you want to place within your container - for example, a SAP Textedit Control (class CL_GUI_TEXTEDIT) or a SAP Tree Control (for which there is more than one global class - an example is CL_GUI_SIMPLE_TREE). When you instantiate the control, you pass a reference to the container in which you want to place it to the PARENT parameter of its constructor method. The container may be an instance of the class CL_GUI_CUSTOM_CONTAINER, but can also be an instance of one of the other SAP Container controls.

Control Methods

For information about control methods and their documentation, refer to the class definitions in the Class Builder or the SAP Library documentation. To minimize the network load between the application and presentation servers, method calls are buffered in the automation queue before being sent to the presentation server at defined synchronization points. One of the automatic synchronization points is the end of PBO processing. You can force a synchronization point in your program by calling a method that is not buffered, or by calling the static method FLUSH.

Control Events

Unlike screens, on which user interaction triggers the PAI event and control returns to the application server, user interaction on controls is not automatically passed back to the application server. If you want an event to be passed back to the application server, you must register it in your program using the special method SET_REGISTERED_EVENTS. For a list of the events that you can register for each control, refer to its wrapper class in the Class Builder. You can register two kinds of event handling using SET_REGISTERED_EVENTS:

System Events (Default)

The event is passed to the application server, but does not trigger the PAI. If you have registered an event handler method in your ABAP program for the event (using the SET HANDLER statement), this method is executed on the application server.

Within the event handler method, you can use the static method SET_NEW_OK_CODE of the global class CL_GUI_CFW to set a function code and trigger the PAI event yourself. After the PAI has been processed, the PBO event of the next screen is triggered.

The advantage of using this technique is that the event handler method is executed automatically and there are no conflicts with the automatic input checks associated with the screen. The disadvantage is that the contents of the screen fields are not transported to the program, which means that obsolete values could appear on the next screen. You can work around this by using the SET_NEW_OK_CODE method to trigger field transport and the PAI event after the event handler has finished.

This graphic is explained in the accompanying text

Application Events

The event is passed to the application server, and triggers the PAI. The function code that you pass contains an internal identifier. You do not have to evaluate this in your ABAP program. Instead, if you want to handle the event, you must include a method call in a PAI dialog module for the static method DISPATCH of the global class CL_GUI_CFW. If you have defined an event handler method in your ABAP program for the event (using the SET HANDLER statement), the DISPATCH method calls it. After the event handler has been processed, control returns to the PAI event after the DISPATCH statement and PAI processing continues.

The advantage of this is that you can specify yourself the point at which the event is handled, and the contents of the screen fields are transported to the application server beforehand. The disadvantage is that this kind of event handling can lead to conflicts with the automatic input checks on the screen, causing events to be lost.

This graphic is explained in the accompanying text

Related Information

For further information about controls, and in particular, help on troubleshooting and optimizing synchronization, refer to BC Controls Tutorial and BC SAP Control Framework.


The following example shows the difference between system and application events.


REPORT demo_custom_control .

* Declarations *****************************************************

CLASS event_handler DEFINITION.
    METHODS: handle_f1 FOR EVENT f1 OF cl_gui_textedit
                       IMPORTING sender,
             handle_f4 FOR EVENT f4 OF cl_gui_textedit
                       IMPORTING sender.


DATA: ok_code LIKE sy-ucomm,
      save_ok LIKE sy-ucomm.

DATA: init,
      container TYPE REF TO cl_gui_custom_container,
      editor    TYPE REF TO cl_gui_textedit.

DATA: event_tab TYPE cntl_simple_events,
      event     TYPE cntl_simple_event.

DATA: line(256) TYPE c,
      text_tab LIKE STANDARD TABLE OF line,
      field LIKE line.

DATA handle TYPE REF TO event_handler.

* Reporting Events ***************************************************

  line = 'First line in TextEditControl'.
  APPEND line TO text_tab.
  line = '--------------------------------------------------'.

  APPEND line TO text_tab.
  line = '...'.

  APPEND line TO text_tab.

* Dialog Modules *****************************************************

MODULE status_0100 OUTPUT.
  IF init is initial.
    init = 'X'.
           container EXPORTING container_name = 'TEXTEDIT',
           editor    EXPORTING parent = container,

    event-eventid = cl_gui_textedit=>event_f1.
    event-appl_event = ' '.                     "system event
    APPEND event TO event_tab.
    event-eventid = cl_gui_textedit=>event_f4.

    event-appl_event = 'X'.                     "application event
    APPEND event TO event_tab.
    CALL METHOD: editor->set_registered_events
                 EXPORTING events = event_tab.
    SET HANDLER handle->handle_f1
                handle->handle_f4 FOR editor.

  CALL METHOD editor->set_text_as_stream
              EXPORTING text = text_tab.


MODULE user_command_0100 INPUT.
  save_ok = ok_code.
  CLEAR ok_code.
  CASE save_ok.
      CALL METHOD editor->get_text_as_stream
                  IMPORTING text = text_tab.
    WHEN 'F1'.

      MESSAGE i888(sabapdocu) WITH text-001.

      MESSAGE i888(sabapdocu) WITH text-002.
      CALL METHOD cl_gui_cfw=>dispatch.


* Class Implementations **********************************************

  METHOD handle_f1.
    DATA row TYPE i.
    MESSAGE i888(sabapdocu) WITH text-003.
    CALL METHOD sender->get_selection_pos
         IMPORTING from_line = row.

    CALL METHOD sender->get_line_text
         EXPORTING line_number = row
         IMPORTING text = field.

    CALL METHOD cl_gui_cfw=>set_new_ok_code  
         EXPORTING new_code = 'F1'.          
    CALL METHOD cl_gui_cfw=>flush.


  METHOD handle_f4.
    DATA row TYPE i.
    MESSAGE i888(sabapdocu) WITH text-004.
    CALL METHOD sender->get_selection_pos
         IMPORTING from_line = row.

    CALL METHOD sender->get_line_text
         EXPORTING line_number = row
         IMPORTING text = field.

    CALL METHOD cl_gui_cfw=>flush.

The layout of screen 100 is:

This graphic is explained in the accompanying text

The screen contains an output field field and a custom control called textedit.

The flow logic of screen 100 is:

  MODULE status_0100.

  MODULE user_command_0100.

The GUI status SCREEN_100 has the functions BACK, EXIT, and CANCEL (all with type E) and the function INSERT (normal function).

There is a local class event_handler defined in the program. It contains event handler methods for the F1 and F4 events of global class CL_GUI_TEXTEDIT. When you run the program, the classes CL_GUI_CUSTOM_CONTROL, CL_GUI_TEXTEDIT, and event_handler are instantiated in the PBO of screen 100.

The container control is linked to the custom control on the screen, and the instance of the textedit control is linked to this container. The F1 and F4 events of the textedit control are registered using the SET_REGISTERED_EVENTS method to ensure that they are passed to the application server when they occur. F1 is defined as a system event, F4 as an application event. The event handler methods of the handle instance of the class event_handler are registered as handlers for the events.

Before screen 100 is displayed, the program fills the textedit control with the contents of table text_tab . The user can edit the text while the screen is displayed. If the user chooses INSERT, the PAI event is triggered and the current text from the textedit control is copied into table text_tab.

If the user chooses F1 on the textedit control, the handle_f1 method is executed. This assigns the contents of the line to the field field: The method SET_NEW_OK_CODE triggers the PAI event. It is this that ensures that the PBO is processed, and the contents of field are sent to the screen.

If the user chooses F4 on the textedit control, the PAI event is triggered. The DISPATCH method is called, and this triggers the method handle_f4. This assigns the contents of the line to the field field: Since the PAI processing continues after the event, the PBO event follows, and the field contents are transferred to the screen.

The contents of the textedit control are not passed to the internal table text_tab either after F1 or after F4. The contents of the textedit control are therefore overwritten in the PBO event with the previous contents of text_tab.



End of Content Area