Introduction to Menus

The Win32 API provides a number of functions to create menus dynamically from scratch, but the preferred way is to create menu templates and store them as resources in the EXE file. This is usually accomplished with a menu editor and a resource compiler, but here we show how to create a menu template without these special tools. The program is winmenu.asm.

[Download source code.]

Back to Win32 ASM Page.

The program preliminaries

First, the usual program startup -- up to just before the call to CreateWindowEx. 
        .386
        .model  flat

        ; If using TLINK32, don't include vlib.inc
        include vclib.inc    ; Microsoft VC++ .lib link names

        include win32hst.inc    ; constants, structures, and entry names

        .data
        align   4
wcx     dd      size WNDCLASSEX           ; cbSize
        dd      CS_VREDRAW or CS_HREDRAW  ; style
        dd      WndProc                   ; lpfnWndProc
        dd      0,0                       ; cbClsExtra, cbWndExtra
        dd      0                         ; hInstance
        dd      0                         ; hIcon
        dd      0                         ; hCursor
        dd      COLOR_WINDOW+1            ; hbrBackground
        dd      0                         ; lpszMenuName
        dd      wndclsname                ; lpszClassName
        dd      0                         ; hIconSm

wndclsname db 'winmain',0

        .code

        public _start
        extrn   GetModuleHandle:near
        extrn   LoadIcon:near,LoadCursor:near
        extrn   RegisterClassEx:near

_start:
        push    large 0         ; NULL string pointer means
        call    GetModuleHandle ; get HINSTANCE/HMODULE of EXE file
        mov     [wcx.wcx_hInstance],eax

        push    large IDI_WINLOGO
        push    large 0         ; hInstance, 0 = stock icon
        call    LoadIcon
        mov     [wcx.wcx_hIcon],eax

        push    large IDC_ARROW
        push    large 0         ; hInstance, 0 = stock cursor
        call    LoadCursor
        mov     [wcx.wcx_hCursor],eax

        push    offset wcx
        call    RegisterClassEx

        .data
        align   4
cwargs   dd   0                  ; dwExStyle
         dd   wndclsname         ; lpszClass
         dd   wnd_title          ; lpszName
         dd   WS_VISIBLE or WS_OVERLAPPED or WS_SYSMENU or WS_THICKFRAME \
              or WS_MINIMIZEBOX or WS_MAXIMIZEBOX  ; style
         dd   100                ; x
         dd   100                ; y
         dd   400                ; cx (width)
         dd   200                ; cy (height)
         dd   0                  ; hwndParent
         dd   0                  ; hMenu
         dd   0                  ; hInstance
         dd   0                  ; lpCreateParams

msgbuf MSG      <>

wnd_title db 'Window with menu',0

        .code

        extrn   CreateWindowEx:near
        extrn   GetMessage:near,DispatchMessage:near
        extrn   ExitProcess:near

        sub     esp,48            ; allocate argument list
        mov     esi,offset cwargs ; set block move source
        mov     edi,esp           ; set block move destination
        mov     ecx,12            ; number of arguments
        rep movsd
        mov     eax,[wcx.wcx_hInstance]
        mov     [esp+40],eax      ; set hInstance argument in stack

Adding a menu to a window

Our program will define the menu template in memory. Here we create a menu "object" by calling LoadMenuIndirect, which returns a menu handle. The menu is attached to the window we are creating by setting a CreateWindowEx argument.
    You can also create a window without a menu and later add it with SetMenu. This API function can also be used to change menus. Menus can also be deleted with this API function by using a NULL (zero) menu handle.
    Menus can be further managed and manipulated via their handles. 
        .code

        extrn   LoadMenuIndirect:near

        push    offset appMenuTemplate
        call    LoadMenuIndirect
        mov     [esp+36],eax    ; set hMenu argument in stack

The rest of the preliminaries

Here we finally call CreateWindowEx, and add the message loop. 
        .code
        call    CreateWindowEx

msg_loop:
        push    large 0         ; uMsgFilterMax
        push    large 0         ; uMsgFilterMin
        push    large 0         ; hWnd (filter), 0 = all windows
        push    offset msgbuf   ; lpMsg
        call    GetMessage      ; returns FALSE if WM_QUIT
        or      eax,eax
        jz      end_loop

        push    offset msgbuf
        call    DispatchMessage

        jmp     msg_loop

end_loop:
        push    large 0 ; (error) return code
        call    ExitProcess

Menu template definition

The first two template entries are part of the template header. The two entries are the menu template version number, and an offset to the list of menu items. The offset allows the skipping of additional header information. Version 0 is the original NT and older Win16 template. We will be using the new version 1 template. It adds the F1 help ID to the header. Note that the offset entry in the header is set to skip this extra information. The header must be aligned on a DWORD boundary.
    Each menu item that follows the header must also be aligned on a DWORD boundary. There are five fields (entries) and a sixth field which is supplied only for a popup menu item. They are, in order: the item type, the item state, the item ID, menu structure info, the item text, and the F1 help ID.
    The item type field contains some valid combination of MFT_ constants. It indicates the kinds of menu information to be shown. Our example uses only the MFT_STRING and MFT_SEPARATOR types. The MFT_SEPARATOR type produces the bar between the Help... and About... menu items.
    The item state field contains some valid combination of MFS_ constants. We use only the MFS_ENABLED type. It indicates a display or selection state.
    The item ID is the ID number sent via the WM_COMMAND message to the window procedure that has the menu. Although the field is 32-bits, only 16-bits are sent via WM_COMMAND. The convention is to name them as constants beginning with IDM_.
    The next field is the menu structure info. It is a byte field padded to a WORD boundary. Intel's little-endian number format allows us to set it and the padding with a DW directive. The API does not have standard names for the valid data of this field. We define MFR_ constants for this purpose. There are only two: the MFR_POPUP flag signals that the items following it are part of a popup submenu. The last item in the main menu or submenu has the MFR_END flag in this field. The two flags can be combined.
    The item text is the text that will be displayed by a MFT_STRING item. In spite of the fact that we use the "A" version of LoadMenuIndirect, the strings in the template must be in wide Unicode format. That's why DW is used instead of DB. As in C, strings are terminated with a zero null (NUL) character. This field always exists because of the need for padding to a DWORD boundary. An '&' in the item string causes the character following it to show up underlined. The underlined character is the keyboard menu selector. So if you press and release the Alt key, the first item in the menu bar will be highlighted. Then press the 'F' key, and the File submenu will pop up. If a submenu pops up, another keypress can select an item on the submenu. To display '&' as a character, you must double it as '&', '&'.
    And finally the F1 help ID. This field must exist for a MFR_POPUP entry; it must not exist for any other. It must be aligned on a DWORD boundary. 
;
; Menu item (command) IDs
;
IDM_EXIT equ 101
IDM_HELP equ 901
IDM_ABOUT equ 902
;
; Menu template
;
MFR_END equ 80h
MFR_POPUP       equ 01h

        .data
        align   4       ; must align on DWORD boundary
appMenuTemplate dw 1    ; menu template version
                        dw 4    ; offset from end of this word to menu item list
                        dd 0    ; menu bar help ID

                        dd MFT_STRING,MFS_ENABLED,0
                        dw MFR_POPUP                    ; first column
                        dw '&','F','i','l','e',0,0      ; pad to align 4
                        dd 0                            ; popup help ID

                        dd MFT_STRING,MFS_ENABLED,IDM_EXIT
                        dw MFR_END                      ; bottom of column
                        dw 'E','&','x','i','t',0,0      ; pad to align 4

                        dd MFT_STRING,MFS_ENABLED,0
                        dw MFR_POPUP or MFR_END         ; second column, last one
                        dw '&','H','e','l','p',0,0      ; pad to align 4
                        dd 0                            ; popup help ID

                        dd MFT_STRING,MFS_ENABLED,IDM_HELP
                        dw 0
                        dw '&','H','e','l','p','.','.','.',0

                        dd MFT_SEPARATOR,0,0
                        dw 0
                        dw 0    ; pad to align 4

                        dd MFT_STRING,MFS_ENABLED,IDM_ABOUT
                        dw MFR_END                      ; bottom of column
                        dw '&','A','b','o','u','t','.','.','.',0,0

Menu dispatch

When a menu item is selected and "activated", Windows sends a WM_COMMAND message to the window containing the menu. The menu item ID functions as the command ID passed to the window procedure in the lower sixteen bits of wParam. 
        .code
        extrn   DefWindowProc:near,PostQuitMessage:near

WndProc:
        mov     eax,[esp+4+4]   ; message ID
        cmp     eax,WM_COMMAND  ; from menu, accelerator, or control
        je      on_command
        cmp     eax,WM_DESTROY  ; window will be destroyed
        je      on_destroy
        jmp     DefWindowProc   ; delegate other message processing

on_destroy:
        push    large 0
        call    PostQuitMessage

        xor     eax,eax
        ret     16

on_command:
        mov     eax,[esp+4+8]   ; wParam
        and     eax,large 0FFFFh        ; command ID
        cmp     eax,IDM_EXIT
        je      on_exit_command
        cmp     eax,IDM_HELP
        je      on_help_command
        cmp     eax,IDM_ABOUT
        je      on_about_command
        xor     eax,eax         ; ignore other commands
        ret     16

Menu actions

For terminating the program, we send a WM_CLOSE message to the "main" window. This will cause a call to DestroyWindow, by default, and send a WM_DESTROY message to our window procedure.

We use MessageBox to display messages when the non-exit menu items are selected.

        .data
helpCaption equ wnd_title
helpText db 'Help not implemented.',0

aboutCaption db 'About Win32 Assembly',0
aboutText db 'Place your copyright here.',0

        .code
        extrn   SendMessage:near
        extrn   MessageBox:near

on_exit_command:
        ; trigger the main window close function
        mov     eax,[esp+4+0]   ; get hWnd before stack changes
        push    large 0         ; lParam
        push    large 0         ; wParam
        push    large WM_CLOSE  ; msgid
        push    eax             ; hwnd
        call    SendMessage

        xor     eax,eax
        ret     16

on_help_command:
        mov     eax,[esp+4+0]   ; get hWnd before stack changes
        push    large MB_OK
        push    offset helpCaption
        push    offset helpText
        push    eax                     ; owner window
        call    MessageBox

        xor     eax,eax
        ret     16

on_about_command:
        mov     eax,[esp+4+0]   ; get hWnd before stack changes
        push    large MB_OK
        push    offset aboutCaption
        push    offset aboutText
        push    eax                     ; owner window
        call    MessageBox

        xor     eax,eax
        ret     16

        end     _start