Data Structures
struct	_MSG

Macros
#define	PM_NOREMOVE 0x0000

#define	PM_REMOVE 0x0001

#define	PM_NOYIELD 0x0002

Typedefs
typedef struct _MSG	MSG

Functions
MG_EXPORT BOOL GUIAPI	PeekMessageEx (PMSG pMsg, HWND hWnd, UINT nMsgFilterMin, UINT nMsgFilterMax, BOOL bWait, UINT uRemoveMsg)
	Peek a message from the message queue of a main window. More...

static BOOL GUIAPI	GetMessage (PMSG pMsg, HWND hWnd)
	Get a message from the message queue of a main window. More...

MG_EXPORT BOOL GUIAPI	WaitMessage (PMSG pMsg, HWND hMainWnd)
	Wait for a message from the message queue of a main window. More...

MG_EXPORT BOOL GUIAPI	HavePendingMessage (HWND hMainWnd)
	Check if there is any pending message in the message queue of a main window. More...

static BOOL GUIAPI	PeekMessage (PMSG pMsg, HWND hWnd, UINT nMsgFilterMin, UINT nMsgFilterMax, UINT uRemoveMsg)
	Peek a message from the message queue of a main window. More...

MG_EXPORT BOOL GUIAPI	PeekPostMessage (PMSG pMsg, HWND hWnd, UINT nMsgFilterMin, UINT nMsgFilterMax, UINT uRemoveMsg)
	Peek a post message from the message queue of a main window. More...

MG_EXPORT int GUIAPI	PostMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Posts a message into the message queue of a window and returns immediatly. More...

MG_EXPORT LRESULT GUIAPI	SendMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Send a message to a window and wait for the handling result. More...

MG_EXPORT void GUIAPI	SetAutoRepeatMessage (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
	Set the auto-repeat message. More...

MG_EXPORT LRESULT GUIAPI	PostSyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Post a synchronical message to a window which is in different thread. More...

MG_EXPORT LRESULT GUIAPI	SendAsyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Send an asynchronical message to a window. More...

MG_EXPORT int GUIAPI	SendNotifyMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Send a notification message to a window. More...

MG_EXPORT int GUIAPI	SendPriorNotifyMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
	Send a prior notification message to a window. More...

MG_EXPORT int GUIAPI	NotifyWindow (HWND hWnd, LINT id, int code, DWORD dwAddData)
	Send a notification message to a window. More...

MG_EXPORT int GUIAPI	BroadcastMessage (UINT nMsg, WPARAM wParam, LPARAM lParam)
	Broadcast a message to all main windows on the desktop. More...

MG_EXPORT int GUIAPI	BroadcastMessageInThisThread (UINT nMsg, WPARAM wParam, LPARAM lParam)
	Broadcast a message to all main/virtual windows in the current thread. More...

MG_EXPORT int GUIAPI	PostQuitMessage (HWND hWnd)
	Puts a MSG_QUIT message into the message queue of a main window. More...

MG_EXPORT BOOL GUIAPI	SetKeyboardLayout (const char *kbd_layout)
	Set a new keyboard layout. More...

MG_EXPORT BOOL GUIAPI	TranslateMessage (PMSG pMsg)
	Translates key down and key up messages to MSG_CHAR message and post it into the message queue. More...

MG_EXPORT BOOL GUIAPI	TranslateKeyMsgToChar (int message, WPARAM wParam, LPARAM lParam, WORD *ch)
	Translates a key down and key up message to a corresponding character. More...

MG_EXPORT LRESULT GUIAPI	DispatchMessage (PMSG pMsg)
	Dispatches a message to the window's callback procedure. More...

MG_EXPORT int GUIAPI	ThrowAwayMessages (HWND pMainWnd)
	Removes all messages in the message queue associated with a window. More...

MG_EXPORT BOOL GUIAPI	EmptyMessageQueue (HWND hWnd)
	Empty a message queue. More...

Detailed Description

Macro Definition Documentation

◆ PM_NOREMOVE

#define PM_NOREMOVE 0x0000

See also: PeekMessage PeekMessageEx

Definition at line 3175 of file window.h.

◆ PM_NOYIELD

#define PM_NOYIELD 0x0002

See also: PeekMessage PeekMessageEx PeekPostMessage

Definition at line 3189 of file window.h.

◆ PM_REMOVE

#define PM_REMOVE 0x0001

See also: PeekMessage PeekMessageEx PeekPostMessage

Definition at line 3182 of file window.h.

Typedef Documentation

◆ MSG

typedef struct _MSG MSG

The message structure.

See also: GetMessage, PostMessage, Messages

Function Documentation

◆ BroadcastMessage()

int BroadcastMessage	(	UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Broadcast a message to all main windows on the desktop.

This function posts the message specified by (nMsg, wParam, lParam) to all the main windows on the desktop.

Parameters

nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: 0 if all OK, < 0 on error.

See also: PostMessage

◆ BroadcastMessageInThisThread()

int BroadcastMessageInThisThread	(	UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Broadcast a message to all main/virtual windows in the current thread.

This function posts the message specified by (nMsg, wParam, lParam) to all the main/virtual windows in the current thread.

Parameters

nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: The number of windows posted the message; < 0 on error.

Note: This function only available when the support for virtual window is enabled. If the support for virtual window is not enabled, this function is defined as an alias of BroadcastMessage.

See also: BroadcastMessage, PostMessage

◆ DispatchMessage()

LRESULT DispatchMessage ( PMSG pMsg )

Dispatches a message to the window's callback procedure.

This function dispatches the message pointed to by pMsg to the target window's callback procedure.

Parameters

pMsg	The pointer to the message.

Returns: The return value of the message handler.

See also: GetMessage

Example:

/*
 * A typical message loop.
 */
 
    MSG Msg;
    MAINWINCREATE CreateInfo;
    HWND hMainWnd;
 
    InitCreateInfo (&CreateInfo);
 
    hMainWnd = CreateMainWindow (&CreateInfo);
    if (hMainWnd == HWND_INVALID)
        return -1;
 
    while (GetMessage (&Msg, hMainWnd)) {
        TranslateMessage (&Msg);
        DispatchMessage (&Msg);
    }

◆ EmptyMessageQueue()

BOOL EmptyMessageQueue ( HWND hWnd )

Empty a message queue.

This function empties the message queue which is used by the window specified by hWnd.

Parameters

hWnd	The handle to the main window.

Returns: TRUE on all success, FALSE on error.

See also: ThrowAwayMessages

◆ GetMessage()

BOOL GetMessage	(	PMSG	pMsg,
		HWND	hMainWnd
	)

inlinestatic

Get a message from the message queue of a main window.

This function gets a message from the message queue of the main window hMainWnd, and returns until there is a message in the message queue.

Parameters

pMsg	Pointer to the result message.
hMainWnd	Handle to the window.

Returns: FALSE on MSG_QUIT have been found or on error, else gets a message.

See also: HavePendingMessage, PostQuitMessage, MSG

Example:

/*
 * A typical message loop.
 */
 
    MSG Msg;
    MAINWINCREATE CreateInfo;
    HWND hMainWnd;
 
    InitCreateInfo (&CreateInfo);
 
    hMainWnd = CreateMainWindow (&CreateInfo);
    if (hMainWnd == HWND_INVALID)
        return -1;
 
    while (GetMessage (&Msg, hMainWnd)) {
        TranslateMessage (&Msg);
        DispatchMessage (&Msg);
    }

Definition at line 3240 of file window.h.

◆ HavePendingMessage()

BOOL HavePendingMessage ( HWND hMainWnd )

Check if there is any pending message in the message queue of a main window.

This function checks whether there is any pending message in the message queue of the main window hMainWnd.

Parameters

hMainWnd The handle to the main window.

Returns: TRUE for pending message, FALSE for empty message queue.

See also: GetMessage, MSG

◆ NotifyWindow()

int GUIAPI NotifyWindow	(	HWND	hWnd,
		LINT	id,
		int	code,
		DWORD	dwAddData
	)

Send a notification message to a window.

This function sends a notification message to the target window hWnd. By default, the notification will be packed as a MSG_NOTIFICATION message and be sent to the target window. This function will return immediately after putting the message to the message queue of the target window.

If you have set the notification callback procedure for the target window, DispatchMessage will call the procedure in the context of the thread of that window, otherwise, the function will convert this message to a MSG_COMMAND message and dispatch the MSG_COMMAND message to the window procedure.

Parameters

hWnd	The handle to target window.
id	The identifier of the source.
code	The notification code.
dwAddData	The additional data of the notification.

Returns: 0 if all OK, < 0 on error.

See also: MSG_COMMAND, MSG_NOTIFICATION, SetNotificationCallback

Since 5.0.0

◆ PeekMessage()

BOOL PeekMessage	(	PMSG	pMsg,
		HWND	hWnd,
		UINT	nMsgFilterMin,
		UINT	nMsgFilterMax,
		UINT	uRemoveMsg
	)

inlinestatic

Peek a message from the message queue of a main window.

This function peeks a message from the message queue of the window hWnd and returns immediatly. Unlike GetMessage, this function does not wait for a message.

Parameters

pMsg	Pointer to the result message.
hWnd	The handle to the window.
nMsgFilterMin	The min identifier of the message that should be peeked.
nMsgFilterMax	The max identifier of the message that should be peeked.
uRemoveMsg	Whether remove the message from the message queue. Should be the following values: PM_NOREMOVE Leave it in the message queue. PM_REMOVE Remove it from the message queue. PM_NOYIELD Nouse now.

Returns: TRUE if there is a message peeked, or FALSE.

See also: GetMessage, PeekPostMessage, HavePendingMessage, PostMessage

Definition at line 3305 of file window.h.

◆ PeekMessageEx()

BOOL PeekMessageEx	(	PMSG	pMsg,
		HWND	hWnd,
		UINT	nMsgFilterMin,
		UINT	nMsgFilterMax,
		BOOL	bWait,
		UINT	uRemoveMsg
	)

Peek a message from the message queue of a main window.

This function peeks a message from the message queue of the window hWnd; if bWait is TRUE, it will wait for the message, else return immediatly.

Parameters

pMsg	Pointer to the result message.
hWnd	The handle to the window.
nMsgFilterMin	The min identifier of the message that should be peeked.
nMsgFilterMax	The max identifier of the message that should be peeked.
bWait	Whether to wait for a message.
uRemoveMsg	Whether remove the message from the message queue. Should be the following values: PM_NOREMOVE Leave it in the message queue. PM_REMOVE Remove it from the message queue. PM_NOYIELD Nouse now.

Returns: TRUE if there is a message peeked, or FALSE.

See also: GetMessage, PeekPostMessage, HavePendingMessage, PostMessage

◆ PeekPostMessage()

BOOL PeekPostMessage	(	PMSG	pMsg,
		HWND	hWnd,
		UINT	nMsgFilterMin,
		UINT	nMsgFilterMax,
		UINT	uRemoveMsg
	)

Peek a post message from the message queue of a main window.

This function peeks a message from the message queue of the window hWnd and returns immediatly. Unlike PeekMessage, this function only peek a post message.

Parameters

pMsg	Pointer to the result message.
hWnd	The handle to the window.
nMsgFilterMin	The min identifier of the message that should be peeked.
nMsgFilterMax	The max identifier of the message that should be peeked.
uRemoveMsg	Whether remove the message from the message queue. Should be the following values: PM_NOREMOVE Leave it in the message queue. PM_REMOVE Remove it from the message queue. PM_NOYIELD Nouse now.

Returns: TRUE if there is a message peeked, or FALSE.

See also: GetMessage, PeekMessage, HavePendingMessage, PostMessage

◆ PostMessage()

int PostMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Posts a message into the message queue of a window and returns immediatly.

This function posts a message into the message queue of the window hWnd and returns immediately.

Parameters

hWnd	The handle to the window.
nMsg	The identifier of the message.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: ERR_OK on success, < 0 on errors.

Return values

ERR_OK	Post message successfully.
ERR_QUEUE_FULL	The message queue is full.
ERR_INV_HWND	Invalid window handle.

See also: SendMessage

◆ PostQuitMessage()

int PostQuitMessage ( HWND hWnd )

Puts a MSG_QUIT message into the message queue of a main window.

This function puts a MSG_QUIT message into the message queue of the main window hWnd. The next call to GetMessage will return 0.

Parameters

hWnd	The handle to the main window.

Returns: 0 if all OK, < 0 on error.

See also: GetMessage

◆ PostSyncMessage()

LRESULT PostSyncMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Post a synchronical message to a window which is in different thread.

This function posts the synchronical message specified by (nMsg, wParam, lParam) to the window hWnd which is in a different thread. This function will return until the message is handled by the window procedure of that window.

Note: The destination window must belong to other thread.

Parameters

hWnd	The handle to the window.
nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: The return value of the message handler.

See also: SendMessage

◆ SendAsyncMessage()

LRESULT SendAsyncMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Send an asynchronical message to a window.

This function sends the asynchronical message specified by (nMsg, wParam, lParam) to the window hWnd which might be in a different thread. This function calls the window procedure immediately, so it is very dangerous. You should make sure that the message handler is thread safe.

Parameters

hWnd	The handle to the window.
nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: The return value of the message handler.

Note: This function may corrupt your data.

See also: PostSyncMessage

◆ SendMessage()

LRESULT SendMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Send a message to a window and wait for the handling result.

This function sends a message to the window hWnd, and will return until the message-handling process returns.

Parameters

hWnd	The handle to the window.
nMsg	The identifier of the message.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: The return value of the message handler. Two special return values are reserved for the errors:

Return values

ERR_INV_HWND	Invalid window handle.
ERR_MSG_CANCELED	The message handling was canceled by the target window. This may occur when the target window which is running in another thread is destroyed.

Note: The special return values are negative prime numbers (-2 and -3). Therefore, it is safe if you return a valid 4- or 8-byte aligned pointer value for the successful result. If you use a negative numbers to indicate the error status of your message handler, please choose a different value other than -2 or -3.

See also: PostMessage

◆ SendNotifyMessage()

int SendNotifyMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Send a notification message to a window.

This function sends the notification message specified by (nMsg, wParam, lParam) to the window hWnd. This function puts the notification message at the tail of the message queue and returns immediately.

Parameters

hWnd	The handle to the window.
nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: 0 if all OK, < 0 on error.

See also: SendMessage, PostMessage

◆ SendPriorNotifyMessage()

int SendPriorNotifyMessage	(	HWND	hWnd,
		UINT	nMsg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Send a prior notification message to a window.

This function sends the notification message specified by (nMsg, wParam, lParam) to the window hWnd. This function puts the notification message at the head of the message queue and returns immediately.

Parameters

hWnd	The handle to the window.
nMsg	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Returns: 0 if all OK, < 0 on error.

See also: SendMessage, PostMessage

◆ SetAutoRepeatMessage()

void GUIAPI SetAutoRepeatMessage	(	HWND	hwnd,
		UINT	msg,
		WPARAM	wParam,
		LPARAM	lParam
	)

Set the auto-repeat message.

This function sets the auto-repeat message. When the default message procedure receives an MSG_IDLE message, the default handler will send the auto-repeat message to the target window as a notification message.

Parameters

hwnd	The handle to the target window. Set it to zero to disable the auto-repeat message.
msg	The identifier of the auto-repeat message.
wParam	The first parameter of the auto-repeat message.
lParam	The second parameter of the auto-repeat message.

◆ SetKeyboardLayout()

BOOL SetKeyboardLayout ( const char * kbd_layout )

Set a new keyboard layout.

This function sets the keymaps to translate key scancodes to MSG_CHAR or MSG_KEYSYM messages. The default keymaps is for US PC keyboard layout, you can call this function to set a different keyboard layout. The argument of kbd_layout specifies the name of the keyboard layout.

Parameters

kbd_layout The keyboard layout name. It can be one of the following values:

KBD_LAYOUT_DEFAULT
The default keyboard layout, i.e., US PC.
KBD_LAYOUT_FRPC
The France PC keyboard layout.
KBD_LAYOUT_FR
The France keyboard layout.
KBD_LAYOUT_DE
The German keyboard layout.
KBD_LAYOUT_DELATIN1
The German Latin1 keyboard layout.
KBD_LAYOUT_IT
The Italian keyboard layout.
KBD_LAYOUT_ES
The Spanish keyboard layout.
KBD_LAYOUT_ESCP850
The Spanish CP850 keyboard layout.
KBD_LAYOUT_HEBREW
The hebrew keyboard layout.
KBD_LAYOUT_ARABIC
The arabic keyboard layout.

Returns: TRUE for success, otherwise FALSE.

See also: TranslateMessage, MSG_CHAR, MSG_KEYSYM

◆ ThrowAwayMessages()

int ThrowAwayMessages ( HWND pMainWnd )

Removes all messages in the message queue associated with a window.

This function removes all messages which are associated with the specified window pMainWnd.

Parameters

pMainWnd The handle to the window.

Returns: The number of thrown messages.

See also: EmptyMessageQueue

◆ TranslateKeyMsgToChar()

BOOL GUIAPI TranslateKeyMsgToChar	(	int	message,
		WPARAM	wParam,
		LPARAM	lParam,
		WORD *	ch
	)

Translates a key down and key up message to a corresponding character.

This function translates a key down and key up message to a character. If the message is not a key message, this function does nothing.

The behavior of this function is inflected by the current keyboard layout. The default keyboard layout is US PC keyboard, but you can call SetKeyboardLayout function to set a different keyboard layout.

Parameters

message	The type of message.
wParam	Message parameter.
lParam	Message parameter.
ch	A string buffer for storing translated characters.

Returns: A boolean indicates whether the message is a key message.

See also: TranslateMessage

◆ TranslateMessage()

BOOL TranslateMessage ( PMSG pMsg )

Translates key down and key up messages to MSG_CHAR message and post it into the message queue.

This function translates key down and key up message to an MSG_CHAR message or some MSG_KEYSYM messages, and send the message(s) to the window procedure as a notification message. If the message is not a key message, this function does nothing.

The behavior of this function is inflected by the current keyboard layout. The default keyboard layout is US PC keyboard, but you can call SetKeyboardLayout function to set a different keyboard layout.

Parameters

pMsg	The pointer of message.

Returns: A boolean indicates whether the message is a key message.

See also: SetKeyboardLayout, MSG_CHAR, MSG_KEYSYM

◆ WaitMessage()

BOOL WaitMessage	(	PMSG	pMsg,
		HWND	hMainWnd
	)

Wait for a message from the message queue of a main window.

This function waits for a message from the message queue of the main window hMainWnd, and returns until there is a message in the message queue. Unlike GetMessage, this function does not remove the message from the message queue.

Parameters

pMsg	Pointer to the result message.
hMainWnd	Handle to the window.

Returns: 0 on MSG_QUIT have been found, else gets a message.

See also: HavePendingMessage, PostQuitMessage, MSG

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PM_NOREMOVE

◆ PM_NOYIELD

◆ PM_REMOVE

Typedef Documentation

◆ MSG

Function Documentation

◆ BroadcastMessage()

◆ BroadcastMessageInThisThread()

◆ DispatchMessage()

◆ EmptyMessageQueue()

◆ GetMessage()

◆ HavePendingMessage()

◆ NotifyWindow()

◆ PeekMessage()

◆ PeekMessageEx()

◆ PeekPostMessage()

◆ PostMessage()

◆ PostQuitMessage()

◆ PostSyncMessage()

◆ SendAsyncMessage()

◆ SendMessage()

◆ SendNotifyMessage()

◆ SendPriorNotifyMessage()

◆ SetAutoRepeatMessage()

◆ SetKeyboardLayout()

◆ ThrowAwayMessages()

◆ TranslateKeyMsgToChar()

◆ TranslateMessage()

◆ WaitMessage()