int InstallWinMsgCallback (int panelHandle, int messageNumber, WinMsgCallback callbackFunction, int callbackMode, void *callbackData, int *postingHandle);
Installs a callback function for a specific Windows message posted or sent to a LabWindows/CVI panel. A call to ProcessSystemEvents or RunUserInterface causes the panel to receive the message, and the specified callback function will be passed the message data.
You must include windows.h in your source code if you use Windows constants such as WM_CLOSE, WM_PAINT, and so on to denote the message numbers. You can install the same callback function to intercept more than one Windows message by calling InstallWinMsgCallback once for each message and passing the callback function's address in each call. After you finish intercepting messages, call RemoveWinMsgCallback to uninstall the callback functions that were installed using the InstallWinMsgCallback function, and free associated memory.
![]() |
Note Windows Messaging is a complicated paradigm, and some things may not work as expected. This is especially true when intercepting messages such as WM_PAINT that occur very frequently during an application's lifetime. Note that these messages are correctly handled by the internal Window Procedures, and that anomalies may be seen when trying to intercept and handle them externally. |
![]() |
Note A message callback cannot be installed for a LabWindows/CVI child panel. In your programs, do not mix the message callback functions with the routing functions in the Route Messages sub–class, as they use different window 'subclassing' mechanisms. |
int CVICALLBACK MyCallback (int panelHandle, int message, unsigned int* wParam, unsigned int* lParam, void* callbackData);
int panelHandle;
int postHandle;
void main (void)
{
if ((panelHandle = LoadPanel (0, "MyUIR.uir", PANEL)) < 0)
return;
/* To intercept the WM_CLOSE message with MyCallback */
InstallWinMsgCallback (panelHandle, WM_CLOSE,
MyCallback, VAL_MODE_INTERCEPT, NULL, &postHandle);
........
/* Uninstall the event handler and free associated memory */
RemoveWinMsgCallback (panelHandle, WM_CLOSE);
}
Input | ||||
Name | Type | Description | ||
panelHandle | integer | The handle of the CVI panel for which you wish to install a Windows message callback function. | ||
messageNumber | integer | The number of the message for which you would like to install a callback function.
|
||
callbackFunction | WinMsgCallback | The callback function to be associated with the specified Windows message. The driver will call this function when the message handler detects the specified message. It will pass all Windows message data to the function. The function must be of the prototype: int CVICALLBACK MyCallback (int panelHandle, int message, unsigned int* wParam, unsigned int* lParam, void* callbackData); If your callback is configured to intercept the message (execution mode = VAL_MODE_INTERCEPT), the function should return 0 if you want the message to be passed on to CVI's normal panel message–handler. If the function returns a 1, then the message will not be detected by CVI's message–handler. Note that the function has access to message data pointers. If passing the messages on to CVI's message handler, you may alter the contents of these pointers and CVI's message–handler will receive the "adjusted" message data. If your callback is configured for queued execution, then the return value or changing the message contents has no effect. An event EVENT_NEWHANDLE may be passed to your callback through the message parameter. When this occurs, it is because the Windows handle of the CVI panel has changed internally. The new Windows handle, which you must now use to post messages, will be passed in via the contents of the wParam pointer. |
||
callbackMode | integer | Specifies when your callback will actually execute. In In–Queue mode, the LabWindows/CVI handler sees the message and places a call to your callback in the LabWindows/CVI standard user interface event queue. In Intercept mode, the callback is executed before LabWindows/CVI sees the message. You can use this mode if you need to adjust the message before the LabWindows/CVI handler sees the message. If you specify Intercept, LabWindows/CVI does not process the event, and the event is passed to the default window procedure, which causes the default event behavior to occur. |
||
callbackData | void * | A pointer to be passed to your message callback function, similar to the standard UI callback mechanism. | ||
Output | ||||
Name | Type | Description | ||
postingHandle | integer * | The Window Handle (HWND) that should be used to post a message to this CVI panel. On certain conditions, this handle may change internally. Therefore, it is necessary to respond to the EVENT_NEWHANDLE message in your callback function and then use the new handle, passed via the contents of the wParam input. |
Name | Type | Description |
status | integer | The status code that the function returns. 0 indicates success. A negative value indicates an error. This function may return a Programmer's Toolbox or UI Library error code. Call GetGeneralErrorString to obtain a text description of the error. |