ACAPI_​Notify_​CatchChangeDefaults

Register or unregister your add-on to be notified if the default settings of a given element type is modified.

    GSErrCode  ACAPI_Notify_CatchChangeDefaults (
        const API_ToolBoxItem*            elemType,
        APIDefaultsChangeHandlerProc*     handlerProc
    );

 

Parameters

elemType
[in] Specifies the type of element for which your add-on should be notified. In order to receive notification on changing the default settings of any type of element, you simply pass nullptr as this parameter.
handlerProc
[in] The callback procedure to call when notifications are sent out on changing the default settings of this element type. Specifying nullptr here means you don’t need the notifications any more.

 

Return Values

NoError
The required operation finished successfully.
APIERR_BADID
The elemType parameter contains an invalid type.

For other common API errors see the API Errors document.

 

Remarks

This function enables the API tool add-on catch the modification of the default settings of a certain element type. Each time when one of the default parameters of the element type is modified the server application calls the supplied callback procedure of the add-on provided that it has been registered for this event previously.

If you do not need to catch the changes of default settings any longer, please remember to unregister by calling ACAPI_Notify_CatchChangeDefaults for the required element type with nullptr in the handlerProc parameter.

 

Example


// -----------------------------------------------------------------------------
// Defaults change handler function
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL ChangeDefaultsHandler (const API_ToolBoxItem *defElemType)

{
    char    msgStr[256];
    char    elemStr[32];

    if (GetElementTypeString (defElemType->type, elemStr))
        sprintf (msgStr, "%s element type defaults changed", elemStr);
    else
        sprintf (msgStr, "Unknown element type defaults changed");

    ACAPI_WriteReport (msgStr, false);

    return NoError;
}   // ChangeDefaultsHandler


// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)

{
    // catch changes in defaults for all element types
    GSErrCode err = ACAPI_Notify_CatchChangeDefaults (nullptr, ChangeDefaultsHandler);

    return err;
}   // Initialize

 

Requirements

Version: API 4.1 or later
Header: ACAPinc.h

 

See Also

API_ToolBoxItem, APIDefaultsChangeHandlerProc,
Notification Manager, API Functions