Defining a Menu Object

PML Customisation User Guide

Menus : Defining a Bar Menu Gadget : Defining a Menu Object

A menu is a set of menu fields, each representing an action that is invoked when the field is selected. The fields’ display text indicates to you what the actions are, and the fields’ replacement text defines what the actions are.

Within the form definition a menu object can be created using the form’s NewMenu method or the menu sub-command. You can then use the menu’s Add(), InsertAfter(), and InsertBefore() methods to add or insert named menu fields. A menu field can do one of three things:

•

Execute a callback.

•

Display a form.

•

Display a sub-menu.

You can also add a visual separator between fields.

Below is an example of a complete menu definition:

!menu = !this.newmenu( 'file', ‘main’ )

!menu.add( 'MENU', 'Send to', 'SendList', 'SendTo' )

!menu.add( 'SEPARATOR', 'saveGroup' )

!menu.add( 'CALLBACK', 'Save', '!this.SaveFile()', 'Save' )

!menu.add( 'FORM', 'Save as...', 'SaveFile', 'SaveAs' )

!menu.add( 'SEPARATOR' )

 --core-code managed field for Explorer Addin, ticked. 

 --Note no Rtext needed

!menu.add( 'CORETOGGLE', 'Explorer', '', 'Expl' ) 

!menu.add( 'MENU', 'Pull-right1', 'Pull1')

 --initialise toggle field as ticked (typically in the constructor)

!menu.SetField( 'Expl', 'Selected', true )

This creates a new main menu called Menu with six fields and two separators between them. For example:

•

The SAVE field when picked will execute the callback command this.SaveFile().

•

The Save as... field when picked will load and display the form !!SaveFile. By convention, the text on a menu field leading to a form ends with three dots, which you must include with the text displayed for the field.

•

The SEPARATOR, usually a line, will appear after the previous field.

•

The Pull-right1 field when picked will display the sub-menu !this.Pull1 to its right. A menu field leading to a sub-menu ends with a > symbol: this is added automatically.

Named Menu Fields

You can add menu fields with an optional fieldname that they can later refer to when editing the menufield or modifying its attributes’. If you do not specify a field name then you will not be able to refer to the field again. You can also assign a name to separator fields, which allows separator group editing.

The general syntax is:

!menu.Add( ‘<FieldType>’,’ <Dtext>’, ‘<Rtext>’, { ‘<FieldName>’ } )

!menu.Add( ‘SEPARATOR’, { ‘<FieldName>’ })

Where the fields have the following meanings:


Field	Description
<FieldType>	has allowable values: ‘CALLBACK’, ‘TOGGLE’, ‘MENU’, and ‘FORM’.
<Dtext>	is the display-text for the field (cannot be null or blank). May contain multi-byte characters.
<Rtext>	is the replacement-text for the field. A null string indicates no replacement-text. The allowable values for RTEXT for the different field types are: ‘CALLBACK’ - callback string ‘TOGGLE’ - callback string ‘MENU’ - menu name string (without preceding ‘.’). It cannot be blank. ‘FORM’ - form name string (without preceding ‘!!’). It cannot be blank.
<FieldName>	is an optional argument, which, if present, is the unique field name within the menu.