A Basic Win32 GUI Program--WINBASIC.ASM

This program produces a basic application window. You can move the window around. You can change the window's size and all the usual buttons appear and are functional. The only things missing are scroll bars and a menu bar. [ More programming information ]
[ Back to Win32 ASM Page ]

Program startup

For single-threaded programs the initial values of the registers are almost of no importance. But just in case you're interested: CS:EIP = start of program; SS:ESP = start of stack; DS = ES = SS; FS = TIB the thread information block; GS = 0 the null selector. CS and DS map to the same linear address. The direction flag DF is cleared.
    [More on program startup.]

We start our GUI app in the same manner as the Console App.

.386
model  flat

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

include win32hst.inc ; constants
structures
and entry names

public _start

.code
_start:

The window class

Every window is described by a run-time data structure known as a window class. (This "class" is not a C++ class.) Every window class has a callback function known as a window procedure that defines most of the behavior of all windows created with this class.
    Before we can create a window its window class defined by a WNDCLASSEX structure must be given a name and registered by calling RegisterClassEx. Windows preregisters a few window classes but these are usually used for creating controls.
    First let's look at the WNDCLASSEX structure defined in WIN32HST.INC. For ease in translating to other assemblers I have prefixed each field with what I call the structure's "signature". These signatures are shown as comments in the .h header files for C. The remainder of the field name after the underscore is exactly the same as in the C header files. 
WNDCLASSEX STRUC
wcx_cbSize              dd ?
wcx_style               dd ?
wcx_lpfnWndProc         dd ?
wcx_cbClsExtra          dd ?
wcx_cbWndExtra          dd ?
wcx_hInstance           dd ?
wcx_hIcon               dd ?
wcx_hCursor             dd ?
wcx_hbrBackground       dd ?
wcx_lpszMenuName        dd ?
wcx_lpszClassName       dd ?
wcx_hIconSm             dd ?
WNDCLASSEX ENDS
Wow! that's a lot of fields. Three fields are the minimum needed to create a window: lpfnWndProc hInstance and lpszClassName. We will also define four other fields: style hIcon hCursor and hbrBackground. Unused fields must be zeroed out.
    We use the names defined in the API docs but we prefix the field names with a class "signature" which is shown in comments in the .h header files for C.
    The lpfnWndProc field contains the address of the window procedure that defines how the windows of this class will behave.
    The hInstance field contains a handle for the module that "owns" the window class. Win16 made a distinction between an instance and a module handle but in Win32 they are one and the same. These module instance handles identify loaded modules (EXE and DLL files) somewhat like file handles identifying opened files. Like file handles module/instance handles are unique only within a running program instance or process.
    The lpszClassName field contains the address of a zero-terminated (C-style) string which names the window class.
    Instead of defining the structure with WNDCLASSEX we will expand it and comment on what is in the WNDCLASSEX structure. 
.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
The field cbSize has the total size of the WNDCLASSEX structure. A number of structures have a structure size as the first field. This makes it easy to extend structures. Later releases of Windows can use this field to determine which version of the structure is being used and act accordingly. It's important to set this field when its structure is used to receive data.
    CS_VREDRAW and CS_HREDRAW in the style field force the normal behavior of redrawing the window whenever it changes size.
    WndProc is the window procedure we will define later in the program.
    The hbrBackground field specifies the default or background coloring of the framed area known as the client area. The value (COLOR_WINDOW + 1) makes it the same as the other window client areas.
    The label "wndclsname" defines the location of the zero-terminated window class name.

Now for the fields that must be filled in at runtime.

extrn   GetModuleHandle:near

.code
push    large 0            ; NULL string pointer means
call    GetModuleHandle    ; get HINSTANCE/HMODULE of EXE file
mov     [wcx.wcx_hInstance]
eax
Calling GetModuleHandle with a NULL pointer gives us the instance handle of the EXE file. This is the module that will "own" the window class. 
extrn   LoadIcon:near
LoadCursor:near

.code
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
The hIcon field gives us an "application" icon. And the hCursor field gives us the cursor image that is used when the cursor is over the window we will create. 
extrn   RegisterClassEx:near

.code
push    offset wcx
call    RegisterClassEx
And thus the window class is registered.
    All versions of Windows use the structure to create their own internal window class "object" so after the window class is registered we can discard our "window class structure" with no ill effects.

Window creation

After the window class name is registered we can create the window using CreateWindowEx.
    Although there are a lot of individual arguments we're basically providing five (and nulling out the others): 1) the window class name 2) a window caption 3) the window location 4) the window size and 5) some standard "style" options.
    The window class name is qualified by the module instance handle that owns it. The owner is established by RegisterClassEx via the hInstance field in the WNDCLASSEX data structure.
    In the following code we use a different approach to passing parameters. We can treat the argument list as a data structure. Instead of pushing each argument individually we create a structure to hold all the arguments (in proper order) and then push the entire structure onto the stack. We can modify any portion before stacking the structure or modify the stacked structure. The following code chooses the latter approach. 
.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   200                ; cx (width)
dd   200                ; cy (height)
dd   0                  ; hwndParent
dd   0                  ; hMenu
dd   0                  ; hInstance
dd   0                  ; lpCreateParams

wnd_title db 'Application'
0

extrn   CreateWindowEx:near

.code
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
call    CreateWindowEx

The message loop

After the window is created and displayed we can then deal with any message sent to our program. Our basic GUI program repeatedly fetches messages from the message queue with GetMessage. We do this with a message loop. This loop is sometimes called the message pump.
    If there are any messages originating from one of the various forms of SendMessage GetMessage will invoke the appropriate window procedure directly. Otherwise the message is copied into a local buffer (the lpMsg argument) and control returns to the caller of GetMessage. A zero (FALSE) value is returned if GetMessage retrieves a WM_QUIT message.
    In our program the message loop quits if a WM_QUIT message is retrieved. Otherwise it invokes the proper window procedure using DispatchMessage. 
extrn GetMessage:near
DispatchMessage:near

.data
msgbuf MSG    <>

.code
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:

Terminating the program

We exit the program with ExitProcess. 
extrn ExitProcess:near

.code
push    large 0    ; (error) return code
call    ExitProcess

The window procedure

Except for some initialization and some cleanup a GUI program is expected to do everything within the various window procedures.  The window procedure may be called by Windows itself (e.g. when a window is first created) or it may be invoked via DispatchMessage. The window procedure receives four DWORD arguments in this order: window handle (hWnd) message ID (nMessage) first message parameter (wParam) second message parameter (lParam). The argument wParam gets its original name from Win16 where it was a WORD argument.
    When a window is closed the default action handled by DefWindowProc is to destroy it. The window is removed from the screen and a WM_DESTROY message is sent to the window procedure. If we want to terminate our program upon closing a specific window then that window must respond to a message associated with closing a window. The recommended message is WM_DESTROY. Our window procedure does this for the one and only window calling PostQuitMessage as a response. After the window procedure is exited a WM_QUIT message will be picked up by GetMessage in our message loop.
    All other messages get processed by DefWindowProc.

One of the advantages of going from 16-bit code to 32-bit code is the extra addressing modes available. All eight primary 32-bit registers can be used in complex addressing modes.
    WndProc takes advantage of this by using ESP to access its arguments. We use the decomposed form [ESP+4+4] to show that part of the offset is for skipping the stacked EIP and the other part is the offset to the second argument (the message ID).

extrn DefWindowProc:near
PostQuitMessage:near

.code
WndProc:
cmp   dword ptr [esp+4+4]
WM_DESTROY
jne   DefWindowProc

on_destroy:
push  large 0
call  PostQuitMessage

xor   eax
eax
ret   16

end   _start

Linking

Linking a standard application is similar to linking a Console App. With the Microsoft linker we specify a different subsystem. 
    link winbasic kernel32.lib user32.lib /entry:start /subsystem:windows
With the Borland linker we specify a standard Windows app with /aa instead of /ap. The /V option tells the linker to set the subsystem version to 4.0. (Warning: The linker that came with TASM 4.0 does not support /V.) 
tlink32 /Tpe /aa /c /V4.0 winbasic


import32.lib