Managing Menus

Terminology: The documentation of Menus commands uses the terms menu command and menu item interchangeably when describing a line in a menu.

The language of 4D offers two ways of managing menus and menu bars: by references or by numbers.

• Managing menus by reference (MenuRef) is the new way of handling menus, introduced with version 11 of 4D. This mode gives access to advanced functions such as the creation of completely dynamic interfaces (menus created "on the fly" without necessarily existing in the Menu editor) and the managing of multi-level hierarchical submenus.
• Managing menus and menu bars by number is based on the menus created in the Menu editor in Design mode. Each menu bar and menu is assigned a fixed number (corresponding to its position in the editor). This number is used by the language commands to specify the menu bar or menu. The scope of language commands applied to menus managed by number is the current menu bar.

This behavior corresponds to previous versions of 4D and complies with several rules (described below in the "Managing menus by number" paragraph). It can still be used but does not take advantage of the new functions offered starting with version 11, more particularly the dynamic management of menus and the use of hierarchical submenus: it is not possible to acccess a hiearchical submenu using a number.

Both menu management modes are compatible and can be used simultaneously in your interfaces. Most of the commands in the “Menus” theme accept both menu numbers and references indiscriminately.

However, managing menus by reference is recommended since it offers many more possibilities. Note that if your menu interface is partially or completely defined via the Menu editor, it remains entirely possible to work with it in the form of references using the Get menu bar reference und GET MENU ITEMS commands.

When menus are handled by means of MenuRef references, there is no difference per se between a menu and a menu bar. In both cases, it consists of a list of items. Only their use differs. In the case of a menu bar, each item corresponds to a menu which is itself composed of items. This is also the principle on which hierarchical menus are based: each item can itself be a menu, and so on.

When a menu is managed by reference, any changes made to this menu during the session are immediately passed on to every instance of this menu and in every process of the database.

Like hierarchical lists, every menu has a unique reference, with which it can be identified during the entire session. This reference, named by convention MenuRef, is a 16-character alphanumeric. All the commands of the “Menus” theme accept either this reference, or a menu number, to specify a menu or menu bar.

Menu references can be obtained using the Create menu, Get menu bar reference or GET MENU ITEMS commands.

Menu bars can be defined in the Menu editor in Design mode. When managed by number, each menu bar is identified by a number and by a name. The first menu bar (created automatically by 4D) has the number 1 and is named Menu Bar #1 by default. You can rename it in the Menu editor. The name of a menu bar may contain up to 31 characters and must be unique.

Menu Bar #1 is also the default menu bar. To open an application with a menu bar other than Menu Bar #1, you must use the SET MENU BAR command in the On Startup database method. It is not possible to modify the contents of a menu bar itself by programming; however, the menus comprising it can be modified. The scope of the language commands applied to static menus is the current menu bar. On each call to the SET MENU BAR command (without the * parameter), all the menus and menu commands return to their original state as defined in the Menu editor.

Every menu bar comes equipped with three menus—the File, Edit and Mode menus.

• The File menu has only one menu command—Quit. The Quit standard action is assigned to it. This action displays an "Are you sure?" confirmation dialog box then quits the 4D application if this dialog box is validated. Otherwise, the operation is cancelled.

Note: Under Mac OS X, the created menu command associated with the Quit action is automatically placed in the application menu when the database is executed on this system.

You can rename the File menu, add menu commands to it or keep it as is. It is recommended that you always keep Quit as the last menu command in the File menu.

• The Edit menu contains the standard editing menu commands. A standard action (Cancel, Cut, Copy, etc.) is assigned to each command of this menu. You can add commands to this menu or use your own methods for managing editing actions.

• The Mode menu contains the Return to Design mode command. This command can be used to return to the Design mode (when it is available) from the Application mode.

Note: 4D automatically manages the Help and application (Mac OS X) system menus. These menus cannot be modified, except for the About 4D command, which can be managed using the SET ABOUT command.

Warning: Menu bars are "interprocess." Any modification carried out on a menu bar in the Design mode will be reflected in all the processes where the menu bar is used.

Like menu bars, menus are numbered. The File menu is generally menu 1. Thereafter, menus are numbered sequentially from left to right (2, 3, 4, and so on). The Application menu (Mac OS ) is excluded from this numbering. On both platforms, the Help menu is also excluded. It should be noted that the Count menus command does not take these menus into account. If, for example, your menu bar consists of the File, Edit, Customers, Inoices and Help menus, Count menus will return 4 (ignoring the system menus maintained by 4D).

Menu numbering is important when you are working, for example, with the Menu selected function.

When a menu is associated with a form, the menu numbering scheme is different. The first appended menu begins with the number 2049. To refer to an appended menu, add 2048 to the normal menu number.

The menu commands within each menu are numbered sequentially from the top of the menu to the bottom including the separators. The topmost menu command is item 1.

You can associate a menu bar with a form in the Form properties (General page). Such a menu bar is called a “form menu bar” in this document.

The menus on a form menu bar are appended to the current menu bar when the form is displayed as an output form in the Application environment.

Form menu bars are specified by a menu bar number and a name. If the number or name of the menu bar displayed with the current form is the same as that of the menu bar appended to the form, the menu bar is not appended.

By default, when a form is displayed with a custom menu bar, the commands of the current menu bar are deactivated, i.e. selecting them has no effect. You can modify this operation by checking the Active Menu Bar
option in the Form properties: in this case, the commands of the current menu bar will remain usable.

In every case, the selection of a menu command causes an On Menu Selected event to be sent to the form method; you can then use the Menu selected command to test the selected menu.

Menus can be attached to menu bars. If an attached menu is modified using one of these commands, every other instance of the menu will reflect these changes. For more information about attaching menus, refer to the 4D Design Reference Manual.

Each menu command can have a project method or a standard action attached to it. If you do not assign a method or a standard action to a menu command, choosing that menu command causes 4D to exit the Application environment and go to the Design environment. If only the Application environment is available or if the user does not have access to the Design environment, this means quitting to the Desktop.

Standard actions can be used to carry out various current operations linked to system functions (copy, quit, etc.) or to those of the 4D database (add record, select all, etc.).

You can assign both a standard action and a project method to a menu command. In this case, the standard action is never executed; however, 4D uses this action to activate/deactivate the menu command according to the current context and to associate a specific operation with it according to the platform (for example, the Preferences action is passed in the application menu under Mac OS). When a menu command is deactivated, the associated project method cannot be executed.

In order to facilitate the managing of menu items, 4D provides a shortcut that can be used to specify the last item added to the menu: you simply need to pass -1 in the menuItem parameter.

This principle can be used in all the commands of the “Menus” theme that work with menu items.