You can specify a bitmap or icon to display next to the menu item, by prepending "|imgspec{=size}|" to the text. XP references removed 7/20. JM may have reviewed.
imgspec may be the filespec (native or AMOS-style) of a BMP or ICO file, or it may be in the "name::library" format used by standard controls which may contain icons. (name is the name of the icon, and library is the name of a DLL containing the icons, such as the ashico1.dll distributed with A-Shell.) The optional {=size} clause may be specified to request a specific size in pixels (menu images display as squares, so only one dimension is required).
Under Windows Vista and later, menu images can be in any reasonable size (say, 10x10 to 99x99), and the menu spacing will adjust accordingly, and the size clause works for both bitmaps (BMP) and icons. The standard icon size is 16x16. Best results will be obtained when the natural size of the BMP file, or when one of the images contained within the ICO, match the default or specified size.
Prior to Vista, the standard menu bitmap size was 13x13 and the resizing feature is not operable (and is essentially ignored). Icons will be automatically scaled to fit the standard space, while BMP files will be clipped. These BMP files are not recommended unless you have a specific set of them for Windows XP and prior that is naturally 13x13 or close to it.
Example
The following code excerpt, from the sample program ASMNU4 in EXLIB:[908,35], adds a new top level menu "Custom" and then adds eight items to that menu, each with a different bitmap, illustrating most of the syntax and image type possibilities—BMP file, ICO file, icon resource in library module, with and without scaling:
++include ashinc:ashell.def
map1 id'cusmnu,b,2,2000
map1 mstatus,f
xcall AUI, AUI_MENU, MNUOP_ADD, 0, "&Custom" , MBST_ENABLE, &
MBF_SUBMNU,"","",mstatus,0,id'cusmnu
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|Back16.bmp|Back (16x16 bmp)", &
MBST_ENABLE, MBF_KBD,"VK_xF501",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|Back24.bmp|Back (24x24 bmp)", &
MBST_ENABLE, MBF_KBD,"VK_xF502",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|Clock24.bmp=16|Clock (24x24 as 16x16 bmp)", &
MBST_ENABLE, MBF_KBD,"VK_xF503",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|add2.ico|Add+ (ico file, default size)", &
MBST_ENABLE, MBF_KBD,"VK_xF504",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|coffee.bmp=64|Coffee (189x189 as 64x64 bmp)", &
MBST_ENABLE, MBF_KBD,"VK_xF505",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, "|back12.bmp|Back (12x12 bmp)", &
MBST_ENABLE, MBF_KBD,"VK_xF506",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, &
"|Arrow_left_green::ashico1v|Arrow_left_green (ashico1v, dft size)", MBST_ENABLE, &
MBF_KBD,"VK_xF507",""
xcall AUI, AUI_MENU, MNUOP_ADD, id'cusmnu, &
"|Arrow_left_green::ashico1=32|Arrow_left_green (ashico1 =32)", MBST_ENABLE, &
MBF_KBD,"VK_xF508",""
Note that in the above examples, we did not specify the optional Mstatus parameter since we weren’t checking the result code anyway, and eliminating any delays waiting for response codes from remote ATE client workstations.
Under Vista and beyond, the result looks something like the picture below. Note that the menu spacing adjusts to the size of the image, and furthermore that all the images can be displayed in a size other than the underlying native size.
Under older versions of Windows (see image below), the visual capabilities are more limited, with no image scaling, and with BMP images being truncated to 13x13. In that environment, either you need to have a set of custom bitmap images sized no larger than 13x13, or you should stick with icons, using either ICO files or taking them from an icon library (like ashico1).
See Also