2.2.7 Creating a Message Loop

Once your application has created and displayed a window, the WinMain function can begin its primary duty: to read messages from the application queue and dispatch them to the appropriate window. WinMain does this by using a message loop. A message loop is a program loop, typically created by using a while statement, in which WinMain retrieves messages and dispatches them.

Windows does not send input directly to an application. Instead, it places all mouse and keyboard input into an application queue (along with messages posted by Windows and other applications). The application must read the application queue, retrieve the messages, and dispatch them so that the appropriate window procedure can process them.

The simplest possible message loop consists of the GetMessage and DispatchMessage functions. This loop has the following form:

MSG msg;
    .
    .
    .

while (GetMessage(&msg, NULL, NULL, NULL)) {
    DispatchMessage(&msg);
}

In this example, the GetMessage function retrieves a message from the application queue and copies it to the message structure named msg. The NULL arguments indicate that all messages should be processed. The DispatchMessage function directs Windows to send each message to the appropriate window procedure. Every message an application receives, except the WM_QUIT message, belongs to one of the windows created by the application. Since an application must not call a window procedure directly, it uses the DispatchMessage function instead to pass each message to the appropriate procedure.

Depending on what your application does, it may require a more complicated message loop. In particular, to process character input from the keyboard, it must translate each message it receives by using the TranslateMessage function. The message loop should then look like this:

while (GetMessage(&msg, /* message structure                  */
        NULL,       /* handle of window receiving the message */
        NULL,       /* lowest message to examine              */
        NULL))      /* highest message to examine             */
    {
    TranslateMessage(&msg); /* translates virtual key codes   */
    DispatchMessage(&msg);  /* dispatches message to window   */

The TranslateMessage function looks for matching WM_KEYDOWN and WM_KEYUP messages and generates a corresponding WM_CHAR message for the window that contains the Windows character code for the given key. This message loop could also contain functions that process menu accelerator keys and keystrokes within dialog boxes. Again, this would depend on what your application does.

Windows places input messages in an application queue when the user moves the cursor in the window, presses or releases a mouse button when the cursor is in the window, or presses or releases a key when the window has the input focus. The window manager first collects all keyboard and mouse input in a system queue and then copies the corresponding messages to the appropriate application queue.

The message loop continues until GetMessage returns NULL, which it does only if it retrieves the WM_QUIT message. This message is a signal to terminate the application and is usually posted (placed in the application queue) by the window procedure of the application's main window.