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