View source for Message loop in Microsoft Windows

{{Inline|date=November 2023}}
The '''message loop''' is an obligatory section of [[Source code|code]] in every [[Computer program|program]] that uses a [[Graphical user interface|graphical user interface]] under [[Software:Microsoft Windows|Microsoft Windows]].<ref>{{Cite web |title=Entering the Message Loop |url=https://learn.microsoft.com/en-us/previous-versions//aa383682(v=vs.85) |access-date=2023-11-23}}</ref>
Windows programs that have a [[Graphical user interface|GUI]] are [[Event-driven programming|event-driven]]. Windows maintains an individual [[Message queue|message queue]] for each thread that has created a window. Usually only the first thread creates windows. Windows places [[Message passing|messages]] into that queue whenever mouse activity occurs on that thread's window, whenever keyboard activity occurs while that window has focus, and at other times. A process can also add messages to its own queue. To accept user input, and for other reasons, each thread with a window must continuously retrieve messages from its queue, and act on them. A programmer makes the process do that by writing a loop that calls GetMessage (which blocks for a message and retrieves it), and then calls DispatchMessage (which dispatches the message), and repeats indefinitely. This is the message loop. There usually is a message loop in the main program, which runs on the main [[Thread (computing)|thread]], and additional message loop in each created modal dialog. Messages for ''every'' window of the process pass through its message queue, and are handled by its message loop. A message loop is one kind of [[Event loop|event loop]].

A basic message loop appears as follows:

<source lang="c">
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
{
    MSG msg;
    BOOL bRet;

    while (1)
    {
        bRet = GetMessage(&msg, NULL, 0, 0);

        if (bRet == -1)  // If bRet is -1, GetMessage has failed.
        {
            // Handle or log the error; possibly exit.
            // ...
        }
        else if (bRet != 0)  // If bRet is not 0 or -1, the message must be processed.
        {
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
        else  // If bRet is 0, the message loop should exit.
        {
            break;
        }
    }
    return msg.wParam;
}
</source>

It is conventional for the event loop to call <code>TranslateMessage</code> on each message which can translate virtual keystrokes into [[Null-terminated string|strings]]. Calling <code>TranslateMessage</code> is not technically required, but problems can result if it is not called. The message loop must call <code>DispatchMessage</code>.

The message loop does not directly act on the messages that it handles. It dispatches them by calling <code>DispatchMessage</code>, which transfers the message to the "window procedure" for the window that the message was addressed to. (The "window procedure" is a [[Callback (computer programming)|callback]] procedure, which got associated with the window class when it was registered.) (More than one window can use the same window procedure.)

Code can also send messages directly to a window procedure. These are called nonqueued messages.

A strict message loop is not the only option. Code elsewhere in the program can also accept and dispatch messages. <code>PeekMessage</code> is a non-blocking call that returns immediately, with a message if any are waiting, or no message if none is waiting. <code>WaitMessage</code> allows a thread to sleep until a message is in the queue.

Modern graphical interface [[Software:Application framework|frameworks]], such as [[Software:Windows Forms|Windows Forms]], [[Organization:Windows Presentation Foundation|Windows Presentation Foundation]], [[Organization:Microsoft Foundation Class Library|MFC]], [[Delphi (programming language)|Delphi]], [[Software:Qt|Qt]], and others do not require applications to code a Windows message loop, because they automatically route events such as key presses and mouse clicks to their appropriate handlers as defined within the framework. However, each framework implements a message loop somewhere, and the message loop can usually be accessed or replaced when more direct control is required.

==See also==
* [[Software:Xlib#Example|Xlib]] for the event loop in the [[Software:X Window System|X Window System]]

== References ==
{{Reflist}}

==External links==
* [https://www.microsoft.com/msj/0795/dilascia/dilascia.aspx Meandering Through the Maze of MFC Message and Command Routing (MSJ, July 1995)]
* [http://edn.embarcadero.com/article/38447 A Key's Odyssey: the path of a keystroke message through the VCL]
* [https://msdn.microsoft.com/en-us/library/ms632590.aspx Platform SDK: Messages and Message Queues]
* [https://msdn.microsoft.com/en-us/library/ms644928.aspx Using Messages and Message Queues (MSDN)]
* [https://msdn.microsoft.com/en-us/library/ms644936.aspx GetMessage function]
* [https://msdn.microsoft.com/en-us/library/ms644943.aspx PeekMessage function]

[[Category:Events (computing)]]
[[Category:Microsoft application programming interfaces]]

{{Sourceattribution|Message loop in Microsoft Windows}}