MiniGUI API Reference (MiniGUI-Threads)  v5.0.6
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)
 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
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

◆ 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
nMsgThe message identifier.
wParamThe first parameter of the message.
lParamThe 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
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)) {
}

◆ 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
hWndThe 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
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 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
hMainWndThe 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
hWndThe handle to target window.
idThe identifier of the source.
codeThe notification code.
dwAddDataThe 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
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 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
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

◆ 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
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

◆ 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
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

◆ 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
hWndThe 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
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

◆ 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
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

◆ 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
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. Two special return values are reserved for the errors:
Return values
ERR_INV_HWNDInvalid window handle.
ERR_MSG_CANCELEDThe 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
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

◆ 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
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

◆ 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
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.

◆ 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_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

◆ 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
pMainWndThe 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
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

◆ 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
pMsgThe 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
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
TranslateMessage
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.
CreateMainWindow
static HWND GUIAPI CreateMainWindow(PMAINWINCREATE pCreateInfo)
A simplified version of CreateMainWindowEx.
Definition: window.h:7046
HWND
GHANDLE HWND
Handle to main window or control.
Definition: common.h:407
_MAINWINCREATE
Definition: window.h:6761
_MSG
Definition: window.h:3148
HWND_INVALID
#define HWND_INVALID
Invalid window handle.
Definition: window.h:6754
GetMessage
static BOOL GUIAPI GetMessage(PMSG pMsg, HWND hWnd)
Get a message from the message queue of a main window.
Definition: window.h:3240
DispatchMessage
MG_EXPORT LRESULT GUIAPI DispatchMessage(PMSG pMsg)
Dispatches a message to the window's callback procedure.