Dialog Status for Lists (SAP Library - ABAP Programming (BC-ABA))

Dialog Status for Lists

To allow the user to communicate with the system when a list is displayed, the lists must be able to direct user actions to the ABAP program. As described in User Actions on Screens, function codes are used to do this. Function codes are maintained in the GUI status of the list screen. You define a GUI status using the Menu Painter tool in the ABAP Workbench. The system assigns function codes to list-specific user actions.

The most important of these functions is for selecting list lines by double-clicking. As described in Using a GUI Status, the double-click function is always linked to the F2 key. If a function code is assigned to the F2 key in the GUI status, it will be triggered when you double-click.

The Standard List Status

As with normal screens, you can define your own GUI status for lists and attach it to a list level using the SET PF-STATUS statement. If you do not set a particular GUI status, the system sets a default list status for the list screen in an executable program. In other programs, for example, when you call a list from screen processing, you must set this status explicitly using the statement

SET PF-STATUS space.

This default interface always contains at least the functions described in the Standard List section.

Unlike normal dialog statuses, the default list status is affected by the ABAP program.

If you define event blocks in your program using the event keywords AT LINE-SELECTION or AT PF<nn>, the system automatically assigns extra functions to other function keys that provide additional functions.

AT PF<nn> (obsolete)
All function keys of the keyboard F<nn> that are not used for predefined system functions, are set to the function codes PF<nn>, where <nn> is a number between 01 and 24. During list processing, the function codes PF<nn> are linked to the events AT PF<nn>. Choosing PF<nn> always triggers AT PF<nn>. You should no longer use event blocks for PF<nn>.

AT LINE-SELECTION
For this event, the F2 key (double-click) is assigned the function code PICK and function code Choose. The function also always appears in the application toolbar. During list processing, the PICK function code is assigned to the event AT LINE-SELECTION. PICK always triggers AT LINE-SELECTION.

All other function codes are either intercepted by the runtime environment or trigger the event AT USER-COMMAND. Function codes that trigger AT USER-COMMAND must be defined in your own GUI status. The easiest way to do this is to use the standard list status and add extra functions of your own to it.

Dialog Status for Lists

You can create a dialog status for a list using the Menu Painter in the ABAP Workbench. As soon as you create the status, you should choose Extras ® Adjust template and select List status for your template. This status already contains standard function codes for list processing. They are distributed as follows on the menus, standard toolbar, and application toolbar:

Code	Menu	Standard toolbar	Function key	Description
%PC	List			Save list to file
%SL	List			Save list in SAPoffice
%ST	List			Save list in report tree
PRI	List		CTRL-P	Print displayed list
%EX	List		Shift-F3	Exit processing
PICK	Edit		F2	Event AT LINE-SELECTION
RW	Edit		F12 , ESC	Cancel processing
%SC	Edit		CTRL-F	Find
%SC+	Edit		CTRL-G	Find next
BACK	Goto		F3	Back one level
P--			CTRL-PgUp	Scroll to first window page
P-			PgUp	Scroll to previous window page
P+			PgDn	Scroll to next window page
P++			Ctrl-PgDn	Scroll to last window page
%CTX			Shift-F10	Context menu on list

In addition, the following function codes are predefined, but not set as status functions. You can assign them freely to any empty status element.

Code

Description

PF<nn>

Event AT PF<nn>

PP<n>

Scroll to top of list page <n>

PP-[<n>]

Scroll back one list page or <n> pages

PP+[<n>]

Scroll forward one list page or <n> pages

PS<n>

Scroll to column <n>

PS--

Scroll to first column of the list

PS-[<n>]

Scroll left by one or <n> columns

PS+[<n>]

Scroll right by one or <n> columns

PS++

Scroll to last column of the list

PZ<n>

Scroll to line <n>

PL-[<n>]

Scroll back to first line of the page or by <n> lines

PL+[<n>]

Scroll to last line of the page or by <n> lines

/....

For other system commands

The runtime environment directly queries and processes all function codes of the above tables, except PICK and PF<nn>. These function codes do not trigger events, and you cannot use them for the AT USER-COMMAND event.

The function code PICK triggers the AT LINE-SELECTION event, whenever the cursor is positioned on a list line. The function codes PF<nn> always trigger the AT PF<nn> event. Therefore, you cannot use them for the AT USER-COMMAND event either.

To trigger AT USER-COMMAND, you can define any number of function codes yourself. If they do not have a function code listed in the above table, they will trigger AT USER-COMMAND. Note the following special function key assignments:

Function key F2 :

A double-click is always equivalent to pressing function key F2 . Each function code you assign to F2 is therefore activated by double-clicking. Double-clicking triggers the AT LINE-SELECTION event only if the function code PICK is assigned to function key F2. If you assign your own function code to F2 , double-clicking triggers the AT USER-COMMAND event. If a predefined function code is assigned to F2 , double-clicking triggers the corresponding action from the runtime environment.

Function key SHIFT-F10 :

The SHIFT-F10 key is always the equivalent of right-clicking. When you use context menus in lists, it is assigned the function code %CTX.

You can change the list-specific template if you have other requirements. You can

replace function code PICK with your own function code to prevent the AT LINE-SELECTION event from being triggered in the report. You can then program all reactions to user actions in a single processing block (AT USER-COMMAND).

delete predefined function codes whose functionality you do not want to support. For example, this allows you to prevent the user from printing the list or saving it in a file on the presentation server.

modify the standard key settings. For example, you can assign your own function code to F3 to navigate within the lists according to your requirements, instead of returning one list level ( Back). This may be important if you keep several lists on the same logical level and therefore do not want to delete the displayed list as would the standard F3 setting. Or you may want to display a warning before leaving a list level.

Setting a Dialog Status

You set the dialog status for lists in the same way as for normal screens, that is, using the statement

SET PF-STATUS <stat> [EXCLUDING <f>|<itab>]
[OF PROGRAM <prog>]
[IMMEDIATELY].

This statement sets the status <stat> for the current output list. The dialog status <stat> must be defined for the current program, unless you have used the OF PROGRAM addition to set a status from another program <prog>. The status is active for all subsequent list levels until you set another status. The SY-PFKEY system field always contains the status of the current list.

Using SET PF-STATUS, you can display different user interfaces for different list levels to provide the user with different functions according to the individual requirements. Use SET PF-STATUS SPACE to set the standard list status. This depends on the event blocks in the program, as described above.

The EXCLUDING option allows you to change the appearance and available functions of a status from within the program. This is useful if the individual user interfaces for a range of list levels are very similar. You can define a single global status, and then just deactivate the functions you do not need using EXCLUDING. Specify <f> to deactivate the function code stored in field <f>. Specify <itab> to deactivate all function codes stored in the internal table <itab>. Field <f> and the lines of table <itab> should be defined with reference to the system field SY-UCOMM.

The IMMEDIATELY addition is intended specially for list processing. You use it while creating a detail list within an event block to change the status of the list currently displayed (index SY-LISTI). Without this option, the system changes the status of the current secondary list (SY-LSIND) that is displayed only at the end of the processing block.

Setting a Title for a List

As with normal screens, you can set a title for a list as follows:

SET TITLEBAR <ttl> [WITH <g1> ... <g9>]
[OF PROGRAM <prog>].

During list processing, this statement sets the title of the user interface for the output list. It remains active for all screens until you specify another using SET TITLEBAR. The GUI title <title> must be a component of the current ABAP program, unless you use the OF PROGRAM addition in the SET TITLEBAR statement to set a GUI status of another program <prog>.

You can use the WITH option of the SET TITLEBAR statement to replace these placeholders in the title at runtime with the contents of the corresponding fields <g ₁ > .... <g9>. The system also replaces '&' placeholders in succession by the contents of the corresponding <g _i > parameters. To display an ampersand character ‘&’, repeat it in the title ‘&&’.

Examples

Example

Example for dialog status in a list.

REPORT demo_list_menu_painter.
START-OF-SELECTION.
  SET PF-STATUS 'TEST'.
  WRITE:  'Basic list, SY-LSIND =', sy-lsind.
AT LINE-SELECTION.
  WRITE:  'LINE-SELECTION, SY-LSIND =', sy-lsind.
AT USER-COMMAND.
  CASE sy-ucomm.
    WHEN 'TEST'.
      WRITE:  'TEST, SY-LSIND =', sy-lsind.
  ENDCASE.

This program uses a status TEST, defined in the Menu Painter.

Function key F5 has the function code TEST and the text Test for demo.

Function code TEST is entered in the List menu.

The function codes PICK and TEST are assigned to pushbuttons.

The user can trigger the AT USER-COMMAND event either by pressing F5 , or by choosing List ® Test for demo, or by choosing the pushbutton Test for demo.The user can trigger the AT LINE-SELECTION event by selecting a line.

Example

Example of setting a dialog status for the current list

REPORT demo_list_set_pf_status_1.
DATA: fcode TYPE TABLE OF sy-ucomm,
      wa_fcode TYPE sy-ucomm.
START-OF-SELECTION.
  wa_fcode = 'FC1 '. APPEND wa_fcode TO fcode.
  wa_fcode = 'FC2 '. APPEND wa_fcode TO fcode.
  wa_fcode = 'FC3 '. APPEND wa_fcode TO fcode.
  wa_fcode = 'FC4 '. APPEND wa_fcode TO fcode.
  wa_fcode = 'FC5 '. APPEND wa_fcode TO fcode.
  wa_fcode = 'PICK'. APPEND wa_fcode TO fcode.
  SET PF-STATUS 'TEST'.
  WRITE: 'PF-Status:', sy-pfkey.
AT LINE-SELECTION.
  IF sy-lsind = 20.
    SET PF-STATUS 'TEST' EXCLUDING fcode.
  ENDIF.
  WRITE: 'Line-Selection, SY-LSIND:', sy-lsind,
       / '                SY-PFKEY:', sy-pfkey.
AT USER-COMMAND.
  IF sy-lsind = 20.
      SET PF-STATUS 'TEST' EXCLUDING fcode.
    ENDIF.
    WRITE: 'User-Command, SY-LSIND:', sy-lsind,
         / '              SY-UCOMM:', sy-ucomm,
         / '              SY-PFKEY:', sy-pfkey.

Suppose that the function codes FC1 to FC5 are defined in the status TEST and assigned to pushbuttons: The function code PICK is assigned to function key F2 .

When the program starts, the user can create detail lists by selecting a line or choosing one of the function codes FC1 to FC5. For all secondary lists up to level 20, the user interface TEST is the same as for the basic list:

On list level 20, EXCLUDING ITAB deactivates all function codes that create detail lists. This prevents the user from causing a program termination by trying to create detail list number 21.

Example

Example of setting a dialog status for the current list

REPORT demo_list_set_pf_status_2.
START-OF-SELECTION.
WRITE: 'SY-LSIND:', sy-lsind.
AT LINE-SELECTION.
SET PF-STATUS 'TEST' IMMEDIATELY.

After executing the program, the output screen shows the basic list and the user interface predefined for line selection (with function code PICK).

When you choose Choose, the user interface changes. However, since the AT LINE-SELECTION processing block does not contain an output statement, the system does not create a detail list: The status TEST is defined as in the previous example.

Example

Example: Titles of detail lists.

REPORT demo_list_title .
START-OF-SELECTION.
  WRITE 'Click me!' HOTSPOT COLOR 5 INVERSE ON.
AT LINE-SELECTION.
  SET TITLEBAR 'TIT' WITH sy-lsind.
  WRITE 'Click again!' HOTSPOT COLOR 5 INVERSE ON.

In this program, a new title is set for each detail list. The title is defined as follows: "Title for Detail List &1".

Code	Description
PF<nn>	Event AT PF<nn>
PP<n>	Scroll to top of list page <n>
PP-[<n>]	Scroll back one list page or <n> pages
PP+[<n>]	Scroll forward one list page or <n> pages
PS<n>	Scroll to column <n>
PS--	Scroll to first column of the list
PS-[<n>]	Scroll left by one or <n> columns
PS+[<n>]	Scroll right by one or <n> columns
PS++	Scroll to last column of the list
PZ<n>	Scroll to line <n>
PL-[<n>]	Scroll back to first line of the page or by <n> lines
PL+[<n>]	Scroll to last line of the page or by <n> lines
/....	For other system commands