Notifications Manager

Functions related to the use of various notifications of Archicad. They can be used to automatically execute different tasks when a given trigger is executed in Archicad. More...

Classes
struct	API_NotifyViewEventType
	Describes the Project Navigator item the notification is coming for, and the type of the notification. More...
struct	API_NotifyElementType
	Describes the element the notification is coming for, and the type of the notification. More...
class	API_IEventNotifier
	Defining an interface for a class that will be used to notify all event handlers. More...
class	API_IEventHandler
	Defining an interface for all event handlers. More...
class	API_IObjectEventHandler
	Defining an interface for Object event handlers. More...
class	API_IDialogEventHandler
	Defining an interface for Dialog event handlers. More...
class	API_IAttributeEventHandler
	Defining an interface for Attribute event handlers. More...
class	API_IAttributeFolderEventHandler
	Defining an interface for Attribute Folder event handlers. More...
class	API_IClassificationSystemEventHandler
	The base class you need to inherit from in case you want to handle API_ClassificationSystem events. More...
class	API_IClassificationItemEventHandler
	The base class you need to inherit from in case you want to handle API_ClassificationItem events. More...
class	API_IPropertyGroupEventHandler
	The base class you need to inherit from in case you want to handle API_PropertyGroup events. More...
class	API_IPropertyDefinitionEventHandler
	The base class you need to inherit from in case you want to handle API_PropertyDefinition events. More...
class	API_IGraphisoftIDEventHandler
class	API_IEnableAllInfoDialogEventHandler
class	API_IMarqueeEventHandler
struct	API_ActTranPars
	Structure for retrieving the transformation data of the actual editing operation. More...

Typedefs
typedef GSErrCode __ACENV_CALL	APIProjectEventHandlerProc(API_NotifyEventID notifID, Int32 param)
	Callback function to receive notifications on changes of the project.
typedef GSErrCode __ACENV_CALL	APIViewEventHandlerProc(const API_NotifyViewEventType *viewEvent)
	User supplied callback function for handling changes of Project Navigator items.
typedef GSErrCode __ACENV_CALL	APIDefaultsChangeHandlerProc(const API_ToolBoxItem *defElemType)
	Callback procedure to receive notifications on changes in element defaults.
typedef GSErrCode __ACENV_CALL	APIToolChangeHandlerProc(const API_ToolBoxItem *newToolMode)
	Callback function to handle changes in the toolbox.
typedef GSErrCode __ACENV_CALL	APISelectionChangeHandlerProc(const API_Neig *selElemNeig)
	User supplied callback procedure for handling selection changes.
typedef GSErrCode __ACENV_CALL	APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)
	User supplied callback procedure for handling attribute replacements.
typedef GSErrCode __ACENV_CALL	APIReservationChangeHandlerProc(const GS::HashTable< API_Guid, short > &reserved, const GS::HashSet< API_Guid > &released, const GS::HashSet< API_Guid > &deleted)
	User supplied callback procedure for handling element reservation changes.
typedef GSErrCode __ACENV_CALL	APILockChangeHandlerProc(const API_Guid &objectId, short ownerId)
	User supplied callback procedure for handling reservation changes of lockable objects.
typedef GSErrCode __ACENV_CALL	APILicenseBorrowStatusChangeHandlerProc(API_LicenseBorrowStatusTypeID licenseBorrowStatus)
	User supplied callback procedure for handling license borrowing status changes.
typedef GSErrCode __ACENV_CALL	APIElementEventHandlerProc(const API_NotifyElementType *elemType)
	User supplied callback function for handling changes in elements.

Enumerations
enum	API_NotifyEventID {   APINotify_New = 0x00000001 , APINotify_NewAndReset = 0x00000002 , APINotify_Open = 0x00000004 , APINotify_PreSave = 0x00000008 ,   APINotify_Save = 0x00000010 , APINotify_Close = 0x00000020 , APINotify_Quit = 0x00000040 , APINotify_TempSave = 0x00000080 ,   APINotify_SendChanges = 0x00008000 , APINotify_ReceiveChanges = 0x00010000 , APINotify_ChangeProjectDB = 0x00040000 , APINotify_ChangeWindow = 0x00080000 ,   APINotify_ChangeFloor = 0x00100000 , APINotify_ChangeLibrary = 0x00200000 , APINotify_AllInputFinished = 0x00400000 , APINotify_UnitChanged = 0x00800000 ,   APINotify_SideviewCreated = 0x01000000 , APINotify_SideviewRebuilt = 0x02000000 , APINotify_PropertyVisibilityChanged = 0x04000000 , APINotify_ClassificationVisibilityChanged = 0x08000000 ,   APINotify_ShowIn3DChanged = 0x10000000 }
	Possible values for notifications on project events. More...
enum	API_NotifyViewEventID {   APINotifyView_Inserted = 0x00000001 , APINotifyView_Modified = 0x00000002 , APINotifyView_Deleted = 0x00000004 , APINotifyView_Opened = 0x00000008 ,   APINotifyView_Begin = 0x00000010 , APINotifyView_End = 0x00000020 }
	Possible values for notifications on Project Navigator events. More...
enum	API_ElementDBEventID {   APINotifyElement_BeginEvents = -1 , APINotifyElement_EndEvents = -2 , APINotifyElement_New = 1 , APINotifyElement_Copy = 2 ,   APINotifyElement_Change = 3 , APINotifyElement_Edit = 4 , APINotifyElement_Delete = 5 , APINotifyElement_Undo_Created = 11 ,   APINotifyElement_Undo_Modified = 12 , APINotifyElement_Undo_Deleted = 13 , APINotifyElement_Redo_Created = 14 , APINotifyElement_Redo_Modified = 15 ,   APINotifyElement_Redo_Deleted = 16 , APINotifyElement_PropertyValueChange = 17 , APINotifyElement_ClassificationChange = 18 }
	Describes the cause of the element notification. More...
enum	API_NavigatorMapID {   API_UndefinedMap = 0 , API_ProjectMap = 1 , API_PublicViewMap = 2 , API_MyViewMap = 3 ,   API_LayoutMap = 4 , API_PublisherSets = 5 }
	Enumeration of Project Navigator maps. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_Element_AttachObserver (const API_Guid &elemGuid, GSFlags notifyFlags=0)
	Attaches an observer to the given element.
GSErrCode __ACENV_CALL	ACAPI_Element_DetachObserver (const API_Guid &elemGuid)
	Detaches the observer from the given element.
GSErrCode __ACENV_CALL	ACAPI_Notification_GetObservedElements (GS::Array< API_Elem_Head > *elemHeads)
	Returns the elements observed by the add-on.
GSErrCode __ACENV_CALL	ACAPI_ProjectOperation_CatchProjectEvent (GSFlags eventTypes, APIProjectEventHandlerProc *handlerProc)
	Register or unregister your add-on to be notified of application and project events.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchViewEvent (GSFlags eventTypes, API_NavigatorMapID mapId, APIViewEventHandlerProc *handlerProc)
	Register or unregister your add-on to be notified of Project Navigator changes.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchToolChange (APIToolChangeHandlerProc *handlerProc)
	Turns the monitoring of toolbox item changes on/off.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchSelectionChange (APISelectionChangeHandlerProc *handlerProc)
	Turns the monitoring of selection changes on/off.
GSErrCode __ACENV_CALL	ACAPI_Element_CatchChangeDefaults (const API_ToolBoxItem *elemType, APIDefaultsChangeHandlerProc *handlerProc)
	Register or unregister your add-on to be notified if the default settings of a given element type is modified.
GSErrCode __ACENV_CALL	ACAPI_Element_CatchNewElement (const API_ToolBoxItem *elemType, APIElementEventHandlerProc *handlerProc)
	Register or unregister your add-on to be notified if the given type of element is created.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchAttributeReplacement (APIAttributeReplacementHandlerProc *handlerProc)
	Register or unregister your add-on to be notified if some attributes are deleted and replaced by other attributes.
GSErrCode __ACENV_CALL	ACAPI_Element_InstallElementObserver (APIElementEventHandlerProc *handlerProc)
	Installs an element observer function which receives notifications on elements' changes.
GSErrCode __ACENV_CALL	ACAPI_Notification_GetTranParams (API_ActTranPars *actTranPars)
	Returns the transformation parameters of the actual edit operation.
GSErrCode __ACENV_CALL	ACAPI_Notification_GetParentElement (API_Element *element, API_ElementMemo *memo, UInt64 mask, API_ElementUserData *userData)
	Returns the parent of the actual element your addon received notification for.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchElementReservationChange (APIReservationChangeHandlerProc *handlerProc, const GS::HashSet< API_Guid > *filterElementsInterestedOnly=nullptr)
	Sets notification handler for element reservation changes.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchLockableReservationChange (APILockChangeHandlerProc *handlerProc, const GS::HashSet< API_Guid > *filterLockablesInterestedOnly=nullptr)
	Sets notification handler for reservation changes of lockable objects.
GSErrCode __ACENV_CALL	ACAPI_Licensing_CatchLicenseBorrowStatusChange (APILicenseBorrowStatusChangeHandlerProc *handlerProc)
	Catches notifications on license borrowing status changes.
GSErrCode __ACENV_CALL	ACAPI_Notification_ClassificationVisibilityChanged ()
	Sends out an APINotify_ClassificationVisibilityChanged project event notification to the other add-ons to state that at least one classification's visibility has changed.
GSErrCode __ACENV_CALL	ACAPI_Notification_PropertyVisibilityChanged ()
	Sends out an APINotify_PropertyVisibilityChanged project event notification to the other add-ons to state that at least one property's visibility has changed.
GSErrCode __ACENV_CALL	ACAPI_Notification_RegisterEventHandler (GS::Owner< API_IEventHandler > eventHandler, API_Guid &id)
	Register an event handler in your add-on.
GSErrCode __ACENV_CALL	ACAPI_Notification_UnregisterEventHandler (const API_Guid &id)
	Unregister an event handler from your add-on.

Detailed Description

Functions related to the use of various notifications of Archicad. They can be used to automatically execute different tasks when a given trigger is executed in Archicad.

Notification Manager

The Notification Manager lets your add-on be integrated more into the Archicad environment.

It is very important to understand the underlying ideas and technologies in order to be able to use the services in the right way.
It is very easy to block Archicad using the Notification Manager in a wrong way; so be very careful!

The key point that you have to keep in mind is that notifications are coming in the background, without any user interaction. Plan your system concentrating on this issue; do not perform time consuming operations, and also do not make changes that have global effects, although the Notification Manager tries to detect and refuse such operations, of course.

What kind of events can an add-on receive notification of?

An add-on can catch events occured to the actual project such as opening, saving, closing the plan file; can be notified of teamwork events, and several changes in the program environment. Furthermore the add-ons can get notification of events happened to the elements of the project database such as creation, modification and deletion. Also there can be notified of undoing and redoing element database changes.

Functions

All of the notification manager functions begin with the ACAPI_Notify_ prefix. This function family gives support to register your add-on to receive notifications when the requested event(s) occured. Once a notification is posted you get the control and you are allowed to call almost all of the API functions to handle the event.

In order to be notified of certain events you have to make a registration with the following functions:

• ACAPI_ProjectOperation_CatchProjectEvent
  
• ACAPI_Notification_CatchViewEvent
• ACAPI_Notification_CatchToolChange
  
• ACAPI_Notification_CatchSelectionChange
  
• ACAPI_Element_CatchChangeDefaults
  
• ACAPI_Element_CatchNewElement
  
• ACAPI_Element_InstallElementObserver
  
• ACAPI_Notification_CatchElementReservationChange
• ACAPI_Notification_CatchLockableReservationChange
• ACAPI_Notification_RegisterEventHandler
• ACAPI_Notification_UnregisterEventHandler

If you would like to receive notifications of certain events from the application start up on, you can claim your add-on to be pre-loaded by returning APIAddon_Preload from the CheckEnvironment function instead of APIAddon_Normal. This ensures that the Initialize function of your add-on will be called right after start up, and there you can register your callback functions. While you have any callback function installed into the API registration, your add-on keeps loaded in the memory, thus the function pointers remain valid.

The following functions are supported to provide access to additional information while handling a notification posted to you:

• ACAPI_Notification_GetParentElement
  
• ACAPI_Notification_GetTranParams

Element related notifications

Monitoring elements

In order to be notified of events that happen to a specified element in the database you have to attach an observer to the element with the ACAPI_Element_AttachObserver function. This information then will be saved into the project file, so next time you use that plan the notification system will notify your add-on about changes of elements you have marked for monitoring before.

You can catch element creation events if your add-on installs an APIElementEventHandlerProc element event handler function with ACAPI_Element_CatchNewElement. You may specify a certain type of elements if you are interested in these new elements only. You can use the same callback function for more element types at the same time. If you want to follow up the modifications of the newly created element, you can attach an observer to it at once right from the new element callback.

How does it work?

The element related notification system is based on the undo list of Archicad, that is it processes the undo entries created by the last operation.

Assume that there are three add-ons monitoring some set of elements in the current project. Add-on "A" has linked objects to walls, and watches if something happens to those walls to keep the objects aligned to the walls. Add-on "B" has a sort of autotext functionality, it is to be notified of word element creation. Finally Add-on "C" controls the length of walls, it may delete some walls and replace them with a note.

The following figure shows what happens in this configuration if the user stretches two walls on the floor plan:

After editing the walls the notification mechanism searches the current undo entry for elements that the first add-on is supposed to do something with. Whenever it finds an element reference that the add-on has attached observer to, or the element was created and the add-on has required notification of new elements of that type, the notification manager calls the appropriate callback function (APIElementEventHandlerProc) of the add-on.

After reaching last entry the original operation created in the undo step, the whole searching method restarts from the beginning for the next add-on to be notified.
On being notified an add-on probably adds new entries to the current undo step. However the add-on will not be notified of element changes made by itself.

Typedef Documentation

APIAttributeReplacementHandlerProc

typedef GSErrCode __ACENV_CALL APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)

User supplied callback procedure for handling attribute replacements.

Since

Archicad 25

Parameters

table

[in] List of attributes replaced. The hash key in the hash table is the type of attribute (material, profile etc.), the paired value is another hash table, which holds the old (deleted) attribute indices as keys, and the replacement attribute indices as values.

Returns

• NoError - The function has completed with success.

Remarks

This callback function should be implemented and set with ACAPI_Notification_CatchAttributeReplacement in order to receive notifications of attribute replacements.

APIDefaultsChangeHandlerProc

typedef GSErrCode __ACENV_CALL APIDefaultsChangeHandlerProc(const API_ToolBoxItem *defElemType)

Callback procedure to receive notifications on changes in element defaults.

Parameters

defElemType

[in] The element type the notification is coming for.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on requested notifications on element default chnages with ACAPI_Element_CatchChangeDefaults.

APIElementEventHandlerProc

typedef GSErrCode __ACENV_CALL APIElementEventHandlerProc(const API_NotifyElementType *elemType)

User supplied callback function for handling changes in elements.

Parameters

elemType

[in] This structure contains the various parameters identifying the element the notification is for.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on attached an observer to an element with ACAPI_Element_AttachObserver, i.e. you are interested in changes to an element. This is a common entry point to your add-on for all observed elements; the element in question is passed in the elemType parameter. The meaning of the notification parameters are desrcribed at the API_NotifyElementType structure.

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_Notification_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_Element_CatchNewElement (&elemType_Wall, ElementEventHandler);
 
    return err;
}   // Initialize

APILicenseBorrowStatusChangeHandlerProc

typedef GSErrCode __ACENV_CALL APILicenseBorrowStatusChangeHandlerProc(API_LicenseBorrowStatusTypeID licenseBorrowStatus)

User supplied callback procedure for handling license borrowing status changes.

Parameters

licenseBorrowStatus

[out] The status of license borrowing, can be API_LicenseBorrowed or API_LicenseReturned.

Returns

• NoError - The function has completed with success.

Remarks

This notification comes when the user borrows or returns a license, and allows you to act accordingly.

APILockChangeHandlerProc

typedef GSErrCode __ACENV_CALL APILockChangeHandlerProc(const API_Guid &objectId, short ownerId)

User supplied callback procedure for handling reservation changes of lockable objects.

Parameters

objectId	[in] Identifies the lockable object set that has been reserved or released. The available identifiers are listed at the description of lockable object sets.
ownerId	[in] The identifier of the locker team member who obtained the reservation, or 0 if the lockable object got released.

Returns

• NoError - The function has completed with success.

Remarks

This callback function should be implemented and set with ACAPI_Notification_CatchLockableReservationChange in order to receive notifications of reservation changes of lockable objects. You can retrieve information of the members with the ACAPI_Teamwork_ProjectSharing environment function. Note that the handler receives reservation changes effected by the current team member as well. In the reservation change handler try to avoid calling functions that would modify the database.

APIProjectEventHandlerProc

typedef GSErrCode __ACENV_CALL APIProjectEventHandlerProc(API_NotifyEventID notifID, Int32 param)

Callback function to receive notifications on changes of the project.

Parameters

notifID	[in] The type of the project event the notification is for.
param	[in] This parameter is valid only if the notifID is APINotify_ChangeLibrary. If an individual library part has changed in the library (e.g. it was added to the library), then this parameter contains the index of that library part. This parameter is also valid if notifID is APINotify_ChangeProjectDB, and contains a code for the cause of the event.

param	Event cause
0	Other
1	Floor(s) edited
2	Merge

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on requested notifications on project events with ACAPI_ProjectOperation_CatchProjectEvent.

APIReservationChangeHandlerProc

typedef GSErrCode __ACENV_CALL APIReservationChangeHandlerProc(const GS::HashTable< API_Guid, short > &reserved, const GS::HashSet< API_Guid > &released, const GS::HashSet< API_Guid > &deleted)

User supplied callback procedure for handling element reservation changes.

Parameters

reserved	[in] List of elements recently reserved. The hash key in the hash table is the element guid, the paired value is the Teamwork owner identifier of the member who reserved the element.
released	[in] List of elements recently released.
deleted	[in] List of elements deleted during the recent Teamwork operations. Element deletions are reported when the member who deleted the elements sends the changes to the BIM Server.

Returns

• NoError - The function has completed with success.

APISelectionChangeHandlerProc

typedef GSErrCode __ACENV_CALL APISelectionChangeHandlerProc(const API_Neig *selElemNeig)

User supplied callback procedure for handling selection changes.

Parameters

selElemNeig

[in] This structure identifies the last selected element.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_Notification_CatchSelectionChange.

APIToolChangeHandlerProc

typedef GSErrCode __ACENV_CALL APIToolChangeHandlerProc(const API_ToolBoxItem *newToolMode)

Callback function to handle changes in the toolbox.

Parameters

newToolMode

[in] The toolbox mode the user switched to.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on requested notifications on toolbox item changes with ACAPI_Notification_CatchToolChange.

APIViewEventHandlerProc

typedef GSErrCode __ACENV_CALL APIViewEventHandlerProc(const API_NotifyViewEventType *viewEvent)

User supplied callback function for handling changes of Project Navigator items.

Parameters

viewEvent

[in] This structure identifies the Project Navigator item and the event the add-on is called for.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on requested notifications on Project Navigator item changes with ACAPI_Notification_CatchViewEvent.

Enumeration Type Documentation

API_ElementDBEventID

enum API_ElementDBEventID

Describes the cause of the element notification.

Remarks

This enumeration type is used in the API_NotifyElementType structure.

API_NavigatorMapID

enum API_NavigatorMapID

Enumeration of Project Navigator maps.

Remarks

This type identifier can be used as mapId in API_NavigatorSet and API_NavigatorItem structures.

API_NotifyEventID

enum API_NotifyEventID

Possible values for notifications on project events.

Since

Archicad 26

Remarks

Refer to ACAPI_ProjectOperation_CatchProjectEvent function for further details.

API_NotifyViewEventID

enum API_NotifyViewEventID

Possible values for notifications on Project Navigator events.

Remarks

Refer to ACAPI_Notification_CatchViewEvent function for further details.

Function Documentation

ACAPI_Element_AttachObserver()

GSErrCode __ACENV_CALL ACAPI_Element_AttachObserver	(	const API_Guid &	elemGuid,
		GSFlags	notifyFlags = 0
	)

Attaches an observer to the given element.

Parameters

elemGuid	[in] Identifies the element to attach the observer to.
notifyFlags	[in] Defines the behavior of the attached observer in certain database operations.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The referenced element cannot be found in the database.

Remarks

This function can be used to track changes in an element. After attaching the observer, the installed APIElementEventHandlerProc will be called with the appropriate notifications.

ACAPI_Element_CatchChangeDefaults()

GSErrCode __ACENV_CALL ACAPI_Element_CatchChangeDefaults	(	const API_ToolBoxItem *	elemType,
		APIDefaultsChangeHandlerProc *	handlerProc
	)

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

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.

Returns

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

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_Element_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_Element_CatchChangeDefaults (nullptr, ChangeDefaultsHandler);
 
    return err;
}   // Initialize

ACAPI_Element_CatchNewElement()

GSErrCode __ACENV_CALL ACAPI_Element_CatchNewElement	(	const API_ToolBoxItem *	elemType,
		APIElementEventHandlerProc *	handlerProc
	)

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

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.

Returns

• NoError - The requested operation finished successfully.
• APIERR_BADID - The elemType parameter contains an invalid type.

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_Element_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_Notification_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_Element_CatchNewElement (&elemType_Wall, ElementEventHandler);
 
    return err;
}   // Initialize

ACAPI_Element_DetachObserver()

GSErrCode __ACENV_CALL ACAPI_Element_DetachObserver

(

const API_Guid &

elemGuid

)

Detaches the observer from the given element.

Parameters

elemGuid

[in] Identifies the element to detach the observer from.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The referenced element cannot be found in the database.

ACAPI_Element_InstallElementObserver()

GSErrCode __ACENV_CALL ACAPI_Element_InstallElementObserver

(

APIElementEventHandlerProc *

handlerProc

)

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

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.

Returns

• NoError - The function completed successfully.

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_Notification_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_Element_InstallElementObserver (ElementEventHandler);
 
    return err;
}   // Initialize

ACAPI_Licensing_CatchLicenseBorrowStatusChange()

GSErrCode __ACENV_CALL ACAPI_Licensing_CatchLicenseBorrowStatusChange

(

APILicenseBorrowStatusChangeHandlerProc *

handlerProc

)

Catches notifications on license borrowing status changes.

Parameters

handlerProc

[in] The callback function which receives the notifications.

Returns

• NoError - The function has completed with success.

Remarks

This function allows you to act on license borrowing and returning.

ACAPI_Notification_CatchAttributeReplacement()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchAttributeReplacement

(

APIAttributeReplacementHandlerProc *

handlerProc

)

Register or unregister your add-on to be notified if some attributes are deleted and replaced by other attributes.

Since

Archicad 25

Parameters

handlerProc

[in] The callback procedure to call when notifications are sent out on replacement of attributes. Specifying nullptr here means you don't need the notifications any more.

Returns

• NoError - The required operation finished successfully.

Remarks

This function enables the API tool add-on to catch the deletion and replacement of the attributes in the project. This operation can be done with the Delete and Replace option in the Attribute Manager dialog. If you do not need to catch the changes of default settings any longer, please remember to unregister by calling ACAPI_Notification_CatchAttributeReplacement for the required element type with nullptr in the handlerProc parameter.

Example

// -----------------------------------------------------------------------------
// Attribute replacement handler function
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL HandleAttributeReplacement (const API_AttributeReplaceIndexTable& table)
{
    char    msgStr[256];
 
    if (table.ContainsKey (API_AttrTypeID::API_BuildingMaterialID)) {
        for (const auto& entry : table[API_AttrTypeID::API_BuildingMaterialID]) {
            sprintf (msgStr, "Changed Material: old index = %d, new index = %d", *entry.key, *entry.value);
            ACAPI_WriteReport (msgStr, false);
        }
    }
 
    return NoError;
}   // HandleAttributeReplacement
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)
 
{
    GSErrCode err = ACAPI_Notification_CatchAttributeReplacement (HandleAttributeReplacement);
 
    return err;
}   // Initialize

ACAPI_Notification_CatchElementReservationChange()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchElementReservationChange	(	APIReservationChangeHandlerProc *	handlerProc,
		const GS::HashSet< API_Guid > *	filterElementsInterestedOnly = nullptr
	)

Sets notification handler for element reservation changes.

Parameters

handlerProc	[in] Notification handler function to be called on the specified event. Pass nullptr to unsubscribe from this notification.
filterElementsInterestedOnly	[in] List of element guids; optional parameter for controlling the range of elements of interest. If passed, the reservation change notifications will be sent for only these elements, otherwise every element reservation changes will be reported.

Returns

• NoError - The function completed successfully.

Remarks

This function is used to subscribe an add-on to be notified when element reservations have been changed in Teamwork. Once a APIReservationChangeHandlerProc function pointer is passed, the add-on remains loaded in the memory, and receives the notifications. When the add-on does not need these notifications any more, you can stop receiving them by calling this function with nullptr in the first argument. In case the add-on is interested only in specified elements, you can set the focus on those elements by passing the list of the element guids in the filterElementsInterestedOnly parameter. Note that there can be only one handler function set for this notification at the same time, that is you cannot set multiple handlers for different lists of elements.

Example

See the Examples section of APIReservationChangeHandlerProc
.
See also the Teamwork Control
 
and Notification Manager
 
example projects of the API Development Kit.

ACAPI_Notification_CatchLockableReservationChange()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchLockableReservationChange	(	APILockChangeHandlerProc *	handlerProc,
		const GS::HashSet< API_Guid > *	filterLockablesInterestedOnly = nullptr
	)

Sets notification handler for reservation changes of lockable objects.

Parameters

handlerProc	[in] Notification handler function to be called on the specified event. Pass nullptr to unsubscribe from this notification.
filterLockablesInterestedOnly	[in] List of guids of lockable objects; optional parameter for controlling the range of objects of interest. If passed, the lock change notifications will be sent for only these objects, otherwise every lock changes will be reported.

Returns

• NoError - The function completed successfully.

Remarks

This function is used to subscribe an add-on to be notified when reservations of lockable objects (e.g. attributes, favorites, model view options) have been changed in Teamwork. Once a APILockChangeHandlerProc function pointer is passed, the add-on remains loaded in the memory, and receives the notifications. When the add-on does not need these notifications any more, you can stop receiving them by calling this function with nullptr in the first argument. In case the add-on is interested only in specified objects, you can set the focus on those objects by passing the list of the guids in the filterLockablesInterestedOnly parameter (see the list of currently available lockable object sets). Note that there can be only one handler function set for this notification at the same time, that is you cannot set multiple handlers for different lists of lockable objects.

Example

See the Examples section of APILockChangeHandlerProc
.
See also the Teamwork Control
 
and Notification Manager
 
example projects of the API Development Kit.

ACAPI_Notification_CatchSelectionChange()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchSelectionChange

(

APISelectionChangeHandlerProc *

handlerProc

)

Turns the monitoring of selection changes on/off.

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.

Returns

• NoError - The function completed successfully.

Remarks

This function is used to register/unregister an add-on which wants to monitor the changes in selection. 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 selection changes.

Example

// -----------------------------------------------------------------------------
// Selection change handler function
// -----------------------------------------------------------------------------
static GSErrCode __ACENV_CALL    SelectionChangeHandler (const API_Neig *selElemNeig)
 
{
    char    msgStr[256];
 
    if (selElemNeig->neigID != APINeig_None) {
        sprintf (msgStr, "Last selected element: NeigID %d; index: %d, inIndex: %d",
                 selElemNeig->neigID, selElemNeig->index, selElemNeig->inIndex);
        ACAPI_WriteReport (msgStr, false);
    } else
        ACAPI_WriteReport ("All elements deselected", false);
 
    return NoError;
}   // SelectionChangeHandler
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)
 
{
    // catch changes in the selection
    GSErrCode err = ACAPI_Notification_CatchSelectionChange (SelectionChangeHandler);
 
    return err;
}   // Initialize

ACAPI_Notification_CatchToolChange()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchToolChange

(

APIToolChangeHandlerProc *

handlerProc

)

Turns the monitoring of toolbox item changes on/off.

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.

Returns

• NoError - The function completed successfully.

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_Notification_CatchToolChange (ToolChangeHandler);
 
    return err;
}   // Initialize

ACAPI_Notification_CatchViewEvent()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchViewEvent	(	GSFlags	eventTypes,
		API_NavigatorMapID	mapId,
		APIViewEventHandlerProc *	handlerProc
	)

Register or unregister your add-on to be notified of Project Navigator changes.

Parameters

eventTypes	[in] A combination of different API_NotifyViewEventID values, specifying the types of project navigator events you are interested in.
mapId	[in] Specifies the project navigator map you are interested in.
handlerProc	[in] The callback procedure to call when notifications are sent out... Specifying nullptr here means you don't need the notifications any more.

Returns

• NoError - The requested operation finished successfully.
• APIERR_BADPARS - The eventTypes parameter is invalid.

Remarks

This function enables the API tool add-on catch the changes of Project Navigator items in the specified map. Each time when a navigator item is inserted, modified, deleted or opened 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 any project navigator event of the specified map any longer, please remember to unregister by calling ACAPI_Notification_CatchViewEvent for the required map with nullptr in the handlerProc parameter.

Example

ACAPI_Notification_CatchViewEvent (APINotifyView_Inserted | APINotifyView_Deleted | APINotifyView_Modified, API_PublicViewMap, ViewNotificationHandlerProc);
ACAPI_Notification_CatchViewEvent (API_AllViewNotificationMask, API_MyViewMap, nullptr);

ACAPI_Notification_ClassificationVisibilityChanged()

GSErrCode __ACENV_CALL ACAPI_Notification_ClassificationVisibilityChanged

(

)

Sends out an APINotify_ClassificationVisibilityChanged project event notification to the other add-ons to state that at least one classification's visibility has changed.

Returns

• NoError - The function completed successfully.

ACAPI_Notification_GetObservedElements()

GSErrCode __ACENV_CALL ACAPI_Notification_GetObservedElements

(

GS::Array< API_Elem_Head > *

elemHeads

)

Returns the elements observed by the add-on.

Parameters

elemHeads

[out] The headers of the observed elements.

Returns

• NoError - The function has completed with success.

ACAPI_Notification_GetParentElement()

GSErrCode __ACENV_CALL ACAPI_Notification_GetParentElement	(	API_Element *	element,
		API_ElementMemo *	memo,
		UInt64	mask,
		API_ElementUserData *	userData
	)

Returns the parent of the actual element your addon received notification for.

Parameters

element	[out] The parent element to be retrieved.
memo	[out] Additional data of the parent element.
mask	[in] Mask for specifying the relevant memo handles to be retrieved.
userData	[out] Userdata of the parent element.

Returns

• NoError - The function was executed without error.
• APIERR_REFUSEDCMD - There was no parent element during the action.

Remarks

This function is used to retrieve the original element data from which the notified element has been derived. If you pass nullptr values in the memo and userData parameters, the function performs an ACAPI_Element_Get operation, otherwise it behaves like the ACAPI_Element_GetMemo or the ACAPI_Element_GetUserData function. You can use this function to find out what changes have been made to the original element during the operation.

Example

See the example for ACAPI_Element_CatchNewElement
.

ACAPI_Notification_GetTranParams()

GSErrCode __ACENV_CALL ACAPI_Notification_GetTranParams

(

API_ActTranPars *

actTranPars

)

Returns the transformation parameters of the actual edit operation.

Parameters

actTranPars

[out] The transformation parameters to be returned.

Returns

• NoError - The function has been executed without error.
• APIERR_BADPARS - The actTranPars parameter is nullptr.

Remarks

This function is used to get the parameters of the actual editing operation. The transformation data is valid only between a APINotifyElement_BeginEvents and the following APINotifyElement_EndEvents notification. By using this function your add-on is able to update some elements according to the user's edit action.

Example

[ ... ]
 
API_Neig        **neig;
API_ActTranPars actTranPars;
API_EditPars    editPars;
Int32           elemIndex = 1;      // transform this element according to
GSErrCode       err;                // the last user edit parameters
 
    case APINotifyElement_Edit:
 
            BNZeroMemory (&editPars, sizeof (API_EditPars));
 
            ACAPI_Notification_GetTranParams (&actTranPars);
 
            switch (actTranPars.typeID) {
                case APIEdit_Drag:
                        editPars.typeID = APIEdit_Drag;
                        editPars.begC.x = 0.0;
                        editPars.endC.y = 0.0;
                        editPars.endC.z = 0.0;
                        editPars.endC.x = actTranPars.theDisp.x;
                        editPars.endC.y = actTranPars.theDisp.y;
                        editPars.endC.z = actTranPars.theDispZ;
                        break;
                case APIEdit_Rotate:
                        editPars.typeID = APIEdit_Rotate;
                        editPars.origC = actTranPars.theOrigo;
                        editPars.begC.x = editPars.origC.x + 1.0;
                        editPars.begC.y = editPars.origC.y;
                        editPars.begC.z = 0.0;
                        editPars.endC.x = editPars.origC.x + actTranPars.theCosA;
                        editPars.endC.y = editPars.origC.y + actTranPars.theSinA;
                        editPars.endC.z = 0.0;
                        break;
                case APIEdit_Mirror:
                        editPars.typeID = APIEdit_Mirror;
                        editPars.begC.x = actTranPars.theOrigo.x;
                        editPars.begC.y = actTranPars.theOrigo.y;
                        editPars.begC.z = 0.0;
                        editPars.endC.x = actTranPars.theOrigo.x + actTranPars.theAxeVect.x;
                        editPars.endC.y = actTranPars.theOrigo.y + actTranPars.theAxeVect.y;
                        editPars.endC.z = 0.0;
                        break;
                case APIEdit_Stretch:
                        editPars.typeID = APIEdit_Stretch;
                        editPars.endC.x = actTranPars.theDisp.x;
                        editPars.endC.y = actTranPars.theDisp.y;
                        editPars.endC.z = 0.0;
                        break;
            }
 
            editPars.withDelete = true;
 
            neig = reinterpret_cast<API_Neig**> BMAllocateHandle (sizeof (API_Neig), ALLOCATE_CLEAR, 0);
            if (neig != nullptr) {
                (*neig)[0].neigID  = APINeig_CircOn;
                (*neig)[0].index   = elemIndex;
                (*neig)[0].inIndex = 1;
 
                err = ACAPI_Element_Edit (neig, 1, &editPars);
                if (err != NoError)
                    GiveMessage_Err ("Error in ACAPI_Element_Edit", err);
 
                BMKillHandle (reinterpret_cast<GSHandle *> &neig);
            }
        }
        break;
}

ACAPI_Notification_PropertyVisibilityChanged()

GSErrCode __ACENV_CALL ACAPI_Notification_PropertyVisibilityChanged

(

)

Sends out an APINotify_PropertyVisibilityChanged project event notification to the other add-ons to state that at least one property's visibility has changed.

Returns

• NoError - The function completed successfully.

ACAPI_Notification_RegisterEventHandler()

GSErrCode __ACENV_CALL ACAPI_Notification_RegisterEventHandler	(	GS::Owner< API_IEventHandler >	eventHandler,
		API_Guid &	id
	)

Register an event handler in your add-on.

Since

Archicad 26

Parameters

eventHandler	[in] The event handler to be registered.
id	[out] The identifier of the successfully registered event handler.

Returns

• NoError - The requested operation finished successfully.
• APIERR_BADPARS - The requested operation failed due to a nullptr in-parameter.

Remarks

In case you register an event handler your add-on will automatically be kept loaded in memory. The id out-parameter can be used to manually unregister the event handler by calling ACAPI_Notification_UnregisterEventHandler.

Example

// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)
{
    class ClassificationSystemEventHandler : public API_IClassificationSystemEventHandler {
    public:
        virtual void OnCreated (const GS::HashSet<API_Guid>& ids) const override
        {
            ACAPI_WriteReport ("The following Classification Systems were created:\n", false);
 
            for (const auto& id : ids) {
                ACAPI_WriteReport ("  - " + APIGuidToString (id) + "\n", false);
            }
        }
    };
 
    return ACAPI_Notification_RegisterEventHandler (GS::NewOwned<ClassificationSystemEventHandler> (), myEventHandlerId);
}

ACAPI_Notification_UnregisterEventHandler()

GSErrCode __ACENV_CALL ACAPI_Notification_UnregisterEventHandler

(

const API_Guid &

id

)

Unregister an event handler from your add-on.

Since

Archicad 26

Parameters

id	[in] The identifier of a previously registered event handler.

Returns

• NoError - The requested operation finished successfully.
• APIERR_BADPARS - The requested operation failed due to an invalid id in-parameter.

Remarks

If not specified otherwise by ACAPI_KeepInMemory the add-on will automatically unload if you unregister all event handlers.

Example

// -----------------------------------------------------------------------------
// Called when the Add-On is going to be unloaded
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    FreeData (void)
{
    return ACAPI_Notification_UnregisterEventHandler (myEventHandlerId);
}

ACAPI_ProjectOperation_CatchProjectEvent()

GSErrCode __ACENV_CALL ACAPI_ProjectOperation_CatchProjectEvent	(	GSFlags	eventTypes,
		APIProjectEventHandlerProc *	handlerProc
	)

Register or unregister your add-on to be notified of application and project events.

Parameters

eventTypes	[in] A combination of different API_NotifyEventID values, specifying the types of project events you are interested in.
handlerProc	[in] The callback procedure to call when notifications are sent out on different project events. Specifying nullptr here means you don't need the notifications any more.

Returns

• NoError - The requested operation finished successfully.

Remarks

This function enables the API tool add-on catch events happening to the project. Each time when such an event occurs 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 project events any longer, please remember to unregister by calling ACAPI_ProjectOperation_CatchProjectEvent for the required element type with nullptr in the handlerProc parameter.

Example

// -----------------------------------------------------------------------------
// Project event handler function
// -----------------------------------------------------------------------------
static GSErrCode __ACENV_CALL    NotificationHandler (API_NotifyEventID notifID, Int32 param)
{
    char    msgStr[256];
 
    switch (notifID) {
        case APINotify_New:                CHCopyC ("APINotify_New", msgStr);             break;
        case APINotify_NewAndReset:        CHCopyC ("APINotify_NewAndReset", msgStr);     break;
        case APINotify_Open:               CHCopyC ("APINotify_Open", msgStr);            break;
        case APINotify_PreSave:            CHCopyC ("APINotify_PreSave", msgStr);         break;
        case APINotify_Save:               CHCopyC ("APINotify_Save", msgStr);            break;
        case APINotify_Close:              CHCopyC ("APINotify_Close", msgStr);           break;
        case APINotify_Quit:               CHCopyC ("APINotify_Quit", msgStr);            break;
 
        case APINotify_SendChanges:        CHCopyC ("APINotify_SendChanges", msgStr);     break;
        case APINotify_ReceiveChanges:     CHCopyC ("APINotify_ReceiveChanges", msgStr);  break;
 
        case APINotify_ChangeProjectDB:    CHCopyC ("APINotify_ChangeProjectDB", msgStr); break;
        case APINotify_ChangeWindow:       CHCopyC ("APINotify_ChangeWindow", msgStr);    break;
        case APINotify_ChangeFloor:        CHCopyC ("APINotify_ChangeFloor", msgStr);     break;
        case APINotify_ChangeLibrary:      CHCopyC ("APINotify_ChangeLibrary", msgStr);   break;
    }
 
    ACAPI_WriteReport (msgStr, false);
 
    return NoError;
}   // NotificationHandler
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)
 
{
    // catch changes in project events
    GSErrCode err = ACAPI_ProjectOperation_CatchProjectEvent (API_AllProjectNotificationMask, NotificationHandler);
 
    return err;
}   // Initialize