create or modify drop-down menu More...

Macros
#define	menu_attach(a, b, c, d) mt_menu_attach(a,b,c,d,aes_global)

#define	menu_bar(a, b) mt_menu_bar(a,b,aes_global)

#define	menu_click(a, b) mt_menu_click(a,b,aes_global)

#define	menu_icheck(a, b, c) mt_menu_icheck(a,b,c,aes_global)

#define	menu_ienable(a, b, c) mt_menu_ienable(a,b,c,aes_global)

#define	menu_istart(a, b, c, d) mt_menu_istart(a,b,c,d,aes_global)

#define	menu_popup(a, b, c, d) mt_menu_popup(a,b,c,d,aes_global)

#define	menu_register(a, b) mt_menu_register(a,b,aes_global)

#define	menu_settings(a, b) mt_menu_settings(a,b,aes_global)

#define	menu_text(a, b, c) mt_menu_text(a,b,c,aes_global)

#define	menu_tnormal(a, b, c) mt_menu_tnormal(a,b,c,aes_global)

#define	menu_unregister(a) mt_menu_unregister(a,aes_global)

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.

Macro Definition Documentation

#define menu_attach	(	a,
		b,
		c,
		d
	)	mt_menu_attach(a,b,c,d,aes_global)

single-thread version of mt_menu_attach()

#define menu_bar	(	a,
		b
	)	mt_menu_bar(a,b,aes_global)

single-thread version of mt_menu_bar()

#define menu_click	(	a,
		b
	)	mt_menu_click(a,b,aes_global)

single-thread version of mt_menu_click()

#define menu_icheck	(	a,
		b,
		c
	)	mt_menu_icheck(a,b,c,aes_global)

single-thread version of mt_menu_icheck()

#define menu_ienable	(	a,
		b,
		c
	)	mt_menu_ienable(a,b,c,aes_global)

single-thread version of mt_menu_ienable()

#define menu_istart	(	a,
		b,
		c,
		d
	)	mt_menu_istart(a,b,c,d,aes_global)

single-thread version of mt_menu_istart()

#define menu_popup	(	a,
		b,
		c,
		d
	)	mt_menu_popup(a,b,c,d,aes_global)

single-thread version of mt_menu_popup()

#define menu_register	(	a,
		b
	)	mt_menu_register(a,b,aes_global)

single-thread version of mt_menu_register()

#define menu_settings	(	a,
		b
	)	mt_menu_settings(a,b,aes_global)

single-thread version of mt_menu_settings()

#define menu_text	(	a,
		b,
		c
	)	mt_menu_text(a,b,c,aes_global)

single-thread version of mt_menu_text()

#define menu_tnormal	(	a,
		b,
		c
	)	mt_menu_tnormal(a,b,c,aes_global)

single-thread version of mt_menu_tnormal()

#define menu_unregister ( a ) mt_menu_unregister(a,aes_global)

single-thread version of mt_menu_unregister()

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:

Menu items which will have sub-menus attached to them should be padded with blanks to the end of the menu.
Menu items which will have sub-menus attached to them should not have a keyboard equivalent.
Sub-menus will display faster if a byte-boundary is specified.
Sub-menus will be shifted vertically to align the start object with the main menu item which it is attached to.
Sub-menus will always be adjusted to automatically fit on the screen.
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).
Do not attach a sub-menu to itself.
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.
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.

Note: [PC GEM 3] : A special calling convention has been established for enabling and disabling menu titles. If the high bit of me_item is set, then it will be enabled/disabled and the result will be drawn on the screen. This only works for menu titles since they are guarenteed to be displayed on the screen.

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()

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation