ChainPanelCallback
int ChainPanelCallback (int panel, PanelCallbackPtr newCallbackFunction, void *newCallbackData, const char typeName[]);
Purpose
This function adds a new callback function to a panel. This function will be called first for every event the panel receives. If this new callback function returns zero (0), then the panel's original callback function, if any, will be called with the same event.
This function is used to customize the behavior of panels. Since the new callback does not replace the original callback, the behavior of a panel which already has a callback function can be customized without disabling the panel's currently defined behavior.
All the linked callbacks for a panel are unchained when the panel is discarded.
Once a panel's callback is chained, the callback data and the callback function should not be changed using the InstallPanelCallback 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. |
| newCallbackFunction | PanelCallbackPtr | Pass the callback function to be chained in with the panel's current callback function. This event function (type PanelCallbackPtr) takes the form: int CVICALLBACK chainPnlCallback(int panel, int event, void *callbackData, int eventData1, int eventData2); For every event the panel 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 panel. For each event, the chained callbacks are called in order from the most recently chained callback to the first chained callback, followed by the panel'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 panel, 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 panel'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 panel'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 ChainPanelCallback from being called twice on the same panel for the same callback chaining. The type name is also used by the GetChainedPanelCallbackData 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 ChainPanelCallback 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 ChainPanelCallback 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