Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINMESSAGEMGR
 
BOOL WinGetMsg(hab, pqmsg, hwndFilter, msgFilterFirst, msgFilterLast)
HAB hab;                  /* handle of the anchor block        */
PQMSG pqmsg;              /* address of structure with message */
HWND hwndFilter;          /* window-filter handle              */
USHORT msgFilterFirst;    /* first message                     */
USHORT msgFilterLast;     /* last message                      */
 
The WinGetMsg function retrieves a message from the thread's message queue,
waits if necessary, and returns when a message conforming to the filtering
criteria is available.
 
Parameter       Description
────────────────────────────────────────────────────────────────────────────
 
hab             Identifies the anchor block.
 
pqmsg           Points to the QMSG structure that contains a message.
 
hwndFilter      Identifies the window filter.
 
msgFilterFirst  Specifies the first message.
 
msgFilterLast   Specifies the last message.
 
Return Value
 
The return value is TRUE if the returned message is not WM_QUIT. The return
value is FALSE if the returned message is WM_QUIT.
 
Comments
 
Filtering allows an application to process messages in a different order
than the one in the queue. Filtering is used so the application can receive
messages of a particular type only, rather than receiving other types of
messages at an inconvenient point in the logic of the application. For
example, when a "mouse button down" message is received, the application can
use filtering to wait for the "mouse button up" message without having to
process other messages.
 
When using filtering, you must ensure that a message satisfying the
specification of the filtering parameters can occur; otherwise, the
WinGetMsg function cannot completely execute. For example, calling the
WinGetMsg function with the msgFilterFirst and msgFilterLast parameters
equal to WM_CHAR and with the hwndFilter parameter set to a window handle
that does not have the input focus prevents WinGetMsg from returning.
 
Keystrokes are passed to the WinTranslateAccel function. This means that
accelerator keys are translated into WM_COMMAND or WM_SYSCOMMAND messages
and are not seen as WM_CHAR messages by the application.
 
The hwndFilter parameter limits the returned message to a specific window or
its child windows. When hwndFilter is NULL, the returned message can be for
any window. The message identity is restricted to the range specified by the
msgFilterFirst and msgFilterLast parameters. When msgFilterFirst and
msgFilterLast are both zero, any message satisfies the range constraint.
When msgFilterFirst is greater than msgFilterLast, messages except those
whose identities lie between msgFilterFirst and msgFilterLast can be
returned. Messages that do not conform to the filtering criteria remain in
the queue.
 
When msgFilterFirst and msgFilterLast are both zero, all messages are
returned.
 
The constants WM_MOUSEFIRST and WM_MOUSELAST can be used for msgFilterFirst
and msgFilterLast to filter all but mouse messages.
 
The constants WM_BUTTONCLICKFIRST and WM_BUTTONCLICKLAST can be used for
msgFilterFirst and msgFilterLast to filter all but mouse button messages.
 
The constants WM_DDE_FIRST and WM_DDE_LAST can be used for msgFilterFirst
and msgFilterLast to filter all but dynamic data exchange messages.
 
Example
 
This example calls WinGetMsg to retrieve a message and WinDispatchMsg to
send the message.
 
HAB hab;
QMSG qmsg;
 
while (WinGetMsg(hab,    /* handle to the anchor block             */
        &qmsg,           /* address of the message queue structure */
        (HWND) NULL,     /* accept messages for any window         */
        0,               /* first message to accept                */
        0))              /* accept all messages                    */
    WinDispatchMsg(hab, &qmsg);
 
See Also
 
WinDispatchMsg, WinPeekMsg, WinPostMsg, WinTranslateAccel, WinWaitMsg, QMSG,
WM_CHAR, WM_COMMAND, WM_QUIT, WM_SYSCOMMAND
 
                                      ♦