A Little More on Messages and an Introduction to the Mouse

Messages are basic to Windows GUI programming. Almost everything a GUI program does is triggered by messages. Writing a program that repeatedly waits for messages results in an event-driven style of programming where each message represents an event.
    The messages WM_QUIT and WM_DESTROY were introduced so that an application can terminate gracefully. In this section we introduce mouse messages that show how a program can respond to mouse events in a simple way. The mouse messages are associated with the framed area of a window the client area.
    For MS-DOS programmers writing a window procedure is somewhat like writing an INT 21H interceptor with the message number on the stack instead of in AH. And instead of jumping to the old DOS address for standard behavior you call (or jump to) DefWindowProc.
    Windows produces a lot of messages but the typical application will provide a custom response to only a small percentage of them. Most of the messages can be classified as notifications--"this happened" or "this is about to happen" messages. A few messages can be interpreted as commands.

Message systems
Messages
Allocation of message identifiers
The client area
Mouse movement and buttons
The example program

[ Back to Win32 ASM Page ]

Message systems

Message systems can be viewed as a collection of senders (or producers) and receivers (or consumers) of messages. The messages are typically managed by holding them in queues. In this manner messages are sent and received by storing and fetching them to and from the queue. This allows senders to signal the receivers at a convenient time and it allows the receivers to respond at a convenient time.

Our basic GUI program handles the reception of messages in two parts: the first part inspects the message queue and the second part actually decides how to respond to a given message. Our basic GUI program is written primarily as a receiver or consumer of messages. The senders or producers of these messages are either the Windows API functions or the Windows system itself.

Messages

A message is a packet of information that contains an identifying number. Numbers not reserved by Windows can be used for our own purposes. Some numbers have been given names by Windows and we have used these names -- those starting with WM.
    Messages are delivered to a window by invoking the window's assigned window procedure. As described before window procedures are assigned in two steps. First by registering a window class containing the address of a window procedure; and second by creating a window using that class.
    Most but not all messages are delivered to windows. WM_QUIT is an example of a message that never goes to a window. That's why we don't handle it in a window procedure.
    The code that is written to respond to a message is often called the message handler for that message. Different windows can respond differently to the same message identifier. (The message "packet" itself is directed to only one window.)

Allocation of message identifiers

The message identifying numbers or message identifiers are allocated as follows:

0 to 03FFh
Standard window messages. These are the WM_ messages. Unused numbers are reserved by Windows. The standard controls also have message numbers in this range.
0400h (WM_USER) to 7FFFh
Class-specific messages. Each window class can define messages in this range for class-specific actions. Numbers are reused by the window classes provided by Windows and we can reuse them for our own window classes.
The new common controls have numbers in this range. (For those familiar with the Win16 values the standard controls no longer have message numbers in this range.)
8000h (WM_APP) to 0BFFFh
Application-specific messages. For messages not specific to any window class. Perhaps this set of messages should be called thread-specific messages.
0C000h to 0FFFFh
System-global messages. These numbers are reserved by the RegisterWindowMessage function. This function generates message numbers in this range.
10000h to 0FFFFFFFFh
Internal (proprietary) system messages. These numbers are reserved by Windows. Because they require more than 16 bits these cannot be used to communicate with old 16-bit Windows programs that are running on a Win32 platform.

The client area

The first mouse messages we will look at are usually delivered only when the cursor (which represents the mouse) is pointing to a spot in the client area.
The client area is the display area framed by the window border. If they exist the title menu and scroll bars are excluded from the client area.

Mouse movement and buttons

A two-button mouse can produce the following fundamental messages whenever the cursor points to a location in the client area:

WM_LBUTTONDOWN when the left button is first pressed
WM_LBUTTONUP when the left button is first released
WM_RBUTTONDOWN when the right button is first pressed
WM_RBUTTONUP when the right button is first released
WM_MOUSEMOVE when the mouse is moved

The example program

Our example program winclick.asm reports on mouse activity within our window.

Prolog and class registration
Window creation and message loop
Message dispatch
Mouse message handlers

Prolog and class registration

Here we create the basic window class.

       .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

.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

Window creation and message loop

We create our window and set it up to display our startup title. The window width is made long enough to avoid clipping of the title text.

       .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 'Mouse activity'
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
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

Message dispatch

The following is one way to dispatch messages. It's not bad because there are so few messages. A bigger set of messages would be easier to handle with an address table.

   .code

extrn   DefWindowProc:near
PostQuitMessage:near

WndProc:
mov     eax
[esp+4+4]           ; message ID
cmp     eax
WM_DESTROY          ; about to start window destruction
je      on_destroy
cmp     eax
WM_LBUTTONDOWN      ; left mouse button pressed
je      on_left_mouse_down
cmp     eax
WM_LBUTTONUP        ; left mouse button released
je      on_left_mouse_up
cmp     eax
WM_RBUTTONDOWN      ; right mouse button pressed
je      on_right_mouse_down
cmp     eax
WM_RBUTTONUP        ; right mouse button released
je      on_right_mouse_up
cmp     eax
WM_MOUSEMOVE        ; mouse moved
je      on_mouse_move
jmp     DefWindowProc           ; delegate other message processing

on_destroy:
push    large 0
call    PostQuitMessage

xor     eax
eax
ret     16

Mouse message handlers

This is where we respond to the mouse messages. The text in the title bar is changed by calling SetWindowText. The text displayed depends on the mouse activity when the cursor is pointing to within the client area. The code is left unoptimized so that it shows more clearly where the hwnd parameter is coming from. (The +4 skips the stacked EIP and +0 is the offset of the first argument.)

       .data
align   4
text_ldown db 'Left mouse button down'
0
text_lup   db 'Left mouse button up'
0
text_rdown db 'Right mouse button down'
0
text_rup   db 'Right mouse button up'
0
text_mmove db 'Mouse moved'
0

.code

extrn   SetWindowText:near

on_left_mouse_down:
mov     eax
[esp+4+0]   ; get hwnd before changing ESP
push    offset text_ldown
push    eax
call    SetWindowText

xor     eax
eax
ret     16

on_left_mouse_up:
mov     eax
[esp+4+0]   ; get hwnd before changing ESP
push    offset text_lup
push    eax
call    SetWindowText

xor     eax
eax
ret     16

on_right_mouse_down:
mov     eax
[esp+4+0]   ; get hwnd before changing ESP
push    offset text_rdown
push    eax
call    SetWindowText

xor     eax
eax

ret     16

on_right_mouse_up:
mov     eax
[esp+4+0]   ; get hwnd before changing ESP
push    offset text_rup
push    eax
call    SetWindowText

xor     eax
eax
ret     16

on_mouse_move:
mov     eax
[esp+4+0]   ; get hwnd before changing ESP
push    offset text_mmove
push    eax
call    SetWindowText

xor     eax
eax
ret     16

end     _start