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
class	ACAPI::EditNotificationInterface
	EditNotificationInterface is responsible for handling Edit Notifications through API. You can make your own notification implementation, which will be executed after element editings. More...

class	ACAPI::UI::Notification::NotificationBubble
	NotificationBubble is a tooltip-like small window, which can display various information for the user. More...

class	ACAPI::UI::Notification::NotificationBubbleManager
	A class that contains notification bubble related functions. More...

class	ACAPI::API_IKeynoteEventNotifier
	Defining an interface for a class that will be used to notify keynote event handlers. More...

class	ACAPI::API_IKeynoteItemEventHandler
	The base class you need to inherit from in case you want to handle keynote item events. More...

class	ACAPI::API_IKeynoteFolderEventHandler
	The base class you need to inherit from in case you want to handle keynote folder events. More...

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_IACEventNotifier
	Defining an interface for a class that will be used to notify 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

class	API_IWindowEventHandler
	The base class you need to inherit from in case you want to handle window change events. More...

class	API_IView3DSettingsEventHandler
	The base class you need to inherit from in case you want to handle view 3D settings events. More...

struct	API_ActTranPars
	Structure for retrieving the transformation data of the actual editing operation. More...

Typedefs
typedef GSErrCode	APIProjectEventHandlerProc(API_NotifyEventID notifID, Int32 param)
	Callback function to receive notifications on changes of the project.

typedef GSErrCode	APIViewEventHandlerProc(const API_NotifyViewEventType *viewEvent)
	User supplied callback function for handling changes of Project Navigator items.

typedef GSErrCode	APIDefaultsChangeHandlerProc(const API_ToolBoxItem *defElemType)
	Callback procedure to receive notifications on changes in element defaults.

typedef GSErrCode	APIToolChangeHandlerProc(const API_ToolBoxItem *newToolMode)
	Callback function to handle changes in the toolbox.

typedef GSErrCode	APISelectionChangeHandlerProc(const API_Neig *selElemNeig)
	User supplied callback procedure for handling selection changes.

typedef GSErrCode	APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)
	User supplied callback procedure for handling attribute replacements.

typedef GSErrCode	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	APILockChangeHandlerProc(const API_Guid &objectId, short ownerId)
	User supplied callback procedure for handling reservation changes of lockable objects.

typedef GSErrCode	APILicenseBorrowStatusChangeHandlerProc(API_LicenseBorrowStatusTypeID licenseBorrowStatus)
	User supplied callback procedure for handling license borrowing status changes.

typedef GSErrCode	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_NotifyWindowEventID { APINotifyWindow_Rebuild = 1 , APINotifyWindow_Activate = 2 , APINotifyWindow_Close = 3 }
	Describes the cause of the window notification. 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
NotificationBubbleManager	ACAPI::UI::Notification::CreateNotificationBubbleManager ()
	A function to create a notification bubble manager, which lets you create notification bubbles from API.

GSErrCode	ACAPI_Element_AttachObserver (const API_Guid &elemGuid, GSFlags notifyFlags=0)
	Attaches an observer to the given element.

GSErrCode	ACAPI_Element_DetachObserver (const API_Guid &elemGuid)
	Detaches the observer from the given element.

GSErrCode	ACAPI_Notification_GetObservedElements (GS::Array< API_Elem_Head > *elemHeads)
	Returns the elements observed by the add-on.

GSErrCode	ACAPI_ProjectOperation_CatchProjectEvent (GSFlags eventTypes, APIProjectEventHandlerProc *handlerProc)
	Register or unregister your add-on to be notified of application and project events.

GSErrCode	ACAPI_Notification_CatchViewEvent (GSFlags eventTypes, API_NavigatorMapID mapId, APIViewEventHandlerProc *handlerProc)
	Register or unregister your add-on to be notified of Project Navigator changes.

GSErrCode	ACAPI_Notification_CatchToolChange (APIToolChangeHandlerProc *handlerProc)
	Turns the monitoring of toolbox item changes on/off.

GSErrCode	ACAPI_Notification_CatchSelectionChange (APISelectionChangeHandlerProc *handlerProc)
	Turns the monitoring of selection changes on/off.

GSErrCode	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	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	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	ACAPI_Element_InstallElementObserver (APIElementEventHandlerProc *handlerProc)
	Installs an element observer function which receives notifications on elements' changes.

GSErrCode	ACAPI_Notification_GetTranParams (API_ActTranPars *actTranPars)
	Returns the transformation parameters of the actual edit operation.

GSErrCode	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	ACAPI_Notification_CatchElementReservationChange (APIReservationChangeHandlerProc handlerProc, const GS::HashSet< API_Guid > filterElementsInterestedOnly=nullptr)
	Sets notification handler for element reservation changes.

GSErrCode	ACAPI_Notification_CatchLockableReservationChange (APILockChangeHandlerProc handlerProc, const GS::HashSet< API_Guid > filterLockablesInterestedOnly=nullptr)
	Sets notification handler for reservation changes of lockable objects.

GSErrCode	ACAPI_Licensing_CatchLicenseBorrowStatusChange (APILicenseBorrowStatusChangeHandlerProc *handlerProc)
	Catches notifications on license borrowing status changes.

GSErrCode	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	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	ACAPI_Notification_RegisterEventHandler (GS::Owner< API_IEventHandler > eventHandler, API_Guid &id)
	Register an event handler in your add-on.

GSErrCode	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 APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)

User supplied callback procedure for handling attribute replacements.

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 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 changes with ACAPI_Element_CatchChangeDefaults.

◆ APIElementEventHandlerProc

typedef GSErrCode 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 described at the API_NotifyElementType structure.

Example: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Element event handler function

// -----------------------------------------------------------------------------

GSErrCode ElementEventHandler (const API_NotifyElementType *elemType)

{

GSErrCode err = NoError;

char msgStr[256];

char elemStr[32];

API_Element parentElement {};

ACAPI_Notification_GetParentElement (&parentElement, nullptr, 0, nullptr);

switch (elemType->notifID) {

case APINotifyElement_New:

if (GetElementTypeString (elemType->elemHead.type, elemStr)) {

if (parentElement.header.guid != APINULLGuid)

sprintf (msgStr, "### API Notify Test: %s #%s created as a copy of #%s",

elemStr, APIGuidToString (elemType->elemHead.guid).ToCStr ().Get (),

APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

else

sprintf (msgStr, "### API Notify Test: %s #%s created", elemStr,

APIGuidToString (elemType->elemHead.guid).ToCStr ().Get ());

err = ACAPI_Element_AttachObserver (elemType->elemHead.guid, 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 Initialize ()

{

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

// catch changes in defaults for all element types

return ACAPI_Element_CatchNewElement (&elemType_Wall, ElementEventHandler);

}

◆ APILicenseBorrowStatusChangeHandlerProc

typedef GSErrCode 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 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 affected by the current team member as well. In the reservation change handler try to avoid calling functions that would modify the database.

Example: GSErrCode LockableReservationChangeHandler (const API_Guid& objectId, short ownerId)

{

GS::UniString reportString;

if (objectId == ACAPI_Teamwork_FindLockableObjectSet ("FillTypes"))

reportString.Append ("Fill Types");

else

reportString.Append ("Layer Settings");

if (ownerId > 0)

reportString.Append (" got reserved");

else

reportString.Append (" got released");

ACAPI_WriteReport (reportString.ToCStr ().Get (), false);

return NoError;

}

// -----------------------------------------------------------------------------

//

// -----------------------------------------------------------------------------

void CatchReservationChangesOfFillTypesAndLayerSettings (bool enableNotifications)

{

if (enableNotifications) {

GS::HashSet<API_Guid> filterLockablesInterestedOnly;

filterLockablesInterestedOnly.Add (ACAPI_Teamwork_FindLockableObjectSet ("FillTypes"));

filterLockablesInterestedOnly.Add (ACAPI_Teamwork_FindLockableObjectSet ("LayerSettingsDialog"));

ACAPI_Notification_CatchLockableReservationChange (LockableReservationChangeHandler, &filterLockablesInterestedOnly);

} else {

ACAPI_Notification_CatchLockableReservationChange (nullptr);

}

}

◆ APIProjectEventHandlerProc

typedef GSErrCode 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 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.

Example: GSErrCode ElementReservationChangeHandler (const GS::HashTable<API_Guid, short>& reserved,

const GS::HashSet<API_Guid>& /*released*/,

const GS::HashSet<API_Guid>& /*deleted*/)

{

GS::HashTable<API_ElemTypeID,Int32> reservedStat;

for (GS::HashTable<API_Guid, short>::ConstPairIterator it = reserved.EnumeratePairs (); it != nullptr; ++it) {

API_Elem_Head elemHead;

BNZeroMemory (&elemHead, sizeof (API_Elem_Head));

elemHead.guid = it->key;

if (ACAPI_Element_GetHeader (&elemHead) == NoError)

++(reservedStat.Retrieve (elemHead.type.typeID, 0)); // counting elements of the same type

}

if (!reservedStat.IsEmpty ()) { // print statistics of reserved elements

GS::UniString reportString ("= Recently reserved elements: ");

for (GS::HashTable<API_ElemTypeID,Int32>::PairIterator it = reservedStat.EnumeratePairs (); it != nullptr; ++it) {

GS::UniString elemTypeName;

ACAPI_Element_GetElemTypeName (it->key, elemTypeName);

GS::UniString elemCountStr = GS::UniString::Printf (" %T:%d", elemTypeName.ToPrintf (), it->value);

reportString.Append (elemCountStr);

}

ACAPI_WriteReport (reportString.ToCStr ().Get (), false);

}

return NoError;

}

// -----------------------------------------------------------------------------

//

// -----------------------------------------------------------------------------

void CatchElementReservationChanges (bool enableNotifications)

{

if (enableNotifications)

ACAPI_Notification_CatchElementReservationChange (ElementReservationChangeHandler);

else

ACAPI_Notification_CatchElementReservationChange (nullptr);

}

◆ APISelectionChangeHandlerProc

typedef GSErrCode 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 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 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.

Enumerator
APINotifyElement_BeginEvents	Indicates the start of element notifications.
APINotifyElement_EndEvents	End of element notifications (no more notifications are expected in this task).
APINotifyElement_New	A new element was created.
APINotifyElement_Copy	The element was copied; the notifications are coming for the copy of the original element.
APINotifyElement_Change	The parameters of the element were changed.
APINotifyElement_Edit	The element was edited. The parameters of the editing transformation can be retrieved with ACAPI_Notification_GetTranParams.
APINotifyElement_Delete	The element was deleted.
APINotifyElement_Undo_Created	The last creating operation performed on the element has been undone.
APINotifyElement_Undo_Modified	The last modifying operation performed on the element has been undone.
APINotifyElement_Undo_Deleted	The last deleting operation performed on the element has been undone.
APINotifyElement_Redo_Created	The last undone creating operation on the element has been redone.
APINotifyElement_Redo_Modified	The last undone modifying operation on the element has been redone.
APINotifyElement_Redo_Deleted	The last undone deleting operation on the element has been redone.
APINotifyElement_PropertyValueChange	A property value attached to the element has been changed.
APINotifyElement_ClassificationChange	An element's classification has changed.

◆ 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.

Enumerator
API_UndefinedMap	Undefined Project Navigator map.
API_ProjectMap	Project map.
API_PublicViewMap	Public View map.
API_MyViewMap	Your own view map (only in Teamwork mode).
API_LayoutMap	Layout map.
API_PublisherSets	Publisher Sets.

◆ 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.

Enumerator
APINotify_New	The user chose New from the File menu.
APINotify_NewAndReset	The user chose New & Reset from the File menu.
APINotify_Open	The user opened an existing project.
APINotify_PreSave	The user has chosen Save from the File menu; this notification is coming before the actual save is performed, so that you could save some data into the project file. Please try to avoid using this method if not necessary, because it can significantly slow down the file saving process. Rather store the additional data into the project when they actually change.
APINotify_Save	The user has chosen Save from the File menu; the project has already been saved.
APINotify_Close	The user closed the current project.
APINotify_Quit	The user chose Quit from the File menu.
APINotify_TempSave	The project is about to be autosaved.
APINotify_SendChanges	The user is about to send changes into the Teamwork project.
APINotify_ReceiveChanges	The user has received the changes from the Teamwork project.
APINotify_ChangeProjectDB	The project database changed.
APINotify_ChangeWindow	The current window changed.
APINotify_ChangeFloor	The user switched to an other floor.
APINotify_ChangeLibrary	The loaded libraries were changed.
APINotify_AllInputFinished	Sent when an input process (open, merge, etc.) is finished.
APINotify_UnitChanged	Notifies that the working units or calculation units have changed on Preferences dialogs.
APINotify_SideviewCreated	The section/elevation/interior elevation was generated. The first time its window was opened.
APINotify_SideviewRebuilt	The section/elevation/interior elevation was rebuilt.
APINotify_PropertyVisibilityChanged	Notifies that Property visibility has changed.
APINotify_ClassificationVisibilityChanged	Notifies that Classification visibility has changed.
APINotify_ShowIn3DChanged	This notification is sent when the user has chosen Show Selection in 3D / Show All in 3D / Show stored selection in 3D.

◆ API_NotifyViewEventID

enum API_NotifyViewEventID

Possible values for notifications on Project Navigator events.

Remarks: Refer to ACAPI_Notification_CatchViewEvent function for further details.

Enumerator
APINotifyView_Inserted	A new Project Navigator item was inserted.
APINotifyView_Modified	A Project Navigator item was modified.
APINotifyView_Deleted	A Project Navigator item was deleted.
APINotifyView_Opened	A Project Navigator item was opened.
APINotifyView_Begin	The begin notification.
APINotifyView_End	The end notification.

◆ API_NotifyWindowEventID

enum API_NotifyWindowEventID

Describes the cause of the window notification.

Enumerator
APINotifyWindow_Rebuild	The user chose Rebuild from the menu.
APINotifyWindow_Activate	Your window was activated.
APINotifyWindow_Close	The user closed your window.

Function Documentation

◆ ACAPI_Element_AttachObserver()

GSErrCode 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 successfully.
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 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: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Defaults change handler function

// -----------------------------------------------------------------------------

GSErrCode 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 Initialize ()

{

// catch changes in defaults for all element types

return ACAPI_Element_CatchChangeDefaults (nullptr, ChangeDefaultsHandler);

} // Initialize

◆ ACAPI_Element_CatchNewElement()

GSErrCode 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: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Element event handler function

// -----------------------------------------------------------------------------

GSErrCode ElementEventHandler (const API_NotifyElementType *elemType)

{

GSErrCode err = NoError;

char msgStr[256];

char elemStr[32];

API_Element parentElement {};

ACAPI_Notification_GetParentElement (&parentElement, nullptr, 0, nullptr);

switch (elemType->notifID) {

case APINotifyElement_New:

if (GetElementTypeString (elemType->elemHead.type, elemStr)) {

if (parentElement.header.guid != APINULLGuid)

sprintf (msgStr, "### API Notify Test: %s #%s created as a copy of #%s",

elemStr, APIGuidToString (elemType->elemHead.guid).ToCStr ().Get (),

APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

else

sprintf (msgStr, "### API Notify Test: %s #%s created", elemStr,

APIGuidToString (elemType->elemHead.guid).ToCStr ().Get ());

err = ACAPI_Element_AttachObserver (elemType->elemHead.guid, 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 Initialize ()

{

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

// catch changes in defaults for all element types

return ACAPI_Element_CatchNewElement (&elemType_Wall, ElementEventHandler);

}

◆ ACAPI_Element_DetachObserver()

GSErrCode 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 successfully.
APIERR_BADID - The referenced element cannot be found in the database.

◆ ACAPI_Element_InstallElementObserver()

GSErrCode 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: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Element observer callback function

// -----------------------------------------------------------------------------

static GSErrCode ElementEventHandler (const API_NotifyElementType *elemType)

{

GSErrCode err = NoError;

char msgStr[256];

char elemStr[32];

API_Element parentElement {};

ACAPI_Notification_GetParentElement (&parentElement, nullptr, 0, nullptr);

switch (elemType->notifID) {

case APINotifyElement_Copy:

if (parentElement.header.guid != APINULLGuid && GetElementTypeString (elemType->elemHead.type, elemStr)) {

sprintf (msgStr, "### Element_Manager: %s #%s copied from #%s",

elemStr, APIGuidToString (elemType->elemHead.guid).ToCStr ().Get (),

APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

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

}

break;

default:

err = APIERR_NOTSUPPORTED;

break;

}

if (err == NoError)

ACAPI_WriteReport (msgStr, false);

return err;

}

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

// catch changes in the selection

return ACAPI_Element_InstallElementObserver (ElementEventHandler);

}

◆ ACAPI_Licensing_CatchLicenseBorrowStatusChange()

GSErrCode 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 successfully.

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

◆ ACAPI_Notification_CatchAttributeReplacement()

GSErrCode 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 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.ToInt32_Deprecated (), entry.value.ToInt32_Deprecated ());

ACAPI_WriteReport (msgStr, false);

}

}

return NoError;

}

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

return ACAPI_Notification_CatchAttributeReplacement (HandleAttributeReplacement);

}

◆ ACAPI_Notification_CatchElementReservationChange()

GSErrCode 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: GSErrCode ElementReservationChangeHandler (const GS::HashTable<API_Guid, short>& reserved,

const GS::HashSet<API_Guid>& /*released*/,

const GS::HashSet<API_Guid>& /*deleted*/)

{

GS::HashTable<API_ElemTypeID,Int32> reservedStat;

for (GS::HashTable<API_Guid, short>::ConstPairIterator it = reserved.EnumeratePairs (); it != nullptr; ++it) {

API_Elem_Head elemHead;

BNZeroMemory (&elemHead, sizeof (API_Elem_Head));

elemHead.guid = it->key;

if (ACAPI_Element_GetHeader (&elemHead) == NoError)

++(reservedStat.Retrieve (elemHead.type.typeID, 0)); // counting elements of the same type

}

if (!reservedStat.IsEmpty ()) { // print statistics of reserved elements

GS::UniString reportString ("= Recently reserved elements: ");

for (GS::HashTable<API_ElemTypeID,Int32>::PairIterator it = reservedStat.EnumeratePairs (); it != nullptr; ++it) {

GS::UniString elemTypeName;

ACAPI_Element_GetElemTypeName (it->key, elemTypeName);

GS::UniString elemCountStr = GS::UniString::Printf (" %T:%d", elemTypeName.ToPrintf (), it->value);

reportString.Append (elemCountStr);

}

ACAPI_WriteReport (reportString.ToCStr ().Get (), false);

}

return NoError;

}

// -----------------------------------------------------------------------------

//

// -----------------------------------------------------------------------------

void CatchElementReservationChanges (bool enableNotifications)

{

if (enableNotifications)

ACAPI_Notification_CatchElementReservationChange (ElementReservationChangeHandler);

else

ACAPI_Notification_CatchElementReservationChange (nullptr);

}

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

◆ ACAPI_Notification_CatchLockableReservationChange()

GSErrCode 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: GSErrCode LockableReservationChangeHandler (const API_Guid& objectId, short ownerId)

{

GS::UniString reportString;

if (objectId == ACAPI_Teamwork_FindLockableObjectSet ("FillTypes"))

reportString.Append ("Fill Types");

else

reportString.Append ("Layer Settings");

if (ownerId > 0)

reportString.Append (" got reserved");

else

reportString.Append (" got released");

ACAPI_WriteReport (reportString.ToCStr ().Get (), false);

return NoError;

}

// -----------------------------------------------------------------------------

//

// -----------------------------------------------------------------------------

void CatchReservationChangesOfFillTypesAndLayerSettings (bool enableNotifications)

{

if (enableNotifications) {

GS::HashSet<API_Guid> filterLockablesInterestedOnly;

filterLockablesInterestedOnly.Add (ACAPI_Teamwork_FindLockableObjectSet ("FillTypes"));

filterLockablesInterestedOnly.Add (ACAPI_Teamwork_FindLockableObjectSet ("LayerSettingsDialog"));

ACAPI_Notification_CatchLockableReservationChange (LockableReservationChangeHandler, &filterLockablesInterestedOnly);

} else {

ACAPI_Notification_CatchLockableReservationChange (nullptr);

}

}

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

◆ ACAPI_Notification_CatchSelectionChange()

GSErrCode 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 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, static_cast<Int32> (selElemNeig->elemPartIndex), selElemNeig->inIndex);

ACAPI_WriteReport (msgStr, false);

} else

ACAPI_WriteReport ("All elements deselected", false);

return NoError;

}

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

// catch changes in the selection

return ACAPI_Notification_CatchSelectionChange (SelectionChangeHandler);

}

◆ ACAPI_Notification_CatchToolChange()

GSErrCode 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: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Toolbox item change handler function

// -----------------------------------------------------------------------------

GSErrCode ToolChangeHandler (const API_ToolBoxItem *newToolMode)

{

char msgStr[256];

char elemStr[32];

if (newToolMode->type.typeID == API_ZombieElemID)

CHCopyC ("Arrow or Marquee", elemStr);

else if (!GetElementTypeString (newToolMode->type.typeID, elemStr))

CHCopyC ("Unknown", elemStr);

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

ACAPI_WriteReport (msgStr, false);

return NoError;

}

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

// catch changes in the toolbox

return ACAPI_Notification_CatchToolChange (ToolChangeHandler);

}

◆ ACAPI_Notification_CatchViewEvent()

GSErrCode 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 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 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 successfully.

◆ ACAPI_Notification_GetParentElement()

GSErrCode 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: #define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Element event handler function

// -----------------------------------------------------------------------------

GSErrCode ElementEventHandler (const API_NotifyElementType *elemType)

{

GSErrCode err = NoError;

char msgStr[256];

char elemStr[32];

API_Element parentElement {};

ACAPI_Notification_GetParentElement (&parentElement, nullptr, 0, nullptr);

switch (elemType->notifID) {

case APINotifyElement_New:

if (GetElementTypeString (elemType->elemHead.type, elemStr)) {

if (parentElement.header.guid != APINULLGuid)

sprintf (msgStr, "### API Notify Test: %s #%s created as a copy of #%s",

elemStr, APIGuidToString (elemType->elemHead.guid).ToCStr ().Get (),

APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

else

sprintf (msgStr, "### API Notify Test: %s #%s created", elemStr,

APIGuidToString (elemType->elemHead.guid).ToCStr ().Get ());

err = ACAPI_Element_AttachObserver (elemType->elemHead.guid, 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 Initialize ()

{

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

// catch changes in defaults for all element types

return ACAPI_Element_CatchNewElement (&elemType_Wall, ElementEventHandler);

}

◆ ACAPI_Notification_GetTranParams()

GSErrCode 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: //[ ... ]

GS::Array<API_Neig> neig;

API_ActTranPars actTranPars;

API_EditPars editPars {};

Int32 elemIndex = 1; // transform this element according to

GSErrCode err; // the last user edit parameters

switch (eventID) {

case APINotifyElement_Edit:

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[0].neigID = APINeig_CircOn;

neig[0].elemPartIndex = elemIndex;

neig[0].inIndex = 1;

err = ACAPI_Element_Edit (&neig, editPars);

if (err != NoError)

WriteReport_Err ("Error in ACAPI_Element_Edit", err);

break;

}

◆ ACAPI_Notification_PropertyVisibilityChanged()

GSErrCode 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 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: class ClassificationSystemEventHandler : public API_IClassificationSystemEventHandler {

public:

virtual ~ClassificationSystemEventHandler ();

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);

}

}

};

ClassificationSystemEventHandler::~ClassificationSystemEventHandler () {}

API_Guid myEventHandlerId = APINULLGuid;

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

return ACAPI_Notification_RegisterEventHandler (GS::NewOwned<ClassificationSystemEventHandler> (), myEventHandlerId);

}

◆ ACAPI_Notification_UnregisterEventHandler()

GSErrCode 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 FreeData ()

{

return ACAPI_Notification_UnregisterEventHandler (myEventHandlerId);

}

◆ ACAPI_ProjectOperation_CatchProjectEvent()

GSErrCode 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

// -----------------------------------------------------------------------------

GSErrCode 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 Initialize ()

{

// catch changes in project events

GSErrCode err = ACAPI_ProjectOperation_CatchProjectEvent (API_AllProjectNotificationMask, NotificationHandler);

return err;

}

◆ CreateNotificationBubbleManager()

NotificationBubbleManager ACAPI::UI::Notification::CreateNotificationBubbleManager ( )

inline

A function to create a notification bubble manager, which lets you create notification bubbles from API.

Returns: The notification bubble manager.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Notification Manager

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

Functions

Element related notifications

Monitoring elements

How does it work?

Typedef Documentation

◆ APIAttributeReplacementHandlerProc

◆ APIDefaultsChangeHandlerProc

◆ APIElementEventHandlerProc

◆ APILicenseBorrowStatusChangeHandlerProc

◆ APILockChangeHandlerProc

◆ APIProjectEventHandlerProc

◆ APIReservationChangeHandlerProc

◆ APISelectionChangeHandlerProc

◆ APIToolChangeHandlerProc

◆ APIViewEventHandlerProc

Enumeration Type Documentation

◆ API_ElementDBEventID

◆ API_NavigatorMapID

◆ API_NotifyEventID

◆ API_NotifyViewEventID

◆ API_NotifyWindowEventID

Function Documentation

◆ ACAPI_Element_AttachObserver()

◆ ACAPI_Element_CatchChangeDefaults()

◆ ACAPI_Element_CatchNewElement()

◆ ACAPI_Element_DetachObserver()

◆ ACAPI_Element_InstallElementObserver()

◆ ACAPI_Licensing_CatchLicenseBorrowStatusChange()

◆ ACAPI_Notification_CatchAttributeReplacement()

◆ ACAPI_Notification_CatchElementReservationChange()

◆ ACAPI_Notification_CatchLockableReservationChange()

◆ ACAPI_Notification_CatchSelectionChange()

◆ ACAPI_Notification_CatchToolChange()

◆ ACAPI_Notification_CatchViewEvent()

◆ ACAPI_Notification_ClassificationVisibilityChanged()

◆ ACAPI_Notification_GetObservedElements()

◆ ACAPI_Notification_GetParentElement()

◆ ACAPI_Notification_GetTranParams()

◆ ACAPI_Notification_PropertyVisibilityChanged()

◆ ACAPI_Notification_RegisterEventHandler()

◆ ACAPI_Notification_UnregisterEventHandler()

◆ ACAPI_ProjectOperation_CatchProjectEvent()

◆ CreateNotificationBubbleManager()