Entering content frame

Using GUI Statuses Locate the document in its SAP Library structure

A GUI status is an independent component of an ABAP program. You create them in the ABAP Workbench using the Structure linkMenu 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 linkdynamic 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 This graphic is explained in the accompanying text (shift+F3), or Cancel This graphic is explained in the accompanying text (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 linkSAP 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

This graphic is explained in the accompanying text

Save

F3

This graphic is explained in the accompanying text

Back

Shift+F3

This graphic is explained in the accompanying text

Exit

Esc or F12

This graphic is explained in the accompanying text

Cancel

Ctrl+P

This graphic is explained in the accompanying text

Print

Ctrl+F

This graphic is explained in the accompanying text

Find

Ctrl+G

This graphic is explained in the accompanying text

Find Next

Ctrl+PgUp

This graphic is explained in the accompanying text

First Page

PgUp

This graphic is explained in the accompanying text

Previous Page

PgDn

This graphic is explained in the accompanying text

Next Page

Ctrl+PgDn

This graphic is explained in the accompanying text

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

This graphic is explained in the accompanying text

 

 

This graphic is explained in the accompanying text

SAVE

Save

This graphic is explained in the accompanying text

BACK

Back

This graphic is explained in the accompanying text

EXIT

Exit

This graphic is explained in the accompanying text

CANCEL

Cancel

This graphic is explained in the accompanying text

PRINT

Print

This graphic is explained in the accompanying text

SEARCH

Find

This graphic is explained in the accompanying text

SEARCH+

Find Next

This graphic is explained in the accompanying text

PAGE_UP

Previous Page

This graphic is explained in the accompanying text

PAGE_DOWN

Next Page

This graphic is explained in the accompanying text

BOTTOM

Last Page

This graphic is explained in the accompanying text

CANCEL

Cancel

Application Toolbar

Position

Function Code

Text

1

SELE

This graphic is explained in the accompanying text

2

MARK

This graphic is explained in the accompanying text

3

DELETE

This graphic is explained in the accompanying text

4

FUNCT_F5

Function 1

5

FUNCT_F6

Function 2

Function Keys

Key

Function Code

Text

Icon

F2

SELE

Choose

This graphic is explained in the accompanying text

F9

MARK

Select

This graphic is explained in the accompanying text

Shift+F2

DELETE

Delete

This graphic is explained in the accompanying text

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.

 

 

Leaving content frame