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