Defining a Bar Menu Gadget

A bar menu is defined within a form definition. The menu bar is created with the bar subcommand.

Note:
Its name is ‘bar’: there can be only one bar menu on a form.

Then you can use the bar’s Add() method to add the options. For example:

!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 code specifies the text of three options labelled Choose, Window, and Help.

The Choose option when picked will open Menu1 as a pull-down (assuming you has defined Menu1).

Note:
That Menu1 need not exist when the bar is defined, it can be defined later in the form definition, but it must exist before the Choose option is selected or an error alert will be raised.

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:

layout form !!MyForm Dialog size 30 5

bar

add 'Choose' .menu1

add window

add help

exit

exit

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:

Window Menu

You can add the system Window menu to a bar menu using:

!this.bar.add (‘<Dtext>’, ‘window’)

This menu is dynamically created on use with a list of the titles of the windows currently displayed as its fields. Selecting a field will pop that window to the front. This can be very useful on a cluttered screen.

Online Help Menu

You can add the system Help menu with the specified display text to a bar menu using:

!this.bar.add (‘Dtext’, ‘Help')

!this.bar.InsertAfter(‘window’, ‘<Dtext>’, ‘Help’

When selected, this Help option displays a system-help pull-down menu that gives access to the application help system. The fields are:

You can access On Window help by pressing the F1 key while the form has keyboard focus, or by including a Help button in the form’s definition.

Note:
By convention, the help menu should be the last one defined for the menu bar, which will make sure that it appears at the right-hand end of the menu bar.

Popup Menus

You can use any of their defined menus as popup menus for most interactive gadgets and for the form background as long as you have specified them as belonging to the popup menu system.

When the cursor is moved over it with the popup mouse button pressed down, and then released, the menu will be displayed, and you can select from it in the normal way.

A popup is added to a gadget or form using its Setpopup() method, with the popup menu as the argument to the method.

Note:
The menu pop1 must exist when the Setpopup() method is executed.

For example:

layout form !!MyForm resizable

menu .pop1 popup

!this.pop1.add( 'MENU', 'Options', 'optionmenu' )

!this.pop1.add( 'MENU', 'More', 'moremenu' )

!this.pop1.add( 'MENU', 'Last', 'Lastmenu'

button .b1 ...

. . .

!this.b1.setpopup( !this.pop1 )

. . .

exit

Finding Who Popped up a Menu

You can find out whether a menu was popped up from a gadget, and if so, the gadget’s name. The method is:

!menu.popupGadget() is GADGET

If the menu was a popup on a gadget then the returned GADGET variable is a reference to the gadget. If the menu was popped up from a pulldown-menu or from a popup on the form itself, the value is UNSET.

Example:

!g = !menu.popupGadget()

if !g.set() then

!n = !g.name()

$p menu popped up by gadget $!n

else

!n = menu.owner().name()

$p menu popped up by form $!n

endif

Toggle Menus

A menu TOGGLE field is a menu field with a callback action and a tick-box to show that the field has been selected or unselected.

By default the field will be unselected so the box will not be ticked. When picked the fields callback action will be executed and the tick-box ticked.

If you pick the field again the callback action will again be executed and the tick removed.

Note:
The open callback is an obvious candidate for toggle menus as the SELECT or UNSELECT action is returned as the second argument to the callback method. Refer to PML Functions and Methods.

For example, in your form definition you can add a toggle field as follows:

layout form !!Myform Dialog size 30 5

. . .

!menu = !this.newmenu(‘Test’, ‘popup’)

!menu.add( 'Toggle' ,’Active/Inactive’, '!this.toggle(‘, 'OnOff' )

. . .

exit

. . .

define method .toggle( !menu IS MENU, !action IS STRING )

!name = !menu.fullname()

!field = !menu.PickedFieldName

$P menu $!name $!action field: $!field

endmethod

Note:
How you use the PickedFieldName member of the menu object to obtain the last picked field.

If you pick this menu field the callback method will print:

menu !!MyForm.Menu1 SELECT field: OnOff