InstallMainCallback
int InstallMainCallback (MainCallbackPtr eventFunction, void *callbackData, int getIdleEvents);
Purpose
Installs the main callback that is called for all panel, control, and menu events.
InstallMainCallback takes the name of an event function (type MainCallbackPtr), a pointer to callback data of any type, and a boolean indicating whether or not to get idle events.
After you install the callback, the event function is called whenever an event is generated and not swallowed by another callback.
Callbacks are initiated through RunUserInterface or GetUserEvent.
 |
Note To uninstall the callback, pass NULL for eventFunction. |
Parameters
| Input | ||||
| Name | Type | Description | ||
| eventFunction | MainCallbackPtr | Name of the function that processes events. The event function, type MainCallbackPtr, takes the following form: int CVICALLBACK EventFunctionName (int panelOrMenuBarHandle, int controlOrMenuItemID, int event, void *callbackData, int eventData1, int eventData2); The event function receives information about the source of the callback, either the panel handle and control ID, or the menubar handle and menu item ID. The event function also receives callback data and the type of the event, such as a left mouse click, and any additional event data such as the mouse position at the time of a left mouse click. User callbacks must always return 0 unless they intend to swallow the event to which they are responding. To swallow the event, the callback should return 1.
|
||
| callbackData | void * | Points to data that you define. The callback function receives the pointer. | ||
| getIdleEvents | int | Specify a nonzero value or select yes in the function panel to respond to idle events. Specify 0 or select no in the function panel to ignore idle events. getIdleEvents allows program execution to proceed when it would normally be suspended. For example, the program is normally suspended in GetUserEvent or RunUserInterface when the user holds down the mouse button on a control or pull-down menu. Idle events occur continuously, even under these circumstances. Because the main callback can receive idle events, the program can continue processing by responding to idle events. Call SetIdleEventRate to set the rate of idle events.
If you pass a nonzero value for getIdleEvents, the callback receives idle events regularly at the rate you specify with SetIdleEventRate, as long as you allow LabWindows/CVI to process events. You can achieve the same effect by using a timer control. National Instruments recommends that you use timer controls rather than a main callback with idle events. |
||
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number indicates that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later