Custom Controls (SAP Library - Screen

Programming)

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

Generated by Jive SBS on 2010-11-18+01:00

1
Custom Controls (SAP Library - Screen Programming)

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.

Application Controls

Generated by Jive SBS on 2010-11-18+01:00

2
Custom Controls (SAP Library - Screen Programming)

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.

Generated by Jive SBS on 2010-11-18+01:00

3
Custom Controls (SAP Library - Screen Programming)

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.

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

Generated by Jive SBS on 2010-11-18+01:00

4
Custom Controls (SAP Library - Screen Programming)

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.

Related Information

Generated by Jive SBS on 2010-11-18+01:00

5
Custom Controls (SAP Library - Screen Programming)

For further information about controls, and in particular, help

on troubleshooting and optimizing synchronization, refer to
BC
Controls Tutorial
and
BC SAP Control Framework.

Example

The following example shows the difference between system 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.

Generated by Jive SBS on 2010-11-18+01:00

6
Custom Controls (SAP Library - Screen Programming)

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
***************************************************

Generated by Jive SBS on 2010-11-18+01:00

7
Custom Controls (SAP Library - Screen Programming)

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,

Generated by Jive SBS on 2010-11-18+01:00

8
Custom Controls (SAP Library - Screen Programming)

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.

Generated by Jive SBS on 2010-11-18+01:00

9
Custom Controls (SAP Library - Screen Programming)

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.

Generated by Jive SBS on 2010-11-18+01:00

10
Custom Controls (SAP Library - Screen Programming)

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

Generated by Jive SBS on 2010-11-18+01:00

11
Custom Controls (SAP Library - Screen Programming)

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 screen

100 is:

The screen contains

an output field field
and a custom control
called textedit .

Generated by Jive SBS on 2010-11-18+01:00

12
Custom Controls (SAP Library - Screen Programming)

The flow logic of

screen 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 you run the
program, the classes
CL_GUI_CUSTOM_CONTROL,
CL_GUI_TEXTEDIT,
and event_handler

Generated by Jive SBS on 2010-11-18+01:00

13
Custom Controls (SAP Library - Screen Programming)

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.

Generated by Jive SBS on 2010-11-18+01:00

14
Custom Controls (SAP Library - Screen Programming)

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

Generated by Jive SBS on 2010-11-18+01:00

15
Custom Controls (SAP Library - Screen Programming)

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
.

Generated by Jive SBS on 2010-11-18+01:00

16