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.