InstallWinMsgCallback
int InstallWinMsgCallback (int panelHandle, int messageNumber, WinMsgCallback callbackFunction, int callbackMode, void *callbackData, intptr_t *postingHandle);
Purpose
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.
 |
Notes
|
Example Code
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);
}
(Linux) This function is not supported.
Parameters
| Input | ||||
| Name | Type | Description | ||
| panelHandle | int | The handle of the LabWindows/CVI panel for which to install a Windows message callback function. | ||
| messageNumber | int | The number of the message for which to install a callback function.
|
||
| callbackFunction | WinMsgCallback | The callback function to associate with the specified Windows message. The driver calls this function when the message handler detects the specified message and passes 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 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 LabWindows/CVI panel has changed internally. You can obtain the new Windows handle, which you must now use to post messages, from the wParam value. |
||
| callbackMode | int | Specifies when your callback will actually execute. If you specify VAL_MODE_IN_QUEUE or select In–Queue in the function panel, the LabWindows/CVI handler sees the message and places a call to your callback in the LabWindows/CVI standard user interface event queue. If you specify VAL_MODE_INTERCEPT or select Intercept in the function panel, 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. In this mode, 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 | intptr_t | The Window Handle (HWND) that you can use to post a message to this LabWindows/CVI panel, if you need to post a message.
|
||
Return Value
| Name | Type | Description |
| status | int | 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. |
Additional Information
Library: Programmer's Toolbox
Include file: toolbox\toolbox.h
LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later
Example
Refer to toolbox\msgdemo.cws for an example of using the InstallWinMsgCallback function.