Only frame windows can have a normal menu, however a popupmenu can be assigned to any window. To create and manage a normal menu there is the class menu, for a popupmenu the class popupMenu must be used (this class is a subclass of menu).
The first two steps in creating a menu are to allocate an instance of the class menu and to populate it with items. Each unique menu item must have a unique identifier or else you cannot differentiate among the different menu items. This identifier is an integer number. Below there is an example of creating a menu and adding menu items to it:
| File new_obj menu, File<-appendItem(100, '&Open...', enabled_unchecked, R), File<-appendItem(101, '&Close...', enabled_unchecked, R), File<-appendSeparator(R), File<-appendItem(102, 'E&xit', disabled_unchecked, R), |
The first argument of each call to appendItem/4 is an identifier for the menu item. Then follows the text of the menu item, the & character in the name of the menu item adds an underscore to the character that follows the & character. Using the & character also creates a keyboard shortcut for the menu item, if the menu is open and the user presses the 'O' character then the item 'Open...' is selected. The third parameter determines the initial state of the menu item, the 'Open...' menu item is created enabled and does not have a checkmark left of the menu item text. The last menu item 'Exit' is initially created disabled, i.e. the menu item cannot be selected.
The four constants for setting the visible state of menu items are:
The third menu item is a separator menu item, a separator menu item is just a line and it is used to separate different groups of menu items.
The next step is to create a top menu bar, this is the menu bar that is always visible at the top of a frame window, it often contains the file-, edit- and helpmenus.
| Top new_obj menu, ...file, edit and help menu instances were created... Top<-append(File, '&File', _), %Append submenu's to the menu bar Top<-append(Edit, '&Edit', _), Top<-append(Help, '&Help', _), |
For the top menu bar an instance of the class menu was created, then the method append/3 was used to append menu instances (which contain the menu items). Like for menu items the & character is used to determine the keyboard shortcut for the menu.
The last step is to assign the complete menu to the frame window, the method putMenu/2 of the frame class can be used for that.
| X new_obj testFrame, add_callback(X, onCommand, X, doOnCommand), X<-create(Result), ...a menu was created... X<-putMenu(Top, Result), X<-show. |
As shown in the example above the best moment to assign a menu to a frame window is between the creation of the window and showing it on the screen. To be able to respond to menu items a callback handler must be specified for the onCommand/2 event. When a menu instance is assigned to a frame window then it is not necessary to delete the menu instance, the menu instance is deleted by the frame window.
Creating a popupmenu
Creating a popupmenu is done by allocating an instance of the class popupMenu. This class is a subclass of menu so all the methods for appending items and controlling the menu are available for popupmenu instances.
A popupmenu can be assigned to any window by the method putPopupMenu/2 of the window class. Below there is an example of creating a popupmenu.
| Popup new_obj popupMenu, Popup<-appendItem(200, '&Test 1', enabled_unchecked, _), Popup<-appendItem(201, '&Test 2', enabled_unchecked, _), putPopupMenu(Popup, true), putAllowDisplayInfo(false). |
The second parameter of the method putPopupMenu/2 determines if the popupmenu automatically appears if the right mouse button is pressed, if the value of the parameter is true, as in the example above, the popupmenu appears if the right mouse button is pressed. The last line of the example contains a call to the method putAllowDisplayInfo/1, the call to this method is to prevent that TPWin appends a standard menu item to the popup menu, this is the menu item "Window Information...". If this menu item is chosen the standard "version information window" dialog is displayed. See the frame class for more about this dialog.
It is not necessary to delete the popupmenu instance if it is assigned to a window, if the window is deleted the popupmenu is also deleted.
Responding to a menu event
Each menu item has a unique identifier and by matching on the identifier value there can be a clause for each separate menu item, the frame that contains the top menu must register a callback event handler for the onCommand/2 event, an example of this is:
| add_callback(X, onCommand, X, doOnCommand) |
Below there is an example of declaring a class derived from the frame class which declares an event handler for the onCommand/2 event and responds it.
| class testFrame. inherit frame. public. doOnCommand/1. endclass testFrame. testFrame::doOnCommand( onCommand(Sender, 100) ) :- ...Pressed menu item File | Open... testFrame::doOnCommand( onCommand(Sender, 101) ) :- ...Pressed menu item File | Close... testFrame::doOnCommand( onCommand(Sender, X) ) :- ...Respond to all remaining menu items... |
The onCommand/2 event structure contains the sender of the event and the integer identifier of the menu item that was selected. The third handler demonstrates the power of matching in Prolog by using a variable that responds to all menu item events.
There is a more complete example demonstrating the menu classes called 'menu', it can be started by opening the 'Examples | Start...' window and choosing menu, the source of the example is located in 'examples\menu\menu.txt'.