ChainCtrlCallback
int ChainCtrlCallback (int panel, int ctrl, CtrlCallbackPtr newCallbackFunction, void *newCallbackData, const char typeName[]);
Purpose
This function adds a new callback function to a control. This function will be called first for every event the control receives. If this new callback function returns zero (0), then the control's original callback function, if any, will be called with the same event.
This function is used to customize the behavior of controls. Since the new callback does not replace the original callback, the behavior of controls which already have callback functions can be customized without disabling the control's currently defined behavior.
All the linked callbacks for a control are unchained when the control is discarded.
Once a control's callback is chained, the callback data and the callback function should not be changed using the InstallCtrlCallback function or the ATTR_CALLBACK_DATA and ATTR_CALLBACK_FUNCTION_POINTER attributes.
Parameters
| Input | ||
| Name | Type | Description |
| panel | int | The specifier for a particular panel that is currently in memory. This handle will have been returned by the LoadPanel, NewPanel, or DuplicatePanel function. |
| ctrl | int | Pass the ID of the control to chain to new callback function to. The ID is the defined constant (located in the UIR header file) which was assigned to the control in the User Interface Editor, or the ID returned by the NewCtrl or DuplicateCtrl function. |
| newCallbackFunction | CtrlCallbackPtr | Pass the callback function to be chained in with the control's current callback function. This event function (type CtrlCallbackPtr) takes the form: int CVICALLBACK ChainCtrlCallback(int panel, int chainCtrlId, int event, void *callbackData, int eventData1, int eventData2); For every event the control receives, the chained callback function will be called first. If the chained callback function returns zero (0), then the original callback function will also be called with the same event. Multiple callbacks can be chained to the same control. For each event, the chained callbacks are called in order from the most recently chained callback to the first chained callback, followed by the control's original callback function (if any). If one of the callback functions returns a non–zero value, then none of the subsequent callbacks are called for that event. For the event EVENT_DISCARD, all the chained callbacks (and the original callback, if any) are called, regardless of what value each callback function returns. |
| newCallbackData | void * | This parameter specifies the callback data that will be passed to the New_Callback_Function in its callbackData parameter each time it is called. The callback data parameter is typically used to hold a pointer to data related to the new behavior the chained callback function is intended to implement. For example, if the chained callback function causes help to be displayed when the right mouse button is clicked on a control, then the callback data could be used to point to a string representing the name of the file with the help information, the topic name for the control's help, or even the help information itself. Alternatively, the callback data could hold a pointer to a structure containing any number of data items that could then be used to implement the control's customized behavior. |
| typeName | const char[] | Pass in the string to use as the type name of the newly created chained callback. The type name is used to prevent ChainCtrlCallback from being called twice on the same control for the same callback chaining. The type name is also used by the GetChainedCallbackData function to retrieve the callbackData for a chained callback. Suggestion: Use a type name which describes the behavior being added to the control. For example, if a callback is being chained in to cause help to be displayed when the right mouse button is clicked on a control, then the type name might be "Help", "Right Click Help", or "Control With Help". If the ChainCtrlCallback function has previously been called for the specified control with the same typeName, then nothing is done and the error code UIEInvalidControlType (–45) is returned. |
Return Value
| Name | Type | Description | ||
| status | int | Returns 0 if the function succeeded or a negative error code if the function failed. If the ChainCtrlCallback has previously been called for the specified control with the same typeName, then nothing is done and the error code UIEInvalidControlType (–45) is returned. The possible negative error codes are:
A description of any of these error codes can be obtained using the GetGeneralErrorString function in the toolbox.fp instrument driver. |
Additional Information
Library: Programmer's Toolbox
Include file: toolbox\toolbox.h
LabWindows/CVI compatibility: LabWindows/CVI 4.0 and later