mirror of
https://github.com/VincentWei/MiniGUI.git
synced 2026-02-06 18:31:57 +08:00
declare NotifyWindow and MSG_NOTIFICATION; tune description words
This commit is contained in:
Vincent Wei
194
include/window.h
194
include/window.h
@@ -2478,14 +2478,16 @@ typedef struct _WINMASKINFO {
|
||||
* \param hwnd The handle to the control.
|
||||
*
|
||||
* \note If you use `MSG_COMMAND` message to handle the notification
|
||||
* sent from children controls, you should make sure the identifier
|
||||
* value is small enough on 64-bit platform. If you use a pointer
|
||||
* as the the identifier of a control, the code above will not work.
|
||||
* sent from other windows, you should make sure the identifier
|
||||
* value and the notification code do not exceed half of the maximal
|
||||
* value of a DWORD (32-bit on 64-bit platform, and 16-bit on 32-bit
|
||||
* platform). If you use a pointer as the identifier,
|
||||
* the code above will not work.
|
||||
*
|
||||
* Instead, we recommend strongly that you use a NOTIFYPOROC
|
||||
* callback to handle the notification generated by controls.
|
||||
* Instead, we recommend strongly that you use a NOTIFYPOROC
|
||||
* callback to handle the notification generated by a window.
|
||||
*
|
||||
* \sa NotifyParentEx
|
||||
* \sa NotifyWindow, NotifyParentEx, SetNotificationCallback
|
||||
*/
|
||||
#define MSG_COMMAND 0x0120
|
||||
|
||||
@@ -2803,6 +2805,31 @@ typedef struct _WINMASKINFO {
|
||||
*/
|
||||
#define MSG_ENABLE 0x0135
|
||||
|
||||
/**
|
||||
* \def MSG_NOTIFICATION
|
||||
* \brief Indicate a notification message.
|
||||
*
|
||||
* This message is an internal message which indicates the message is a
|
||||
* notification sent by calling \a NotifyWindow or \a NotifyParentEx functions.
|
||||
*
|
||||
* For this message, \a DispatchMessage function will call the notification
|
||||
* callback procedure if the target window has been set the notification
|
||||
* callback procedure, or convert the message to a MSG_COMMAND message and
|
||||
* pass it to the window procedure.
|
||||
*
|
||||
* \code
|
||||
* MSG_NOTIFICATION
|
||||
* LINT id = (LINT)wParam;
|
||||
* int nc = (int)lParam;
|
||||
* DWORD adData = msg->time;
|
||||
* \endcode
|
||||
*
|
||||
* Since 5.0.0.
|
||||
*
|
||||
* \sa MSG_COMMAND, SetNotificationCallback, NotifyWindow, NotifyParentEx
|
||||
*/
|
||||
#define MSG_NOTIFICATION 0x0136
|
||||
|
||||
#define MSG_LASTCONTROLMSG 0x013F
|
||||
|
||||
/** @} end of ctrl_msgs */
|
||||
@@ -3063,15 +3090,18 @@ typedef struct _MSG
|
||||
HWND hwnd;
|
||||
/** The message identifier. */
|
||||
UINT message;
|
||||
/** The first parameter of the message (a unsigned integer with pointer precision). */
|
||||
/** The first parameter of the message
|
||||
(a unsigned integer with pointer precision). */
|
||||
WPARAM wParam;
|
||||
/** The second parameter of the message (a unsigned integer with pointer precision). */
|
||||
/** The second parameter of the message
|
||||
(a unsigned integer with pointer precision). */
|
||||
LPARAM lParam;
|
||||
/** Time */
|
||||
/** Time (ticks when the message generated);
|
||||
reuse for the additional data of a notification. */
|
||||
DWORD time;
|
||||
#ifdef _MGHAVE_VIRTUAL_WINDOW
|
||||
/** Addtional data*/
|
||||
void* pAdd;
|
||||
/* pointer to the sync MSG (internal use) */
|
||||
void* pSyncMsg;
|
||||
#endif
|
||||
} MSG;
|
||||
typedef MSG* PMSG;
|
||||
@@ -3101,9 +3131,9 @@ typedef MSG* PMSG;
|
||||
* \fn BOOL PeekMessageEx (PMSG pMsg, HWND hWnd, \
|
||||
* UINT nMsgFilterMin, UINT nMsgFilterMax, \
|
||||
* BOOL bWait, UINT uRemoveMsg)
|
||||
* \brief Peeks a message from the message queue of a main window.
|
||||
* \brief Peek a message from the message queue of a main window.
|
||||
*
|
||||
* This functions peek a message from the message queue of the window \a hWnd;
|
||||
* This function peeks a message from the message queue of the window \a hWnd;
|
||||
* if \a bWait is TRUE, it will wait for the message, else return immediatly.
|
||||
*
|
||||
* \param pMsg Pointer to the result message.
|
||||
@@ -3130,7 +3160,7 @@ MG_EXPORT BOOL GUIAPI PeekMessageEx (PMSG pMsg, HWND hWnd,
|
||||
|
||||
/**
|
||||
* \fn BOOL GetMessage (PMSG pMsg, HWND hMainWnd)
|
||||
* \brief Gets a message from the message queue of a main window.
|
||||
* \brief Get a message from the message queue of a main window.
|
||||
*
|
||||
* This function gets a message from the message queue of the main window
|
||||
* \a hMainWnd, and returns until there is a message in the message queue.
|
||||
@@ -3153,7 +3183,7 @@ static inline BOOL GUIAPI GetMessage (PMSG pMsg, HWND hWnd)
|
||||
|
||||
/**
|
||||
* \fn BOOL WaitMessage (PMSG pMsg, HWND hMainWnd)
|
||||
* \brief Waits for a message from the message queue of a main window.
|
||||
* \brief 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 \a hMainWnd, and returns until there is a message in the message
|
||||
@@ -3188,9 +3218,9 @@ MG_EXPORT BOOL GUIAPI HavePendingMessage (HWND hMainWnd);
|
||||
/**
|
||||
* \fn BOOL PeekMessage (PMSG pMsg, HWND hWnd, \
|
||||
* UINT nMsgFilterMin, UINT nMsgFilterMax, UINT uRemoveMsg)
|
||||
* \brief Peeks a message from the message queue of a main window
|
||||
* \brief Peek a message from the message queue of a main window
|
||||
*
|
||||
* This functions peek a message from the message queue of the window \a hWnd
|
||||
* This function peeks a message from the message queue of the window \a hWnd
|
||||
* and returns immediatly. Unlike \a GetMessage, this function does not wait
|
||||
* for a message.
|
||||
*
|
||||
@@ -3219,11 +3249,11 @@ static inline BOOL GUIAPI PeekMessage (PMSG pMsg, HWND hWnd, UINT nMsgFilterMin,
|
||||
}
|
||||
|
||||
/**
|
||||
* \fn BOOL PeekPostMessage (PMSG pMsg, HWND hWnd, \
|
||||
* \fn BOOL PeekPostMessage (PMSG pMsg, HWND hWnd,
|
||||
UINT nMsgFilterMin, UINT nMsgFilterMax, UINT uRemoveMsg)
|
||||
* \brief Peeks a post message from the message queue of a main window
|
||||
* \brief Peek a post message from the message queue of a main window
|
||||
*
|
||||
* This functions peek a message from the message queue of the window \a hWnd
|
||||
* This function peeks a message from the message queue of the window \a hWnd
|
||||
* and returns immediatly. Unlike \a PeekMessage, this function only peek a
|
||||
* post message.
|
||||
*
|
||||
@@ -3252,7 +3282,7 @@ MG_EXPORT BOOL GUIAPI PeekPostMessage (PMSG pMsg, HWND hWnd, UINT nMsgFilterMin,
|
||||
* \brief 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 \a hWnd
|
||||
* This function posts a message into the message queue of the window \a hWnd
|
||||
* and returns immediately.
|
||||
*
|
||||
* \param hWnd The handle to the window.
|
||||
@@ -3290,7 +3320,7 @@ MG_EXPORT LRESULT GUIAPI SendMessage (HWND hWnd, UINT nMsg,
|
||||
WPARAM wParam, LPARAM lParam);
|
||||
|
||||
/**
|
||||
* \fn void GUIAPI SetAutoRepeatMessage (HWND hwnd, UINT msg, \
|
||||
* \fn void GUIAPI SetAutoRepeatMessage (HWND hwnd, UINT msg,
|
||||
WPARAM wParam, LPARAM lParam)
|
||||
* \brief Sets the auto-repeat message.
|
||||
*
|
||||
@@ -3348,7 +3378,7 @@ int GUIAPI Send2Client (const MSG* msg, int cli);
|
||||
|
||||
/**
|
||||
* \fn BOOL Send2TopMostClients (UINT nMsg, WPARAM wParam, LPARAM lParam)
|
||||
* \brief Sends a message to all clients in the topmost layer.
|
||||
* \brief Send a message to all clients in the topmost layer.
|
||||
*
|
||||
* This function sends the message specified by (\a nMsg, \a wParam, \a lParam)
|
||||
* to all clients in the topmost layer.
|
||||
@@ -3368,9 +3398,9 @@ int GUIAPI Send2Client (const MSG* msg, int cli);
|
||||
BOOL GUIAPI Send2TopMostClients (UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
|
||||
/**
|
||||
* \fn BOOL Send2ActiveWindow (const MG_Layer* layer, \
|
||||
UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
* \brief Sends a message to the active window in layer.
|
||||
* \fn BOOL Send2ActiveWindow (const MG_Layer* layer,
|
||||
* UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
* \brief Send a message to the active window in a layer.
|
||||
*
|
||||
* This function sends the message specified by (\a nMsg, \a wParam, \a lParam)
|
||||
* to the current active window in the specific layer (\a layer).
|
||||
@@ -3395,13 +3425,14 @@ BOOL GUIAPI Send2ActiveWindow (const MG_Layer* layer,
|
||||
#ifdef _MGHAVE_VIRTUAL_WINDOW
|
||||
|
||||
/**
|
||||
* \fn LRESULT PostSyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
|
||||
* \brief Posts a synchronical message to a window which is in different thread.
|
||||
* \fn LRESULT PostSyncMessage (HWND hWnd, UINT nMsg,
|
||||
* WPARAM wParam, LPARAM lParam)
|
||||
* \brief Post a synchronical message to a window which is in different thread.
|
||||
*
|
||||
* This function posts the synchronical message specified by
|
||||
* (\a nMsg, \a wParam, \a lParam) to the window \a hWnd which
|
||||
* is in different thread. This function will return until
|
||||
* the message is handled by the window procedure.
|
||||
* 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.
|
||||
*
|
||||
@@ -3414,16 +3445,19 @@ BOOL GUIAPI Send2ActiveWindow (const MG_Layer* layer,
|
||||
*
|
||||
* \sa SendMessage
|
||||
*/
|
||||
MG_EXPORT LRESULT GUIAPI PostSyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
MG_EXPORT LRESULT GUIAPI PostSyncMessage (HWND hWnd, UINT nMsg,
|
||||
WPARAM wParam, LPARAM lParam);
|
||||
|
||||
/**
|
||||
* \fn LRESULT SendAsyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
|
||||
* \fn LRESULT SendAsyncMessage (HWND hWnd, UINT nMsg,
|
||||
* WPARAM wParam, LPARAM lParam)
|
||||
* \brief Sends an asynchronical message to a window.
|
||||
*
|
||||
* This function sends the asynchronical message specified by
|
||||
* (\a nMsg, \a wParam, \a lParam) to the window \a hWnd
|
||||
* which is in different thread. This function calls
|
||||
* 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.
|
||||
*
|
||||
* \param hWnd The handle to the window.
|
||||
* \param nMsg The message identifier.
|
||||
@@ -3436,13 +3470,14 @@ MG_EXPORT LRESULT GUIAPI PostSyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, L
|
||||
*
|
||||
* \sa PostSyncMessage
|
||||
*/
|
||||
MG_EXPORT LRESULT GUIAPI SendAsyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
MG_EXPORT LRESULT GUIAPI SendAsyncMessage (HWND hWnd, UINT nMsg,
|
||||
WPARAM wParam, LPARAM lParam);
|
||||
|
||||
#else /* defined _MGHAVE_VIRTUAL_WINDOW */
|
||||
|
||||
/**
|
||||
* \def SendAsyncMessage
|
||||
* \brief Is an alias of \a SendMessage if _MGHAVE_VIRTUAL_WINDOW
|
||||
* \brief An alias of \a SendMessage if _MGHAVE_VIRTUAL_WINDOW
|
||||
* is not enabled.
|
||||
*
|
||||
* \sa SendMessage
|
||||
@@ -3452,12 +3487,13 @@ MG_EXPORT LRESULT GUIAPI SendAsyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam,
|
||||
#endif /* not defined _MGHAVE_VIRTUAL_WINDOW */
|
||||
|
||||
/**
|
||||
* \fn int SendNotifyMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
|
||||
* \fn int SendNotifyMessage (HWND hWnd, UINT nMsg,
|
||||
* WPARAM wParam, LPARAM lParam)
|
||||
* \brief Sends a notification message to a window.
|
||||
*
|
||||
* This function sends the notification message specified by
|
||||
* (\a nMsg, \a wParam, \a lParam) to the window \a hWnd. This function
|
||||
* puts the notication message in the message queue and then returns
|
||||
* puts the notification message in the message queue and then returns
|
||||
* immediately.
|
||||
*
|
||||
* \param hWnd The handle to the window.
|
||||
@@ -3469,7 +3505,37 @@ MG_EXPORT LRESULT GUIAPI SendAsyncMessage (HWND hWnd, UINT nMsg, WPARAM wParam,
|
||||
*
|
||||
* \sa SendMessage, PostMessage
|
||||
*/
|
||||
MG_EXPORT int GUIAPI SendNotifyMessage (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam);
|
||||
MG_EXPORT int GUIAPI SendNotifyMessage (HWND hWnd, UINT nMsg,
|
||||
WPARAM wParam, LPARAM lParam);
|
||||
|
||||
/**
|
||||
* \fn int GUIAPI NotifyWindow (HWND hWnd, LINT id, int code, DWORD dwAddData)
|
||||
* \brief Send a notification message to a window.
|
||||
*
|
||||
* This function sends a notification message to the target window \a 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.
|
||||
*
|
||||
* \param hWnd The handle to target window.
|
||||
* \param id The identifier of the source.
|
||||
* \param code The notification code.
|
||||
* \param dwAddData The additional data of the notification.
|
||||
*
|
||||
* \return 0 if all OK, < 0 on error.
|
||||
*
|
||||
* \sa MSG_COMMAND, MSG_NOTIFICATION, SetNotificationCallback
|
||||
*
|
||||
* Since 5.0.0
|
||||
*/
|
||||
MG_EXPORT int GUIAPI NotifyWindow (HWND hWnd, LINT id, int code,
|
||||
DWORD dwAddData);
|
||||
|
||||
/**
|
||||
* \fn int BroadcastMessage (UINT nMsg, WPARAM wParam, LPARAM lParam)
|
||||
@@ -4802,14 +4868,21 @@ typedef LRESULT (* WNDPROC)(HWND, UINT, WPARAM, LPARAM);
|
||||
* \var typedef void (* NOTIFPROC)(HWND hwnd, LINT id, int nc, DWORD add_data)
|
||||
* \brief Type of the notification callback procedure.
|
||||
*
|
||||
* This is the function type of Notification Callback Procedure.
|
||||
* If you set the Notification Callback Procedure for a control,
|
||||
* when a notification occurred the control will call this callback
|
||||
* procedure.
|
||||
* This is the function type of notification callback procedure.
|
||||
* If you set the notification callback procedure for a window.
|
||||
* When MiniGUI got a notification message, MiniGUI will call this
|
||||
* callback procedure in the context of the target window thread.
|
||||
*
|
||||
* If you have not set the notification callback procedure of the target
|
||||
* window, MiniGUI will send a MSG_COMMAND message to the window procedure.
|
||||
*
|
||||
* Since 5.0.0, you can also set the notification callback procedure for
|
||||
* a main window or a virtual window. You can call \a NotifyWindow function
|
||||
* to send a notify message to the traget window.
|
||||
*
|
||||
* \note The type of \a id changed from int to LINT since v3.2.
|
||||
*
|
||||
* \sa SetNotificationCallback
|
||||
* \sa SetNotificationCallback, NotifyWindow, NotifyParentEx
|
||||
*/
|
||||
typedef void (* NOTIFPROC) (HWND hwnd, LINT id, int nc, DWORD add_data);
|
||||
|
||||
@@ -9390,30 +9463,39 @@ static inline HWND GUIAPI CreateWindowEx (const char* spClassName,
|
||||
MG_EXPORT BOOL GUIAPI DestroyWindow (HWND hWnd);
|
||||
|
||||
/**
|
||||
* \fn NOTIFPROC GUIAPI SetNotificationCallback (HWND hwnd, \
|
||||
* NOTIFPROC notif_proc)
|
||||
* \brief Sets a new notification callback procedure for a control.
|
||||
* \fn NOTIFPROC GUIAPI SetNotificationCallback (HWND hwnd,
|
||||
* NOTIFPROC notif_proc)
|
||||
* \brief Set a new notification callback procedure for a window.
|
||||
*
|
||||
* This function sets the new notification callback procedure (\a notif_proc)
|
||||
* for the control of \a hwnd.
|
||||
* for the specified window \a hwnd.
|
||||
*
|
||||
* By default, the notification from a control will be sent to its parent
|
||||
* window within a MSG_COMMAND messsage.
|
||||
* In the early versions, the notification message will be sent to
|
||||
* the target window as a MSG_COMMAND message.
|
||||
*
|
||||
* Since version 1.2.6, MiniGUI defines the Notification Callback Procedure
|
||||
* for control. You can specify a callback function for a control by calling
|
||||
* for a window. You can specify a callback function for a window by calling
|
||||
* \a SetNotificationCallback to receive and handle the notifications from
|
||||
* the control.
|
||||
* its children in the procedure.
|
||||
*
|
||||
* If you did not set the notification callback function for a control,
|
||||
* the notification will be sent to its parent as same as the earlier
|
||||
* version of MiniGUI.
|
||||
* Since version 5.0.0, the notification callback procedure also works for
|
||||
* a main window or a virtual window.
|
||||
*
|
||||
* \param hwnd The handle to the control.
|
||||
* If you did not set the notification callback function of the target window,
|
||||
* you must handle MSG_COMMAND message in the window procedure of the
|
||||
* target window. However, due to historical reasons, MSG_COMMAND has
|
||||
* the following restrictions:
|
||||
* - The additional data you specified when calling \a NotifyWindow or
|
||||
* \a NotifyParentEx will be lost.
|
||||
* - The value of the identifier and the notification code cannot exceed
|
||||
* a WORD.
|
||||
*
|
||||
* \param hwnd The handle to the window.
|
||||
* \param notif_proc The new notification callback procedure, can be NULL.
|
||||
*
|
||||
* \return The old notification callback procedure.
|
||||
*
|
||||
* \sa NOTIFPROC, GetNotificationCallback
|
||||
* \sa NOTIFPROC, GetNotificationCallback, NotifyWindow, NotifyParentEx
|
||||
*/
|
||||
MG_EXPORT NOTIFPROC GUIAPI SetNotificationCallback (HWND hwnd,
|
||||
NOTIFPROC notif_proc);
|
||||
|
||||
Reference in New Issue
Block a user