Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-Filemenu_istart()menu_settings()menu_popup()Menu Librarymenu_attach() AESSyntaxWORD menu_attach( flag, tree, item, mdata )
WORD flag;
OBJECT *tree;
WORD item;
MENU *mdata;
Function menu_attach() 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.
Opcode 37 (0x25)
Availability This function is only available from AES version 3.30 and
above. In AESversions 4.0 and greater, appl_getinfo() should be used to determine its exact functionality.
Parameters flag indicates the action the application desires as
follows:
# Define Meaning
0 ME_INQUIRE Return information on a sub-menu attached
to the menu item designated by tree and
item in mdata.
1 ME_ATTACH Attach or change a sub-menu. mdata should
be initialized by the application.
tree and item should be the OBJECT pointer
and index to the menu which is to have the
sub-menu attached. If mdata is NULLPTR, any
sub-menu attached will be removed.
2 ME_REMOVE Remove a sub-menu. tree and item should be
the OBJECT pointer and index to the menu
item which a sub-menu was attached to.
mdata should be NULLPTR.
In all cases except ME_REMOVE, mdata should point to a MENU structure as defined here:
typedef struct
{
OBJECT *mn_tree;
WORD mn_menu;
WORD mn_item;
WORD mn_scroll;
WORD mn_keystate;
} MENU;
The MENU structure members are defined as follows:
Member Meaning
mn_tree Points to the OBJECT tree of the sub-menu.
mn_menu Is an index to the parent object of the menu
items.
mn_item Is the starting menu item.
mn_scroll If SCROLL_NO (0), the menu will not scroll.
If SCROLL_YES (1), and the number of menu
items exceed the menu scroll height, arrows
will appear which allow the user to scroll
selections.
mn_keystate This member is unused and should be 0 for
this call.
Binding intin[0] = flag;
intin[1] = item;
addrin[0] = tree;
addrin[1] = mdata;
return crys_if(0x25);
Return Value menu_attach() returns 0 if an error occurred and the
sub-menu could not be attached or 1 if the operation was
successful.
Caveats AESversions supporting 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 menu_attach() call.
In addition, under AES 3.40, no more than one scrolling
sub-menu should be contained in each tree.
Comments If a menu bar having attachments is removed with
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:
1. Menu items which will have sub-menus attached to them
should be padded with blanks to the end of the menu.
2. Menu items which will have sub-menus attached to them
should not have a keyboard equivalent.
3. Sub-menus will display faster if a byte-boundary is
specified.
4. Sub-menus will be shifted vertically to align the start
object with the main menu item which it is attached to.
5. Sub-menus will always be adjusted to automatically fit
on the screen.
6. 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).
7. Do not attach a sub-menu to itself.
8. 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.
9. menu_istart() works only on sub-menus attached with
menu_attach().
See Also menu_istart(), menu_settings(), menu_popup()Group Menu Library