ACAPI_Notify_CatchToolChange

Turns the monitoring of toolbox item changes on/off.

    GSErrCode  ACAPI_Notify_CatchToolChange (
        APIToolChangeHandlerProc*     handlerProc
    );

Parameters

handlerProc: [in] The callback procedure to call when notifications are sent out on changes in the selection. Specifying nullptr here means you don’t need the notifications any more.

Return Values

NoError: The function completed successfully.

For other common errors see the list of error codes.

Remarks

This function is used to register/unregister an addon which wants to monitor the changes in the toolbox, i.e. when the user switches to an other toolbox item. You do not have to call ACAPI_KeepInMemory afterwards, as the API ensures that add-ons with installed notification handlers won’t be unloaded.
After registration your add-on’s handlerProc you will be called when the selected toolbox item changes.

Example


// -----------------------------------------------------------------------------
// Toolbox item change handler function
// -----------------------------------------------------------------------------
static GSErrCode __ACENV_CALL   ToolChangeHandler (const API_ToolBoxItem *newToolMode)

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

        if (newToolMode->typeID == API_ZombieElemID)
                CHCopyC ("Arrow or Marquee", elemStr);
        else if (!GetElementTypeString (newToolMode->typeID, elemStr))
                CHCopyC ("Unknown", elemStr);

        sprintf (msgStr, "%s toolbox mode selected", elemStr);
        ACAPI_WriteReport (msgStr, false);

        return NoError;
}   // ToolChangeHandler


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

{
    // catch changes in the toolbox
    GSErrCode err = ACAPI_Notify_CatchToolChange (ToolChangeHandler);

    return err;
}   // Initialize

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also