InstallCtrlCallback

int InstallCtrlCallback (int panelHandle, int controlID, CtrlCallbackPtr eventFunction, void *callbackData);

Purpose

Installs a control callback.

InstallCtrlCallback takes a panel handle and control ID, the name of the event function, type CtrlCallbackPtr, that processes events for that control, and callback data of any type.

After you install the callback, the event function is called whenever the user generates an event on the control.

The event function receives the panel handle and control ID of the control generating the event; 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; and the callbackData for processing.

You do not need call InstallCtrlCallback if you already associated a callback function with the control in the User Interface Editor.

Callbacks are initiated through RunUserInterface or GetUserEvent.

Note  To uninstall the callback, pass NULL for eventFunction.

Parameters

Input
Name Type Description
panelHandle integer Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID integer The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
eventFunction CtrlCallbackPtr Name of the function that processes the control events.

The event function, type CtrlCallbackPtr, takes the following form:

int CVICALLBACK EventFunctionName (int panelHandle, int controlID, int event, void *callbackData, int eventData1, int eventData2);

The event function receives the panel handle and control ID of the control generating the event; 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; and the callbackData for processing.

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.

Note  To uninstall the callback, pass NULL for this parameter.
callbackData void * Points to data that you define. The callback function receives the pointer.

Return Value

Name Type Description
status integer Return value indicating whether the function was successful. A negative number indicates that an error occurred.

Code Error Message String
xx Success