Library Management

Functions to load, iterate and manipulate Libraries. More...

Classes
struct	API_LibraryInfo
	Describes the data of an active library of an Archicad project. More...

Enumerations
enum	API_LibraryTypeID {   API_Undefined , API_LocalLibrary , API_UrlLibrary , API_BuiltInLibrary ,   API_EmbeddedLibrary , API_OtherObject , API_UrlOtherObject , API_ServerLibrary }
	Project library types. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_ProjectOperation_ReloadLibraries ()
	Resets and loads the active libraries.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_OpenLibraryPart (const API_OpenLibPartInfo *libPartToOpen)
	Opens the given library part in the Library Part Editor window.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_GetLibraries (GS::Array< API_LibraryInfo > *activeLibs, Int32 *embeddedLibraryIndex=nullptr)
	Returns the list of loaded libraries.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_SetLibraries (const GS::Array< API_LibraryInfo > *activeLibs)
	Changes the list of loaded libraries.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_NewLibDial (char *defName, IO::Location *newLib)
	Instructs the user to select a new library folder in a dialog.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_AddLibraries (IO::Location *newLib)
	Registers a new folder into the list of active libraries.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_CheckLibraries ()
	Checks the currently loaded libraries.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_OverwriteLibPart (bool overwriteOn)
	Sets the overwrite mode for the library part create function.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_DeleteEmbeddedLibItem (const IO::Location *location, bool keepGSMFile=false, bool silentMode=false)
	Deletes the given embedded library item (folder or library part).
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_DeleteEmbeddedLibItems (const GS::Array< IO::Location > *location, bool keepGSMFile=false, bool silentMode=false)
	Delete embeded lib items.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_CreateFolderInLibrary (const IO::Location *newFolderLocationInLibrary)
	Creates a new folder inside a loaded library.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_CopyFilesIntoLibrary (const IO::Location *targetFolderLocationInLibrary, const GS::Array< IO::Location > *filesToCopy, const bool *overwriteIfExists)
	Copies files into a folder inside a loaded library.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_GetGDLDate (Int32 *date)
	Returns GDL environment date information (GDL_PROJECT_DATE).
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_ChangeGDLDate (Int32 *date)
	Changes GDL environment date (GDL_PROJECT_DATE).
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_CreateCopyOfGdlUserGlobalsHandle (GDL::Parameters **userGlobals)
	Returns a copy of the current GDL globals.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_DestroyCopyOfGdlUserGlobalsHandle (GDL::Parameters **userGlobals)
	Destroys the previously copied GDL globals handle.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_GetLibPartOrigLocation (const Int32 *libItemIndex, IO::Location *origLocation)
	Returns the original location of a library part.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_UsableGDLString (const char *str)
	Determines whether the string is a GDL keyword or reserved symbol.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_RunGDLParScript (const API_Elem_Head *elemHead, UInt32 mask=0)
	Run GDL parameter script.
GSErrCode __ACENV_CALL	ACAPI_LibraryManagement_InterpretGDLScript3D (const GS::UniString *script, API_AddParType **addPars, void *modelerAPIModel=nullptr, void *modelerModel=nullptr)
	Interprets a 3D GDL script with the same settings as GDL Editor.
GSErrCode __ACENV_CALL	ACAPI_LibraryPart_RegisterSubtype (GSType signature, short templateFileResID, bool transparentNode, short stringResID, short smallIconResID, short largeIconResID, API_TBoxGroup toolGroupId, API_TBoxEnabled enableFlags, short defaultsResID)
	Registers a new library part subtype.
GSErrCode __ACENV_CALL	ACAPI_Element_GetDescriptors (const API_Elem_Head *elemHead, API_DescriptorRefType ***descRef, Int32 *nDesc)
	Returns the descriptors of an element.

Detailed Description

Functions to load, iterate and manipulate Libraries.

Enumeration Type Documentation

API_LibraryTypeID

enum API_LibraryTypeID

Project library types.

Remarks

The libraryType data member in the API_LibraryInfo structure defines the type of the project library, which can be

• Local Library
• Embedded Library
• Built-In Library
• Library on a BIMcloud / BIM Server
• Web Objects (addressed by URL)
• Other local objects

Function Documentation

ACAPI_Element_GetDescriptors()

GSErrCode __ACENV_CALL ACAPI_Element_GetDescriptors	(	const API_Elem_Head *	elemHead,
		API_DescriptorRefType ***	descRef,
		Int32 *	nDesc
	)

Returns the descriptors of an element.

Parameters

elemHead	[in] The element you want to get the descriptors for.
descRef	[out] List of the descriptors.
nDesc	[out] Number of the descriptors in the list.

Returns

• APIERR_BADPARS - descRef is nullptr or nDesc is nullptr.
• APIERR_BADID - Incorrect elemHead was specified.
• APIERR_MEMFULL - Not enough memory to get the descriptors.

Remarks

This function is used to get information for every descriptor of an element. These descriptors are in the property objects of the element. This applies to all the construction elements.

Example

void GetDiscriptors (const API_Guid& guid)
{
    API_Elem_Head          elemHead;
    API_DescriptorRefType  **descRefs;
    API_ListData           listdata;
    Int32                  nDesc, i;
    char                   s[256];
    GSErrCode              err;
 
    BNClear (elemHead);
    elemHead.guid = guid;
 
    err = ACAPI_Element_GetDescriptors (&elemHead, &descRefs, &nDesc);
    if (err == NoError) {
        for (i = 0; i < nDesc; i++) {
            listdata.header.type     = API_Obsolete_ComponentID;
            listdata.header.index    = (*descRefs)[i].index;
            listdata.header.setIndex = (*descRefs)[i].setIndex;
            if ((*descRefs)[i].status != APIDBRef_Deleted) {
                BNZeroMemory (&listdata, sizeof (API_ListData));
                listdata.header.type     = API_DescriptorID;
                listdata.header.setIndex = (*descRefs)[i].setIndex;
                listdata.header.index    = (*descRefs)[i].index;
                switch ((*descRefs)[i].status) {
                    case APIDBRef_Normal:
                        err = ACAPI_OldListing_Get (&listdata);
                        break;
                    case APIDBRef_Local:
                        err = ACAPI_OldListing_GetLocal ((*descRefs)[i].libIndex, &listdata);
                        break;
                }
            }
            if (err == NoError) {
                sprintf (s, "Keycode/code: \"%s\"/\"%s\"", listdata.descriptor.keycode, listdata.descriptor.code);
                ACAPI_WriteReport (s, false);
                ACAPI_WriteReport (*(listdata.descriptor.name), false);
            }
            BMKillHandle (&listdata.descriptor.name);
        }
        BMKillHandle ((GSHandle *) &descRefs);
    }
}

ACAPI_LibraryManagement_AddLibraries()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_AddLibraries

(

IO::Location *

newLib

)

Registers a new folder into the list of active libraries.

Parameters

newLib

[in] The file system location of the folder to add.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - newLib is nullptr.
• APIERR_NOTMINE - The project library list is not editable in Teamwork. You need to reserve it first.

Remarks

The registered folder will be the default one, which means that Library Parts created by the subsequent ACAPI_LibraryPart_Create functions automatically will go into this library, unless an other folder is specified. The modified list of active libraries will be enumerated. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview. Note that BIM Server libraries cannot be added to the project with this function.

ACAPI_LibraryManagement_ChangeGDLDate()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_ChangeGDLDate

(

Int32 *

date

)

Changes GDL environment date (GDL_PROJECT_DATE).

Parameters

date	[in] The new GDL environment date. It must be an Int32 array with 6 size.

Returns

• NoError - The function has completed with success.

Remarks

The input date array must contain the new date in the following format:

Date component	Meaning
date[0]	Year
date[1]	Month
date[2]	Day
date[3]	Hour
date[4]	Minute
date[5]	Second

Example

Int32 date[6];
date[0] = 2017;
date[1] = 1;
date[2] = 17;
date[3] = 12;
date[4] = 0;
date[5] = 0;
 
ACAPI_Environment (APIEnv_ChangeGDLDateID
, &date);

ACAPI_LibraryManagement_CheckLibraries()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_CheckLibraries

(

)

Checks the currently loaded libraries.

Returns

• NoError - Always returns NoError.

Remarks

Check the active library folders for the required Library Parts. If any of them are missing, an alert is highlighted to inform the user. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_LibraryManagement_CopyFilesIntoLibrary()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_CopyFilesIntoLibrary	(	const IO::Location *	targetFolderLocationInLibrary,
		const GS::Array< IO::Location > *	filesToCopy,
		const bool *	overwriteIfExists
	)

Copies files into a folder inside a loaded library.

Parameters

targetFolderLocationInLibrary	[in] The target folder location.
filesToCopy	[in] The list of files to be copied.
overwriteIfExists	[in] Overwrite existing files found on the target location (optional parameter; if omitted, the value is considered false, resulting existing files to be skipped).

Returns

• APIERR_BADPARS - The target folder location parameter is invalid or nullptr.

Remarks

The function copies file from the passed locations into a folder in an existing library loaded in the current project. The target folder must be writable and, in Teamwork, must be reserved.

Example

GS::Array<IO::Location> filesToCopy;
API_SpecFolderID specID = API_UserDocumentsFolderID;
IO::Location fileLocation;
ACAPI_Environment (APIEnv_GetSpecFolderID, &specID, &fileLocation);
filesToCopy.Push (IO::Location (fileLocation, IO::Name ("Test1.JPG")));
filesToCopy.Push (IO::Location (fileLocation, IO::Name ("Test2.JPG")));
 
GS::Array<API_LibraryInfo> libInfo;
GSErrCode err = ACAPI_Environment (APIEnv_GetLibrariesID, &libInfo);
if (err == NoError) {
    for (UInt32 ii = libInfo.GetSize (); ii > 0; --ii) {
        const API_LibraryInfo& libraryInfo = libInfo[ii - 1];
        if (libraryInfo.libraryType == API_LocalLibrary || libraryInfo.libraryType == API_EmbeddedLibrary || libraryInfo.libraryType == API_ServerLibrary) {
            IO::Location targetFolderLocation = libraryInfo.location;
            bool overwriteIfExists = true;
            err = ACAPI_Environment (APIEnv_CopyFilesIntoLibraryID
, &targetFolderLocation, &filesToCopy, &overwriteIfExists);
            break;
        }
    }
}

ACAPI_LibraryManagement_CreateCopyOfGdlUserGlobalsHandle()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_CreateCopyOfGdlUserGlobalsHandle

(

GDL::Parameters **

userGlobals

)

Returns a copy of the current GDL globals.

Parameters

userGlobals

[out] The object containing the GDL globals required by the GDL interpreter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The userGlobals parameter is nullptr.

Remarks

You can use this function to obtain the current GDL globals. Do not forget to destroy the returned pointer using ACAPI_LibraryManagement_DestroyCopyOfGdlUserGlobalsHandle.

ACAPI_LibraryManagement_CreateFolderInLibrary()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_CreateFolderInLibrary

(

const IO::Location *

newFolderLocationInLibrary

)

Creates a new folder inside a loaded library.

Parameters

newFolderLocationInLibrary

[in] The location of the folder to be created in an existing active library.

Returns

• APIERR_BADPARS - The passed location parameter is invalid or nullptr.

Remarks

The function creates a new folder in an existing library loaded in the current project. The given location must be writable and, in Teamwork, must be reserved. If the folder already exists, the function returns NoError.

Example

GS::Array<API_LibraryInfo> libInfo;
GSErrCode err = ACAPI_Environment (APIEnv_GetLibrariesID, &libInfo);
if (err == NoError) {
    for (UInt32 ii = libInfo.GetSize (); ii > 0; --ii) {
        const API_LibraryInfo& libraryInfo = libInfo[ii - 1];
        if (libraryInfo.libraryType == API_LocalLibrary || libraryInfo.libraryType == API_EmbeddedLibrary || libraryInfo.libraryType == API_ServerLibrary) {
            IO::Location targetFolderLocation (libraryInfo.location, IO::Name ("New Folder"));
            err = ACAPI_Environment (APIEnv_CreateFolderInLibraryID
, &targetFolderLocation);
            break;
        }
    }
}

ACAPI_LibraryManagement_DeleteEmbeddedLibItem()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_DeleteEmbeddedLibItem	(	const IO::Location *	location,
		bool	keepGSMFile = false,
		bool	silentMode = false
	)

Deletes the given embedded library item (folder or library part).

Parameters

location	[in] The location of the embedded library item.
keepGSMFile	[in] If this parameter is true, then the operation deletes libpart only from the embedded library, but keeps the.gsm file in the filesystem. (optional parameter, by default it's false)
silentMode	[in] If this parameter is true, then the missing libpart window won't open in case of any warning. (optional parameter, by default it's false)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The given loc parameter is nullptr.
• APIERR_NOTMINE - The operation attempted to delete a library part that belongs to another user. Likely to occur in teamwork mode.

Remarks

This operation is not undoable.

ACAPI_LibraryManagement_DeleteEmbeddedLibItems()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_DeleteEmbeddedLibItems	(	const GS::Array< IO::Location > *	location,
		bool	keepGSMFile = false,
		bool	silentMode = false
	)

Delete embeded lib items.

Parameters

location	[in] Array of locations of the library items.
keepGSMFile	[in] Keep the GSM file.
silentMode	[in] Missing library parts dialog window should pop up.

Returns

• NoError - The function has completed with success.

ACAPI_LibraryManagement_DestroyCopyOfGdlUserGlobalsHandle()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_DestroyCopyOfGdlUserGlobalsHandle

(

GDL::Parameters **

userGlobals

)

Destroys the previously copied GDL globals handle.

Parameters

userGlobals

[in] The object containing the GDL globals required by the GDL interpreter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The userGlobals parameter is nullptr.

Remarks

This function destroys the object pointer returned from ACAPI_LibraryManagement_CreateCopyOfGdlUserGlobalsHandle.

ACAPI_LibraryManagement_GetGDLDate()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_GetGDLDate

(

Int32 *

date

)

Returns GDL environment date information (GDL_PROJECT_DATE).

Parameters

date	[out] GDL environment date. It must be an Int32 array with 6 size.

Returns

• NoError - The function has completed with success.

Remarks

The returned array contains the date in the following format:

Date component	Meaning
date[0]	Year
date[1]	Month
date[2]	Day
date[3]	Hour
date[4]	Minute
date[5]	Second

Example

Int32 date[6];
ACAPI_Environment (APIEnv_GetGDLDateID
, &date);

ACAPI_LibraryManagement_GetLibPartOrigLocation()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_GetLibPartOrigLocation	(	const Int32 *	libItemIndex,
		IO::Location *	origLocation
	)

Returns the original location of a library part.

Parameters

libItemIndex	[in] The index of the library part.
origLocation	[out] The location of the given library part.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - libItemIndex or origLocation is nullptr

ACAPI_LibraryManagement_GetLibraries()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_GetLibraries	(	GS::Array< API_LibraryInfo > *	activeLibs,
		Int32 *	embeddedLibraryIndex = nullptr
	)

Returns the list of loaded libraries.

Parameters

activeLibs	the active library list
embeddedLibraryIndex	[out] optional; the 0-based index of the embedded library in this list

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - activeLibs is nullptr.
• APIERR_MEMFULL - Low memory condition.

Remarks

This function is used to get the list of active libraries of Archicad. Refer to the API_LibraryInfo for further details. For linked BIMcloud or BIM Server Libraries the location of local library cache will be returned. To change the active libraries use the ACAPI_LibraryManagement_SetLibraries function.

Example

GS::Array<API_LibraryInfo>    activeLibs;
UInt32               i;
char                 buffer[1024];
GS::UniString        path;
GSErrCode            err;
 
err = ACAPI_Environment (APIEnv_GetLibrariesID, &activeLibs);
if (err != NoError) {
    GiveMessage_Err ("Error in APIEnv_GetLibrariesID", err);
    return;
}
 
GiveMessage ("Active library folders", false);
 
for (i = 0; i < activeLibs.GetSize (); i++) {
    activeLibs[i].location.ToPath (&path);
    sprintf (buffer, "[%u]  %s", i+1, path.ToCStr (0, MaxUSize, CC_UTF8).Get ());
    GiveMessage (buffer, false);
}

ACAPI_LibraryManagement_InterpretGDLScript3D()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_InterpretGDLScript3D	(	const GS::UniString *	script,
		API_AddParType **	addPars,
		void *	modelerAPIModel = nullptr,
		void *	modelerModel = nullptr
	)

Interprets a 3D GDL script with the same settings as GDL Editor.

Since

Archicad 25

Parameters

script	[in] The 3D GDL Script.
addPars	[in] Parameters for script running. Can be NULL, in this case the script will run with empty parameter list.
modelerAPIModel	[out] The generated 3D model as ModelerAPI::Model. Use either this or the modelerModel, but only one at the same time.
modelerModel	[out] The generated 3D model as Modeler::ConstModel3DPtr. Use either this or the modelerAPIModel, but only one at the same time.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect parameters were specified.
• APIERR_GENERAL - Failed to interpret the script.

ACAPI_LibraryManagement_NewLibDial()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_NewLibDial	(	char *	defName,
		IO::Location *	newLib
	)

Instructs the user to select a new library folder in a dialog.

Parameters

defName	[in] A pointer to the default name of the new library.
newLib	[out] The file system location of the selected folder.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - any of the parameters are nullptr.
• APIERR_CANCEL - The user canceled the operation by the cancel button in the dialog.

Remarks

If a library is created or selected, the file specification is returned in the second parameter. To add a new folder to the active libraries use either the ACAPI_LibraryManagement_AddLibraries or the ACAPI_LibraryManagement_SetLibraries functions. You may also use directly the base class DG::FolderDialog of the Dialog Manager instead of calling ACAPI_LibraryManagement_NewLibDial.

ACAPI_LibraryManagement_OpenLibraryPart()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_OpenLibraryPart

(

const API_OpenLibPartInfo *

libPartToOpen

)

Opens the given library part in the Library Part Editor window.

Parameters

libPartToOpen

[in] Identifies the library part to open.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed library part information is incorrect.

Remarks

First it tries to open by the document name, then the file name (which may come from the location).

ACAPI_LibraryManagement_OverwriteLibPart()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_OverwriteLibPart

(

bool

overwriteOn

)

Sets the overwrite mode for the library part create function.

Parameters

overwriteOn

[in] Switch ON or OFF the overwrite mode.

Returns

• NoError - The function always returns NoError.

Remarks

This function is used to configure the ACAPI_LibraryPart_Create function to overwrite an existing library part instead of creating a new one with unique name. The parameter should be pass as a value, instead of a pointer. See the example.

Example

API_LibPart      libPart;
GSErrCode        err;
 
BNZeroMemory (&libPart, sizeof (API_LibPart));
libPart.typeID = APILib_ObjectID;
libPart.ownerID = APIOwnerID_ArchiCAD;
GS::ucscpy (libPart.docu_UName, L("Toilet P Dispenser 15"));
 
/* replace the existing the library part */
 
err = ACAPI_LibraryPart_Search (&libPart, false);
if (err == NoError) {
    ACAPI_Environment (APIEnv_OverwriteLibPartID, (void *) (Int32) true, nullptr);
    err = ACAPI_LibraryPart_Create (&libPart);
    ACAPI_Environment (APIEnv_OverwriteLibPartID, (void *) (Int32) false, nullptr);
}

ACAPI_LibraryManagement_RunGDLParScript()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_RunGDLParScript	(	const API_Elem_Head *	elemHead,
		UInt32	mask = 0
	)

Run GDL parameter script.

Parameters

elemHead	[in] Head of the element. It is identified by the guid field.
mask	Element mask; can be APIElemMask_FromFloorplan (= use the element from the floor plan).

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The element doesn't exist.

Remarks

You are eble to run the GDL parameter script of an object, lamp, window or door element via this function. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_LibraryManagement_SetLibraries()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_SetLibraries

(

const GS::Array< API_LibraryInfo > *

activeLibs

)

Changes the list of loaded libraries.

Parameters

activeLibs

the active library list to set

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - activeLibs is nullptr or size of the internal locations handle is not match to nLib
• APIERR_NOTMINE - The project library list is not editable in Teamwork. You need to reserve it first.

Remarks

This function is used to reset the list of active libraries of Archicad. The passed library folders will be enumerated. Refer to the API_LibraryInfo for further details. To get the active libraries use the ACAPI_LibraryManagement_GetLibraries function. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

See the example of APIEnv_GetLibrariesID
.

ACAPI_LibraryManagement_UsableGDLString()

GSErrCode __ACENV_CALL ACAPI_LibraryManagement_UsableGDLString

(

const char *

str

)

Determines whether the string is a GDL keyword or reserved symbol.

Parameters

str	[in] a string to check as a GDL keyword or reserved symbol

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - str is nullptr
• APIERR_GENERAL - the string is a valid GDL keyword or reserved symbol

Remarks

This function is used to check whether the given string is a reserved GDL keyword or symbol; or fulfills or not certain requirements to become one. By general the function returns NoError if the passed string can be used in a GDL script as an own identifier. For example if your creates a LibraryPart with scripts installed, and some part of the script is generated on the fly, it is a good idea to check the components for usability.

Example

GSErrCode   err;
 
err = ACAPI_Goodies (APIAny_UsableGDLStringID, "material", nullptr);
/* returns APIERR_GENERAL, it is reserved keyword; */
/* cannot be used as a script variable  */
 
err = ACAPI_Goodies (APIAny_UsableGDLStringID, "list", nullptr);
/* OK; returns NoError */
/* it can be used as a script variable */

ACAPI_LibraryPart_RegisterSubtype()

GSErrCode __ACENV_CALL ACAPI_LibraryPart_RegisterSubtype	(	GSType	signature,
		short	templateFileResID,
		bool	transparentNode,
		short	stringResID,
		short	smallIconResID,
		short	largeIconResID,
		API_TBoxGroup	toolGroupId,
		API_TBoxEnabled	enableFlags,
		short	defaultsResID
	)

Registers a new library part subtype.

Parameters

signature	[in] A four-character identifier of this library part subtype
templateFileResID	[in] 'FILE' resource ID of the subtype template library part compiled into the add-on
transparentNode	[in] Objects of this subtype can be shown on higher ancestry levels as well
stringResID	[in] Resource ID of the library part subtype description string
smallIconResID	[in] Resource ID of the small-sized toolbox (toolbar) item icon
largeIconResID	[in] Resource ID of the large-sized toolbox item icon
toolGroupId	[in] Toolbox item position
enableFlags	[in] Enable or disable the subtype tool depending on the active window
defaultsResID	[in] ID of the 'ACP0' resource that contains the element default values for this subtype

Returns

• APIERR_BADPARS - templateFileResID refers to an invalid 'FILE' resource or the built-in library part cannot be accepted as subtype template.
• NoError - The function has completed with success.

Remarks

This function registers a new library part subtype. In order to have an own element subtype the add-on must contain a built-in library part in its reource module. This library part will be loaded into the active libraries, and become a new node in the ancestry tree. The new element type will be identified with the signature identifier chosen by the add-on's writer. The signature should be unique in order to avoid collisions. You may pass 0 in the signature parameter if you do not need a new element type but a single subtype node. The subtype can appear in the toolbox as an external tool, and also on the Windows toolbar. In this case you must pass two valid icon resource IDs in the smallIconResID and the largeIconResID parameters. The size of the icons should be 16x16 and 30x21 pixels respectively. You can specify the position of the subtype item inserted into the toolbox with the toolGroupId parameter as follows:

API_TBoxGroup	Meaning
TBoxGroup_Root	The subtype tool item will be appended to the group of model element tools
TBoxGroup_Objects	The subtype tool item will be added to the object tools
TBoxGroup_Openings	The subtype tool item will be added to the window/door tools

You can control the availability of the subtype tool in the toolbox by setting the enableFlags bits:

API_TBoxEnabled	The subtype tool is enabled
API_TBoxEnabled_FloorPlan	on floor plan window
API_TBoxEnabled_ModelSection	on model type section and elevation windows
API_TBoxEnabled_DrawingSection	on drawing type section and elevation windows
API_TBoxEnabled_3D	on 3D model window
API_TBoxEnabled_Detail	on detail window
API_TBoxEnabled_Layout	on layout and master layout windows
API_TBoxEnabled_Worksheet	on worksheet window
API_TBoxEnabled_ModelInteriorElevation	on model type interior elevation windows
API_TBoxEnabled_DrawingInteriorElevation	on drawing type interior elevation windows

If you want to register your subtype tool without appearing in the toolbox, pass 0 for both the smallIconResID and the largeIconResID parameters. If you register a subtype tool you should define the factory default values for this element type in an 'ACP0' resource. The element default will be initialized with these parameters when no preferences data is stored. The structure of this resource is shown at the example below. The resource ID should be passed in the defaultsResID parameter. Learn more about this topic at the general description of Library Part Subtypes.

Example

Resources in the .GRC file:

ACAPI_ProjectOperation_ReloadLibraries()

GSErrCode __ACENV_CALL ACAPI_ProjectOperation_ReloadLibraries

(

)

Resets and loads the active libraries.

Returns

• NoError - The function has completed with success.

Remarks

This function is used to perform a Reload Libraries command in the server application. All the active libraries (included the BIMcloud and BIM Server Libraries too) will be reloaded.