Use
A custom control is a rectangular area on the screen of a dynpro. They are created in Screen Painter and, like all other screen objects, have a unique name. Custom controls are used to embed controls in these areas. Controls are software components of the presentation server. Depending on the SAP GUI used, these components are either ActiveX controls or JavaBeans. They allow certain tasks, such as editing texts, to be performed locally on the presentation server. The control is driven by the application logic, which continues to run on the application server.
SAP Control Framework
The controls on the presentation server and the ABAP application programs on the application server communicate using SAP Control Framework. SAP Control Framework 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. The classes for controls shipped by SAP can be found, for example, in the class library under Basis Frontend Services, or Basis Component Integration. Programs that use controls on a screen of a dynpro work exclusively with the methods and events of these classes.
Container Controls
Before a custom control on a screen can be used, it must be assigned a container control. Container controls are instances of special global classes from SAP Control Framework. The global class for custom controls is called CL_GUI_CUSTOM_CONTAINER. To associate a custom control with a container control, the custom control name is passed to the constructor of the container control when it is instantiated using CREATE OBJECT.
As well as using custom containers, controls can be associated with dynpros using a docking container from the class CL_GUI_DOCKING_CONTAINER. Docking containers do not embed the control in a dynpro. Instead, they attach it to one of its four edges. Containers can also be nested. For example, splitter controls from the classes CL_GUI_EASY_SPLITTER_CONTAINER or CL_GUI_SPLITTER_CONTAINER can be associated with other containers. This makes it possible to split a custom control or docking control into more than one window, so enabling more than one standalone control to be used in a single container.
Application Controls
An instance in the ABAP program must also be created for the actual application control to be displayed in the custom control area, for example a TextEdit control from the class CL_GUI_TEXTEDIT or a tree control from the class CL_GUI_SIMPLE_TREE. When the control is instantiated, a reference to the required container control is passed to the parameter PARENT of the constructor. The container may be an instance of the class CL_GUI_CUSTOM_CONTAINER, but can also be an instance of one of the other containers.
Control Methods
For information about control methods and their documentation, see the class definitions in 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. A synchronization point can be forced in the program by using non-buffered method calls or by calling the static method FLUSH from the global class CL_GUI_CFW in Control Framework.
Control Events
Unlike dynpros, where user interaction triggers the PAI event and control is passed to the application server, user interaction on controls is not automatically passed back to the application server. If an event is to be passed back to the application server, it must be registered in the program using the special method SET_REGISTERED_EVENTS from the class of the control. For a list of the events that can be registered for each control, see to its wrapper class in Class Builder. Two kinds of event handler can be defined using SET_REGISTERED_EVENTS:
Handling as System Events (Default)
The event is passed to the application server, but does not trigger the PAI. If an event handler method is registered in the associated ABAP program for the event (using the statement SET HANDLER), this method is executed on the application server.
Within the event handler method, the static method SET_NEW_OK_CODE of the global class CL_GUI_CFW is used to set a function code and trigger the PAI event in a program-driven way and pass any function code. After PAI processing, 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 dynpro. One drawback, however, is that the contents of the remaining dynpro fields are not transported to the program automatically, which means that obsolete values could appear on the next screen. A workaround for this is to use the SET_NEW_OK_CODE method to trigger a field transport after the event handler has finished.
Handling as Application Events
The event is passed to the application server and triggers the PAI. The function code passed contains an internal identifier. This does not have to be evaluated in the ABAP program. Instead, if the event is to be handled, a method call must be included in a PAI dialog module for the static method DISPATCH of the global class CL_GUI_CFW. If an event handler method is defined in the ABAP program for the event (using the statement SET HANDLER ), the DISPATCH method calls it. After the event is handled, control is passed to the PAI event after the DISPATCH method call and PAI processing continues.
The advantage of this is that the point at which the event is handled can be specified and the contents of the dynpro fields are transported to the application server beforehand. One drawback, however, is that this kind of event handling can produce conflicts with the automatic input checks on the dynpro, causing events to be lost.
More Information
For further information about controls, and in particular help on troubleshooting and optimizing synchronization, see BC Controls Tutorial and
Example
The following example shows the difference between system events and application events.
REPORT demo_custom_control .* Declarations *****************************************************CLASS event_handler DEFINITION. PUBLIC SECTION. METHODS: handle_f1 FOR EVENT f1 OF cl_gui_textedit IMPORTING sender, handle_f4 FOR EVENT f4 OF cl_gui_textedit IMPORTING sender.ENDCLASS.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 ***************************************************START-OF-SELECTION. line = 'First line in TextEditControl'. APPEND line TO text_tab. line = '--------------------------------------------------'. APPEND line TO text_tab. line = '...'. APPEND line TO text_tab. CALL SCREEN 100.* Dialog Modules *****************************************************MODULE status_0100 OUTPUT. SET PF-STATUS 'SCREEN_100'. IF init is initial. init = 'X'. CREATE OBJECT: container EXPORTING container_name = 'TEXTEDIT', editor EXPORTING parent = container, handle. 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. ENDIF. CALL METHOD editor->set_text_as_stream EXPORTING text = text_tab.ENDMODULE.MODULE cancel INPUT. LEAVE PROGRAM.ENDMODULE.MODULE user_command_0100 INPUT. save_ok = ok_code. CLEAR ok_code. CASE save_ok. WHEN 'INSERT'. CALL METHOD editor->get_text_as_stream IMPORTING text = text_tab. WHEN 'F1'. MESSAGE i888(sabapdocu) WITH text-001. WHEN OTHERS. MESSAGE i888(sabapdocu) WITH text-002. CALL METHOD cl_gui_cfw=>dispatch. ENDCASE. SET SCREEN 100.ENDMODULE.* Class Implementations **********************************************CLASS event_handler IMPLEMENTATION. 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. ENDMETHOD. 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. ENDMETHOD.ENDCLASS.
The layout of dynpro 100 is:
The dynpro contains an output field field and a custom control called textedit.
The flow logic of dynpro 100 is:
PROCESS BEFORE OUTPUT. MODULE status_0100.PROCESS AFTER INPUT. MODULE cancel AT EXIT-COMMAND. 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 the program is executed, objects of the classes CL_GUI_CUSTOM_CONTROL, CL_GUI_TEXTEDIT, and event_handler are instantiated at PBO of dynpro 100.
The container control is associated with the custom control on the dynpro and the instance of the textedit control is associated with 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 and 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 dynpro 100 is displayed, the textedit control is filled with the contents of table text_tab . The user can edit the text while the dynpro is being displayed. If the user chooses INSERT, the PAI event is triggered and the current text from the textedit control is passed to 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. This is the only way to ensure that the PBO is processed and the contents of field are sent to the dynpro.
If the user chooses F4 on the textedit control, the PAI event is triggered. The DISPATCH method is called and triggers the method handle_f 4. 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 sent.
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.
