Installs an element observer function which receives notifications on elements’ changes.

    GSErrCode  ACAPI_Notify_InstallElementObserver (
        APIElementEventHandlerProc*     handlerProc
    );

 

Parameters

handlerProc

[in] The callback procedure to call when notifications are sent out on changes of elements. 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 add-on which wants to monitor the changes in elements. This is a common callback for all the different element observers which can be attached to an element with ACAPI_Element_AttachObserver.
After registration your add-on’s handlerProc you will be called when any of the monitored elements change.
For more details see also the Element related notifications paragraph of the Notification Manager.

 

Example

// -----------------------------------------------------------------------------
// Element observer callback function
// -----------------------------------------------------------------------------
static GSErrCode __ACENV_CALL    ElementEventHandler (const API_NotifyElementType *elemType)

{
    GSErrCode       err = NoError;
    char            msgStr[256];
    char            elemStr[32];
    API_Elem_Head   elemHead;
    API_Element     parentElement;

    BNZeroMemory (&parentElement, sizeof (API_Element));
    ACAPI_Notify_GetParentElement (&parentElement, nullptr, 0, nullptr);

    switch (elemType->notifID) {
        case APINotifyElement_Copy:
                    BNZeroMemory (&elemHead, sizeof (API_Elem_Head));

                    if (parentElement.header.guid != APINULLGuid && GetElementTypeString (elemType->type, elemStr)) {
                        sprintf (msgStr, "### Element_Manager: %s #%d copied from #%d",
                                 elemStr, APIGuidToString (elemType->guid).ToCStr ().Get (), 
                                 APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

                        elemHead.guid = elemType->guid;
                        err = ACAPI_Element_AttachObserver (&elemHead, 0);
                    }
                    break;


        default:
                    err = APIERR_NOTSUPPORTED;
                    break;
    }

    if (err == NoError)
        ACAPI_WriteReport (msgStr, false);

    return err;
}   // ElementEventHandler


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

{
    // catch changes in the selection
    GSErrCode err = ACAPI_Notify_InstallElementObserver (ElementEventHandler);

    return err;
}   // Initialize

 

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

 

See Also

APIElementEventHandlerProc
ACAPI_Element_AttachObserver
ACAPI_Element_DetachObserver
Notification Manager
API Functions