Back to Contents

Topmenus

Summary:

• Basics
• Syntax
• Usage
  • Defining TopMenus
  • TopMenu Structure
  • Defining a TopMenu in form file
  • Loading a TopMenu from a file
  • Loading a default TopMenu from a file
  • Creating a TopMenu dynamically
• Examples
  • Simple Topmenu in XML format
  • Topmenu definition in a PER file

See also: Action Defaults, Toolbars, Form Specification Files

Basics

A Topmenu is a view for actions presented as a typical pull-down menu, having options that can trigger events in an interactive instruction. This page describes how to use Topmenus in programs; it is also possible to define Topmenus in forms with the TOPMENU section.

Syntax

<TopMenu [ topmenu-attribute="value" [...] ] >
  group
  [...]
</TopMenu>

where group is:

<TopMenuGroup group-attribute="value" [...]>
  { <TopMenuSeparator separator-attribute="value" [...] />
  | <TopMenuCommand command-attribute="value" [...] />
  | group
  } [...]
</TopMenuGroup>

Notes:

1. The TopMenu node can hold TopMenuSeparator, TopMenuGroup or TopMenuCommand children.
2. topmenu-attribute defines a property of the TopMenu.
3. A TopMenuGroup node can hold TopMenuSeparator, TopMenuGroup or TopMenuCommand children.
4. group-attribute defines a property of a TopMenuGroup.
5. A TopMenuCommand node defines a leaf of the TopMenu tree and can be selected to execute an action.
6. command-attribute defines a property of a TopMenuCommand.
7. A TopMenuSeparator node defines an horizontal line in a TopMenu group.
8. separator-attribute defines a property of a TopMenuSeparator.

Warnings:

1. The DOM tag names are case sensitive; Topmenu is different from TopMenu.
2. 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.
3. When binding to a key, make sure the name attribute value is in lowercase letters ("f5").
4. Make sure that the image file is available to the Front End.

Tips:

1. For common actions, it is recommended that you define the decoration of a Topmenu command with Action Defaults.

Usage

Defining TopMenus

A Topmenu defines a graphical pull-down menu that holds views for actions controlled in BDL programs with ON ACTION clauses. See Interaction Model for more details about action management.

You can define a Topmenu in form files with the TOPMENU section, or you can load a Topmenu at runtime into the current form by using the following methods: ui.Form.loadTopMenu()

The Topmenu commands (pull-down menu options) are enabled according to the actions defined by the current interactive instruction, which can be MENU, INPUT, INPUT ARRAY, DISPLAY ARRAY or CONSTRUCT. When a Topmenu option is selected, the program executes the action trigger the Topmenu command is bound to.

A Topmenu command is bound to an action node of the current interactive instruction if its name attribute corresponds to an action node name (typically, the name of a ring menu option). In this case, a Topmenu command selection has the same effect as raising the action. For example, if the current interactive instruction is a ring menu, this would have the same effect as selecting the ring menu option.

A Topmenu command is bound to a key trigger if the name attribute of the command corresponds to a valid hot-key, in lowercase letters. In this case, selecting a Topmenu command has the same effect as pressing the hot-key.

A Topmenu command is automatically disabled if the corresponding action is not available (for example, when a ring menu option is hidden).

TopMenu structure

A Topmenu is part of a form definition; the TopMenu node must be created under the Form node.

The following table shows the list of topmenu-attributes supported for the TopMenu node:

The following table shows the list of command-attributes supported for the TopMenuCommand node:

In order to define the tree structure of the pull-down menu, the TopMenuGroup node is provided to hold Topmenu commands and Topmenu groups:

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

The following table shows the list of group-attributes supported for the TopMenuGroup node:

The following table shows the list of separator-attributes supported for the TopMenuSeparator node:

Defining the Topmenu in a form file

You typically define a Topmenu in the form specification file, with the TOPMENU section; see below for an example.

Loading a Topmenu from an XML file

To load a Topmenu definition file, use the utility method provided by the Form built-in class:

01 CALL myform.loadTopMenu("standard")

This method accepts a filename with or without the "4tm" extension. If you omit the file extension (recommended), the runtime system adds the extension automatically. If the file does not exist in the current directory, it is searched in the directories defined in the DBPATH environment variable.

If a form contains a specific topmenu loaded by the ui.Form.loadTopmenu() method or defined in the Form Specification File, it will be replaced by the new topmenu loaded from this function.

Loading a default topmenu from an XML file

To load a default topmenu from an XML definition file, use the utility method provided by the Interface built-in class:

01 CALL ui.Interface.loadTopMenu("standard")

This method accepts a filename with or without the "4tm" extension. If you omit the file extension (recommended), the runtime system adds the extension automatically. If the file does not exist in the current directory, it is searched in the directories defined in the DBPATH environment variable.

The default topmenu loaded by this method is also used for the MDI container.

Creating the Topmenu dynamically

This example shows how to create a Topmenu in all forms by using the default initialization function and the DomNode class:

01 CALL ui.Form.setDefaultInitializer("myinit")
02 OPEN FORM f1 FROM "form1"
03 DISPLAY FORM f1
04 ...
05 FUNCTION myinit(form)
06   DEFINE form ui.Form
06   DEFINE f om.DomNode
08   LET f = form.getNode()
09   ...
10 END FUNCTION

After getting the DOM node of the form, create a node with the "TopMenu" tag name:

01 DEFINE tm om.DomNode
02 LET tm = f.createChild("TopMenu")

For each Topmenu group, create a sub-node with the "TopMenuGroup" tag name and set the attributes to define the group:

01 DEFINE tmg om.DomNode
02 LET tmg = tm.createChild("TopMenuGroup")
03 CALL tmg.setAttribute("text","Reports")

For each Topmenu option, create a sub-node in a group node with the "TopMenuCommand" tag name and set the attributes to define the option:

01 DEFINE tmi om.DomNode
02 LET tmi = tmg.createChild("TopMenuCommand")
03 CALL tmi.setAttribute("name","report")
04 CALL tmi.setAttribute("text","Order report")
05 CALL tmi.setAttribute("comment","Orders entered today")
06 CALL tmi.setAttribute("image","smiley")

If needed, you can create a "TopMenuSeparator" node inside a group, to separate menu options:

01 DEFINE tms om.DomNode
02 LET tms = tmg.createChild("TopMenuSeparator")

Examples

Example 1: Simple Topmenu in XML format

01 <TopMenu>
02    <TopMenuGroup text="Form" >
03       <TopMenuCommand name="help" text="Help" image="quest" />
04       <TopMenuCommand name="quit" text="Quit" acceleratorName="alt-F4"/>
05    </TopMenuGroup>
06    <TopMenuGroup text="Edit" >
07       <TopMenuCommand name="accept" text="Validate" image="ok" />
08       <TopMenuCommand name="cancel" text="Cancel" image="cancel" />
09       <TopMenuSeparator/>
10       <TopMenuCommand name="editcut" text="Cut" />
11       <TopMenuCommand name="editcopy" text="Copy" />
12       <TopMenuCommand name="editpaste" text="Paste" />
13    </TopMenuGroup>
14    <TopMenuGroup text="Records" >
15       <TopMenuCommand name="append" text="Add" image="add" />
16       <TopMenuCommand name="delete" text="Remove" image="delete" />
17       <TopMenuCommand name="update" text="Modify" image="change" />
18       <TopMenuSeparator/>
19       <TopMenuCommand name="search" text="Query" image="find" />
20    </TopMenuGroup>
21 </TopMenu>

Example 2: Topmenu definition in a PER file

01 TOPMENU
02   GROUP form (TEXT="Form")
03      COMMAND help (TEXT="Help", IMAGE="quest")
04      COMMAND quit (TEXT="Quit", ACCELERATOR=ALT-F4)
05   END
06   GROUP edit (TEXT="Edit")
07      COMMAND accept (TEXT="Validate", IMAGE="ok")
08      COMMAND cancel (TEXT="Cancel", IMAGE="cancel")
09      SEPARATOR
10      COMMAND editcut   -- Gets decoration from action defaults
11      COMMAND editcopy  -- Gets decoration from action defaults
12      COMMAND editpaste -- Gets decoration from action defaults
13   END
14   GROUP records (TEXT="Records")
15      COMMAND append (TEXT="Add", IMAGE="add")
16      COMMAND delete (TEXT="Remove", IMAGE="del")
17      COMMAND update (TEXT="Modify", IMAGE="change")
18      SEPARATOR
19      COMMAND search (TEXT="Search", IMAGE="find")
20   END
21 END