This library makes functions available for drawing and
manipulating menu bars. The following routines are available for this
purpose:
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.
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
|
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
|
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
|
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
|
|
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
|
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
|