Register or unregister your add-on to be notified if the given type of element is created.

    GSErrCode  ACAPI_Notify_CatchNewElement (
        const API_ToolBoxItem*          elemType,
        APIElementEventHandlerProc*     handlerProc
    );

 

Parameters

elemType

[in] Specifies the type of element for which your add-on should be notified. In order to receive notification on the creation of any type of elements, you simply pass nullptr as this parameter.

handlerProc

[in] The callback procedure to call when notifications are sent out on creating this type of element. Specifying nullptr here means you don’t need the notifications any more.

 

Return Values

NoError

The requested 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 event of creating a certain type of element. Each time when an element of this type is created the server application calls the supplied handlerProc of your those add-ons which have been registered for this event previously.

If you do not need to catch the creation of new elements any longer, please remember to unregister by calling ACAPI_Notify_CatchNewElement for the required element type with nullptr in the handlerProc parameter.

 

Example

// -----------------------------------------------------------------------------
// Element event handler function
// -----------------------------------------------------------------------------
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_New:
                    BNZeroMemory (&elemHead, sizeof (API_Elem_Head));

                    if (GetElementTypeString (elemType->type, elemStr)) {
                        if (parentElement.header.guid != APINULLGuid)
                            sprintf (msgStr, "### API Notify Test: %s #%d created as a copy of #%d",
                                     elemStr, APIGuidToString (elemType->guid).ToCStr ().Get (), 
                                     APIGuidToString (parentElement.header.guid).ToCStr ().Get ());
                        else
                            sprintf (msgStr, "### API Notify Test: %s #%d created", elemStr, 
                                     APIGuidToString (elemType->guid).ToCStr ().Get ());

                        elemHead.guid = elemType->guid;
                        err = ACAPI_Element_AttachObserver (&elemHead, 0);
                    } else
                        sprintf (msgStr, "### API Notify Test: Unknown element type created");
                    break;

        default:
                    err = APIERR_NOTSUPPORTED;
                    break;
    }

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

    return NoError;
}   // ElementEventHandler


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

{
    API_ToolBoxItem  elemType_Wall = { API_WallID, 0, 0, 0 };

    // catch changes in defaults for all element types
    GSErrCode err = ACAPI_Notify_CatchNewElement (&elemType_Wall, ElementEventHandler);

    return err;
}   // Initialize

 

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

 

See Also

API_ToolBoxItem, APIElementEventHandlerProc,
Notification Manager, API Functions