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
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:
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. 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 |
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: |
|
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:
Definitions: MENU_HIDE = 0 MENU_SHOW = 1 MENU_INSTL = 100 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 |
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: |
|
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:
| ||||||||||||||||||||
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 |
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: |
|
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:
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 |
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: |
|
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:
| ||||||||||||||||
Return value: | An error has arisen only if the value 0 is returned. | ||||||||||||||||
Availability: | All AES versions. | ||||||||||||||||
Group: | Menu library | ||||||||||||||||
See also: | Binding OBJECT |
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: |
|
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:
| ||||||||||||
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 |
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: |
|
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:
| ||||||||||||
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. 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. 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 |
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: |
|
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:
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 |
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: |
|
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:
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 |
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: |
|
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:
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 |
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: |
|
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:
| ||||||||||||||||
Return value: | An error has arisen only if the value 0 is returned. | ||||||||||||||||
Availability: | All AES versions. | ||||||||||||||||
Group: | Menu library | ||||||||||||||||
See also: | Binding |
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: |
|
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 |
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: |