List Events in an ABAP Program

After a user interaction on a list, the ABAP runtime environment checks whether it should
process the function code itself (for example, %EX or %PC), or whether it should trigger the
relevant event. Unlike normal screens, in which the PAI event is triggered, the runtime
environment triggers three special events when list events occur. You can use the corresponding
event blocks in your ABAP program to react to the user action. From within the program, you
can use the SY-UCOMM system field to access the function code. There is no OK_CODE field that
is filled.

Event Blocks for Function Codes PF<nn> (Obsolete)

When the user chooses a function code PF<nn> (<nn> can be between 01 and 24), the system
always triggers the AT PF<nn> event. In the standard list status, the function keys F<nn> that
are not reserved for predefined system functions all have the function code PF<nn> as long as a
corresponding event block is defined in the program.

AT PF<nn>.
<statements>.

These event blocks are executed when the user chooses the corresponding function key. The
position of the cursor in the list is irrelevant.

If you use these event blocks at all, it should only be for temporary test versions. In
production programs, you should only use AT USER-COMMAND with a dialog status of your own
to assign function codes to function keys. When you use your own interfaces, the system
displays a function text explaining what the function does. This does not happen when you use
AT PF<nn> event blocks.

Event Block for Function Code PICK

When the user triggers the function code PICK, AT LINE-SELECTION is always triggered if the
cursor is positioned on a list line. The function code PICK is, by default, always linked with
function key F2 and hence with the mouse double-click. Consequently, if you have a simple
program that does not react to any further user actions, you only need to write this event block.

AT LINE-SELECTION.
<statements>.

As described in the section Dialog Status for Lists, the function code PICK is always added to the
standard list status when you have an AT LINE-SELECTION event in your program.

If you assign PICK to other function keys or menu entries, AT LINE-SELECTION is also triggered
when the user chooses then. You should avoid this for the sake of the semantics.

Conversely, if you have a more extensive program that does not react to line selection, you
should not use the function code PICK. Instead you should assign a different function code to
F2 , to ensure that as many events as possible trigger the AT USER-COMMAND event.

Event Block for User-Defined Function Codes

If the user chooses a function code during list processing that is neither processed by the
system, or PICK or PF<nn>, the system triggers the event AT USER-COMMAND. For this event,
you must define your own GUI status for a list. To react to your own function codes in a
program, you must define the following event block:

AT USER-COMMAND.
<statements>.

In this event block, you can use an IF or CASE structure to tell the function codes apart. They
are available in the system field SY-UCOMM. There are further system fields that are filled in list
events, such as SY-LSIND and SY-PFKEY, that allow you to make further case distinctions.

Triggering a List Event from the Program

You can trigger a list event from the program as follows:

SET USER-COMMAND <fc>.

This statement takes effect after the current list is completed. Before the list is displayed, the
event assigned to function code <fc> is triggered, regardless of the dialog status you are using.

The effect is the same as when the user chooses the function. In other words, predefined list
function codes are trapped and processed by the runtime environment, the function codes PICK
and PF<nn> trigger the AT LINE-SELECTION and AT PF<nn> events, and user-defined function
codes trigger the AT USER-COMMAND event block.

Function code PICK triggers an event only if the cursor is located on a list line.

Using this statement in conjunction with the function codes reserved for system functions, you
can call the system functions from the program. For example, you can use SET USER-COMMAND
'%SC' to call the Find dialog box directly, or to position the list correctly before it is displayed.

If you use several SET USER-COMMAND statements while creating a list, the system executes
only the last one.

Examples

Example for AT LINE-SELECTION.

REPORT demo_list_at_line_selection.

START-OF-SELECTION.
WRITE 'Basic List'.

AT LINE-SELECTION.
WRITE: 'Secondary List by Line-Selection',
/ 'SY-UCOMM =', sy-ucomm.

When you run the program, the basic list appears with the standard list status.
The detail list shows that SY-UCOMM has the value PICK.
Example for AT PF<nn>.

REPORT demo_list_at_pf.

START-OF-SELECTION.
WRITE 'Basic List, Press PF5, PF6, PF7, or PF8'.

AT pf5.
PERFORM out.

AT pf6.
PERFORM out.

AT pf7.
PERFORM out.

AT pf8.
PERFORM out.

FORM out.
WRITE: 'Secondary List by PF-Key Selection',
/ 'SY-LSIND =', sy-lsind,
/ 'SY-UCOMM =', sy-ucomm.
ENDFORM.

After executing the program, the system displays the basic list. The user can
press the function keys F5 , F6 , F7 , and F8 to create secondary lists. If, for
example, the 14th key the user presses is F6 , the output on the displayed
secondary list looks as follows:

Secondary List by PF-Key Selection

SY-LSIND = 14

SY-UCOMM = PF06

Example for AT USER-COMMAND.

REPORT demo_list_at_user_command NO STANDARD PAGE HEADING.

START-OF-SELECTION.
WRITE: 'Basic List',
/ 'SY-LSIND:', sy-lsind.

TOP-OF-PAGE.
WRITE 'Top-of-Page'.
ULINE.

TOP-OF-PAGE DURING LINE-SELECTION.

CASE sy-pfkey.
WHEN 'TEST'.
 WRITE 'Self-defined GUI for Function Codes'.
ULINE.
ENDCASE.

AT LINE-SELECTION.
SET PF-STATUS 'TEST' EXCLUDING 'PICK'.
PERFORM out.
sy-lsind = sy-lsind - 1.

AT USER-COMMAND.
CASE sy-ucomm.
WHEN 'FC1'.
PERFORM out.
WRITE / 'Button FUN 1 was pressed'.
WHEN 'FC2'.
PERFORM out.
WRITE / 'Button FUN 2 was pressed'.
WHEN 'FC3'.
PERFORM out.
WRITE / 'Button FUN 3 was pressed'.
WHEN 'FC4'.
PERFORM out.
WRITE / 'Button FUN 4 was pressed'.
WHEN 'FC5'.
PERFORM out.
WRITE / 'Button FUN 5 was pressed'.
ENDCASE.
sy-lsind = sy-lsind - 1.

FORM out.
WRITE: 'Secondary List',
/ 'SY-LSIND:', sy-lsind,
/ 'SY-PFKEY:', sy-pfkey.
ENDFORM.

When you run the program, the system displays the following basic list with a
the page header defined in the program:

You can trigger the AT LINE-SELECTION event by double-clicking a line. The

system sets the status TEST and deactivates the function code PICK. The status
TEST contains function codes FC1 to FC5. These are assigned to pushbuttons in
the application toolbar. The page header of the detail list depends on the status.

Here, double-clicking a line no longer triggers an event. However, there is now

an application toolbar containing five user-defined pushbuttons. You can use
these to trigger the AT USER-COMMAND event. The CASE statement contains a
different reaction for each pushbutton.

For each interactive event, the system decreases the SY-LSIND system field by
one, thus canceling out the automatic increase. All detail lists now have the
same level as the basic list and thus overwrite it. While the detail list is being
created, SY-LSIND still has the value 1.

Example for SET USER-COMMAND.

REPORT demo_list_set_user_command NO STANDARD PAGE HEADING.

START-OF-SELECTION.
SET USER-COMMAND 'MYCO'.
WRITE 'Basic List'.

AT USER-COMMAND.
CASE sy-ucomm.
WHEN 'MYCO'.
WRITE 'Secondary List from USER-COMMAND,'.
WRITE: 'SY-LSIND', sy-lsind.
SET USER-COMMAND 'PF05'.
ENDCASE.

AT pf05.
WRITE 'Secondary List from PF05,'.
WRITE: 'SY-LSIND', sy-lsind.
SET CURSOR LINE 1.
SET USER-COMMAND 'PICK'.

AT LINE-SELECTION.
WRITE 'Secondary List from LINE-SELECTION,'.
WRITE: 'SY-LSIND', sy-lsind.
SET USER-COMMAND '%SC'.

This program creates one basic list and three detail lists. When the program
starts, the third detail list is displayed immediately, along with a dialog box for
searching in the list. The dialog box is displayed by setting the predefined
function code %SC. To view the other lists, the user chooses Back.

Note that in the event AT PF05, the SET CURSOR statement is used to position
the cursor on a list line in order to support the function code PICK.