Introduction -turn page- Reference List Menu Library

Contents | Start

The Menu Library

2. The Menu Library
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
2.9
2.10
2.11
Definition of Menus
Menu Query
Evaluating the Variable Entry
Submenus
Menu Attributes
Inserting and Deleting Items
Deleting a Menu
Managing Several Menus Using EasyGem
Guidelines for the Programming of Menus
Pop-up Menus
Link with Mac OS Toolbox
Reference List Menu Library
 
 

The menus are a rather important aspect of any user interface. You are familiar with the Finder menu: the upper line shows a variety of different entries. Using the mouse cursor to click on an entry causes a box with several subentries to appear. Then you can use the mouse to select the desired item.
Such menus are usually created with a resource editor that writes the required information into the resource fork of your program. From there, they then have to be identified using a number and a type, loaded by the program, and registered with the MacOS.
All of this is much easier with EasyGem: You do not need an additional program, all menus are defined and managed with the use of simple and clearly arranged commands directly from within your program. Even a novice programmer can use EasyGem to create professional looking menus.


2.1 Definition of Menus

Let's start these instructions at the point where the programming commences: determining the appearance of the menus.
First, of course, you need to have a clear picture of how the menus are supposed to look. Every menu has at least one menu title. This is usually the Apple menu from which the control fields are called. This menu allows the addition of exactly one additional menu item or menu entry. Most programmers place their copyright message right here.
All other menu titles can be assigned freely and as desired. Thus, it is advisable to think about the names of the menu titles first, how many are supposed to be used, and which entries are to be registered for each respective menu title. The menu itself is then easily created from within the program using the following EasyGem commands:

Make_Menu Apple$,Info$,R Info[,Menuname$]
Def_Menu [R Menu_Id,] Info$, R Info
Begins menu definition.
M_Title Title$[,R Entry]
Determines menu title.
M_Entry Txt$, R Entry
M_Subtitle Subtitel$[,R Entry]
Defines menu item and/or menu subtitle.
M_Line_Entry
Defines menu line.
M_End_Title
Ends title or subtitle.
End_Menu
Ends menu definition.


First, a little example to illustrate this point:
Def_Menu Menu1,"About this program",Info
 M_Title "File"
  M_Entry "New",New1
  M_Entry "Open",Open1
  M_Entry "Save",Save1
  M_Line_Entry
  M_Entry "Quit",Quit1
End_Menu
This sample program illustrates that Def_Menu initiates the definition of the menu and End_Menu concludes it. The actual determination of how the menu will appear, that is, the names of the entries and menu titles, and which entry corresponds to which title, is listed in the program between the Def_Menu and the End_Menu.

In the first variable behind
Def_Menu an identification number is returned. You may later need this number for other EasyGem functions. If you want to use only one menu, the first variable can be omitted as well.
The second parameter behind
Def_Menu is the text of the first entry of the Apple menu (usually some sort of copyright message). The variable Info in the Def_Menu serves to identify whether a corresponding entry has been clicked on.
M_Title is used to begin a new menu title. The name of the menu title has to be passed as the parameter.

This is followed by
M_Entry, which determines the individual entries of the menu title. These are the parts that fold out as soon as the mouse is used to click on the menu title. The name of the entry as well as a variable returning a reference number for this entry have to be indicated behind M_Entry. This can be used later on to determine which menu item has been selected.

Finally, the use of
End_Menu concludes the menu definition process.

After a menu has been defined using the described method, it can now be brought to the screen. The following command is used for this process:

M_Show
Displays menu.

Of course, initially none of the boxes are folded out and only the title
bar of the menu is visible.

Note: The command Make_Menu is available only for kompatibility reasons with older EasyGem versions. With new programs you better should use Def_Menu instead of Make_Menu.

In many cases, it is necessary to turn of a menu in its entirety, for example, if a modal dialog box is being displayed or if the program execution should not be disturbed by menu activities of the user for other reasons. For this purpose, the command M_Hide exists. It will render the entire menu inactive, which means that the menu is still visible but cannot be accessed any longer.

M_Hide
Hide menu (menu is no longer accessible). The previously deactivated menu can be reactivated using M_Show.


Already you can use the up to now introduced commands to write a small program. For this purpose we will take the program above and add a few lines. Our small program will not contain a menu query as of yet but rather just depict the menu and then delete it again after 5 seconds.

COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init

Def_Menu Menu1,"About this program",Info
 M_Title "File"
  M_Entry "New",New1
  M_Entry "Open",Open1
  M_Entry "Save",Save1
  M_Line_Entry
  M_Entry "Quit",Quit1
End_Menu
M_Show
WAIT 5
Easy_Exit
END




2.2 Menu Query

During these 5 seconds - when the menu was displayed - you might have tried to use the mouse to access the title bar to fold down an entry. If you tried this, you noticed that nothing happened, nothing was folded out.
The reason for this is that EasyGem has not been asked yet to take care of such events as "mouse is in uppermost line," meaning, "fold down menu." In order to introduce the corresponding procedure, we have to cover some tasks in a bit more detail first.

There are several types of tasks a user can carry out: windows can be modified (enlarged/reduced, moved, deleted, moved to the background, a slider bar can be set, etc.), and it is possible to work with the menu (fold down menus and click on individual entries). EasyGem offers a variety of different procedures, depending on whether users are supposed to work only with windows or with windows and menus.

The simplest call of EasyGem, which only covers menu tasks of the user, is as follows:

M_Waitmesag R Entry
Waits for menu event.

The procedure M_Waitmesag will take care of everything else for you: If the mouse moves into the area of the uppermost line and if the mouse button is depressed, the corresponding menu will fold out. As soon as the user has selected an entry from the folded down box, M_Waitmesag sets the variable Entry accordingly and returns.

If you still have the program from the previous sample stored in memory, you can use that program for a trial replacement, substituting the
WAIT 5 with M_Waitmesag Entry. The modified program displays the menu header and waits until you folded down any of the menu boxes and have clicked on an item. Then the M_Waitmesag will return again, Easy_Exit will be called, and the program is terminated.

Important: M_Waitmesag waits until a menu item has been selected by clicking on it with the mouse; only then will the control be returned to the program! If the menu query is supposed to take place on the side, meaning, your program is supposed to carry out other tasks at the same time it queries the menu, then you have to use Easy_Mesag:
Easy_Mesag R Entry
Queries the menu and returns either 0 (nothing clicked on) in Entry or the clicked on menu item.

Easy_Mesag corresponds to M_Waitmesag, the only difference is that it does not wait until a menu item has been chosen. However, the query whether to fold down a box or not and which menu item has been chosen, only takes place within Easy_Mesag. It is therefore necessary to repeatedly call Easy_Mesag! Should you neglect to do so, e.g., call up Easy_Mesag only once, then only the mouse will be queried during the short time required for the execution of Easy_Mesag. No further queries of the mouse by EasyGem will take place after that, and the user can certainly move the mouse into the header - but with no effect. The proper use of Easy_Mesag is thus as follows:

REPEAT
 Easy_Mesag Entry
 'A short program part may be listed here.
UNTIL End_Condition

It is important that the "short program part" does not take too long to be executed. If that is the case, it is an indication that Easy_Mesag is not called often enough and the mouse is thus not queried as much as it should be. The result might be that the user takes the mouse to the title bar, but the menu will only fold down after a delay of half a second (the next time when Easy_Mesag is called, to be precise).


2.3 Evaluating the Variable Entry

Which menu item has been chosen by the user is returned in the variable
Entry with M_Waitmesag as well as with Easy_Mesag. Nevertheless, when M_Waitmesag is being used, there is a delay until a menu item has been chosen. Easy_Mesag, however, can also return zero in Entry, namely at that exact point in time when no menu item has been clicked on for the moment. The difference is about the same as between INPUT$(1) and INKEY$. In the first case, the computer waits until a key has been pressed; if no key has been pressed yet, an empty string is reported in the latter case.

It is really not that easy to express the information about which entry has been clicked on in one simple number. One could number the entries all the way through and then return the number of the entry in
Entry, but what happens if an entry is added in the menu? All queries directed towards any of the entries following the new one are no longer accurate. That is the reason EasyGem has chosen a different path.

You might remember the variable you have to indicate with every
M_Entry. As we know, the syntax of M_Entry is as follows:
M_Entry Txt$,R Entry
Defines menu item.

Entry then will return the internal ID number of the respective entry. This number will be returned later by M_Waitmesag and Easy_Mesag as well. A simple comparison will then determine whether the respective entry has been chosen or not. The number itself may remain unknown to you.

Basically, the query of menus thus functions as follows:

1. You define your menu with
Def_Menu, M_Title, M_sub_Title, M_Entry, and End_Menu. Every time you use M_Entry, you indicate a variable. The 'File' menu - already known to us - may serve as an example. There, we used the variables New1, Open1, Save1 and Quit1.

2. You call
M_Waitmesag or Easy_Mesag, and the variable Entry is returned to you.

3. In order to determine which entry has been chosen, compare
Entry with New1, Open1, Save1 and Quit1. If Entry equals New1, the menu item "New" has been chosen; if Entry equals Open1, the entry "Open" has been selected, and so forth. If Entry equals zero, nothing has been clicked on (this response is only possible with Easy_Mesag; if nothing has been clicked on, M_Waitmesag does not return.

4. Depending on the selections made, your program can now respond appropriately.


The following sample program displays a small menu on the screen and outputs the respective name of each menu item that has been clicked on. The program can be exited by choosing
"Quit".

COMPILER "MIN_SIZE 500000"
COMPILER "BAS_MEM 1000000"
COMPILER "OPW 320*200"
COMPILER "Warnings off"

Easy_Init

'Definition part.
Def_Menu Menu1,"About this program",Info
 M_Title "File"
  M_Entry "New",New1
  M_Entry "Open",Open1
  M_Entry "Save",Save1
  M_Line_Entry
  M_Entry "Quit",Quit1
End_Menu
'End definition part.

M_Show:'Menu will be displayed.

REPEAT
 M_Waitmesag X
 Select X
  CASE Info:PRINT "About this program"
  CASE New1:PRINT "New"
  CASE Open1:PRINT "Open"
  CASE Save1:PRINT "Save"
 END_SELECT
UNTIL X=Quit1

Easy_Exit:'Program ends: EasyGem is unmounted.
END


2.4 Submenus

Starting with EasyGem 4.0, it is also possible to define submenus. The following two procedures are available for this purpose:


M_Subtitle Title$[,R Entry]
M_End_Title
Defines submenu.

Let's assume you have written a paint or drawing program and would like to offer the option to choose between different file formats to the user. For this purpose, you can include a submenu as depicted by the following example:

Def_Menu Menu1,"About this program",Info
 M_Title "File"
  M_Entry "New",New1
  M_Entry "Open",Open1
  M_Subtitle "Save",Save1
   M_Entry "as 'PICT'",Save_Pict1
   M_Entry "as 'GIF'",Save_Gif1
   M_Entry "as 'TIFF'",Save_Tiff1
  M_End_Title
  M_Line_Entry
  M_Entry "Quit",Quit1
End_Menu
As you can see, the menu item "Save" is now replaced by the definition of a submenu. The individual items of the submenu are defined in the same way as items for a normal menu. However, you have to ensure that the definition of the submenu is terminated with M_End_Title so that EasyGem knows that all of the following entries belong with the main menu again.

It is even possible to nestle submenus, which means to create submenus for submenus. But you need to remember that each indivdual submenu has to be terminated with
M_End_Title. Your definition thus has to contain just as many M_Subtitle commands as M_End_Title commands.

2.5 Menu Attributes

You might have seen menus already that offer a variety of extras. Some entries could not be chosen (indicated by the letters being grayed out); some entries have little check marks or a symbol next to them; there are entries represented by a different font than the other entries, or entries, which have an assigned keyboard shortcut; and finally, there are programs, which change their entries while they are being run. All of that you can achieve with EasyGem as well and as easy as the creation of the menus themselves.

An attribute is considered to be a characteristic of a menu item. If the attribute is "checked," it means that a check mark is next to the menu item. If an attribute is "disabled," it is represented as being grayed out and cannot be selected.

With EasyGem you can easily change the attributes of all menu entries. For example, in order to set the attribute "checked," all you need to do is call
M_Check:

M_Check Entry
Assigns the attribute "checked" (the check mark) to the menu item Entry.

In this case, Entry once again denotes the internal ID number of the respective menu item. This internal ID number has already been returned by M_Entry in the definition of the menu. Consequently, you can always just indicate the variable for Entry that you have also used with M_Entry.
Def_Menu "Info",Info
 M_Title "File"
  M_Entry "With check mark",Checkmark1
  M_Line_Entry
  M_Entry " Quit ",Quit1
End_Menu
M_Check Checkmark1:'The entry "With check mark" is here equipped with the
'attribute "checked". As soon as the box unfolds, the entry will have
'a check mark next to it.

As you can see, the variable Checkmark1 is simply indicated in the case of M_Check. This convention is the central thread running through all of EasyGem. The variable Checkmark1 denotes the entry "With check mark!" Any time this entry is the intended target, one either explicitly indicates the variable Checkmark1 (as in the case of M_Check), or one compares using this variable (as in the case of M_Waitmesag or Easy_Mesag ).
In order to clarify the subject at hand, you can substitute the line

CASE New1:PRINT "New"

from the previous sample program with the following:
CASE New1:M_Check New1

Now, if the menu item "New" is being clicked on, it will then be assigned the attribute "checked," meaning that a check mark will be placed next to it.
Each menu item has to have that variable representing the entry, which has been indicated when the menu item was defined with
M_Entry.

Of course, there are numerous other types of attributes and assigned commands, which are listed here as follows:

Attribute "checked" (preceding check mark):
M_Check Entry
Set.
M_Uncheck Entry
Delete.

Attribute "disabled" (grayed out - cannot be selected):
M_Disable Entry
Set.
M_Enable Entry
Delete.

Note: This command may also be used to "disable" or "enable" the menu title itself and all corresponding entries. To accomplish this, you have to pass the number of the menu title for Entry and subsequently call M_Draw to make the change visible.

Attribute "crossed" (crossed out rectangular or square):
M_Cross Entry
Set.
M_Uncross Entry
Delete.

Attribute "font" (changes font):
M_Font Entry,Font
Font has to receive the identification number of the desired font. If you dont't know this number, you can use the function FN Get_Font_Number from the Extension Library to get the font number from the font name.

Attribute "style" (changes font style):
M_Style Entry,Style
Style has to receive the same value as the BASIC command TEXT STYLE.

Attribute "mark" (set mark):
M_Mark Entry,Mark
Mark has to contain the ASCII code of the symbol or character, which is to be placed next to the menu.

Delete all attributes:
M_Normal Entry
The entry is once again displayed normally (without any attributes).

Maybe some menu entries are supposed to be available via a keyboard shortcut as well. In this case, Apple has determined that the command key - together with a normal key - should be used for this purpose. Capital letters and small letters are used indiscriminately in this case. EasyGem offers a command to set these so-called shortcuts as well:
Attribute "shortcut" (define key):
M_Command Entry,Cmd
For Cmd, please indicate the ASCII code of the character which is supposed to trigger the menu item.
Note: If Cmd=0 is indicated, the shortcut will be removed again.
Starting with Mac OS 8.0, it is possible to utilize the other modifier keys for menu shortcuts as well. The command M_Modifier was implemented into EasyGem 4.0 just for this purpose.
Attribute "modifier" (define modifier keys):
M_Modifier Entry,Modifier
In Modifier, you have to pass a bit mask. The individual bits, therefore, have the following meaning:

Bit 0: Shift Key
Bit 1: Alt Key
Bit 2: Ctrl Key
Bit 3: NOT Cmd Key

Please note: Bit 3 is a negative bit. If this bit is set, the Cmd key is not used.
Example:
Def_Menu "Info",Info
 M_Title "File"
  M_Entry "Shift+Alt+A",Entry1
  M_Line_Entry
  M_Entry "Quit",Quit1
End_Menu
M_Command Entry1,65::'Here you define that the entry "Shift+Alt+A" can also
M_Modifier Entry1,%1011:'be triggered by the key combination [Shift]+[Alt]+A.
'The otherwise utilized Cmd key is deactivated by the 3rd bit.


Sometimes it is necessary to change the text of a menu item during the execution of a program. For example, depending on what type of contents an uppermost window contains, an UNDO function might apply at one time to text and at another time to graphics. In order for the user to know which type of task can be reversed, the text in the menu item should be adapted accordingly.
The following command can be used for this:
M_Text Entry,Txt$
Any string expression may be passed in Txt$ (max. 255 characters).

Sometimes it is necessary to be able to query whether or not an entry has a specific attribute. EasyGem offers functions for this task as well:

You probably have already noticed that some programs also use icons in their menus. This is now an option starting with EasyGem version 4.0. However, one problem is that the appearance of an icon cannot be defined just by using a command as it is the case for text. If your menus are to feature icons you will need additional software - a so-called resource editor. "ResEdit" is a free program by Apple that will serve most purposes of this kind and can can be downloaded from Apple's Internet site.
You use this program to open the file with the BASIC code of your program and create the resource type 'cicn'. This is a small picture consisting of 32 x 32 pixels, which you can create with the editor included in ResEdit. A number between 256 and 510 has to be assigned to the icon resource. This number you then indicate for
M_Icon to define the Icon.

Attribute "icon" (assign icon):
M_Icon Entry,Icon
In Icon, you have to pass the resource number of the desired icon.

The icon is usually displayed in the menu in its full size of 32 x 32 pixels. Since this increases the size of the menu item significantly, it is possible to use the command M_Command Entry,$1D to decrease the size of the item to 16 x 16 pixels.

Querying for "checked" (check mark):
FN M_Checked(Entry)
Returns -1, if the entry is "checked," otherwise 0.

Querying for "disabled" (grayed out - cannot be selected):
FN M_Enabled(Entry)
Returns -1, if the entry is "enabled," (if entry can be selected), otherwise 0.

Querying for "crossed" (crossed out rectangular or square):
FN M_Crossed(Entry)
Returns -1, if the entry is "crossed," otherwise 0.
Querying for "font" (font number of menu item):
FN M_Font(Entry)
Returns the font number.

Querying for "style" (font style of menu item):
FN M_Style(Entry)
Returns the text style (significance is same as for TEXT STYLE).

Querying for "mark" (marking of the menu item):
FN M_Mark(Entry)
Returns the ASCII code of the marking of the menu item.

Querying for "shortcut" (shortcut for menu item):
FN M_Command(Entry)
Returns the ASCII code of the shortcut belonging to the menu item.

Querying for "modifier" (modifier keys for menu item):
FN M_Modifier(Entry)
Returns a value which tells you what combination of modifier keys triggers this menu option. Description of the return value at M_Modifier.

Querying for "text" (text of the menu item):
FN M_Text$(Entry)
Returns text of the menu item as a string.

Querying for "icon" (Icon number of the menu item):
FN M_Icon(Entry)
Returns the number of the icon which is attached to this menu item.

For example, in order to query our demo program whether the entry "Text 1" has been "checked" or not, the following program line has to be added:

IF FN M_Checked(Open1)
 THEN PRINT "With check mark"
 ELSE PRINT "Without check mark"
ENDIF

This illustrates the fact that the attributes may be set even though the menu has not been displayed yet. However, the up to now discussed functions and procedures only function correctly if the menu definition has already been concluded - after End_Menu has been executed.
If you would like to assign a certain attribute to an entry right from the start, you can choose a different path (example is for attribute "checked"): Simply write
the call M_Check (without parameter) in the line containing the M_Entry. Write M_Check directly behind M_Entry itself. This would then look as follows:
M_Entry "Open",Open1:M_Check 'This entry is now being checked, meaning,
'it will receive a check mark.

All other attributes can be handled completely analogously:
M_Disable
"Disable" entry at once.
M_Check
"Check" entry at once.
M_Cross
"Cross" entry at once.
M_Font Font
Set text font.
M_Style Style
Set text style.
M_Mark Mark
Set mark.
M_Command Cmd
Set shortcut.
M_Modifier Modifier
Set modifier keys.
M_Icon Icon
Set icon.

The appropriate and corresponding attribute is set in each case. In order for EasyGem to know which menu item is targeted by which command, these calls have to be written directly behind the M_Entry to which they apply.
Incidentally, a reverse function does not exist. If an entry is not supposed to be "crossed," then simply omit indicating
M_Cross.

Another optional method to assign menu attributes already during the definition phase is to use so-called meta-characters. These can be written immediately behind the text of the respective menu item. The following meta-characters exist:

!
The letter behind the exclamation mark is used to mark the beginning of the entry (e.g., the diamond-shaped symbol or check mark).
<
This may be used to determine the text attributes of the menu. To achieve this task, the letters B (bold), I (italic), U (underline), O (outline), and S (shadow) are used. Several of these letters may also be listed simultaneously behind the 'less than' symbol.
/
Serves to determine the keyboard shortcuts for this menu item.
(
The entry will be disabled, is therefore no longer selectable.

For example, in order to define a menu item called "Print", which can also be triggered by the shortcut [Cmd] + [P] and which is at first "disabled", because after the program's initial start there are no documents loaded as of yet which might be available for printing, the following command has to be used:

M_Entry "Print/P(",Prn

Note: Of course, as soon as a document has been loaded that is also printable, you have to use M_Enable to ensure that the menu item "Print" becomes selectable.


Since all good things come in threes, EasyGem offers yet another option to assign attributes while the menu items are being defined. The following four commands may be used to that effect:


M_Disabled_Entry Txt$,R Entry
Defines an entry analogously to M_Entry, with the difference that the entry is "disabled" at once.
M_Checked_Entry Txt$,R Entry
Defines an entry analogously to M_Entry, with the difference that the entry is "checked" at once.
M_Crossed_Entry Txt$,R Entry
Defines an entry analogously to M_Entry, with the difference that the entry is "crossed" at once.
M_Disabled_Entry Txt$
Corresponds to M_Disabled_Entry Text$,R Entry, with the difference that no identifying variable is returned here. This means that the entry cannot be queried, a condition that is hardly serious, since the entry cannot be clicked on at any rate.

The individual items or entries of a menu can often be sorted according to specific function groups, e.g., functions that open windows, others that close windows, or functions that print the contents of windows. In order to separate these individual function groups it is best to draw a continuous line into the menu. The following EasyGem command will draw this line:


M_Line_Entry
Defines continuous line.
Of course, the separator itself is not selectable and only serves as a visual aid.



2.6 Inserting and Deleting Items

You have probably did already work with programs that change their menus during runtime. A frequently encountered example is a generated menu titeled "Window," which will then dynamically display the headers of the currently opened windows. If the user opens a new window, the name of this window will also be incorporated into the window menu. If the user closes a window, this window will then be removed again from the window menu.
The user can then easily bring the desired window to the front by selecting the corresponding menu item.

Starting with version 4.0, you can manage your EasyGem menus dynamically as well. There are two procedures for this purpose:

M_Insert Item, Txt$,R Entry
M_Delete Item
Both of these commands can be used to subsequently insert or delete menu items.
Of course, if you would like to add a new menu item, you have to inform EasyGem about the location of the new item. To this purpose you use Item to pass the number of an already existing item (can also be the number of a title, if no other item exists yet). EasyGem then inserts the new item directly behind the item specified by Item.
If you pass
-Item instead of Item, the new item is not inserted behind but rather in front of Item. Of course, with M_Delete this differentiation does not serve any purpose.
The remaining parameters have the same meaning as with
M_Entry.

Once again we wrote a little sample program to illustrate each necessary step in detail:

COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init

DIM Window(64)
'Definition Section.
Def_Menu Menu1,"About this program",Info
 M_Title "Static"
  M_Entry "Insert",Insert1
  M_Entry "Delete",Delete1
  M_Line_Entry
  M_Entry "Quit",Quit1
 M_Title "Dynamic",Window(0)
End_Menu
'End definition section.

M_Show:'Menu is displayed.

REPEAT
 M_Waitmesag X
 Select X
  CASE Insert1:N+=1
   M_Insert Window(N-1),"Window"+STR$(N),Window(N)
  CASE Delete1
   If N>0 THEN M_Delete Window(N):N-=1
 END_SELECT
UNTIL X=Quit1

Easy_Exit:'Program end: Log off EasyGem.
END

Anytime you select the "Insert" menu item from the "Static" menu, a new item is added to the "Dynamic" menu. This new entry is added behind those that already exist. The last item is removed accordingly when clicking on "Remove."
This inserting or removing would not be associated with clicking on certain menu items but rather with the opening or closing of windows when applied to real applications.

Note: Since these commands can be used to insert or remove menu items at or from any desired location, you can no longer assume that sequential menu items also have sequential numbers. Instead, EasyGem searches for a free number for the new item, for example, the number of an item that has been removed from some other location previously using M_Delete.



2.7 Deleting a Menu

It is rather uncommon to want to delete an already defined menu during the lifetime of a program, but there might be special circumstances requiring this action. In order to meet any and all requirements, the EasyGem Library offers a command to delete a menu as well:

Clear_Menu
Delete menu.




2.8 Managing Several Menus Using EasyGem

If one menu suffices for your programs there is no need for you to read the remainder of this chapter. If, however, you would like to use several, individual menus from within one program, you need to apply the following procedures and functions.

The use of more than one menu requires a way to differentiate between the individual menus. EasyGem makes use of another parameter, which has to be included with all commands necessary to identify a specific menu.

This identification number is returned in the first parameter with Def_Menu. The command End_Menu with a return parameter still exists due to reasons of compatibility with older EasyGem versions:

End_Menu R Menu_Id
Corresponds with End_Menu, but returns the identification number of the just defined menu as well. This number is identical with the number already returned with Def_Menu.

Note: Of course, if you use Def_Menu with three parameters, you do not need to get the identification number again using End_Menu.


The definition of a menu using Def_Menu, M_Title, M_Subtitle, and M_Entry (or M_Disabled_Entry, or, or ... ) is carried out the same way for several menus as when working with just one menu. However, you have to always use Def_Menu with three parameters with the first variable being assigned the identification number of the just defined menu. Contrary to a simple case, such a prorgam as this one contains several Def_Menu each with an assigned End_Menu. Each menu gets its own, unique identification number.

Once the menus are finalized and defined, those commands which are already known to us can be used on these menus. Of course, it is impossible to display two menus at the same time, but what is possible is to turn off one menu and to display another one in its place. The M_Show command is equipped with the identification number of the desired menu as an additional parameter to achieve this task.

M_Show Menu_Id
Displays the menu with the identification number Menu_Id.

Note: The menu for the Omikron Basic output window will be displayed if you indicate Menu_Id=0. Naturally, this only functions if you have also defined an Omikron Basic output window as well.


The following function may be used to determine which menu is currently displayed:
FN M_Which
Determines the identification number of the displayed menu.

Since the management of several menus differs from the management for one menu only by the additional parameter Menu_Id but all other management tasks and functions remain the same, we will refrain from explaining them all once more at this point. However, the following table lists them in their entirety.

M_Check Menu_Id,Entry
M_Uncheck Menu_Id,Entry
M_Disable Menu_Id,Entry
M_Enable Menu_Id,Entry
M_Cross Menu_Id,Entry
M_Uncross Menu_Id,Entry
M_Font Menu_Id,Entry,Font
M_Style Menu_Id,Entry,Style
M_Mark Menu_Id,Entry,Mark
M_Normal Menu_Id,Entry
M_Command Menu_Id,Entry,Cmd
M_Modifier Menu_Id,Entry,Modifier
M_Text Menu_Id,Entry,Txt$
M_Icon Menu_Id,Entry,Icon
FN M_Checked(Menu_Id,Entry)
FN M_Enabled(Menu_Id,Entry)
FN M_Crossed(Menu_Id,Entry)
FN M_Font(Menu_Id,Entry)
FN M_Style(Menu_Id,Entry)
FN M_Mark(Menu_Id,Entry)
FN M_Command(Menu_Id,Entry)
FN M_Modifier(Menu_Id,Entry)
FN M_Text$(Menu_Id,Entry)
FN M_Icon(Menu_Id,Entry)
M_Insert [Menu_Id,] Item, Txt$,R Entry
M_Delete [Menu_Id,] Item
Clear_Menu Menu_Id
As always, the actual use of these EasyGem commands are best illustrated using an example:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init:'Initializes EasyGem.

'Define first menu.
Def_Menu Menu1,"About this program",Info1
 M_Title "Planets",Planets
  M_Entry "Merkury",Mercury
  M_Entry "Venus",Venus
  M_Entry "Earth",Earth
  M_Entry "Mars",Mars
 M_Title "Moons",Moons
  M_Entry "Earth-Moon",Earth_Moon
  M_Entry "Phobos",Phobos
  M_Entry "Deimos",Deimos
 M_Title "Menu 1"
  M_Entry "To Menu 2",To_Menu2
  M_Line_Entry 
  M_Entry "Quit",Quit1
End_Menu

'Define second menu.
Def_Menu Menu2,"About this program",Info2
 M_Title "Baryons"
  M_Entry "Proton",Proton
  M_Entry "Anti-Proton",Anti_Proton
  M_Entry "Neutron",Neutron
 M_Title "Leptons"
  M_Entry "Electron",Electron
  M_Entry "Positron",Positron
  M_Entry "Neutrino",Neutrino
 M_Title "Menu 2"
  M_Entry "To Menu 1",To_Menu1
  M_Line_Entry 
  M_Entry "Quit",Quit2
End_Menu
'Display Menu 1.

M_Show Menu1
'At this point, the program waits for any menu activity.
REPEAT:
 M_Waitmesag Entry
 IF FN M_Which=Menu1
  THEN
   IF Entry=Quit1 THEN EXIT
   IF Entry=To_Menu2 THEN M_Show Menu2
   'More queries for Menu1.
  ELSE
   IF Entry=Quit2 THEN EXIT
   IF Entry=To_Menu1 THEN M_Show Menu1
   'More queries for Menu2.
 ENDIF
UNTIL 0:'Infinite Loop.
Easy_Exit:'Unmounts EasyGem again.
END
Note: If your program initially needs only one menu but might require additional menus further down the line, you should include Menu_Id right from the start. This will save a lot of time and effort in reprogramming the parts for the first menu if and when you decide to add additional menus. It might also be sensible to save the identification numbers as well as the reference numbers for the individual entries and items in fields in case numerous menus are needed. Saving this information in fields will make it more obvious which entries are assigned to which menus.



2.9 Guidelines for Programming Menus

Please note that the preceding examples and sample programs were created using random menu items. They only served the purpose of explaining diverse EasyGem functions and should not be used as the basic for finished programs. Certain rules have become established regarding the creation of menus, which, if at all possible, should be adhered to in the interest of a unified and standardized operationability of different programs.
Each menu should start with the menu titles
"File" and "Edit" and offer a few basic functions for each of these:

Def_Menu Menu1,"About this program",Info
 M_Title "File"
  M_Entry "New/N",New1
  M_Entry "Open ... /O",Open1
  M_Line_Entry
  M_Entry "Close/W",Close1
  M_Entry "Save/S",Save1
  M_Subtitle "Save As ... ",Save_As1
   M_Entry "ASCII code",Save_As_Ascii1
   M_Entry "BASIC code",Save_As_Basic1
   M_Entry "Picture",Save_As_Pict1
  M_End_Title
  M_Line_Entry
  M_Entry "Page Setup ... ",Page_Setup1
  M_Entry "Print ... /P",Print1
  M_Line_Entry
  M_Entry "Quit/Q",Quit1
 M_Title "Edit"
  M_Entry "Undo/Z",Undo1
  M_Line_Entry
  M_Entry "Cut/X",Cut1
  M_Entry "Copy/C",Copy1
  M_Entry "Paste/V",Paste1
  M_Entry "Clear",Clear1
End_Menu

2.10 Pop-up Menus

Starting with version 4.0, you can also use EasyGem to create and manage pop-up menus. You need only three additional procedures for this, because you can use the same procedures and functions for the definition and management as used for normal menus:

Def_Popup R Menu_Id
Begins definition of a pop-up menu.
End_Popup
Ends definition of a pop-up menu.
M_Show_Popup Menu_Id,X,Y,R Entry
Displays a pop-up menu.
A pop-up menu has to be defined before it can be used. This works the same way as with normal menus but do not use Def_Menu and End_Menu but the procedures Def_Popup and End_Popup instead. In between you can define the menu items as usually. Submenus and icons are possible as well.

Caution: Due to technical reasons, pop-up menus function only if a menu bar has been defined as well. For practical purposes, however, this does not represent a restriction, because each application program should have a menu bar.

Pop-up menus are usually called with a specific key combination (most often mouse button + Ctrl key). The command
M_Show_Popup serves this purpose. The following has to be passed to this command: identification number of the desired pop-up menu, position of the pop-up menu (mostly the current mouse position), and number of the default item.
The procedure sets the pop-up menu at the desired location and assumes all actions as long as the mouse button remains pressed. As soon as the user releases the mouse button, the procedure removes the pop-up menu from the screen and the number of the selected item is returned to you in
Entry. This number can also be 0 if no items has been selected.

It's best to use an example to illustrate the individual steps:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"
COMPILER "OPW 320*200"

Easy_Init

'Definition section.
Def_Menu Menu1,"Info about this program",Info
 M_Title "File"
  M_Entry "Quit",Quit1
End_Menu

Def_Popup Popup1
 M_Entry "Undo/Z",Undo_Popup1
 M_Line_Entry
 M_Entry "Cut/X",Cut_Popup1
 M_Entry "Copy/C",Copy_Popup1
 M_Entry "Paste/V",Paste_Popup1
 M_Entry "Delete",Clear_Popup1
End_Popup
'End of definition section.

M_Show:'Menu is displayed.

REPEAT
 Easy_Mesag Entry,Buffer$,Mx,My,Mb
 If Entry
  THEN 'Normal menu processing.
  ELSE
   IF Mb=17
    THEN 'Ctrl+Mouse Button.
     Item=0:M_Show_Popup Popup1,Mx,My,Item
     SELECT Item
      CASE 0:PRINT "Nothing selected"
      CASE Undo_Popup1:PRINT "Undo"
      CASE Cut_Popup1:PRINT "Cut"
      CASE Copy_Popup1:PRINT "Copy"
      CASE Paste_Popup1:PRINT "Paste"
      CASE Clear_Popup1:PRINT "Delete"
     END_SELECT
   ENDIF
 ENDIF
UNTIL Entry=Quit1

Easy_Exit:'Program end: Log off EasyGem.
END

As you can see, a normal menu is defined first; however, this menu has only one item used to exit the program. This is followed by the definition of the pop-up menu.
The program uses an extended version of
Easy_Mesag, which also returns the position of the mouse (Mx,My) and the status of the mouse buttons (Mb). You do not have to worry about the meaning of Buffer$ at this point. This will be discussed later during the window programming.
The pop-up menu appears whenever the user presses Ctrl+mouse button (
Mb=17) and the mouse moves across the Omikron Basic output window. Then the selected item is displayed in the window. Of course, in practice one would call a routine, which then carries out the actual function.

Note: The sample program uses an Omikron output window because we have not explained yet how to use EasyGem to create and manage windows. Once you have mastered the EasyGem window programming, you should not use the Omnikron output windows any longer.


2.11 Link with Mac OS Toolbox

Although almost everything needed for normal programs can be programmed with the Menu Library, you might want to apply the functions of the Mac OS Toolbox directly to the menus defined with the Menu Library . This is possible with the Omikron Basic command
MAC_OS. A detailed description of this command can be found in the Omikron Basic manual.
In order for the Mac OS to know to which menu the command refers, the passing of a so-called handle is usually required. The following function is available for this purpose:
FN M_Handle([Menu_Id,]Entry)
Returns the handle, under which the menu associated with the entry with the number Entry is managed by the Mac OS.
This function may be used for normal menus as well as for pop-up menus.


Introduction -turn page- Reference List Menu Library

Contents | Start



© 1998-2000 Berkhan-Software
www.berkhan.com | Home