Understanding topmenus

This is an introduction to topmenu definitions.

A topmenu defines a graphical menu that holds views for actions controlled in programs with ON ACTION handlers. A topmenu renders to the user following the front-end platform standards.

On a desktop / web front-end, the topmenu appears as a typical pull-down menu.

On mobile devices, a topmenu displays as a flat list of options (Android™), and as a set of option screens the user can drill down (iOS).

This section describes how to define topmenus with XML in files or in programs as global/default topmenus; it is also possible to define topmenus in forms with the TOPMENU section, as form-specific topmenus.

Topmenu files can be loaded by program with the methods ui.Interface.loadTopMenu() (for default topmenus) or ui.Form.loadTopMenu() (for form-initializers).

In the abstract user interface tree, the TopMenu node must be created under the Form node, and must contain TopMenuGroup nodes. The TopMenuGroup nodes group topmenu commands and other topmenu groups. A TopMenuCommand is a leaf node in the topmenu tree that will trigger an action:

TopMenu
 +- TopMenuGroup     
  +- TopMenuCommand      
  +- TopMenuCommand      
  +- TopMenuCommand  
 +- TopMenuGroup     
  +- TopMenuGroup        
   +- TopMenuCommand        
   +- TopMenuCommand     
  +- TopMenuGroup         
   +- TopMenuCommand         
   +- TopMenuCommand        
   +- TopMenuCommand 

The topmenu options are enabled based on the ON ACTION handlers defined by the current interactive instruction. A topmenu option is bound to an action handler by name. Selecting the topmenu option will execute the user code in the action handler.

Topmenu elements can get a style attribute in order to use a specific rendering/decoration following presentation style definitions.

The DOM tag names are case sensitive; Topmenu is different from TopMenu.

When binding to an action, make sure that you are using the right value in the name attribute. As ON ACTION and COMMAND generate lowercase identifiers, it is recommended to use lowercase names.

It is recommended that you define the decoration of topmenu options for common actions with action defaults.

Images cannot be displayed for the first level of TopMenuGroup elements.