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 Structure link Menu Painter. There are three different types of GUI status:

· Dialog status

· Dialog box

· Context menus

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 of up to 20 characters, 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 Evaluating Function Codes.

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

This graphic is explained in the accompanying text

The GUI status type defines how the function codes are displayed:

· A dialog status comprises a menu bar, a toolbar, an application toolbar, and the function key settings.

· A status for a dialog box only contains a toolbar. The standard function codes of the toolbar and function codes that are linked with function keys but not with the application toolbar are available using the keyboard.

· A context menu consists solely of a context menu and serves as the static model for the dynamic creation of context menus.

Dialog statuses are the most general form of user interface for screens and from now on we will refer only to them. With the above restrictions, the same applies for statuses for dialog boxes as for dialog statuses. Both are generally created statically for an ABAP program. Context menus play a somewhat different role and are handled specially.

Dialog Status

A dialog status consists of a menu bar, a standard toolbar, an application toolbar, and a function key setting. When you define a dialog status in the Menu Painter, every function code is assigned to a menu entry in a menu bar and/or to a freely-assignable 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. For each function code, there is a static or Structure link 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 dialog 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), or 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 Structure link 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. Such function codes can also be assigned to pushbuttons, checkboxes, or radio buttons on screens. To do so however, you must assign a different function type to the function code in either the Menu Painter or the Screen Painter.

Area Menus

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

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 a Dialog Status

To assign a dialog 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 dialog status is set using a new SET PF-STATUSstatement. The dialog status stat must be a component of the current ABAP program, unless you use the OF PROGRAM addition to set a dialog status of another program prog.

The EXCLUDING addition allows you to change the appearance and function of a dialog 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. The field f and the rows of table itab should be of the type c with the length 20.

You should set the dialog status for a screen in the PBO event. If you do not specify a dialog status for a screen, it is displayed with the interface of the previous screen. If you do not specify a dialog 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 dialog 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 tit [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 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 WITHaddition. The system also replaces '&' placeholders in succession by the contents of the corresponding g 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

Dialog status and screen

PROGRAM demo_dynpro_gui_status.

DATA: ok_code TYPE 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 100. 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_0100 sets the dialog status status_0100 and a title 100. The dialog 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.

The module user_command_0100 copies the contents of the ok_code field 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 This graphic is explained in the accompanying text 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.