Element Links

Functions for creating, handling and deleting custom (Add-On specific) Element Links. These links can provide associations between two elements. The advantage of using element linking is that the server application automatically tracks changes in the GUIDs, and updates them accordingly. More...

Functions
GSErrCode	ACAPI_ElementLink_Link (const API_Guid &guid_linkFrom, const API_Guid &guid_linkTo, GSFlags linkFlags)
	Links one element to another.
GSErrCode	ACAPI_ElementLink_Unlink (const API_Guid &guid_linkFrom, const API_Guid &guid_linkTo)
	Removes the link from the second element to the first.
GSErrCode	ACAPI_ElementLink_GetLinks (const API_Guid &guid_linkFrom, GS::Array< API_Guid > *guid_linkTo)
	Returns a list of elements linked to the given element.
GSErrCode	ACAPI_ElementLink_GetLinkFlags (const API_Guid &guid_linkFrom, const API_Guid &guid_linkTo, GSFlags *linkFlags)
	Retrieves the link flags associated to the link between the two elements.
GSErrCode	ACAPI_ElementLink_GetLinkedPropertyObjects (const API_Elem_Head *head, bool *criteria, Int32 *inviduallyLibInd, Int32 **critLibInds, Int32 *nCrits)
	Retrieves property objects linked to an element or the element default.
GSErrCode	ACAPI_ElementLink_SetLinkedPropertyObjects (API_Elem_Head *head, bool criteria, Int32 inviduallyLibInd)
	Link property objects to an element or the element default.

Detailed Description

Functions for creating, handling and deleting custom (Add-On specific) Element Links. These links can provide associations between two elements. The advantage of using element linking is that the server application automatically tracks changes in the GUIDs, and updates them accordingly.

Function Documentation

ACAPI_ElementLink_GetLinkedPropertyObjects()

GSErrCode ACAPI_ElementLink_GetLinkedPropertyObjects	(	const API_Elem_Head *	head,
		bool *	criteria,
		Int32 *	inviduallyLibInd,
		Int32 **	critLibInds,
		Int32 *	nCrits
	)

Retrieves property objects linked to an element or the element default.

Parameters

head	[in] Header of the element (only field guid is used). Properties linked to the default element are retrieved when guid is APINULLGuid
criteria	[out] Determines whether the matching properties by criteria are linked to the element
inviduallyLibInd	[out] Library index of individually assigned property (value zero means no individual property assigned)
critLibInds	[out] Aray of the library indices of linked properties matching the criteria
nCrits	[out] Number of linked properties matching the criteria

Returns

Remarks

This function is used to get the list of property objects for a linked element. Properties can be associated with construction elements by criteria and/or by individual direct assignment (at most one individual assignment can be applied to an element). This applies to all types of construction elements. If no element is specified (ie. guid is APINULLGuid), the default settings of the given element type are retrieved. Any of the arguments except head can be nullptr, in this case the function retrieves only the rest of the parameters. Remember to free the critLibInds array when not needed any more.

Example

void GetLinkedProperties (const API_Guid& guid)
{
    API_Element     element;
 
    BNClear (element);
    element.header.guid  = guid;
    err = ACAPI_Element_Get (&element);
    if (err == NoError) {
        bool    byCrit;
        Int32   indivLibInd;
        Int32   nCrits;
        Int32   *critLibInds;
        if (ACAPI_ElementLink_GetLinkedPropertyObjects (&element.header, &byCrit, &indivLibInd, &critLibInds, &nCrits) == NoError) {
            if (indivLibInd != 0) {
                DBPrintf ("Library index of individually linked property is %d.\n", indivLibInd);
            }
            if (byCrit) {
                DBPrintf ("Library indices of linked properties matching criteria are [ ");
                for (Int32 i = 0; i < nCrits; ++i) {
                    DBPrintf ("%d ", critLibInds[i]);
                }
                DBPrintf ("].\n");
            }
            BMKillPtr ((GSPtr *) &critLibInds);  // dispose critLibInds
        }
    }
}

ACAPI_ElementLink_GetLinkFlags()

GSErrCode ACAPI_ElementLink_GetLinkFlags	(	const API_Guid &	guid_linkFrom,
		const API_Guid &	guid_linkTo,
		GSFlags *	linkFlags
	)

Retrieves the link flags associated to the link between the two elements.

Parameters

guid_linkFrom	[in] Identifies the element to which the other element was linked.
guid_linkTo	[in] Identifies the element which was linked to the first element.
linkFlags	[out] Returns the custom flags assigned to the link with ACAPI_ElementLink_Link.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed linkFlags pointer is nullptr.
• APIERR_BADDATABASE, APIERR_NOTMINE - The function cannot operate on the current database.

Remarks

When you link an element to an other, you can also pass custom flags which are stored with the link in the database. With this function you can retrieve these flags.

ACAPI_ElementLink_GetLinks()

GSErrCode ACAPI_ElementLink_GetLinks	(	const API_Guid &	guid_linkFrom,
		GS::Array< API_Guid > *	guid_linkTo
	)

Returns a list of elements linked to the given element.

Parameters

guid_linkFrom	[in] Identifies the element to which the other elements were linked.
guid_linkTo	[out] Returns the GUIDs of the elements which were linked to the first element.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed guid_linkTo pointer is nullptr.
• APIERR_BADDATABASE, APIERR_NOTMINE - The function cannot operate on the current database.

Remarks

The element links are not bidirectional, you always link one element to another. This function returns the list of elements linked to the element having the guid_linkFrom GUID. Note that if this function is called in an unclosed undoable session, then it returns not only the existing links, but also the links which have been deleted in the current undoable session.

ACAPI_ElementLink_Link()

GSErrCode ACAPI_ElementLink_Link	(	const API_Guid &	guid_linkFrom,
		const API_Guid &	guid_linkTo,
		GSFlags	linkFlags
	)

Links one element to another.

Parameters

guid_linkFrom	[in] Identifies the element to which the other element will be linked.
guid_linkTo	[in] Identifies the element to link to the first element.
linkFlags	[in] Custom flags to store with the link.

Returns

• NoError - The function has completed with success.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADDATABASE, APIERR_NOTMINE - The function cannot operate on the current database.
• APIERR_BADID - One or both of the passed unique IDs are invalid, or the two IDs are equal.
• APIERR_LINKEXIST - The elements has already been linked together.

Remarks

The add-on creating the link is also registered with the link; so the link "belongs" to the add-on. The advantage of using element linking is that the server application automatically tracks changes in the GUIDs, and updates them accordingly. After establishing a link, you can also install an element observer with a callback function, that will be called when any of the observed elements change. In this callback you can find out which other elements are linked to the observed element with ACAPI_ElementLink_GetLinks, and retrieve the supplied linkFlags with ACAPI_ElementLink_GetLinkFlags. You can remove the link when you are done with ACAPI_ElementLink_Unlink.

ACAPI_ElementLink_SetLinkedPropertyObjects()

GSErrCode ACAPI_ElementLink_SetLinkedPropertyObjects	(	API_Elem_Head *	head,
		bool	criteria,
		Int32	inviduallyLibInd
	)

Link property objects to an element or the element default.

Parameters

head	[in] Header of the element (only fields type and guid are used). The setting is applied to element defaults if guid is APINULLGuid.
criteria	[in] Determines whether the matching properties by criteria need to be linked to the element
inviduallyLibInd	[in] Library index of individually selected property to be linked to the element (value zero means no individual property is to be assigned)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - head is nullptr
• APIERR_BADID - Incorrect type was specified, or an element with the specified guid was not found.
• APIERR_MEMFULL - Not enough memory to set the properties

Remarks

This function is used to link property objects to an element. Properties can be associated with construction elements by criteria and/or by individual direct assignment (at most one individual assignment can be applied to an element). This applies to all types of construction elements. If no element is specified (ie. guid is APINULLGuid), the setting is applied to the defaults of the given element type.

Example

API_Element     element;
bool            byCrit;
Int32           indivLibInd;
 
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_ColumnID;
ACAPI_Element_GetDefaults (&element, nullptr);
element.column.origoPos.x = x;
element.column.origoPos.y = y;
...
 
ACAPI_CallUndoableCommand ("Create column with properties linked",
    [&] () -> GSErrCode {
        GSErrCode err = ACAPI_Element_Create (&element, nullptr);
        if (err == NoError) {
            API_Elem_Head   defHead;
            BNZeroMemory (&defHead, sizeof (API_Elem_Head));
            defHead.type = API_ColumnID;      // guid remains APINULLGuid
            err = ACAPI_ElementLink_GetLinkedPropertyObjects (&defHead, &byCrit, &indivLibInd, nullptr, nullptr);  // retrieve defaults
            if (err == NoError)
                err = ACAPI_ElementLink_SetLinkedPropertyObjects (&element.header, true, 0);  // link properties
        }
 
        return err;
    });

ACAPI_ElementLink_Unlink()

GSErrCode ACAPI_ElementLink_Unlink	(	const API_Guid &	guid_linkFrom,
		const API_Guid &	guid_linkTo
	)

Removes the link from the second element to the first.

Parameters

guid_linkFrom	[in] Identifies the element to which the other element is linked.
guid_linkTo	[in] Identifies the element which is linked to the first element.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE, APIERR_NOTMINE - The function cannot operate on the current database.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_LINKNOTEXIST - There isn't any link from the second element to the first.

Remarks

This element removes the link to the second element (identified by guid_linkTo) from the element identified by guid_linkFrom. See ACAPI_ElementLink_Link for more details.