Home AESAES MagiC libraryMagiC library Object libraryObject library

8.17 Menu library

This library makes functions available for drawing and manipulating menu bars. The following routines are available for this purpose:

• menu_attach Adds, alters or deletes a submenu
• menu_bar Processes the menu bar
• menu_click Processes pulldown menus
• menu_icheck Sets or clears check mark (tick) in menu options
• menu_ienable Enables or disables a menu entry
• menu_istart Aligns a submenu entry
• menu_popup Displays and processes a popup menu
• menu_register Enters desk accessory in 'Desk' menu
• menu_settings Sets or inquires popup/submenu parameters
• menu_text Alters the text of a menu item
• menu_tnormal Inverts menu title
• menu_unregister Removes accessory name from 'Desk' menu.

Note: As of AES version 4.0 (or MagiC 3) this library was revised intensely, and now also takes on the display and management of popup and submenus.

See also: Menus and menu bars   Style guidelines   XMEN_MGR

8.17.1 menu_attach

Name: »Menu attach« - Add, alter, delete or obtain information about a submenu.
 
Opcode: 37
 
Syntax: int16_t menu_attach ( int16_t mode, OBJECT *tree, int16_t item, MENU *mdata );
 
Description: The call menu_attach permits adding, deleting or altering a submenu. In addition one can obtain information about a submenu. The following apply:
 
Parameter Meaning
   
mode Desired action:
0 = Get information about a submenu and store it in mdata
1 = Add to, or alter, a submenu whose description is stored in mdata; if mdata has the value NULL, the submenu will be removed
2 = Direct removal of a submenu; mdata should be a NULL-pointer
tree Address of the menu object tree
item Index of the object with which the submenu is (or should become) connected, or from which the submenu should be removed or altered
mdata MENU structure of the submenu

Note: If possible, not more than one submenu level should be created for a menu entry, though up to four levels are supported. The number of submenus per menu is restricted to 64.
 
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.
 
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 front of the right edge. Any character at that location will be overwritten.
 
When detaching a submenu the right arrow will be overwritten with a blank.
 
The ob_x and ob_y fields of the root object should always be set to 0 before making a menu_attach call.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: This function is available only from AES version 3.30 onwards. In AES versions 4.0 and greater appl_getinfo (opcode 9) should be used to determine its exact functionality.
 
Group: Menu library
 
See also: Binding   menu_istart   menu_settings   menu_popup   XMEN_MGR
 

8.17.1.1 Bindings for menu_attach

C: int16_t menu_attach ( int16_t mode, OBJECT *tree, int16_t item, MENU *mdata );
 
Binding:
  
int16_t menu_attach (int16_t mode, OBJECT *tree, int16_t item,
                     MENU *mdata)
{
   int_in[0]  = mode;
   int_in[1]  = item;
   addr_in[0] = tree;
   addr_in[1] = mdata;

   return ( crys_if(37) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 37 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] mode
int_in+2 int_in[1] item
addr_in addr_in[0] tree
addr_in+4 addr_in[1] mdata
int_out int_out[0] Return value

8.17.2 menu_bar

Name: »Menu bar« - Display, delete or install a menu bar.
 
Opcode: 30
 
Syntax: int16_t menu_bar ( OBJECT *me_btree, int16_t me_bshow );
 
Description: The call menu_bar performs various operations, depending on the parameter me_bshow:
 
me_bshow Meaning
   
-3 Inquire low-WORD of an application's menu bar
-2 Inquire high-WORD of an application's menu bar
-1 Inquire owner (application) of the menu bar; as this can change continuously, the screen must be locked with wind_update to make a safe inquiry
0 Delete menu bar specified in me_btree
1 Draw menu bar specified in me_btree
3 Get the menu bar mode (N.AES)
4 Set the menu bar mode (N.AES, not implemented)
5 Update the system part of the menu bar (N.AES)
100 Install menu bar, without forcing a change-over of the top application

Definitions:
 
MENU_HIDE = 0
MENU_SHOW = 1
MENU_GETMODE = 3
MENU_SETMODE = 4
MENU_UPDATE = 5
MENU_INSTL = 100
 
Menu bar modes:
 
MENU_HIDDEN = 0x0001 Menu bar only visible when needed
MENU_PULLDOWN = 0x0002 Pulldown-Menus
MENU_SHADOWED = 0x0004 Menu bar with shadows
 
Note: The parameter me_btree is a pointer to the object tree of the corresponding menu. At termination of the program one must not forget to remove the menu bar again.
 
With menu_bar(-2/-3) one can inquire the tree address of an application's menu bar. menu_bar(-2) returns the high-WORD and menu_bar(-3) the low-WORD. Only available if the cookie 'MbAr' or 'AmAN' is present.
  
OBJECT *get_menu(int apid)
{
  unsigned int hi = menu_bar((OBJECT *)apid, -2);
  unsigned int lo = menu_bar((OBJECT *)apid, -3);
  OBJECT *tree = (OBJECT *)(((unsigned long)hi << 16) | lo);
  return tree;
}

The presence of the extended possibilities can be checked for with appl_getinfo (opcode 6).
 
Return value: An error has arisen only if the value 0 is returned. A value of -1 signals that there is no owner of the menu bar.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding   OBJECT
 

8.17.2.1 Bindings for menu_bar

C: int16_t menu_bar ( OBJECT *me_btree, int16_t me_bshow );
 
Binding:
  
int16_t menu_bar (OBJECT *me_btree, int16_t me_bshow)
{
   int_in[0]  = me_bshow;
   addr_in[0] = me_btree;

   return ( crys_if(30) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 30 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_bshow
addr_in addr_in[0] me_btree
int_out int_out[0] Return value

8.17.3 menu_click

Name: »Menu click« - »Menu click« - Set or inquire type of menu control.
 
Opcode: 37
 
Syntax: int16_t menu_click ( int16_t click, int16_t setit );
 
Description: With the aid of the menu_click function it is possible to change the operation of dropdown menus to that of pulldown menus, familiar from the Macintosh. The following apply:
 
Parameter Meaning
   
click
0 = Dropdown
1 = Pulldown
setit
0 = Inquire menu control
1 = Set menu control
Return value: The function returns the type of menu control set (0 = Dropdown, 1 = Pulldown).
 
Availability: On the PC this function is available only from GEM/3, KAOS 1.4.2 and MagiC; on the Atari the presence should be checked for with appl_getinfo (opcode 5).
 
Group: Menu library
 
See also: Binding
 

8.17.3.1 Bindings for menu_click

C: int16_t menu_click ( int16_t click, int16_t setit );
 
Binding:
  
int16_t menu_click (int16_t click, int16_t setit)
{
   int_in[0] = click;
   int_in[1] = setit;

   return ( crys_if(37) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 37 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] click
int_in+2 int_in[1] setit
int_out int_out[0] Return value

8.17.4 menu_icheck

Name: »Menu indicate check« - Set or clear check mark (tick) in menu options.
 
Opcode: 31
 
Syntax: int16_t menu_icheck ( OBJECT *me_ctree, int16_t me_citem, int16_t me_ccheck );
 
Description: The call menu_icheck sets or removes a check mark (tick) before a menu entry. The following apply:
 
Parameter Meaning
   
me_ctree Address of the menu object tree
me_citem Index of the menu entry
me_ccheck
0 = Clear tick
1 = Set tick

Note: For appearance's sake, every entry of a menu should start with two space characters. From PC-GEM 2.0 onwards, small triangles instead of a tick are used for this purpose.
 
Return value: The value 0 indicates that an error has arisen.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding   OBJECT
 

8.17.4.1 Bindings for menu_icheck

C: int16_t menu_icheck ( OBJECT *me_ctree, int16_t me_citem, int16_t me_ccheck );
 
Binding:
  
int16_t menu_icheck (OBJECT *me_ctree, int16_t me_citem,
                     int16_t me_ccheck)
{
   int_in[0]  = me_citem;
   int_in[1]  = me_ccheck;
   addr_in[0] = me_ctree;

   return ( crys_if(31) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 31 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_citem
int_in+2 int_in[1] me_ccheck
addr_in addr_in[0] me_ctree
int_out int_out[0] Return value

8.17.5 menu_ienable

Name: »Menu indicate enable« - Enable or disable a menu entry.
 
Opcode: 32
 
Syntax: int16_t menu_ienable ( OBJECT *me_etree, int16_t me_eitem, int16_t me_eenable );
 
Description: The call menu_ienable switches menu entries on or off. The following apply:
 
Parameter Meaning
   
me_etree Address of the menu object tree
me_eitem Index of the menu entry
me_eenable
0 = Disable menu entry
1 = Enable menu entry
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding   OBJECT
 

8.17.5.1 Bindings for menu_ienable

C: int16_t menu_ienable ( OBJECT *me_etree, int16_t me_eitem, int16_t me_eenable );
 
Binding:
  
int16_t menu_ienable (OBJECT *me_etree, int16_t me_eitem,
                      int16_t me_eenable)
{
   int_in[0]  = me_eitem;
   int_in[1]  = me_eenable;
   addr_in[0] = me_etree;

   return ( crys_if(32) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 32 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_eitem
int_in+2 int_in[1] me_eenable
addr_in addr_in[0] me_etree
int_out int_out[0] Return value

8.17.6 menu_istart

Name: »Menu istart« - Align a submenu entry.
 
Opcode: 38
 
Syntax: int16_t menu_istart ( int16_t flag, OBJECT *tree, int16_t imenu, int16_t item );
 
Description: The call menu_istart enables the alignment of a submenu item vertically with the corresponding entry of the parent (main) menu. The following apply:
 
Parameter Meaning
   
flag 1 = Align, 0 = Don't align
tree Address of the menu object tree
imenu Index of the submenu entry that is to be aligned
item Index of the menu entry with which the submenu is to be associated
Return value: An error has arisen only if the value 0 is returned; a positive number is the object index of the submenu item currently aligned with its parent menu entry.
 
Availability: This function is available only with AES versions 3.30 and above.
 
The presence of this function can be ascertained with a call of appl_getinfo (opcode 9).
 
Group: Menu library
 
See also: Binding   menu_attach   XMEN_MGR
 

8.17.6.1 Bindings for menu_istart

C: int16_t menu_istart ( int16_t flag, OBJECT *tree, int16_t imenu, int16_t item );
 
Binding:
  
int16_t menu_istart (int16_t flag, OBJECT *tree,
                     int16_t imenu,
                     int16_t item)
{
   int_in[0]  = flag;
   int_in[1]  = imenu;
   int_in[2]  = item;
   addr_in[0] = tree;

   return ( crys_if(38) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 38 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] flag
int_in+2 int_in[1] imenu
int_in+4 int_in[2] item
addr_in addr_in[0] tree
int_out int_out[0] Return value

8.17.7 menu_popup

Name: »Menu popup« - Take over the display and handling of a popup menu.
 
Opcode: 36
 
Syntax: int16_t menu_popup ( MENU *me_menu, int16_t me_xpos, int16_t me_ypos, MENU *me_mdata );
 
Description: The call menu_popup takes over the display and handling of a popup menu, returning the user's selection. The following apply:
 
Parameter Meaning
   
me_menu Pointer to the structure of the popup
me_xpos X-coordinate, and
me_ypos Y-coordinate of the menu's top left corner
me_mdata Pointer to the data of the selected menu entry

If mn_scroll of MENU is set to 0 when menu_popup is called, a non-scrollable popup menu will be displayed.
 
if mn_scroll of MENU is set to >0 when menu_popup is called, a scrolling popup menu will be displayed; height of MN_SET determines it's height in items (note that Atari's AES implements up/down arrows within the popup for scrolling to maintain the same look and feel of dropdown menus as they can be attached to menubar items, note that NAES mimics this exact behavior). See also menu_settings.
 
As of AES version 4.1, if mn_scroll of MENU is set to -1 when menu_popup is called, a dropdown list box instead of a popup menu will be displayed; this will have a scroll bar if eight entries or more exist.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: This function is available only with AES versions 3.30 and above.
 
The presence of this function can be ascertained by a call of appl_getinfo (opcode 9).
 
Group: Menu library
 
See also: Binding   menu_settings   XMEN_MGR
 

8.17.7.1 Bindings for menu_popup

C: int16_t menu_popup ( MENU *me_menu, int16_t me_xpos, int16_t me_ypos, MENU *me_mdata );
 
Binding:
  
int16_t menu_popup (MENU *me_menu, int16_t me_xpos,
                    int16_t me_ypos,
                    MENU *me_mdata)
{
   int_in[0]  = me_xpos;
   int_in[1]  = me_ypos;
   addr_in[0] = me_menu;
   addr_in[1] = me_mdata;

   return ( crys_if(36) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 36 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_xpos
int_in+2 int_in[1] me_ypos
addr_in addr_in[0] me_menu
addr_in+4 addr_in[1] me_mdata
int_out int_out[0] Return value

8.17.8 menu_register

Name: »Menu register« - Register a desk accessory in the 'Desk' accessory menu.
 
Opcode: 35
 
Syntax: int16_t menu_register ( int16_t me_rapid, CONST int8_t *me_rpstring );
 
Description: The call menu_register enters the name of a desk accessory in the accessory menu (below the left-most entry of the menu bar), or alters it. The following apply:
 
Parameter Meaning
   
me_rapid Application ID of the accessory, or -1 to alter the process name of the application to that specified in me_rpstring
me_rpstring Address of the NULL-terminated text string for the menu entry

Although altering the name of the application is only documented as of AES 4.0, this feature seems to work in all TOS versions.
 
Important: The parameter me_rpstring is used by GEM only as a pointer; thus no copy of the new entry will be created. The function call only becomes effective when the corresponding main program makes a menu_bar call. Hence desk accessories should call this function immediately after launching, else there is the danger that they will miss the menu_bar of the desktop.
 
If the cookie 'MbAr' or 'AmAN' is present, then one can find the appication ID with menu_register(-1,"?\0\n"), where n specifies the ID of the accessory in question. The return value then represents the menu_id (or -1).
 
Note: Applications other than desk accessories should not call this function unless they are running under MultiTOS, where they can use it to provide a more meaningful title for the 'Desk' menu than the program's filename. Calling menu_register with a parameter of -1 for me_rapid is used to change the internal process name of the application returned by appl_find and appl_search - useful if you know that another process will try to find your application as a specific process name and the user may have altered the application's filename (which is normally used as the process name).
 
Return value: The function returns the menu identifier for the accessory, or (in case of error) the value -1. Desk accessories should store the return value, as it is included in AC_OPEN messages to identify the accessory.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding   menu_bar   menu_unregister
 

8.17.8.1 Bindings for menu_register

C: int16_t menu_register ( int16_t me_rapid, CONST int8_t *me_rpstring );
 
Binding:
  
int16_t menu_register (int16_t me_rapid,
                       CONST int8_t *me_rpstring)
{
   int_in[0]  = me_rapid;
   addr_in[0] = me_rpstring;

   return ( crys_if(35) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 35 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_rapid
addr_in addr_in[0] me_rpstring
int_out int_out[0] Return value

8.17.9 menu_settings

Name: »Menu settings« - Set or inquire popup/submenu parameters.
 
Opcode: 39
 
Syntax: int16_t menu_settings ( int16_t me_flag, MN_SET *me_values );
 
Description: The call menu_settings enables manipulation of the global parameters for popups and for submenus. The following apply:
 
Parameter Meaning
   
me_flag Parameter
0 = Inquire current settings
1 = Set current settings from MN_SET
me_values Pointer to MN_SET structure

Note: The settings made with this function apply not just for the calling program, but for the whole system. For this reason this call should not be used by normal application programs but only in configuration programs (such as CPX modules, for instance).
 
Return value: The function always returns the value 1.
 
Availability: This function is available only with AES versions 3.30 and above.
 
The presence of this function can be ascertained with a call of appl_getinfo (opcode 9).
 
Group: Menu library
 
See also: Binding   menu_popup   XMEN_MGR
 

8.17.9.1 Bindings for menu_settings

C: int16_t menu_settings ( int16_t me_flag, MN_SET *me_values );
 
Binding:
  
int16_t menu_settings (int16_t me_flag, MN_SET *me_values)
{
   int_in[0]  = me_flag;
   addr_in[0] = me_values;

   return ( crys_if(39) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 39 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_flag
addr_in addr_in[0] me_values
int_out int_out[0] Return value

8.17.10 menu_text

Name: »Menu text« - Replaces the text of a menu item.
 
Opcode: 34
 
Syntax: int16_t menu_text ( OBJECT *me_ttree, int16_t me_titem, CONST int8_t *me_ttext );
 
Description: The call menu_text alters the text in a menu item. In this way menu texts can be dependent of the state of the application, i.e. become context-sensitive. The following apply:
 
Parameter Meaning
   
me_ttree Address of the menu object tree
me_titem Index of the menu item to be altered
me_ttext Address of the new NULL-terminated character string for the item

Important: The parameter me_ttext is used by GEM only as a pointer; thus no copy of the new entry will be created. Furthermore one should ensure that the new entry does not exceed the length of the old one.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding   OBJECT
 

8.17.10.1 Bindings for menu_text

C: int16_t menu_text ( OBJECT *me_ttree, int16_t me_titem, CONST int8_t *me_ttext );
 
Binding:
  
int16_t menu_text (OBJECT *me_ttree, int16_t me_titem,
                   CONST int8_t *me_ttext)
{
   int_in[0]  = me_titem;
   addr_in[0] = me_ttree;
   addr_in[1] = me_ttext;

   return ( crys_if(34) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 34 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_titem
addr_in addr_in[0] me_ttree
addr_in+4 addr_in[1] me_ttext
int_out int_out[0] Return value

8.17.11 menu_tnormal

Name: »Menu text normal« - Displays a menu title in inverse video or normal.
 
Opcode: 33
 
Syntax: int16_t menu_tnormal ( OBJECT *me_ntree, int16_t me_ntitle, int16_t me_nnormal );
 
Description: The call menu_tnormal highlights a menu title by displaying it in inverse video. The following apply:
 
Parameter Meaning
   
me_ntree Address of the menu object tree
me_ntitle Index of the menu item to change
me_nnormal
0 = Display menu item inverse
1 = Display menu item normal
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Menu library
 
See also: Binding
 

8.17.11.1 Bindings for menu_tnormal

C: int16_t menu_tnormal ( OBJECT *me_ntree, int16_t me_ntitle, int16_t me_nnormal );
 
Binding:
  
int16_t menu_tnormal (OBJECT *me_ntree, int16_t me_ntitle,
                      int16_t me_nnormal)
{
   int_in[0]  = me_ntitle;
   int_in[1]  = me_nnormal;
   addr_in[0] = me_ntree;

   return ( crys_if(33) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 33 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] me_ntitle
int_in+2 int_in[1] me_nnormal
addr_in addr_in[0] me_ntree
int_out int_out[0] Return value

8.17.12 menu_unregister

Name: »Menu unregister« - Remove accessory name from 'Desk' menu.
 
Opcode: 36
 
Syntax: int16_t menu_unregister ( int16_t mid );
 
Description: The call menu_unregister allows a desk accessory to remove its name from the 'Desk' menu again.
 
The parameter mid is the application ID of the corresponding desk accessory.
 
Return value: Not known at present.
 
Availability: The function is available only under PC-GEM as of 2.0, KAOS as of 1.4.2 and MagiC.
 
Group: Menu library
 
See also: Binding   menu_register
 

8.17.12.1 Bindings for menu_unregister

C: int16_t menu_unregister ( int16_t mid );
 
Binding:
  
int16_t menu_unregister (int16_t mid)
{
   int_in[0] = mid;
   return ( crys_if(36) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 36 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] mid
int_out int_out[0] Return value
Home AESAES MagiC libraryMagiC library Object libraryObject library