Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                                    Menus


Most GEM applications use a menu bar to allow the user to navigate
through program options. In addition, newer versions of the AES now allow
popup menus and drop-down list boxes (a special form of a popup menu).
Menus are simply specially designed OBJECT trees activated using special
AES calls.

The Menu Bar

The menu bar is a special OBJECT which is usually registered in the
beginning stages of a GEM program which contains choices which the user
may select to trigger a special menu event (MN_SELECTED) to be sent to the
application's message loop. Normally, you will use a resource construction
set to create a menu but if you are designing an RCS or must create
a menu bar by hand, the format for the OBJECT structure of a GEM menu bar
is shown below:

                       ROOT (G_IBOX)


          BAR  (G_BOX)                DROPDOWNS (G_BOX)


         ACTIVE (G_BOX)           G_BOX     G_BOX      G_BOX


  G_TITLE   G_TITLE   G_TITLE   G_STRING   G_STRING   G_STRING
                                G_STRING   G_STRING   G_STRING
                                G_STRING   G_STRING   G_STRING
                                G_STRING   G_STRING   G_STRING
                                G_STRING   G_STRING   G_STRING
                                G_STRING   G_STRING   G_STRING

The ROOT object is a G_IBOX and should be set to the same width and
height of the screen. It has two children, the BAR object and the
DROPDOWNS object.

The BAR object is a G_BOX which should be the width of the screen and the
height of the system font plus two pixels for a border line. The DROPDOWNS
object is a G_IBOX and should be of a size large enough to encompass all
of the drop-down menu boxes.

The BAR object has one child, the ACTIVE object, it should be the width
of the screen and the height of the system font. It has as many G_TITLE
children as there are menu titles.

The DROPDOWNS object has the same number of G_BOX child objects as the
ACTIVE object has G_TITLE children. Each box must be high enough to
support the number of G_STRING menu items and wide enough to support the
longest item. Each G_BOX must be aligned so that it falls underneath its
corresponding G_TITLE. In addition, each G_STRING menu item should be the
same length as its parent G_BOX object.

Each G_STRING menu item should be preceded by two spaces. Each G_TITLE
should be preceded and followed by one space. The first G_BOX object
should appear under a G_TITLE object named 'Desk' and should contain eight
children. The first child G_STRING is application defined (it usually
leads to the 'About...' program credits), the second item should be
a disabled separator ('-----------') line. The next six items are dummy
objects used by the AES to display program and desk accessory titles.

Utilizing a Menu Bar

Menu bars can be displayed and their handling initiated by calling
menu_bar(). In addition, using this command, a menu bar may be turned off
or replaced with another menu bar at any time.

Individual menu items may be altered with three AES calls. menu_icheck()
sets or removes a checkmark from in front of menu items. menu_ienable()
enables or disables a menu item. menu_itext() alters the text of a menu
item. After receiving a message indicating that a menu item has been
clicked, perform the action appropriate to the menu item and then call
menu_tnormal() to return the menu title text to normal video.

Hierarchical Menus

AES versions 3.3 and above support hierarchical submenus. When a submenu
is attached to a regular menu item, a right arrow is appended to the end
of the menu item text and a submenu is displayed whenever the mouse is
positioned over the menu item. The user may select submenu items which
cause an extended version of the MN_SELECTED message to be delivered
(containing the menu object tree).

Up to 64 submenu attachments may be in effect at any time per process.
Attaching a single submenu to more than one menu item counts as only one
attachment.

Submenus should be G_BOX objects with as many G_STRING (or other) child
objects as necessary. One or several submenus may be contained in a single
OBJECT tree. If the submenu's scroll flag is set, scroll arrows will
appear and the menu will be scrollable if it contains more items than the
currently set system scroll value. Submenus containing user-defined
objects should not have their scroll flag set.

Submenus are attached and removed with the menu_attach() call. A serious
bug exists in AES versions lower than 4.0 which causes menu_attach() to
crash the system if you use it to remove or inquire the state of an
existing submenu. This means that submenus may only be removed in AES
versions 4.0 and above. Submenus may be nested to up to four levels
though only one level is recommended.

Submenus may not be attached to menu items in the left-most 'Desk' menu.
Individual submenu items may be aligned with the parent object by using
menu_istart().

Popup Menus

AES versions 3.3 and above support popup menus. Popup menus share the
same OBJECT structure as hierarchical menus but are never attached to
a parent menu item. They may be displayed anywhere on the screen and are
often called in response to selecting a special dialog item
(see Chapter 11: GEM User Interface Guidelines). Popup menus are displayed
with the AES call menu_popup().

Menu Settings

The AES call menu_settings() may be used to adjust certain global
defaults regarding the appearance and timing delays of submenus and popup
menus. Because this call affects all system applications it should only be
utilized by a system configuration utility and not by individual
applications.

Drop-Down List Boxes

AES versions 4.0 and later support a special type of popup menu called
a drop-down list box. Setting the menu scroll flag to a value of -1 will
cause a popup menu to be displayed as a drop-down list instead.

A drop-down list reveals up to eight items from a multiple item list to
the user. A slider bar is displayed next to the list and is automatically
handled during the menu_popup() call. Several considerations must be taken
when using a drop-down list box:

Drop-down lists may only contain G_STRING objects.
If you want to force the AES to always draw scroll bars for the list
box, the OBJECT tree must contain at least eight G_STRING objects. If less
than that number of items exist, pad the remaining items with blanks and
set the object's DISABLED flag.

As long as the OBJECT tree has at least eight G_STRING objects, it
should not be padded with any additional objects since the size of the
slider is based on the number of objects.

The Menu Buffer

A special memory area is allocated by the AES so that it may reserve the
screen area underneath displayed menus. A pointer to this memory and its
length may be obtained by calling wind_get( WF_SCREEN, ... ). Menu buffer
memory may be used as a temporary holding arena for applications as long
as the following rules are maintained:

The application must not use a menu bar or it must be locked with
wind_update( BEG_UPDATE ).

Access to the menu buffer in a multitasking  is not controlled so
information stored by one application may be overwritten by another. It is
therefore recommended that the menu buffer should not be used under
MultiTOS.