Section 5 Addendum

Menu Library Enhancements


5.1 Introduction

This section describes the additional features of the Menu Library.  All
enhancements are backwards compatible with previous versions of the AES, so
existing applications will continue to work.  The new features will work on
all machines with an AES version number of 3.3 and up.

The enhancements to the Menu Library are:

o   Hierarchical menus are now supported.
o   Pop-Up Menus are now supported.
o   Scrolling menus are supported for pop-up menus and submenus.
    Scrolling for the first level menus of a menu bar are not supported.


Hierarchical Menus

Hierarchical menus allow a menu item to be the title of a submenu.  Menu
items with a right arrow signify that a submenu is attached.  Hierarchical
menu items must be of the type G_STRING.  As a rule, the Desk Menu of a menu
bar is not allowed to have submenus.

Two delay values are used to prevent the rapid appearance and disappearance
of submenus:

o   Submenu Display Delay

    This delay is used to prevent the rapid flashing of submenus as the mouse
    pointer is dragged thru a menu item with an attached submenu.  The mouse
    pointer must remain within the menu item for the delay period before the
    submenu is displayed.  The default Submenu Display Delay is 1/5 of a
    second.  menu_settings can be used to inquire the current delay value,
    or to set a new delay.

o   Submenu Drag Delay
    
    This delay is used to prevent the disappearance of the submenu as the
    mouse pointer is dragged toward the submenu from a menu item.  The default
    Submenu Drag Delay is 10 seconds.  menu_settings can be used to inquire
    the current delay value, or to set a new delay.

There are several actions that will cancel the Submenu Drag Delay prematurely:

1)  If the mouse pointer is dragged away from the direction of the submenu,
    the submenu will disappear.

2)  If the mouse pointer remains in the same position after the drag has
    begun, the submenu will also disappear.

3)  If the user clicks on the left mouse button before the mouse pointer has
    entered the submenu, the system will return to the application the menu
    item that started the drag.

4)  If the mouse pointer is dragged vertically into another menu item, the
    submenu will disappear.

As a rule, only one level of hierarchical menus should be used.  The actual
number of recursions possible is currently set to 4.


Pop-Up Menus

Pop-up menus are menus that are not in the menu bar.  They can be placed
anywhere on the screen and once displayed, act like any other menu.


Scrolling Menus

When the number of menu items exceeds the menu scroll height, a scroll
indicator appears at the bottom of the menu.  The scroll indicators are
displayed as UP or DOWN ARROWS.  Clicking  on the bottom arrow will scroll
the menu items.  When the last item is shown, the DOWN ARROW indicator
disappears.  Note that as soon as the menu started scrolling, the UP ARROW
indicator appeared at the top of the menu.  This is to show that there are
now menu items in that direction.  The default menu scroll height is 16.
menu_settings can be used to inquire the current menu scroll height, or to
set a new menu scroll height.

When the user clicks and holds down the left mouse button, there is a 1/4 of
a second delay after one menu item has scrolled.  After the delay, scrolling
continues uninterrupted.  This delay is used to prevent rapid scrolling for
those just clicking on the scroll indicators.  menu_settings can be used to
inquire the current delay, or to set a new delay.

Another delay value is used to slow down the scrolling speed.  This prevents
the menu items from scrolling by too fast.  menu_settings can be used to
inquire the current delay, or to set a new delay.

Pop-up menus and submenus might consist of objects other than G_STRINGS.
Such a menu might consist of user-defined objects that display the system's
fill patterns.  The system cannot scroll non-G_STRING object types.  Scrolling
non-G_STRING object types will crash the system.  Pop-up menus and submenus
containing non-G_STRING object types should have its scroll_flag field set to
FALSE.

The first-level menus of a menu bar are set to be non-scrollable.  This is
due to the parent-child relationships between the menu titles, menus and
menu items.  Therefore, scrolling is applicable only to pop-up menus and
submenus.


5.2	Using the Extended Menu Library

The existing Menu Library functions are still applicable to pop-up menus
and submenus.  The Menu Library will continue to have the following
responsibilities:

o   displaying the appropriate menu bar for each active application
o   enabling and disabling menu items
o   displaying check marks in menus
o   returning a highlighted menu title to its normal state
o   displaying context-sensitive menu text
o   displaying a desk accessory's name on the Desk Menu

To use pop-up menus and submenus in one's application:

Create an object tree consisting of a G_BOX and as many G_STRINGS within the
G_BOX as required.  The G_BOX is the menu and the G_STRINGS are the menu
items.  An object tree is not limited to just one menu and can contain one,
two or more menus.  If a menu item is expected to have a submenu attachment,
the G_STRING must be padded with blanks to the width of the menu.  

The object tree does not need to be created with the Resource Construction
Set.  It can be created  during runtime by the application.  However, the
programmer is responsible for this procedure.

Attaching a submenu to a menu item is done by calling menu_attach.  A submenu
is associated to a menu item by placing a right arrow two characters in from
the right edge.  Any characters at that location will be overwritten.

The high-byte of the object's type field is used to store an
internal Menu ID.  The values between 128 and 192 are used by the new
menu sytem.

In addition, Bit 11 of the object's ObFlag field will be set.  Bit 11 is
defined as:  '#define SUBMENU  0x800'.  Applications using the Extended
Object Type AND SUBMENUS should first check the object's ObFlag field
to see if the value in the Extended Object Type is a submenu attachment.

Each process can have up to 64 unique submenu attachments. Attaching the
same submenu to multiple menu items counts as one attachment.

In addition to attaching a submenu, menu_attach can be used to change or
remove a submenu. menu_attach can also be used to find out what submenu,
if any, is attached to a menu item. menu_istart can be used to set and get
the starting menu item of a submenu.

menu_settings can be used to set the menu delay values and to set the height
at which pop-up menus and submenus will start to scroll.


5.2.1	Using a Menu Bar

Supplement to 5.2  Using the Menu Library 

When the user chooses an item, the Screen Manager writes a message to the
pipe.  Control then returns to the application, which must read the pipe.

The pipe message contains the following:

o   a code indicating that it is a menu message ( MN_SELECTED )
o   the object index of the menu title selected
o   the object index of the menu item chosen
o   the object tree of the menu item chosen ( NEW )
o   the object index of the parent of the menu item ( NEW )

( If the user does not choose an item, or if the user selects a disabled
menu item,  the Screen Manager does not write a message to the pipe. )

After processing the chosen item, the application makes a Menu Library call
to dehighlight the menu title and waits for the next message to come through
the message pipe.


5.3-b	Extended Menu Library Routines

The additions to the Menu Library routines are:

o   menu_popup:    Displays a menu anywhere on the screen.  Clipping is
                   performed for a standard menu.  Menus with user-defined
                   objects will have to perform their own clipping.

o   menu_attach:   Lets an application attach, change, remove or inquire
                   about a submenu associated with a menu item.

o   menu_istart:   Lets an application set and inquire the starting menu
                   item of a pop-up menu or submenu

o   menu_settings: Lets an application set and inquire the delay and height
                   parameters of the submenus.


menu_popup and menu_attach use a new structure for passing and receiving
submenu data.  The MENU structure is defined as follows:

   typedef struct _menu
   {
      OBJECT *mn_tree;   - the object tree of the menu 
      WORD    mn_menu;   - the parent object of the menu items
      WORD    mn_item;   - the starting menu item
      WORD    mn_scroll; - the scroll field status of the menu
                           0  - The menu will not scroll
                           !0 - The menu will scroll if the number of menu
                                items exceed the menu scroll height. The 
				non-zero value is the object at which 
				scrolling will begin.  This will allow one
				to have a menu in which the scrollable region
				is only a part of the whole menu.  The value
				must be a menu item in the menu.
				
                                menu_settings can be used to change the menu
                                scroll height. 

                         NOTE: If the scroll field status is !0, the menu
                               items must consist entirely of G_STRINGS.
      WORD   mn_keystate; - The CTRL, ALT, SHIFT Key state at the time the
			    mouse button was pressed.
   }MENU;

menu_settings uses a new structure for setting and inquiring the submenu
delay values and the menu scroll height.  The delay values are measured in
milliseconds and the height is based upon the number of menu items.

    typedef struct _mn_set
    {
       LONG  Display; - the submenu display delay
       LONG  Drag;    - the submenu drag delay
       LONG  Delay;   - the single-click scroll delay
       LONG  Speed;   - the continuous scroll delay
       WORD  Height;  - the menu scroll height
    }MN_SET;

o  Submenu Display Delay:

   The delay is used to prevent the rapid flashing of submenus as the mouse
   pointer is dragged thru a menu item with an attach submenu.  The default
   value is 200 milliseconds ( 1/5th of a second ).

o  Submenu Drag Delay:

   The delay is used to prevent the disappearance of the submenu as the mouse
   pointer is dragged toward the submenu from a menu item.  The default value
   is 10000 milliseconds ( 10 seconds ).

o  Single-Click Scroll Delay:
  
   This is the delay period after one menu item has initiallly scrolled.
   After the delay, scrolling continues at the rate specified by the
   Continuous Scroll Delay.  The delay is used to prevent rapid scrolling for
   those just clicking on the scroll indicators.  The default value is
   250 milliseconds ( 1/4th of a second ).

o  Continuous Scroll Delay:

   This is the delay period after each menu item has scrolled.  The delay is
   used to slow down the scrolling speed.  The default value is 0 milliseconds.

o  Menu Scroll Height:

   This value is the height at which a pop-up menu or a submenu will start to
   scroll if its scroll field is TRUE.  The default value is 16 menu items.

The following sections describe these routines.


-------------------------------------------------------------------------------

5.3.7	MENU_POPUP

Purpose:

Allows an application to display a popup menu anywhere on the screen.  The
popup menu may also have submenus.  If the number of menu items exceed the
menu scroll height, the menu may also be set to scroll.  menu_settings can
be used to set the height at which all menus will start to scroll.

Parameters:

     control(0)  =  36
     control(1)  =  2
     control(2)  =  1
     control(3)  =  2
     control(4)  =  0

     int_in(0)   =  me_xpos
     int_in(1)   =  me_ypos

     int_out(0)  =  me_return

     addr_in(0)  =  me_menu
     addr_in(1)  =  me_mdata

o    me_xpos - the left edge of where the starting menu item will be displayed

o    me_ypos - the top edge of where the starting menu item will be displayed

o    me_return - a coded return message
	
                 0 - FAILURE: The data returned by me_mdata is invalid
                 1 - SUCCESS: The data returned by me_data is valid

     FAILURE is returned if the user did not click on an enabled menu item

o    me_menu  -	pointer to the pop-up MENU structure.  The structure must be
                initialized with the object tree of the pop-up menu, the menu
                object, the starting menu item and the scroll field status.

o    me_mdata -	pointer to the data MENU structure.  If menu_popup returns
                TRUE,  me_mdata will contain information about the submenu
                that the user selected.  This includes the object tree of the
                submenu, the menu object, the menu item selected and the
                scroll field status for this submenu.

	------------------------------------------------

        Sample call to C language binding:

        me_return = menu_popup( MENU *me_menu, word me_xpos, word me_ypos,
                                MENU *me_mdata);



-------------------------------------------------------------------------------

5.3.8	MENU_ATTACH

Purpose:

Allows an application to attach, change, remove or inquire about a submenu
associated with a menu item.

Parameters:

     control(0)  =  37
     control(1)  =  2
     control(2)  =  1
     control(3)  =  2
     control(4)  =  0

     int_in(0)   =  me_flag	
     int_in(1)   =  me_item

     int_out(0)  =  me_return

     addr_in(0)  =  me_tree
     addr_in(1)  =  me_mdata

o  me_flag - the action to be performed by menu_attach.
		
   The options for me_flag are:

   0  Inquire data about the submenu that is associated with the menu item.
      The data concerning the submenu is returned in me_mdata.

   1  Attach or change a submenu associated with a menu item.  me_mdata must
      be initialized by the application.  The data must consist of the object
      tree of the submenu, the menu object, the starting menu item and the
      scroll field status.  Attaching a NULLPTR structure will remove the
      submenu associated with the menu item.  There can be a maximum of 64
      associations per process.  Bit 11 of the object's ObFlag will be
      set if a submenu is actually attached.

   2  Remove a submenu associated with a menu item.  me_mdata should be set
      to NULLPTR. Bit 11 of the object's ObFlag will be cleared.
	
o  me_item - the menu item that the submenu will be attached to

o  me_return - a coded return message
	
   0 - FAILURE: the submenu was not attached for whatever reasons
   1 - SUCCESS: the submenu was attached, changed or removed successfully

o  me_tree - the object tree of the menu item that will have a submenu
             attach to

o  me_mdata - pointer to the MENU structure. The contents of me_mdata are
              dependant upon the value of me_flag:

   0  Upon return from menu_attach, me_mdata will contain the MENU data
      regarding the submenu associated with the menu item.

   1  me_mdata must be initialized with the new submenu MENU data.
      The submenu will be attached to the menu item - me_item.

   2  me_mdata should be set to NULLPTR.  The submenu associated with the
      menu item will be removed.

   ------------------------------------------------

   Sample call to C language binding:

   me_return = menu_attach( word me_flag, object *me_tree, word me_item,
                            MENU *me_mdata );


-------------------------------------------------------------------------------


5.3.9	MENU_ISTART

Purpose:

Allows an application to set or inquire the starting menu item of a submenu
that is associated with a menu item.  The submenu is shifted vertically so
that the starting menu item is aligned with the menu item that is associated
with this submenu.  

Parameters:

     control(0)  =  38
     control(1)  =  3
     control(2)  =  1
     control(3)  =  1
     control(4)  =  0

     int_in(0)   =  me_flag
     int_in(1)   =  me_imenu
     int_in(2)   =  me_item

     int_out(0)  =  me_return

     addr_in(0)  =  me_tree

o    me_flag - the action to be performed by menu_istart 

     0  Inquire the starting menu item for the submenu

     1  Set the starting menu item for the submenu to be me_item

o    me_imenu - the menu object of the submenu that is either to be set
                or inquired

o    me_item - the starting menu item that is either to be set or inquired

o    me_return - a coded return message
	
     0 - FAILURE: the submenu is not associated with a menu item.  The
                  submenu must be attached via menu_attach before this
                  call can be made. 

     >0 - SUCCESS: the starting menu item is currently set to this value.

o    me_tree - the object tree of the menu item that we are setting or
               inquiring about

     ------------------------------------------------

     Sample call to C language binding:

     me_return = menu_istart( word me_flag, object *me_tree, word me_imenu,
                              word me_item );


-------------------------------------------------------------------------------


5.3.10	MENU_SETTINGS

Purpose:

Allows an application to set or inquire the submenu delay values and the
menu scroll height value. 

Parameters:

     control(0)   =  39
     control(1)   =  1
     control(2)   =  1
     control(3)   =  1
     control(4)   =  0

     int_in(0)    =  me_flag

     int_out(0)   =  me_return

     addr_in(0)   =  me_values


o    me_flag - the action to be taken by menu_settings

     0  Inquire the current delay and menu scroll height values.
     1  Set the delay and menu scroll height values

o    me_return - always returns 1 ( one )
	
o    me_values - pointer to the MN_SET structure.  me_values is dependant
                 upon the value of me_flag:

     0   Upon the return of menu_settings, me_values will contain the
         current delay and menu scroll height values.

     1   me_values must be initialized.  The delay and menu scroll height
         values will be set to those values found in me_values.  A value
         set to NIL will be ignored.

     ------------------------------------------------

     Sample call to C language binding:

     me_return = menu_settings( word me_flag, MN_SET *me_values );




AES Supplemental Documentation
---------------------------------------------------------------------------
The following section contains documentation supplemental to the existing
AES manual, and clarifications of existing documentation related to
hierarchical submenus and the menubar.


Supplement to: 4.2.5.2 MN_SELECTED

GEM AES uses this message to notify an application that a user has selected
a menu item.

o   word 0   = 10
o   word 3   = the object index of the menu title selected
o   word 4   = the object index of the menu item selected
o   word 5,6 = the object tree of the menu item selected
o   word 7   = the parent object of the menu item selected




5.4.1	Pop-Up Menus

o   The button on a dialog box that brings up a pop-up menu should be shadowed.

o   It would be nice if the pop-up menu was shadowed also.

o   While the pop-up menu is displayed, if it has a title, the title should
    be inverted.

o   The pop-up menu should be aligned on a byte boundary.  This speeds up
    the drawing of the menu considerably.

o   The pop-up menu will be shifted vertically in order to line up the start
    object with the given coordinates.

o   If the menu exceeds the top of the screen, it will be shifted down.

o   No horizontal adjustments will be done to the menu.




5.4.2	Submenus

o   Menu items expecting a submenu attachment must be of type G_STRING.

o   Menu items should be padded with blanks to the width of the menu.

o   Menu items expecting a submenu attachment should not have any keyboard
    short-cut characters.

o   Submenus will automatically be displayed on a byte boundary.

o   The menu will be shifted vertically to align the start object with the
    menu item.  In addition, the menu will be shifted to remain entirely on
    the screen in the vertical plane.

o   The submenu will be displayed at the right edge of the menu item.  If the
    menu extends off the edge of the screen, the menu will be displayed to
    the left of the menu item.  If it exceeds the left edge of the screen,
    the menu will be shifted right a character at a time, until it fits.

o   There can be a maximum of 64 submenu attachments per process.

o   A menu item with an attached submenu uses the high-byte of its object
    type field.  Values 128 thru 192 are used by the submenu menu system.

o   A menu item with an attached submenu will have Bit 11 of its 
    object flag field SET.  

    The bit is defined as:   #define SUBMENU 0x800

o   Applications using the Extended Object Type should check the
    object's ObFlag field to see if Bit 11 is SET.  If the bit is SET,
    the menu item has a submenu attached.
   
o   A submenu should not be attached to itself.

o   Attaching a submenu	to different menu items counts as one attachment.
    There will only be one scroll flag and one start object.

o   As a user interface guideline, there should only be one level of
    hierarchical menus.  The system currently allows up to four levels
    of recursion.

o   menu_istart works only on submenus attached with menu_attach.  

o   Menu items with attached submenus cannot have keyboard shortcuts.


5.4.3	Scrolling Menus

o   In order to scroll properly, all menu items must be G_STRINGS.  Menus
    that contain objects other than G_STRINGS should set the scroll flag
    to 0.

o   The first-level menus of a menu bar are not scrollable.

o   Pop-up menus and submenus with greater than sixteen items can be
    scrolled if their scroll flag is set.  The number of items to scroll at
    can be adjusted with menu_settings.

o   If the pop-up menu or submenu is designed to be a toolbox,
    (ie: fill patterns ), set the scroll flag to FALSE.

o   Setting the scroll flag to one of the menu items will initiate
    scrolling from that menu item if the number of items exceeds the
    menu height limit.

o   One should NOT set the scroll object to the last menu item of a menu.

o   Setting the scroll object to a value less than the first menu item
    defaults to the first menu item.

o   Setting the scroll object to a value greater than or equal to
    the last menu item defaults to the first menu item.


HISTORY

January 19, 1993   Updated for ObFlag usage

