DialogAddMenu Function (Macro)

AMS 2.00 or higher dialogs.h

HANDLE DialogAddMenu (HANDLE Handle, short flags, short x, short y, void *Menu, unsigned short MaxMenuWidth);

Adds a menu into a dialog box.

DialogAddMenu adds the menu Menu, with a maximum width of MaxMenuWidth (or zero to automatically calculate the width) at the position (x,y) to the dialog structure associated with the handle Handle, where the coordinates are relative to the top-left corner of the dialog box.

A menu item is defined by a pointer Menu to a toolbar menu structure created statically (i.e. you must include a pre-filled static menu in your source code) or dynamically with MenuNew (in this case the caller must ensure the structure remains locked while in use in the dialog box, i.e. use HLock in the same way as for MenuBegin). The menu is drawn by an internal call to MenuBegin. When a menu key is pressed, the callback's (see DialogNew for more information) Message value will be the item's identification number and Value will be passed the menu handle returned from MenuBegin in the high word and the key code in the low word. You can specify a maximum width for your menu in MaxMenuWidth or zero if you want it to be automatically calculated. Each dialog box can have at most one menu. The creation of menus is explained in the header file menus.h. Note that if you want a menu, you must write a callback function, else you will not be able to do anything but dispaying it!

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCREEN_SAVE The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_MAX_MENU_WIDTH AMS 2.00 or higher: Passes MBF_MAX_MENU_WIDTH to MenuBegin when the menu is drawn.


DialogAddMenu returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddMenu is in fact a macro created for your convenience. It calls DialogAdd with D_MENU as the ItemType parameter.


Uses: DialogAdd