Menu

Description

The Menu class implements menu bars, sub-menus, and individual menu items. It also implements pop-up menus. The behavior depends on the parent of the Menu object:

• If the Menu object is created as the child of a window object, it represents an item in the menubar of the window, for example the 'File' menu of a typical application window.
• If the Menu object is defined as top-level object, it is a pop-up menu which can be displayed using the Popup method.
• If the Menu object is the child of another Menu object, it is an item in the parent menu or sub-menu. Sub-menus can be multiple levels deep if required.

Principal Menu properties

The main properties used when working with Menu objects are:

caption: A character vector containing the menu title string. An ampersand character '&' in the string will not be displayed, but under Windows will cause the next character to be the keyboard-selection character for the menu. Under MacOS, the ampersand will have no effect but again will not be displayed, so you can use the same string for cross-platform applications. To display an ampersand in the menu title, put two ampersands in the character vector.

enabled: 1 if menu is enabled, 0 to disable it (default: 1)

visible: 1 if menu is visible, 0 to hide it (default: 1)

value: 1 to place a check mark by the menu item, else 0 (default 0)

separator: 1 if the item is just a separator line, else 0

shortcut: The shortcut key (if any) as a two-element vector. The first element is the letter corresponding to the key (for example, 'A'), or alternatively an integer which is the virtual key code (for alphabetic keys, this is just the ASCII code, for example 65 for 'A'). Under Windows and Linux, the second element is the modifier code: 0 (plain), 1 (shift), 2 (ctrl), 4 (alt) and sums thereof. Note: Some of these may not be useful in practice because the operating-system intervenes before APLX sees the keystroke; in Windows, for example, this happens with the Alt key. The second element can be omitted and defaults to 2 (ctrl). Under MacOS, the second element is ignored since the Command key is always used for menu shortcuts. If the shortcut property is an empty vector, there is no shortcut key.

Other Menu properties

Other less commonly-used properties include:

order: Position of menu item in parent menu, in index origin 1. Set by default to the order of creation, but you can change it under program control (under Windows only). Set a fractional value to insert a menu item between two existing items. The menu items will be renumbered from 1 to the total number of items. Writing to this property has no effect under MacOS.

group: Menu items can automatically work like radio buttons, i.e. if one of the group is selected, all others are automatically deselected. Normally, this behavior is switched off, with the group property set to 0. Setting the group property to an integer in the range 1 to 255 makes the the item a member of that group, and enables the radio-button behavior.

style: If the style property is 1, the menu item is automatically selected/deselected when the user clicks it (the value property will reflect the state). This may sometimes mean that there is no need to define an onClick handler for the menu, because you can read back its value property when you need it.

Pop-up Menu Methods

When you want to display the pop-up menu (for example, in response to a right-mouse click), you call the Popup method. If you call this without parameters, the menu pops up at the mouse position. Alternatively you can supply the Top and Left coordinates as a two-element vector in the parent (System object's) scaling units.

Menu callbacks

You typically respond to menu selections by defining the onClick callback of the menu item, to carry out the appropriate action when the user selects a menu. An alternative way of doing this is to define an onMenu callback for the window containing the menu bar; this allows a single callback function to respond to a whole set of menu items. You can combine the two approaches if it is more convenient to do so.

Placing images next to menu items

Under Windows and Linux, you can optionally place images next to menu items. To do this, you need to create an ImageList object which contains all the images which appear in the menubar (or pop-up menu) and any sub-menu items. You then associate the ImageList with the menu hierarchy as follows:

• For the menus in a window's menubar, write the name of the ImageList to the window's menuimagelist property.
• For a pop-up menu, write the name of the ImageList to the pop-up menu's imagelist property.

Finally, you set the imageindex property of each menu item where you want to display an image. This selects one of the images from the ImageList. (See the description of the ImageList object for an example.)

Example 1: Window menu bar

      ∇DEMO_Menu;DEMO
[1]  ⍝ Sample function demonstrating use of the Menu object
[2]   DEMO←'⎕' ⎕NEW 'Window' ⋄ DEMO.title←'Menu Example'
[3]  ⍝
[4]  ⍝ Set up the File menu
[5]   DEMO.File.New 'Menu' ⋄ DEMO.File.caption←'&File'
[6]   DEMO.File.Open.New 'Menu' ⋄ DEMO.File.Open.caption←'&Open'
[7]   DEMO.File.Close.New 'Menu' ⋄ DEMO.File.Close.caption←'&Close'
[8]   DEMO.File.Exit.New 'Menu' ⋄ DEMO.File.Exit.caption←'&Exit'
[9]   DEMO.File.Exit.shortcut←81 2
[10] ⍝
[11] ⍝ Set up the Edit menu
[12]  DEMO.Edit.New 'Menu' ⋄ DEMO.Edit.caption←'&Edit'
[13]  DEMO.Edit.Undo.New 'Menu' ⋄ DEMO.Edit.Undo.caption←'&Undo'
[14]  DEMO.Edit.Undo.shortcut←92 2
[15]  DEMO.Edit.Undo.enabled←0
[16]  DEMO.Edit.Sep1.New 'Menu' ⋄ DEMO.Edit.Sep1.separator←1
[17]  DEMO.Edit.Cut.New 'Menu' ⋄ DEMO.Edit.Cut.caption←'&Cut'
[18]  DEMO.Edit.Cut.shortcut←'C' 2
[19]  DEMO.Edit.Copy.New 'Menu' ⋄ DEMO.Edit.Copy.caption←'&Copy'
[20]  DEMO.Edit.Copy.shortcut←'X' 2
[21]  DEMO.Edit.Paste.New 'Menu' ⋄ DEMO.Edit.Paste.caption←'&Paste'
[22]  DEMO.Edit.Paste.shortcut←'V' 2
[23] ⍝
[24] ⍝ Set up callbacks. In a real example, these would be functions.
[25] ⍝ We just print the name of the menu which was clicked
[26]  DEMO.File.Open.onClick←'⎕←⎕WSELF,'' selected'''
[27]  DEMO.File.Close.onClick←'⎕←⎕WSELF,'' selected'''
[28]  DEMO.File.Exit.onClick←'⎕←⎕WSELF,'' selected'''
[29]  DEMO.Edit.Undo.onClick←'⎕←⎕WSELF,'' selected'''
[30]  DEMO.Edit.Cut.onClick←'⎕←⎕WSELF,'' selected'''
[31]  DEMO.Edit.Copy.onClick←'⎕←⎕WSELF,'' selected'''
[32]  DEMO.Edit.Paste.onClick←'⎕←⎕WSELF,'' selected'''
[33] ⍝
[34] ⍝ Wait for the user to close the window
[35]  0 0⍴⎕WE DEMO
      ∇

Example 2: Pop-up menu

      ∇DEMO_Popup;MyPopUp
[1]  ⍝ Sample function demonstrating pop-up menu
[2]  ⍝ Create the pop-up menu itsel
[3]   MyPopUp←'⎕' ⎕NEW 'Menu'
[4]  ⍝
[5]  ⍝ Create the pop-up menu items
[6]   MyPopUp.Rect.New 'Menu' ⋄ MyPopUp.Rect.caption←'Rectangle'
[7]   MyPopUp.Circle.New 'Menu' ⋄ MyPopUp.Circle.caption←'Circle'
[8]   MyPopUp.Triangle.New 'Menu' ⋄ MyPopUp.Triangle.caption←'Triangle'
[9]   MyPopUp.Line.New 'Menu' ⋄ MyPopUp.Line.caption←'Line'
[10] ⍝
[11] ⍝ In a real example, you would define onClick callbacks here
[12] ⍝
[13] ⍝ Pop up the menu at the mouse position
[14]  MyPopUp.Popup
      ∇ 

Properties

caption children class data enabled events group imageindex imagelist menuimagelist methods name opened order properties self separator shortcut style tie value visible

Methods

Click Clienttoscreen Close Create Delete New Open Popup Send Set Trigger

Callbacks

onClick onClose onDestroy onOpen onPopup onSend

See also onMenu