All DatabasesMacTech Vol 03-1987
Hierarchical
Volume Number: 3
Issue Number: 8
Column Tag: Macintosh II
Hierarchical Menus
By Steven Sheets, Hoffman Estates, IL
MenuFun: Macintosh // Menu Manager
Like most of the toolbox managers, the Menu Manager of the Macintosh // has
undergone several enhancements and improvements. The Apple Menu is automatically
multicolored (like the Apple logo) on any color monitor, while every portion of the
menu bar and menus can be displayed in any RGB color by the program. Menus can now
include Hierarchical Menus. These Hierarchical menus (sometimes called Cascading
Menus or Submenus, or Nested menus ) can have menus within menus within menus,
up to 5 levels of depth. This article will show you how to include Hierarchical and
Color Menus in your own program.
The Menu Manager programmers have implemented the new features in a
exceptionally intelligent way. Of course the new Menu Manager is backwardly
compatible so that all the old programs will run their menus correctly, however the
new features can be added to a program that will run on either the old or new Manager.
Color can added without any new Tool Box calls (though there are a few new ones for
Mac // only programs). By adding certain resources, which the new Menu Manager
looks for and uses, the Menus will be displayed in color. Of course these resources are
ignored by the old Menu Manager. Thus Color Menus will be automatically used when
the program is running on a Mac //, and will not be used when it runs on the Mac Plus
or SE. The use of Hierarchical Menus are even more universal. Not only do they
function on the Mac //, but Hierarchical Menus have been implement into the latest
System/Finder (ie. they run on the Mac Plus and/or SE). Programs using
Hierarchical menus can be written without having to worry about what machine the
program will run on.
Documenting Programs
The new system file does have an impact on documenting programs however. The
capture menu script used to restore the ability to capture pulled down menus with
cmd-shift-3 only partially works with the new system. The figures in this article
were captured using it, but only after cleaning them up. The little arrow character is
not correctly displayed when the menu capture resource is installed, and in fact, the
menu manager pretty much gets clobbered so don’t try to use it except on a floppy
system dedicated to that purpose. Another interesting change is that cmd-shift-3,
which captures the screen in a paint document, only works in black and white 2-bit
mode. If you try to capture a color display, it beeps!
[This is a good place for the Editor to begin his editorial Apple bashing about how
none of Apple’s programs (paint, draw, write, project and terminal) have ever been
upgraded for new system features. The ‘ole Do as I say, not as I do syndrome. Since
Apple has announced upgrades of these products, it will be interesting next month to
see if they work any differently. In any case, the very useful menu capture facility,
removed with the 128K ROMS, is nearly dead and buried now, and that is a shame,
since it was very useful for this article, even if it didn’t really work correctly. For
anyone wondering what to write about or develop, a new screen capture function that
handles both nested menus and color would be very nice. -Ed]
Fig. 1 Hierarchal Menus
RGB Color
First a quick review of Macintosh // RGB color is needed. Unlike the old
Quickdraw color where only 8 colors are available, the new Macintosh // Quickdraw
allows 16,777,216 colors. The new Color Quickdraw does this by using the new
record type RGBColor to define exactly what color is being used (to draw, erase, fill,
etc.). The format of RGBColor is:
TYPE
RGBColor = RECORD
red : INTEGER;
green : INTEGER;
blue : INTEGER;
END;
The three unsigned 16-Bit integer values in the RGBColor record defines the
intensity values for the 3 additive primary colors (Red, Green, Blue). Since values of
each primary colors are in the range 0 to 65535, hex notation is usually easier to
work with. For example the values ($FFFF,$0,$0) gives a solid red RGB color. White
is ($FFFF,$FFFF,$FFFF), Black is ($0,$0,$0), medium Gray is
($7FFF,$7FFF,$7FFF) and Yellow is ($FFFF,$FFFF,$0).
Remember that the display device (monitor, printer, etc.) that is being used
defines what actual color is displayed. When some drawing is done in a specific RGB
color, the output device tries to match the closest specific color it has to draw with.
Most devices (like the Apple Video Card/Monitor) can display any of the range of
16,777,216 colors, but can only display so many at a given time. For example the
Apple Video Card/Monitor, can either display 16 or 256 colors depending on how much
memory is on the card. So subtle differences in colors can sometimes be lost on
monitors, e specially if many colors are being displayed at the same time.
Color Menus
As stated, all parts of the menu bar and menus can be displayed in any RGB color.
These parts include each Menu (Title and Background color) and each Menu Item
(Title, Mark, Command Key and Background color). The information for what color to
draw each menu part is not stored in the MenuHandle nor the MenuList, but in a new
data structure, the Menu Color Information Table (or MCIT). The MCIT is created by
the InitMenu call of the Mac // Menu Manager, and is modified by subsequential Menu
Manager calls. The MCIT contains 1 or more Menu Color Entries. There are different
types of entries, but they all have the following format:
TYPE
MCInfoRec = RECORD
MenuID : INTEGER;
MenuItem : INTEGER;
RGB1 : RGBColor;
RGB2 : RGBColor;
RGB3 : RGBColor;
RGB4 : RGBColor;
Filler : INTEGER;
END;
The MCIT will always contain a special “End-of-table” entry (MenuID = -99).
The MCIT can also include 3 other types of entries; the Menu Bar Entry, the Menu Title
Entry and the Menu Item Entry. In all three entries, filler is a reserved integer used
by the Menu Manager (should not be used by the program).
In a Menu Bar Entry, MenuID and MenuItem equals 0. It contains the 4 RGB
Colors that are used to draw the default Menu Title color, default Menu Background
color (background of the pull down menu), default Menu Item color and default Menu
Bar color (RGB1-RGB4, in that order). There should be at most only 1 Menu Bar
Entry, though there does not have to be one. If there is not a Menu Bar Entry, the
default colors are Black on White (normal monochrome menu).
In a Menu Title Entry, MenuID is not equal to 0 and MenuItem is equal to 0. The
MenuID number will match the ID number of the Menu it is describing. RGB1 is the
Title Color; RGB2 is the Menu Bar Color; RGB3 is the default Menu Item color; RGB4 is
the default Menu Background color. There should be at most only 1 Menu Title Entry
per each Menu displayed in the MenuList, though there does not have to be one. If there
is no Menu Title Entry to match a Menu, the Menu uses the colors defined in the Menu
Bar Entry.
In a Menu Item Entry, MenuID and MenuItem do not equal 0. The MenuID and
MenuItem defines a specific Menu Item (with the Menu ID of MenuID and the Menu Item
number of MenuItem). RGB1 is the Mark color of that Menu, RGB2 is the Name color
(ie. text), RGB3 is the Command Key color and RGB4 is the Background color. There
should be at most only 1 Menu Item Entry per each Menu Item displayed in the
MenuList, though there does not have to be one. If there is no Menu Item Entry for a
specific Menu Item, the Menu Title Entry is used.
Thus the Menu Bar Entry defines the global default colors. These default colors
can be overridden for a specific menu by a Menu Title Entry. The Menu Title Entry
defines the default colors for a single Menu, unless overridden by the Menu Item Entry.
The Menu Item Entry defines the colors for a single Menu Item.
There are a few ways to alter the MCIT. The Mac // Menu Manager has modified
two of the older calls so that they work with the MCIT. When InitMenu is called,
InitMenu checks for a resource of type “mctb” and ID number 0. Resource of this type
contain 1 or more Menu Color Entries. InitMenu loads the entries the resource
contains into the MCIT (assuming the resource exists). That specific resource (type
“mctb” and ID number 0) is usually in the System file of the Macintosh // and usually
contains the Menu Bar Entry. For most Mac // System files, this resource contains
the color information for a Black on White menu. By altering this resource in the
System file, the colors of the menu can be changed for all programs. A modified
version of the resource can be added to any application so that the colors change for
that application only (because resources inside an application override the resource of
the same type and ID number that reside in the System file).
The other older Menu Manager call that works with the MCIT is the GetMenu call.
When GetMenu load a certain “MENU” resource, it also looks for the resource of type
“mctb” with the same ID number. GetMenu then loads the Entries, contained in the
resource, into the MCIT. Usually the resource holds the Menu Title Entry and Menu
Item Entries for that specific Menu.
The “mctb” resources is a variable size resource with the following format:
TYPE
Referenced by (55):