Back to Contents

Menus

Summary:

• Basics
• Syntax
• Usage
  • Programming Steps
  • Instruction Configuration
  • Default Actions
  • Control Blocks
  • Interaction Blocks
  • Action Defaults and MENU
  • Control Instructions
• Examples

See also: Dynamic User Interface

Basics

A Menu defines a list of options (also called actions) that can trigger program routines. The MENU statement is an interactive instruction defining the possible actions that can be executed in a specific context at a given place in the program. One Menu can only define a set of options for a given level. You cannot define all menu options of your program in a unique Menu; you must use nested Menu calls. A typical application starts with a global Menu, defining general options to access sub-routines, which in turn implement specific Menus with options like 'Append', 'Delete', 'Modify', and 'Search' that trigger sub-routines to manage database records.

A MENU statement is a controller for user actions.  You can bind actions views with the Menu options by name, for example:

• Toolbar buttons (see Toolbars for more details).
• Topmenu options (see Topmenus for more details).
• Buttons in forms (see Form Specification Files).

Action views are bound to an action controller by name. See the Interaction Model description for more details.

Warning: The compiler converts COMMAND labels and ON ACTION identifiers to lowercase for the action. When binding action views to menu option clauses, the action name is case sensitive.

By default, if no action views are associated with Menu options, these are displayed as a simple push buttons in a specific area, depending on the front end. The following screen is produced by the program shown in Example 1:

You can display a Menu in a modal dialog window by setting some attributes, as shown in the source code of Example 2:

For more details about default and explicit action views, see Interaction Model.

MENU

Purpose:

The MENU instruction defines a set of user choices.

Syntax:

where menu-option is one of:

{ COMMAND option [comment] [ HELP help-number ]
    menu-statement
    [...]
| COMMAND KEY ( key-name ) option [comment] [ HELP help-number ]
    menu-statement
    [...]
| COMMAND KEY ( key-name )
    menu-statement
    [...]
| ON ACTION action-name
    menu-statement
    [...]
| ON IDLE idle-seconds
    menu-statement
    [...]
}

where menu-statement is:

{ statement
| CONTINUE MENU
| EXIT MENU
| NEXT OPTION option
| SHOW OPTION { ALL | option [,...] }
| HIDE OPTION { ALL | option [,...] }
}

Notes:

1. title is a string expression defining the title of the menu.
2. control-attributes is a list of attributes that defines the behavior and presentation of the menu.
3. key-name is an hot-key identifier (like F11 or Control-z).
4. option is a string expression defining the label of the menu option and identifying the action that can be executed by the user.
5. comment is a string expression containing a description for the menu option. This description appears when the option is the current.
6. help-number is an integer that allows you to associate a help message number with the menu option.
7. action-name identifies an action that can be executed by the user.
8. idle-seconds is an integer expression that defines a number of seconds.
9. action-name identifies an action that can be executed by the user.
10. bool-expr is an integer expression that must evaluate to 0 or 1.
11. variable is a program variable that receives the return of the GET instruction.

The following table shows the control-attributes supported by the MENU statement:

Usage:

When the runtime system encounters an MENU statement, it does the following::

1. In console mode, displays the menu options. In graphical mode, enables action views bound to menu options.
2. Waits for the user to select on of the menu options.

The MENU instruction can be used to control user actions. See Interaction Model for more details about actions.

Warnings:

1. It is recommended that you do not use the COMMAND KEY clause to handle user actions; use the ON ACTION clause instead.
2. The compiler converts the ON ACTION identifiers to lowercase for internal storage. This means that ON ACTION APPEND is equivalent to ON ACTION append.
3. When using COMMAND "label", you can use uppercase letters: The compiler converts the command label to lowercase for the action name. This means that COMMAND "Append" is equivalent to ON ACTION append, except that the text and comment attributes are defined at the program level.
4. For backward compatibility, it is possible to use simple characters and multiple keys in the COMMAND KEY clause, but this is not recommended. If multiple keys are defined in the COMMAND KEY clause, only the last element will be used as accelerator key.

Tips:

1. Window close events can be trapped with COMMAND KEY(INTERRUPT) clause. See Windows and Forms for more details.
2. Default presentation of menu buttons can be shown in different positions in the window, according to the Window Style.

Usage

Programming Steps

The typical usage of a MENU instruction is show in the following example, using a set of ON ACTION control blocks:

01 MENU
02    ON ACTION new
03      CALL newFile()
04    ON ACTION open
05      CALL openFile()
06    ON ACTION quit
07      EXIT PROGRAM
08 END MENU

The COMMAND clause defines both the action name and the label of the menu option, which is by default decorated on the front end side as a push-button in a specific area. The ON ACTION clause defines an action trigger clause as described in the User Interaction section. To write abstract code, we recommend that you use the ON ACTION clause instead of COMMAND. However, when using 'dialog' menus, sometimes you only need to provide the title of the buttons, and you can use COMMAND clauses. 

Instruction Configuration

When the STYLE instruction attribute is set to 'default' or when you do not specify the menu type, the runtime system generates a default decoration as a set of buttons in a specific area of the current window. When this attribute is set to 'dialog', the menu options appear as buttons at the bottom in a temporary modal window, in which you can define the message and the icon with the COMMENT and IMAGE attributes. When the STYLE is set to 'popup', the menu appears as a popup menu (contextual menu).

Warning: If the menu is a "dialog" or "popup", the dialog is automatically exited after any action clause such as ON ACTION, COMMAND or ON IDLE.

Default Actions

When an MENU instruction executes, the runtime system creates a set of default actions.

The following table lists the default actions created for this dialog:

Control Blocks

If the menu block contains a BEFORE MENU clause, statements within this clause will be executed before the menu is displayed.

Interaction Blocks

The ON ACTION action-name clause defines a set of instructions that must be executed when an action is fired.

During a dialog, you can enable or disable an action with the setActionActive() method of the dialog. You can also hide and show the default action view with the setActionHidden() method: 

01 ...
02    BEFORE MENU
03       CALL dialog.setActionActive("query",FALSE)
04       CALL dialog.setActionHidden("adduser",TRUE)
05 ...

The ON IDLE idle-seconds clause defines a set of instructions that must be executed after idle-seconds of inactivity. This can be used, for example, to quit the dialog after the user has not interacted with the program for a specified period of time. The parameter idle-seconds must be an integer expression. If it evaluates to zero, the timeout is disabled.

01 ...
02    ON IDLE 10
03       IF ask_question("Do you want to leave the dialog?") THEN
04          EXIT MENU
05       END IF
06 ...

Action Defaults and MENU

When using the traditional COMMAND clause, it automatically defines the text and comment decoration attributes for the default action view. Since these attributes are defined by the program, the corresponding text and comment attributes in action defaults are not applied to these menu options. For example, when you define a COMMAND "Hello" menu option, the button text will be "Hello", even if an action default defines a text "Bye!" for the action "hello".

When using COMMAND KEY, it automatically defines the acceleratorName attribute for the action and the corresponding action default accelerator will be ignored. For example, when you define a COMMAND KEY(F10) "Hello" menu option, the first accelerator will be "F10", even if an action default defines an accelerator "F5" for the action "hello". However, you can set the second accelerator with the acceleratorName2 attribute in action defaults.

Control Instructions

CONTINUE MENU statement causes the runtime system to ignore the remaining instructions in the current block and redisplays the menu.

EXIT MENU statement terminates the MENU block without executing any other statement.

The NEXT OPTION option statement defines option as the default. This cannot apply to a hidden option, and works only with default action views created when an explicit view is not used.

The SHOW OPTION and HIDE OPTION  statements are provided for backward compatibility only. The SHOW OPTION statement  is used to make the default action view visible and the explicit action views enabled. The HIDE OPTION statement  is used to make the default action view invisible and the explicit action views disabled. The ALL clause can be used to specify all options.

Examples

Example 1: Simple menu (old Informix 4GL style).

01 MENU "File"
02    COMMAND KEY ( CONTROL-N ) "New" "Creates New File" HELP 101
03      CALL newFile()
04    COMMAND KEY ( CONTROL-O ) "Open" "Open existing File" HELP 102
05      CALL openFile()
06    COMMAND KEY ( CONTROL-S ) "Save" "Save Current File" HELP 103
07      CALL saveFile()
08    COMMAND "Import"
09      LOAD FROM "infile.dat" INSERT INTO table
10    COMMAND KEY ( CONTROL-Q ) "Quit" "Quit Program" HELP 201
11      EXIT PROGRAM
12 END MENU

Example 2: Using a modal menu

01 MAIN
02    MENU "Example of dialog menu"
03       ATTRIBUTE ( STYLE="dialog", COMMENT="Delete the file?" )
04       COMMAND "Yes"
05         DISPLAY "Yes"
06       COMMAND "No"
07         DISPLAY "No"
08       COMMAND "Cancel"
09         DISPLAY "Cancel"
10    END MENU
11 END MAIN

Example 3: Abstract action controller

01 MENU
02    ON ACTION new
03      CALL newFile()
04    ON ACTION open
05      CALL openFile()
06    ON ACTION save
07      CALL saveFile()
08    ON ACTION import
09      LOAD FROM "infile.dat" INSERT INTO table
10    ON ACTION quit
11      EXIT PROGRAM
12 END MENU