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
                                GEM  Menus


The Menu Bar

Each application in the system should initialize a menu bar as soon as
it is called. The menu bar consists of several titles which when
pointed to by the mouse cause a list of individual menu items to be
displayed.

The leftmost menu title (commonly referred to as the 'Desk' menu)
should be the application name∙This menu title used to be labeled "Desk"
or contain the fuji logo. Width the advent
of MultiTOS, however, placing the application
name here makes it possible for the user
to easily determine the application which
has the input focus.
. An example of the first menu
title/items are shown below:



The first item in the menu should be "PRGNAME...". PRGNAME should be
substituted with the name of the application. The lines below are
reserved for desk accessories and applications (when running under
MultiTOS)..

An application should call menu_register() (under MultiTOS) to change
its entry in the menu from the filename to the program title.

The second and third menu titles should be "File" and "Edit" as
appropriate (though the inclusion of both of these menus is highly
recommended). Application defined menus should be placed after these.
If a "Help" menu is available it should be the rightmost title.
A "Window" menu should be placed rightmost second only to "Help" if it
exists. An example title bar follows:



Menu entries should be grouped by function under appropriate titles
and subgrouped by placing separator bars between them (disabled
dashes).

Menu entries which end in an ellipsis should lead to a dialog box.
Those without ellipsis should carry out an action with no further user
interaction.

The File Menu

The "File" menu should consist of the following items (presented in
order):

   ∙ New
   ∙ Open...
   ∙ Recall (optional - has cascading menu attached with most-recently
     used file list)
   ∙ Save
   ∙ Save as...
   ∙ Save all (optional)
   ∙ Any other document closing commands as required
   Separator
   ∙ Import (if applicable)
   ∙ Export (if applicable)
   ∙ Any other file operations as required ∙∙This doesn't refer to operations such
as "Delete File" or "Rename File".
These commands should not be supported
in applications because they are available
from the Desktop running under MultiTOS or
from disk utility CPX's and accessories.

   Separator
   ∙ Page Setup... (if applicable)
   ∙ Print (if applicable)
   ∙ Any other printing commands as required
   Separator
   ∙ Quit

Following is an example "File" menu:



The Edit Menu

The next menu, "Edit", usually contains the following items:

   ∙ Undo (if supported)
   ∙ Redo (if supported ∙∙∙"Redo" is used when multiple levels
of "Undo" are to be provided.
)
   Separator
   ∙ Cut
   ∙ Copy
   ∙ Paste
   ∙ Delete
   Separator
   ∙ Select All (optional)
   Separator
   ∙ Find... (optional)
   ∙ Replace... (optional)
   ∙ Find Next (optional)
   Separator
   ∙ Any other editing/searching commands.

An example "Edit" menu follows:



Dual-State Menu Items

Menu selections can be designed to represent toggles. There are two
methods of accomplishing this as follows:

   ∙ Apply a checkmark to the item to indicate an enabled state.

   ∙ Alter the text. For example, when "Hide Toolbar" is clicked, change
     the text to "Show Toolbar".

In addition, some menu item groups may provide a choice between more
than two options.



Again, checkmarks can be used to indicate the selection.

Here are some other general pointers about using menus:

   ∙ Menu items such as "Preferences..." or "Save Preferences" belong in
     the "Options" menu.

   ∙ Menu items for text styles (like bold, italic) can be made G_USERDEF
     objects and made to reflect their actual state.

   ∙ If you add a "Window" menu, items such as "New Window" which opens
     a new window for the current document, "Arrange All", "Tile All",
     "Cascade All", which positions windows can optionally be included.
     Followed by a separator, a generic item "Window" can be attached to
     a cascading menu which contains an updated list of all document windows
     so that the user can use the menu bar to 'top' a window.

   ∙ If you add a "Help" menu, different options can provide different
   ∙ levels of help such as "Contents" or "Index". Don't list help items for
     each possible dialog box or mode, instead provide context sensitive
     help that is activated through a "Help" button or by pressing the HELP
     key.

Popup Menus

Popup menus are menus which can appear anywhere on screen at the
request of the user. A common use of popup menus is for
object-specific options which are called upon when an object is
right-clicked on with the mouse.

Popup menus can also be placed in dialog boxes as shown below. Dialog
objects which lead to popup menus should be TOUCHEXIT and SHADOWED. If
text describing the popup appears at the left of the button, it should
be inverted when the popup is displayed and until it is closed.

When a popup menu contains a list of exclusive options, the option
currently selected should be properly identified to the menu_popup()
command so that it is aligned with the object in addition to having
a checkmark. Popups with no selected option should always start at the
first selection.

Popup menus may contain objects other than text (like fill styles or
bitmaps) but will be unable to scroll.

Drop-Down List Boxes

Drop-down list boxes are handled in the same manner as popup menus
with the following exceptions:

An 'equivalence' character (ASCII 240) in a BOXCHAR object should be
displayed immediately to the right of the box leading to the drop-down
list and should also be TOUCHEXIT and SHADOWED. A click on this object
is the same as clicking on the main object.

No checkmark should be displayed next to the current selection.
The TOUCHEXIT box leading to a drop-down list may be editable, if
appropriate, to allow the user to add items to those currently in the
list.

The following illustrations show examples of both a 'closed' (prior to
being selected) and 'open' (during selection) drop-down list:



Hierarchical Menus

Hierarchical menus (or sub-menus) are menus attached to either a main
menu item or a popup menu item. These menus can be nested several
levels deep but it is recommended that this feature not be used because
your menu bar, in general, should never be this complex. An example of
a hierarchical menu follows: