Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

Menu Library
[AES Function Reference]

create or modify drop-down menu More...

Functions

short mt_menu_attach (short me_flag, OBJECT *me_tree, short me_item, MENU *me_mdata, short *global)
short mt_menu_bar (OBJECT *me_tree, short me_mode, short *global)
short mt_menu_click (short click, short setit, short *global)
short mt_menu_icheck (OBJECT *me_tree, short me_item, short me_check, short *global)
short mt_menu_ienable (OBJECT *me_tree, short me_item, short me_enable, short *global)
short mt_menu_istart (short me_flag, OBJECT *me_tree, short me_imenu, short me_item, short *global)
short mt_menu_popup (MENU *me_menu, short me_xpos, short me_ypos, MENU *me_mdata, short *global)
short mt_menu_register (short ap_id, char *me_text, short *global)
short mt_menu_settings (short me_flag, MN_SET *me_values, short *global)
short mt_menu_text (OBJECT *me_tree, short me_item, char *me_text, short *global)
short mt_menu_tnormal (OBJECT *me_tree, short me_item, short me_normal, short *global)
short mt_menu_unregister (short id, short *global)

Detailed Description

create or modify drop-down menu

The Menu Library assists in the handling of system menu bars and popup menus. In addition, individual control of menu items can also be handled through these functions.


Function Documentation

short mt_menu_attach short  me_flag,
OBJECT me_tree,
short  me_item,
MENU me_mdata,
short global_aes
 

allows an application to attach, change, or remove a sub-menu. It also allows the application to inquire information regarding a currently defined sub-menu.

Parameters:
me_flag indicates the action the application desires as follows:
  • ME_INQUIRE (0) Return information on a sub-menu attached to the menu item designated by me_tree and me_item in me_mdata.
  • ME_ATTACH (1) Attach or change a sub-menu. me_mdata should be initialized by the application. me_tree and me_item should be the OBJECT pointer and index to the menu which is to have the sub-menu attached. If me_mdata is NULL, any sub-menu attached will be removed.
  • ME_REMOVE (2) Remove a sub-menu. me_tree and me_item should be the OBJECT pointer and index to the menu item which a sub-menu was attached to. me_mdata should be NULL.
me_tree see above
me_item see above
me_mdata see above
global_aes global AES array
Returns:
0 if an error occurred and the sub-menu could not be attached or 1 if the operation was successful.
Since:
This function is only available from AES version 3.30 and above. In AES versions 4.0 and greater, mt_appl_getinfo() should be used to determine its exact functionality.
AES versions supporting mt_menu_attach() less than 4.1 contain a bug which causes the AES to crash when changing or removing a sub-menu attachment. At present, if you wish to attach a scrolling menu, the menu items must be G_STRING's. The ob_x and ob_y fields of the root menu object should always be set to 0 prior to making the mt_menu_attach() call. In addition, under AES 3.40, no more than one scrolling sub-menu should be contained in each tree.

If a menu bar having attachments is removed with mt_menu_bar( NULL, MENU_REMOVE ) those attachments are removed by the system and must be reattached with this call if the menu is redisplayed at a later time.

Several recommendations regarding sub-menus should be adhered to:

  1. Menu items which will have sub-menus attached to them should be padded with blanks to the end of the menu.
  2. Menu items which will have sub-menus attached to them should not have a keyboard equivalent.
  3. Sub-menus will display faster if a byte-boundary is specified.
  4. Sub-menus will be shifted vertically to align the start object with the main menu item which it is attached to.
  5. Sub-menus will always be adjusted to automatically fit on the screen.
  6. There can be a maximum of 64 sub-menu attachments per process (attaching a sub-menu to more than one menu item counts as only one attachment).
  7. Do not attach a sub-menu to itself.
  8. As a user-interface guideline, there should only be one level of sub-menus, though it is possible to have up to four levels currently.
  9. mt_menu_istart() works only on sub-menus attached with mt_menu_attach().

See also:
mt_menu_istart(), mt_menu_settings(), mt_menu_popup()

short mt_menu_bar OBJECT me_tree,
short  me_mode,
short global_aes
 

displays a specialized OBJECT tree on the screen as the application menu. It can also be used to determine the owner of the currently displayed menu bar in a multitasking AES.

Parameters:
me_tree is a pointer to an OBJECT tree which has been formatted for use as a system menu.
me_mode is a flag indicating the action to take as follows:
  • MENU_REMOVE (0) Erase the menu bar specified in me_tree.
  • MENU_INSTALL (1) Display the menu bar specified in me_tree.
  • MENU_INQUIRE (-1) Return the AES application identifier of the process which owns the currently displayed system menu. me_tree can be set to NULL. The AES version must be greater than 4.0 and mt_appl_getinfo() with AES_INQUIRE mode must indicate that this is feature is supported.
global_aes global AES array
Returns:
The return value depend on me_mode parameter as follow:
  • If me_mode is MENU_REMOVE or MENU_INSTALL, the return value indicates an error condition where >0 means no error and 0 means an error occurred.
  • if me_mode is MENU_INQUIRE, mt_menu_bar() returns the application identifier of the process which owns the currently displayed menu bar.
Since:
AES versions
See also:
mt_menu_ienable(), mt_menu_icheck()
The safest way to redraw an application's menu bar is to redraw it only if you are sure it is currently the active menu bar. In a non-multitasking AES, this is a certainty, however, in a multitasking AES you should first inquire the menu bar's owner within the scope of a mt_wind_update() call with BEG_UPDATE mode to prevent the system from swapping active menu bars while in the process of redrawing.

Note:
it seems that some AES support other values for me_mode. These values are MENU_GETMODE, MENU_SETMODE, MENU_UPDATE and MENU_INSTL. TO BE COMPLETED.

short mt_menu_click short  click,
short  setit,
short global_aes
 

Parameters:
click specifies if the AES shall manage menu as
  • 0 : Drop down menu
  • 1 : PullDown
setit is one of the following value:
  • 0 = Menu prompting query
  • 1 = Menu prompting set
global_aes global AES array
Returns:
adjusted menu prompting (0 = drop down, 1 = Pulldown)
Since:
PC/GEM3, mt_appl_getinfo() with parameter AES_PCGEM gives the availability of this function.
See also:

short mt_menu_icheck OBJECT me_tree,
short  me_item,
short  me_check,
short global_aes
 

adds/removes a checkmark in front of a menu item.

Parameters:
me_tree specifies the object tree of the current menu
me_item should be the object index of a menu item
me_check If me_check is UNCHECK (0), no checkmark will be displayed next to this item whereas if me_check is CHECK (1), a checkmark will be displayed.
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
All AES versions
See also:
mt_objc_change()

short mt_menu_ienable OBJECT me_tree,
short  me_item,
short  me_enable,
short global_aes
 

enables/disables menu items.

Parameters:
me_tree specifies the object tree of the menu to alter
me_item is the object index of the menu item to modify
me_enable should be set to DISABLE (0) to disable the item or ENABLE (1) to enable it.
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
All AES versions.
See also:
mt_objc_change()

short mt_menu_istart short  me_flag,
OBJECT me_tree,
short  me_imenu,
short  me_item,
short global_aes
 

shifts a sub-menu that is attached to a menu item to align vertically with the specified object in the sub-menu.

Parameters:
me_flag should be set to MIS_SETALIGN (1) to modify the alignment of a sub-menu and its parent menu item. If me_flag is set to MIS_GETALIGN (0), no modifications will be made, however the sub-menu item index which is currently aligned with its parent menu item is returned.
me_tree points to the object tree of the menu to alter
me_imenu specifies the object within the submenu which will be aligned with menu item me_item
me_item see above
global_aes global AES array
Returns:
0 if an error occurred or the positive object index of the sub-menu item which is currently aligned with its parent menu item.
Since:
This function is only available with AES versions 3.30 and above.
See also:
mt_menu_attach()
Generally, a sub-menu is aligned so that the currently selected sub-menu item is aligned with its parent menu.

short mt_menu_popup MENU me_menu,
short  me_xpos,
short  me_ypos,
MENU me_mdata,
short global_aes
 

displays a popup menu and returns the user's selection.

Parameters:
me_menu points to a MENU structure containing the popup menu
me_xpos x-coordinate of the upper-left corner where the starting object will be placed.
me_ypos y-coordinate of the upper-left corner where the starting object will be placed.
me_mdata If the function returns a value of 1, the MENU structure pointed to by me_mdata will be filled in with the ending state of the menu (including the object the user selected).
As of AES version 4.1, if me_menu->mn_scroll is set to SCROLL_LISTBOX when this function is called, a drop-down list box will be displayed instead of a popup menu.
Dropdown list boxes will only display a scroll bar if at least eight entries exist. If you want to force the scroll bar to appear, pad the object with empty G_STRING objects with their OS_DISABLED flag set.
global_aes global AES array
Returns:
0 if an error occurred or 1 if successful.
Since:
This function is only available with AES versions 3.30 and above.
See also:
mt_menu_attach(), mt_menu_settings()

short mt_menu_register short  ap_id,
char *  me_text,
short global_aes
 

registers desk accessories in the 'Desk' menu and renames MultiTOS applications which appear there.

Parameters:
ap_id specifies the application identifier of the application to register
me_text points to a NULL-terminated string containing the title which is to appear in the 'Desk' menu for the accessory or application.
global_aes global AES array
Returns:
-1 if an error occurred or the menu identifier otherwise.
Since:
All AES versions.
See also:
Note:
Applications other than desk accessories should not call this function unless they are running under MultiTOS.

If ap_id is set to REG_NEWNAME (-1) then the process name given in me_text will be used as the new process name. The new process name should be exactly eight characters terminated with a NULL. Pad the string with space characters if necessary.

Desk accessories should store the return value as this is the value that will be included with future AC_OPEN messages to identify the accessory.
Applications running under MultiTOS may use this function to provide a more functional title for the 'Desk' menu than the program's filename.
Calling mt_menu_register() with a parameter of REG_NEWNAME is used to change the internal process name of the application returned by mt_appl_find() and mt_appl_search(). This is useful if you know another process will attempt to find your application as a specific process name and the user may have renamed your application filename (normally used as the process name).

short mt_menu_settings short  me_flag,
MN_SET me_values,
short global_aes
 

changes the global settings for popup and scrollable menus

Parameters:
me_flag is one of the following value:
  • MN_INQUIRE (0) : current settings are read into the MN_SET structure pointed to by me_values.
  • MN_CHANGE (1) : current settings are set from the MN_SET structure pointed to by me_values.
me_values see above
global_aes global AES array
Returns:
1
Since:
This function is only available with AES versions 3.30 and above.
The defaults set by mt_menu_settings() are global and not local to an application. You should therefore limit your use of this function to system applications like CPX's and so forth.

short mt_menu_text OBJECT me_tree,
short  me_item,
char *  me_text,
short global_aes
 

changes the text of a menu item.

Parameters:
me_tree specifies the object tree of the menu bar
me_item specifies the object index of the menu item to change
me_text points to a NULL-terminated character string containing the new text.
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
All AES versions.

short mt_menu_tnormal OBJECT me_tree,
short  me_item,
short  me_normal,
short global_aes
 

highlights/un-highlights a menu-title.

Parameters:
me_tree specifies the object tree of the menu
me_item specifies the object index of the title to change
me_normal should be set to HIGHLIGHT (0) to display the title in reverse (highlighted) or UNHIGHLIGHT (1) to display it normally
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
AES versions
This call is usually called by an application after a MN_SELECTED message is received and processed to return the menu title to normal.

short mt_menu_unregister short  id,
short global_aes
 

remove accessory name from menu

Parameters:
id application ID of the accessory
global_aes global AES array
Returns:
at present unknown
This function allows an Accessorie to remove its name from the menu line.

Since:
PC/GEM2 and MagiC 2.0
See also:
mt_menu_register()


Generated on Wed Nov 3 22:42:20 2004 for GEMLIB by  doxygen 1.3.9.1