MiniGUI API Reference (MiniGUI-Threads)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Data Structures | Macros | Typedefs | Functions
Message passing functions

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)
 Peeks a message from the message queue of a main window. More...
 
static BOOL GUIAPI GetMessage (PMSG pMsg, HWND hWnd)
 Gets a message from the message queue of a main window. More...
 
MG_EXPORT BOOL GUIAPI WaitMessage (PMSG pMsg, HWND hMainWnd)
 Waits for a message from the message queue of a main window. More...
 
MG_EXPORT BOOL GUIAPI HavePendingMessage (HWND hMainWnd)
 Checks 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)
 Peeks 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)
 Peeks 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)
 Sends a message to a window. More...
 
MG_EXPORT void GUIAPI SetAutoRepeatMessage (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
 Sets the auto-repeat message. More...
 
MG_EXPORT LRESULT GUIAPI PostSyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
 Posts 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)
 Sends an asynchronical message to a window. More...
 
MG_EXPORT int GUIAPI SendNotifyMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
 Sends a notification message to a window. More...
 
MG_EXPORT int GUIAPI BroadcastMessage (UINT nMsg, WPARAM wParam, LPARAM lParam)
 Broadcasts a message to all main window on the desktop. 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)
 Sets 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...
 

Detailed Description

Macro Definition Documentation

#define PM_NOREMOVE   0x0000
See also
PeekMessage PeekMessageEx

Definition at line 2262 of file window.h.

#define PM_NOYIELD   0x0002
See also
PeekMessage PeekMessageEx PeekPostMessage

Definition at line 2276 of file window.h.

#define PM_REMOVE   0x0001
See also
PeekMessage PeekMessageEx PeekPostMessage

Definition at line 2269 of file window.h.

Referenced by GetMessage().

Typedef Documentation

typedef struct _MSG MSG

The message structure.

See also
GetMessage, PostMessage, Messages

Function Documentation

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

Broadcasts a message to all main window on the desktop.

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

Parameters
nMsgThe message identifier.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
0 if all OK, < 0 on error.
See also
PostMessage

Referenced by PeekMessage().

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
pMsgThe 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)) {
}

Referenced by PeekMessage().

BOOL GetMessage ( PMSG  pMsg,
HWND  hMainWnd 
)
inlinestatic

Gets 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
pMsgPointer to the result message.
hMainWndHandle 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)) {
}

Definition at line 2327 of file window.h.

References HavePendingMessage(), PeekMessageEx(), PM_REMOVE, TRUE, and WaitMessage().

BOOL HavePendingMessage ( HWND  hMainWnd)

Checks 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
hMainWndThe handle to the main window.
Returns
TRUE for pending message, FALSE for empty message queue.
See also
GetMessage, MSG

Referenced by GetMessage().

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

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

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

Parameters
pMsgPointer to the result message.
hWndThe handle to the window.
nMsgFilterMinThe min identifier of the message that should be peeked.
nMsgFilterMaxThe max identifier of the message that should be peeked.
uRemoveMsgWhether 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 2392 of file window.h.

References BroadcastMessage(), DispatchMessage(), FALSE, PeekMessageEx(), PeekPostMessage(), PostMessage(), PostQuitMessage(), PostSyncMessage(), SendAsyncMessage(), SendMessage(), SendNotifyMessage(), SetAutoRepeatMessage(), SetKeyboardLayout(), ThrowAwayMessages(), TranslateKeyMsgToChar(), and TranslateMessage().

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

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

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

Parameters
pMsgPointer to the result message.
hWndThe handle to the window.
nMsgFilterMinThe min identifier of the message that should be peeked.
nMsgFilterMaxThe max identifier of the message that should be peeked.
bWaitWhether to wait for a message.
uRemoveMsgWhether 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

Referenced by GetMessage(), and PeekMessage().

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

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

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

Parameters
pMsgPointer to the result message.
hWndThe handle to the window.
nMsgFilterMinThe min identifier of the message that should be peeked.
nMsgFilterMaxThe max identifier of the message that should be peeked.
uRemoveMsgWhether 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

Referenced by PeekMessage().

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

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

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

Parameters
hWndThe handle to the window.
nMsgThe identifier of the message.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
ERR_OK on success, < 0 on errors.
Return values
ERR_OKPost message successfully.
ERR_QUEUE_FULLThe message queue is full.
ERR_INV_HWNDInvalid window handle.
See also
SendMessage

Referenced by PeekMessage().

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
hWndThe handle to the main window.
Returns
0 if all OK, < 0 on error.
See also
GetMessage

Referenced by PeekMessage().

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

Posts 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 different thread. This function will return until the message is handled by the window procedure.

Note
The destination window must belong to other thread.
Parameters
hWndThe handle to the window.
nMsgThe message identifier.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
The return value of the message handler.
See also
SendMessage

Referenced by PeekMessage().

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

Sends an asynchronical message to a window.

This function sends the asynchronical message specified by (nMsg, wParam, lParam) to the window hWnd which is in different thread. This function calls the window procedure immediately, so it is very dangerous.

Parameters
hWndThe handle to the window.
nMsgThe message identifier.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
The return value of the message handler.
Note
This function may corrupt your data.
See also
PostSyncMessage

Referenced by PeekMessage().

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

Sends a message to a window.

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

Parameters
hWndThe handle to the window.
nMsgThe identifier of the message.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
The return value of the message handler.
See also
PostMessage

Referenced by PeekMessage().

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

Sends 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 notication message in the message queue and then returns immediately.

Parameters
hWndThe handle to the window.
nMsgThe message identifier.
wParamThe first parameter of the message.
lParamThe second parameter of the message.
Returns
0 if all OK, < 0 on error.
See also
SendMessage, PostMessage

Referenced by PeekMessage().

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

Sets 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
hwndThe handle to the target window. Set it to zero to disable the auto-repeat message.
msgThe identifier of the auto-repeat message.
wParamThe first parameter of the auto-repeat message.
lParamThe second parameter of the auto-repeat message.

Referenced by PeekMessage().

BOOL SetKeyboardLayout ( const char *  kbd_layout)

Sets 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_layoutThe 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

Referenced by PeekMessage().

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
pMainWndThe handle to the window.
Returns
The number of thrown messages.
See also
EmptyMessageQueue

Referenced by PeekMessage().

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
messageThe type of message.
wParamMessage parameter.
lParamMessage parameter.
chA string buffer for storing translated characters.
Returns
A boolean indicates whether the message is a key message.
See also
TranslateMessage

Referenced by PeekMessage().

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
pMsgThe pointer of message.
Returns
A boolean indicates whether the message is a key message.
See also
SetKeyboardLayout, MSG_CHAR, MSG_KEYSYM

Referenced by PeekMessage().

BOOL WaitMessage ( PMSG  pMsg,
HWND  hMainWnd 
)

Waits 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
pMsgPointer to the result message.
hMainWndHandle to the window.
Returns
0 on MSG_QUIT have been found, else gets a message.
See also
HavePendingMessage, PostQuitMessage, MSG

Referenced by GetMessage().