Using GUI Statuses (SAP Library - ABAP Programming (BC-ABA))

Using GUI Statuses

A GUI status is an independent component of an ABAP program. You create them in the ABAP Workbench using the Menu Painter. The relevant documentation provides comprehensive information about creating GUI statuses and their elements. The most important details are contained below.

GUI Status

The function of a GUI status is to provide the user with a range of functions on a screen. Each function has an associated function code, and when the user chooses a function, the PAI event is triggered. In each PAI event, the function code, as long as it is not empty, is placed in the system field SYST-UCOMM (SY-UCOMM) and assigned to the OK_CODE field. Empty function codes are placed in neither the SY-UCOMM field nor the OK_CODE field. Before you can work with the OK_CODE field, you must assign a name to it in the Screen Painter. For further information, refer to Reading Function Codes.

All function codes in an ABAP program, apart from those only assigned to pushbuttons on screens, are defined and adminstered in the Menu Painter.

This graphic is explained in the accompanying text

When you define a function code in the Menu Painter, you assign it to a menu entry in a menu bar, and possibly also to a freely-assigned function key on the keyboard. Function codes that are assigned to a function key can also be assigned to an icon in the standard toolbar or a pushbutton in the application toolbar. A GUI status consists of a menu bar, a standard toolbar, an application toolbar, and a function key setting. For each function code, there is a static or dynamic function text. Dynamic function texts allow you to use context-sensitive texts in your ABAP program.

The user interface is a visualization of all possible functions, and is meant to make programs easier to use. From a technical point of view, you could just enter the function code in the command field and trigger the PAI event by pressing ENTER. However, a GUI status should contain all possible function codes as menu entries. The most important functions should also be assigned to function keys, and the most important of these should also be assigned to icons in the standard toolbar or the application toolbar.

In the Menu Painter, the functions that you assign to the icons in the standard toolbar must also be assigned to particular function keys. You cannot assign them freely. Instead, the system automatically assigns them to the corresponding function key when you assign the function code to an icon. You should always activate at least one of the Back This graphic is explained in the accompanying text (F3), Exit (shift+F3), and Cancel (F12) functions, so that the user can always leave the screen in the normal fashion. The assignment of function keys to pushbuttons in the application toolbar is not fixed.

Whenever you assign function codes to interface elements, you should refer to the ergonomic guidelines in the SAP Style Guide. The Menu Painter provides you with help in this respect, since you can use the Display standards function and corresponding checks.

As well as the function codes for Normal application functions, which trigger the PAI event, you can also create function codes in the Menu Painter with other functions, for example, to call another transaction or trigger a system functions. You can also create special function codes for pushbuttons on screens, but you must assign another function type to the function code in either the Menu Painter or the Screen Painter.

You can also use the Menu Painter to create area menus. An area menu is a user interface that does not belong to an ABAP program and may therefore not trigger any PAI events. It may only contain function codes that call transactions or system functions. Examples of area menus are the initial screen of the R/3 System (S000) and the initial screen of the ABAP Workbench (S001).

Special Function Keys and Function Codes

Some keys and function codes have special functions. This section deals with the special functions on screens. There are also special functions that apply to lists.

Reserved Function Keys

The following function keys do not trigger the PAI event, but are reserved for other functions:

F1 calls the field help
F4 calls the input help
F10 places the cursor in the menu bar

Function Keys for the Standard Toolbar

The following function keys are firmly assigned to icons in the standard toolbar. The function code that you assign and the corresponding ABAP coding should reflect the sense of the icon.

Function key

Icon

Purpose

Ctrl+S or F11

This graphic is explained in the accompanying text

Save

F3

Back

Shift+F3

Exit

Esc or F12

Cancel

Ctrl+P

Print

Ctrl+F

Find

Ctrl+G

Find next

Ctrl+PgUp

First page

PgUp

This graphic is explained in the accompanying text

Previous page

PgDn

Next page

Ctrl+PgDn

Last page

The ENTER Key

The ENTER key belongs to the This graphic is explained in the accompanying text icon in the standard toolbar, and is always active, even if no function is assigned to it in the GUI status, or there is no GUI status set at all. The PAI event is always triggered when the user chooses ENTER. The following function codes can be passed to SY-UCOMM or the OK_CODE field:

Any entry in the command field when the user presses ENTER
If there is no entry in the command field, any function code assigned to the ENTER key in the Menu Painter.
If the command field does not contain an entry and no function code is assigned to the ENTER key in the Menu Painter, the function code is empty and therefore not passed to SY-UCOMM or the OK_CODE field.

The F2 Key

The F2 key is always linked to a mouse double-click. If a function code in the GUI status is assigned to the F2 key, the PAI event can be triggered either when the user chooses F2 or when he or she double-clicks a screen element. In both cases, the corresponding function code is passed to SY-UCOMM and the OK_CODE field. If you need to use the cursor position to control what happens next, you must find it out yourself using the GET CURSOR statement.

Setting the GUI Status

To assign a GUI status to a screen, use the ABAP statement

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

This statement defines the user interface for all subsequent screens of a screen sequence until another is set using a new SET PF-STATUS statement. The GUI status <stat> must be a component of the current ABAP program, unless you use the OF PROGRAM addition in the SET PF-STATUS statement to set a GUI status of another program <prog>.

The EXCLUDING function allows you to change the appearance and function of a GUI status dynamically. This is useful if the individual user interfaces for a range of screens 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 of type C, and have length 20.

You should set the GUI status for a screen in the PBO event. If you do not specify a GUI status for a screen, it is displayed with the interface of the previous screen. If you do not specify a GUI status for the first screen of a program, it has no user interface, and the user may not be able to leave the screen.

Setting a GUI Title

As well as the GUI status, a user interface also contains a GUI title, which you also create using the Menu Painter. To assign a GUI status to a screen, use the ABAP statement

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

This statement defines the title of the user interface for all subsequent screens of a screen sequence until another is set using a new SET TITLEBAR statement. 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>.

A GUI title can contain up to nine placeholders &1 ... &9 that can be replaced with the contents of the corresponding fields <g1> ... <g9> in the WITH addition. 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 ‘&&’.

You should set the GUI title for a screen in the PBO event.

Example

GUI status and screen

PROGRAM DEMO_DYNPRO_GUI_STATUS.

DATA: OK_CODE LIKE SY-UCOMM,
SAVE_OK LIKE OK_CODE,
OUTPUT LIKE OK_CODE.

CALL SCREEN 100.

MODULE INIT_SCREEN_0100 OUTPUT.
SET PF-STATUS 'STATUS_100'.
SET TITLEBAR '100'.
ENDMODULE.

MODULE USER_COMMAND_0100 INPUT.
  SAVE_OK = OK_CODE.
  CLEAR OK_CODE.
  CASE SAVE_OK.
    WHEN 'BACK' OR 'EXIT' OR 'CANCEL'.
      LEAVE PROGRAM.
    WHEN OTHERS.
      OUTPUT = SAVE_OK.
    ENDCASE.
ENDMODULE.

The next screen (statically defined) for screen 100 is itself. It has the following layout:

This graphic is explained in the accompanying text

The part of the element list relevant for the screen fields is as follows:

Name

Type

Format

OUTPUT

I/O

CHAR

OK_CODE

OK

OK

The input option for the screen field OUTPUT has been switched off in the Screen Painter.

The screen flow logic is as follows:

PROCESS BEFORE OUTPUT.
MODULE INIT_SCREEN_0100.

PROCESS AFTER INPUT.
MODULE USER_COMMAND_0100.

The PBO module INIT_SCREEN_100 sets the GUI status STATUS_100 and a title 100. The GUI status was created using the Menu Painter as follows:

Menu bar

Menu Demo:

Function code

Text

SAVE

Save

PRINT

Print

DELETE

Delete

EXIT

Exit

Menu Edit:

Function code

Text

MARK

Select

SELE

Choose

SEARCH

Find

SEARCH+

Find next

TOP

First page

PAGE_UP

Previous page

PAGE_DOWN

Next page

BOTTOM

Last page

CANCEL

Cancel

Menu Goto:

Function code

Text

BACK

Back

Menu Extras:

Function code

Text

FUNCT_F5

Function 1

FUNCT_F6

Function 2

FUNCT_F7

Function 3

FUNCT_F8

Function 4

Menu Environment:

Function code

Text

MENU_1

Menu 1

MENU_2

Menu 2

MENU_3

Menu 3

Standard toolbar

Icon	Function code	Text

	SAVE	Save
	BACK	Back
	EXIT	Exit
	CANCEL	Cancel
	PRINT	Print
	SEARCH	Find
	SEARCH+	Find next
	PAGE_UP	Previous page
	PAGE_DOWN	Next page
	BOTTOM	Last page
	CANCEL	Cancel

Application toolbar

Position	Function code	Text
1	SELE
2	MARK
3	DELETE
4	FUNCT_F5	Function 1
5	FUNCT_F6	Function 2

function keys

Key	Function code	Text	Icon
F2	SELE	Choose
F9	MARK	Select
Shift+F2	DELETE	Delete
F5	FUNCT_F5	Function 1
F6	FUNCT_F6	Function 2
F7	FUNCT_F7	Function 3
F8	FUNCT_F8	Function 4

All function codes exist as menu entries, but not all of them are assigned to function keys. The function codes in the standard toolbar activate the icons and are automatically assigned to their function keys. Some of the additional function keys are assigned to the application toolbar.

In the module USER_COMMAND_100, the contents of the OK_CODE field are copied to the auxiliary variable SAVE_OK code, and OK_CODE is initialized. You should always do this, since it ensures that the screen field OK_CODE has always been initialized before the PBO event and can therefore not unintentionally contain an incorrect value. The function code of the function chosen by the user is then assigned to the OUTPUT field and displayed in the corresponding screen field (but not if the user chose BACK, EXIT, or CANCEL, in which cases, the program ends).

The function code SELE can be passed to the ABAP program in the following ways:

When you choose Choose in the Edit menu
When you choose the pushbutton in the application toolbar
When you choose the F2 key on the keyboard
When you click the right-hand mouse button and then choose Choose.
When you double-click the screen field OUTPUT
When you enter SELE in the command field and press ENTER.

The other function codes are passed according to their definition, but without the double-click function.

Function key	Icon	Purpose
Ctrl+S or F11		Save
F3		Back
Shift+F3		Exit
Esc or F12		Cancel
Ctrl+P		Print
Ctrl+F		Find
Ctrl+G		Find next
Ctrl+PgUp		First page
PgUp		Previous page
PgDn		Next page
Ctrl+PgDn		Last page

Function code	Text
MENU_1	Menu 1
MENU_2	Menu 2
MENU_3	Menu 3