Old functionalities to iterate and manipulate Library Parts. Most of these structures and functions are deprecated since AC 28. It's recommended to use Library Management components instead. More...

Classes
struct	API_OpenLibPartInfo
	The information of a library part required for opening the library part with ACAPI_LibraryManagement_OpenLibraryPart. More...

struct	API_ESYMParams
	Describes the current external symbol your add-on can work on. More...

struct	API_Prim_Head
	Header information for primitive elements. More...

struct	API_PrimHotspot
	A primitive hotspot. More...

struct	API_ParamOwnerType
	Parameters to specify the target parameter list to change. More...

struct	API_VLNumType
	The possible values for a numeric parameter. More...

struct	API_GetParamValuesType
	The possible parameter values of a non-array Library Part parameter. More...

struct	API_ChangeParamType
	Parameters to change a value in a Library Part parameter list. More...

struct	API_GetParamsType
	The changed parameter values of a Library Part. More...

struct	API_LibPart
	Definition of a Library Part. More...

struct	API_LibPartObjectDetails
	Library part's details of object, light, label and zone. Used in API_LibPartDetails. More...

struct	API_LibPartDoorWindowDetails
	Library part's details of window and door. Used in API_LibPartDetails. More...

union	API_LibPartDetails
	Detail parameters of a Library Part. More...

struct	API_LibPartSection
	Definition of a Library Part section. More...

Typedefs
typedef GSErrCode	APIESYMCommandProc(const API_ESYMParams *esymParams)
	User supplied callback function for handling external symbols.

Enumerations
enum	API_PrimTypeID { API_ZombiePrimID = 0 , API_PrimPointID , API_PrimLineID , API_PrimArcID , API_PrimTextID , API_PrimPLineID , API_PrimTriID , API_PrimPolyID , API_PrimPictID , API_PrimCtrl_BegID , API_PrimCtrl_HatchBorderBegID , API_PrimCtrl_HatchBorderEndID , API_PrimCtrl_HatchLinesBegID , API_PrimCtrl_HatchLinesEndID , API_PrimCtrl_HoledimLinesBegID , API_PrimCtrl_HoledimLinesEndID , API_PrimCtrl_ArrowBegID , API_PrimCtrl_ArrowEndID , API_PrimCtrl_ElementRefID , API_PrimCtrl_EndID , API_PrimCtrl_PlacedBorderBegID , API_PrimCtrl_PlacedBorderEndID , API_PrimCtrl_TextBegID , API_PrimCtrl_TextEndID , API_PrimCtrl_CWallPanelBegID , API_PrimCtrl_CWallPanelEndID , API_PrimCtrl_BackgroundFillBegID , API_PrimCtrl_BackgroundFillEndID , API_PrimCtrl_FrameBegID , API_PrimCtrl_FrameEndID }
	Various primitive element types and control codes. More...

enum	API_LockableStatus { APILockableStatus_NotExist , APILockableStatus_Free , APILockableStatus_Editable , APILockableStatus_Locked , APILockableStatus_NotAvailable }
	Possible Teamwork lockable status. More...

enum	API_LibTypeID { API_ZombieLibID = 0 , APILib_SpecID = 1 , APILib_WindowID = 2 , APILib_DoorID = 3 , APILib_ObjectID = 4 , APILib_LampID = 5 , APILib_RoomID = 6 , APILib_PropertyID = 7 , APILib_PlanSignID = 8 , APILib_LabelID = 9 , APILib_MacroID = 10 , APILib_PictID = 11 , APILib_ListSchemeID = 12 , APILib_SkylightID = 13 , APILib_OpeningSymbolID = 14 }
	Library Part types. From Archicad 8 these categories are obsolete due to the introduction of library part subtypes. More...

Functions
GSErrCode	ACAPI_LibraryPart_GetLibPartRefGuid (const IO::Location location, API_Guid guid)
	This function is used to obtain the reference guid of a library part.

GSErrCode	ACAPI_LibraryPart_GetLibPartUnIDStr (const IO::Location location, char libPartUnId)
	This function is used to obtain the given library part's own unique ID.

GSErrCode	ACAPI_LibraryPart_GetLibPartLockStatus (const IO::Location location, API_LockableStatus status, IO::Location *userCacheLibPartLocation=nullptr)
	Returns the current lock status of the given library part.

GSErrCode	ACAPI_LibraryManagement_DeleteEmbeddedLibItem (const IO::Location *location, bool keepGSMFile=false, bool silentMode=false)
	Deletes the given embedded library item (folder or library part).

GSErrCode	ACAPI_LibraryManagement_DeleteEmbeddedLibItems (const GS::Array< IO::Location > *location, bool keepGSMFile=false, bool silentMode=false)
	Delete embeded lib items.

GSErrCode	ACAPI_LibraryPart_OpenParameters (API_ParamOwnerType *paramOwner)
	Opens a Library Part parameter list to edit.

GSErrCode	ACAPI_LibraryPart_GetParamValues (API_GetParamValuesType *getValues)
	Returns the possible values defined for a Library Part parameter.

GSErrCode	ACAPI_LibraryPart_ChangeAParameter (API_ChangeParamType *changeParamType)
	Changes a value in an opened Library Part parameter list.

GSErrCode	ACAPI_LibraryPart_GetActParameters (API_GetParamsType *theParams)
	Returns the actual (edited) values of a Library Part parameter list opened to edit.

GSErrCode	ACAPI_LibraryPart_CloseParameters ()
	Closes the Library Part parameter list opened for editing.

GSErrCode	ACAPI_LibraryPart_GetBuiltInLibpartUnId (short templateFileResID, char *lpfUnId)
	Retrieves the GUID of a built-in library part.

GSErrCode	ACAPI_LibraryPart_GetUnloadedLibpartName (const API_Guid guid, GS::UniString name)
	Retrieves the name of a Libpart, even if the library is unloaded.

GSErrCode	ACAPI_LibraryPart_CheckLibPartSubtypeOf (const char successorUnIDStr, const char predecessorUnIDStr)
	Checks whether a library part unique ID refers to a subtype of another.

GSErrCode	ACAPI_LibraryPart_CheckLibPartSubtypeOfbyMain (const char successorUnIDStr, const char predecessorUnIDStr)
	Checks whether a library part unique ID refers to a subtype of another.

GSErrCode	ACAPI_LibraryPart_CompareLibPartUnIds (const char unIDStr1, const char unIDStr2)
	Compares two library part unique IDs.

GSErrCode	ACAPI_LibraryPart_GetElemLibPartUnId (API_Elem_Head elemHead, char lpfUnId)
	Returns the library part unique identifier of the GDL based element (object/lamp/window/door).

GSErrCode	ACAPI_LibraryPart_GetLibPartToolVariation (API_LibPart libPart, API_ToolBoxItem toolboxItem)
	Returns the library part's creator element type and variation ID.

GSErrCode	ACAPI_LibraryPart_GetMarkerParent (const API_ElemType &elemType, API_LibPart &libPart)
	Returns the parent ID of the marker, in the parentUnID member of the libPart structure.

GSErrCode	ACAPI_LibraryPart_GetLastValidEmbeddedLPName (GS::UniString name, IO::Location location)
	Retrieves the last valid embedded library location.

GSErrCode	ACAPI_LibraryPart_RegisterESYM (GSType signature, API_LibTypeID typeID, short stringResID)
	Registers an external symbol type with Archicad.

GSErrCode	ACAPI_LibraryPart_InstallESYMHandler (GSType signature, APIESYMCommandProc *handlerProc)
	Installs a callback for handling external symbols.

GSErrCode	ACAPI_DisposeAddParHdl (API_AddParType ***addPars)
	Frees the memory occupied by a handle to an array of API_AddParType.

GSErrCode	ACAPI_LibraryPart_GetNum (Int32 *count)
	Returns the number of registered library parts.

GSErrCode	ACAPI_LibraryPart_Search (API_LibPart *ancestor, bool createIfMissing, bool onlyPlaceable=false)
	Searches for a registered Library Part in the loaded libraries.

GSErrCode	ACAPI_LibraryPart_PatternSearch (const API_LibPart ancestor, const GS::UniString &pattern, API_LibPart result[50], Int32 numFound)
	Searches for registered Library Parts in the loaded libraries.

GSErrCode	ACAPI_LibraryPart_Get (API_LibPart *libPart)
	Returns the data of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_GetParams (Int32 libInd, double a, double b, Int32 addParNum, API_AddParType **addPars)
	Returns the default parameters of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_GetSection (Int32 libInd, API_LibPartSection section, GSHandle sectionHdl, GS::UniString sectionStr, GS::UniString password=nullptr)
	Returns an existing section of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_UpdateSection (Int32 libInd, const API_LibPartSection section, GSHandle sectionHdl, GS::UniString sectionStr, GS::UniString *password=nullptr)
	Updates a section of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_SetUpSect_2DDrawHdl (void)
	Sets up an empty 2D binary (drawing) section to fill up from API elements.

GSErrCode	ACAPI_LibraryPart_GetSect_2DDrawHdl (GSHandle *sectionHdl)
	Returns the 2D binary (drawing) section data created from API elements.

GSErrCode	ACAPI_LibraryPart_GetSect_ParamDef (const API_LibPart libPart, API_AddParType addPars, double a, double b, GSHandle sect2DDrawHdl, GSHandle sectionHdl, GS::UniString *password=nullptr)
	Prepares the parameter section data to save into a Library Part.

GSErrCode	ACAPI_LibraryPart_Create (const API_LibPart *libPart)
	Starts to create a new Library Part from scratch.

GSErrCode	ACAPI_LibraryPart_AddSection (const API_LibPartSection section, GSHandle sectionHdl, GS::UniString sectionStr)
	Adds a new section to the Library Part under creation.

GSErrCode	ACAPI_LibraryPart_NewSection (const API_LibPartSection *section)
	Opens a new section to write into the Library Part under creation.

GSErrCode	ACAPI_LibraryPart_WriteSection (Int32 nByte, GSConstPtr data)
	Writes data into an opened section of the Library Part under creation.

GSErrCode	ACAPI_LibraryPart_EndSection (void)
	Closes the last opened section of the Library Part under creation.

GSErrCode	ACAPI_LibraryPart_Save (API_LibPart *libPart)
	Saves the Library Part has been created and registers it.

GSErrCode	ACAPI_LibraryPart_ShapePrims (Int32 libInd, const API_Guid &instanceElemGuid, short gdlContext, ShapePrimsProc *shapePrimsProc)
	Virtually draws the shape of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_GetHotspots (Int32 libInd, const API_Guid &instanceElemGuid, Int32 nHotspots, API_PrimHotspot **hotspots)
	Retrieves the hotspots of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_Register (API_LibPart *libPart)
	Registers a Library Part.

GSErrCode	ACAPI_LibraryPart_RegisterAll (GS::Array< API_LibPart > *libParts)
	Registers an array of Library Parts.

GSErrCode	ACAPI_LibraryPart_GetSectionList (Int32 libInd, Int32 nSection, API_LibPartSection **sections)
	Returns the list of sections contained by a registered Library.

GSErrCode	ACAPI_LibraryPart_GetDetails (Int32 libInd, API_LibPartDetails *details)
	Returns the detail parameters of a registered Library Part.

GSErrCode	ACAPI_LibraryPart_SetDetails_ParamDef (const API_LibPart libPart, GSHandle paramHdl, const API_LibPartDetails details)
	Sets the detail parameters of a Library Part parameter section handle.

Detailed Description

Old functionalities to iterate and manipulate Library Parts. Most of these structures and functions are deprecated since AC 28. It's recommended to use Library Management components instead.

Library Part Overview

Library Parts are collected into library folders, like the default Archicad Library. The active library folders themselves can be manipulated. With the ACAPI_LibraryManagement_ResetLibraries function you can reset the installed libraries, also you can add a new folder, or even to give a complete list of folders.

From Archicad 8 libraries can be packed in and loaded from archive files and module resources as well. This capability lets the add-ons store their library parts in their own resources and use them as a read-only library added to the active libraries (ACAPI_AddOnIntegration_RegisterBuiltInLibrary).

References to Library Part

The active library folders are enumerated and the Library Part files are registered in Archicad. The Library Part Manager functions can work only on registered Library Parts.

The drawing elements (objects, doors, windows, lamps, and zone definitions) which require a Library Part to reference, do it with indices. The index is the index of the Library Part in the library part pool, which contains the parts from all the active libraries.

Library Part types

Up to Archicad 8 applicable types of Library Parts were enumerated in the API_LibTypeID structure. From Archicad 8 a new kind of library part hierarchy was introduced: every library part is derived from a subtype parent library part. This tree structure gives much more flexible classification of library parts. For a detailed description see the Library Part Subtypes section.

The definition of a Library Part is described in the API_LibPart structure.

Some kind of Library Parts do not contain any Archicad specific information. For example macros are simple text files, pictures are standard TIFF, GIF etc. files. They become Library Parts, just because they are located in the active library folders. There are no any API functions to give support to work on their content.

Internal Structure

A real Library Part is built from several sections, as you can see and also edit in the Library Part dialog of Archicad. Each section has an identifier and a subcode which allows implementation of more than one section with the very same type, as can be seen in the API_LibPartSection structure.

The sectType field is the identifier of the section, which is implemented as a four byte code. Predefined identifiers are also listed, and Archicad can work on these sections only. Of course you can insert sections with custom identifiers to save your own data into the Library Part. Archicad never modifies or deletes custom sections.

The subIdent field gives a sub-identifier. There are sections which may have more instances in the same Library Part, like the 3D binary section. Sections which can have only one instance always have the value zero. For custom sections, this value is not checked for validity and you can use it for any purpose, like version controlling.

The API functions related to Library Parts give all of the necessary support to build a new Library Part from scratch, and provide the possibility to modify, delete or append any section in existing ones. If you create a new library part, it is automatically registered into the internal database, so it can be referred by any element. Refer to the ACAPI_LibraryPart_Create function for details.

The API functions hide the internal structure of a Library Part, however there is some public documentation available on these topics, which allows you to build them on your own. It is highly recommended to use the API functions for this purpose, because of compatibility issues.

Textual sections like the 2D script, 3D script or property script etc. can be generated without any problem. You just have to allocate some memory which can hold the necessary text. From API 11, these sections contain Unicode text, which you can also manipulate through the API.

Producing or interpreting binary sections like the 3D binary or 2D drawing sections are more complicated to manage. You have two ways to work on them.

The internal structure of these binary sections are public. If you have the necessary documentation, you can build or interpret them on your own. This method is not recommended.
There are API functions which translate the binary data into API structures. You should use these methods, as shown later.

The list of sections of a Library Part can be get by the ACAPI_LibraryPart_GetSectionList function.

If you are interested in the data of any section, you can get it by simply calling the ACAPI_LibraryPart_GetSection function. In case of binary sections, you will get binary data which does not correspond to any API structure. For textual sections, the returned sectionHdl contains the required text.

The 2D drawing section

The 2D drawing section describes the shape of the Library Part which can be drawn with the applicable 2D toolbar elements.

At this time, the only way to get this data in API form is to use the ACAPI_LibraryPart_ShapePrims function. This function call explodes the shape of the library part into drawing primitives.

In order to build this binary section, you should redirect the element creation procedure. In this case, the subsequent calls to the ACAPI_Element_Create function place the given elements into a temporary pool, instead of the project database. When you have finished the drawing creation procedure you can convert these elements to the required binary form.

GSHandle            bin2DHdl;
API_SelectionInfo   section = {};
GSErrCode           err;
 
err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl ();
ACAPI_Element_Create()
...
ACAPI_Element_Create()
err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&bin2DHdl);
 
section.sectType = API_Sect2DDraw;
err = ACAPI_LibraryPart_AddSection (&section, bin2DHdl, nullptr);
 
BMKillHandle (&bin2DHdl);

The parameters section

The parameters section describes the default parameters of the Library Part.

All real Library Parts contain two predefined parameters; named A and B. The different kind of Library Parts may contain additional required parameters. You can check these by creating a new library part of that kind in Archicad. The parameters appearing in the dialog are the required ones. Beside these, you may define or retrieve additional parameters (maximum 64). The parameter manipulating functions all refer to these additional (required and/or optional) parameters, but not to the A and B parameters, which are separate parameters where needed.

Applicable additional parameter types are enumerated in the API_AddParID structure. The definition of an additional parameter is described in the API_AddParType structure:

If you want to get the parameter list of a Library Part in an API based form you should use the following template:

Int32            addParNum;
API_AddParType   addParHdl;
double           a, b;
err = ACAPI_LibraryPart_GetParams (libIndex, &a, &b, &addParNum, &addParHdl);

In this case, Archicad translates the binary data into an array of API_AddParType structure. This function also returns the a and b parameter in separate variables, because the addParHdl will contain the additional parameters only.

The creation of the parameter section is also very simple. First you have to allocate the required size of array based on the API_AddParType structure and fill with the data of the parameters. In the next step, this API data should be converted to binary data. To do that you also need the 2D binary section data, because the binary parameter handle is a full description which owns the a and b parameters. These parameters are calculated automatically and the built binary section is returned to you through the paramsHdl argument. You also get back the calculated a and b parameter.

GSHandle            paramsHdl;
API_SelectionInfo   section = {};
GSErrCode           err;
 
err = ACAPI_LibraryPart_GetSect_ParamDef (APILib_ObjectID, addParHdl,
                                      &a, &b, bin2DHdl,
                                      &paramsHdl);
 
section.sectType = API_SectParamDef;
err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr);
 
BMKillHandle (&paramsHdl);

The 3D binary sections

In the present version of the API, there is no support to process the internal data of the 3D binary sections. If you are interested to work with these sections please contact Graphisoft to get the necessary documentation on the binary format.

A Library Part can own more than one 3D binary section up to 16 fragments. In order to get the right fragment, you need to set up the subIdent field of the API_LibPartSection structure correctly.

The Preview picture

A preview picture can be embedded into Library Parts either in PICT or GIF format. They are public formats, so they do not need any explanation.

Typedef Documentation

◆ APIESYMCommandProc

typedef GSErrCode APIESYMCommandProc(const API_ESYMParams *esymParams)

User supplied callback function for handling external symbols.

Parameters

esymParams [in] This structure contains the various parameters identifying the external symbol (type, index) and the type of operation (new/edit).

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

Enumeration Type Documentation

◆ API_LibTypeID

enum API_LibTypeID

Library Part types. From Archicad 8 these categories are obsolete due to the introduction of library part subtypes.

Remarks: The values correspond to a given type of Library Part. Generally this value is referenced from the API_LibPart structure.

◆ API_LockableStatus

enum API_LockableStatus

Possible Teamwork lockable status.

Remarks: This enum is the return type of the ACAPI_Teamwork_GetLockableStatus function.

◆ API_PrimTypeID

enum API_PrimTypeID

Various primitive element types and control codes.

Enumerator
API_ZombiePrimID	Dummy primitive.
API_PrimPointID	Primitive point.
API_PrimLineID	Primitive line.
API_PrimArcID	Primitive arc.
API_PrimTextID	Primitive text.
API_PrimPLineID	Primitive polyline.
API_PrimTriID	Primitive triangle.
API_PrimPolyID	Primitive polygon.
API_PrimPictID	Picture on placed drawing in PlotMaker.
API_PrimCtrl_BegID	Begin drawing the element.
API_PrimCtrl_HatchBorderBegID	Begin exporting hatch border ( `par1:` API_PrimHatchBorder ).
API_PrimCtrl_HatchBorderEndID	Finished exporting hatch border.
API_PrimCtrl_HatchLinesBegID	Begin exporting hatch lines.
API_PrimCtrl_HatchLinesEndID	Finished exporting hatch lines.
API_PrimCtrl_HoledimLinesBegID	Begin exporting window/door dimension lines (obsolete, not used from Archicad 8).
API_PrimCtrl_HoledimLinesEndID	Finished exporting window/door dimension lines (obsolete, not used from Archicad 8).
API_PrimCtrl_ArrowBegID	Begin exporting arrow primitives.
API_PrimCtrl_ArrowEndID	Finished exporting arrow primitives.
API_PrimCtrl_ElementRefID	Reference to another element ( `par1:` API_PrimElemRef ).
API_PrimCtrl_EndID	Finished element drawing.
API_PrimCtrl_PlacedBorderBegID	Begin exporting placed drawing border.
API_PrimCtrl_PlacedBorderEndID	Finished exporting placed drawing border.
API_PrimCtrl_TextBegID	Begin exporting text block.
API_PrimCtrl_TextEndID	Finished exporting text block.
API_PrimCtrl_CWallPanelBegID	Begin exporting a curtain wall panel.
API_PrimCtrl_CWallPanelEndID	Finished exporting a curtain wall panel.
API_PrimCtrl_BackgroundFillBegID	Begin exporting drawing background fill.
API_PrimCtrl_BackgroundFillEndID	End exporting drawing background fill.
API_PrimCtrl_FrameBegID	Begin exporting text frame primitives.
API_PrimCtrl_FrameEndID	End exporting text frame primitives.

Function Documentation

◆ ACAPI_DisposeAddParHdl()

GSErrCode ACAPI_DisposeAddParHdl ( API_AddParType *** addPars )

Frees the memory occupied by a handle to an array of API_AddParType.

Parameters

addPars [in] A handle to an array of API_AddParType.

Returns

Remarks: This is the recommended way of disposing the parameter description handles for compatibility reasons, as in a later version of the API the API_AddParType structure might change. Also, you might have array-type parameters among the additional parameters; this function also takes care of those.

◆ ACAPI_LibraryManagement_DeleteEmbeddedLibItem()

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

GSErrCode ACAPI_LibraryPart_AddSection	(	const API_LibPartSection *	section,
		GSHandle	sectionHdl,
		GS::UniString *	sectionStr )

Adds a new section to the Library Part under creation.

Parameters

section	[in] Parameters of the new section.
sectionHdl	[in] Section data.
sectionStr	[in] Content of any textual section as a Unicode string.

Returns

NoError - The function has completed with success.
APIERR_GENERAL - No scratch file has been opened by the ACAPI_LibraryPart_Create function.

Remarks: This function is used to add a whole section to the Library Part opened to create. This function is allowed to call between the ACAPI_LibraryPart_Create and ACAPI_LibraryPart_Save functions only, while creating a Library Part from scratch. The identifier of the section must be defined in the API_LibPartSection parameter. The section data is passed through the sectionHdl parameter.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_ChangeAParameter()

GSErrCode ACAPI_LibraryPart_ChangeAParameter ( API_ChangeParamType * changeParamType )

Changes a value in an opened Library Part parameter list.

Parameters

changeParamType [in] The Library Part parameter (variable) to change the value of it.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - chgParam is nullptr or the variable reference is invalid
APIERR_NOTINIT - there is no parameter list opened

Remarks: This function is used to change a Library Part parameter. Refer to the API_ChangeParamType structure to get details on the parametrization possibilities. Use this function after a parameter list has been opened by the ACAPI_LibraryPart_OpenParameters function. Refer to that function to get more details on this topics. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: /* change parameter 'zzyzx' of the default object */

API_ParamOwnerType paramOwner {};

API_ChangeParamType chgParam {};

API_GetParamsType getParams {};

API_Element element {}, mask;

API_ElementMemo memo {};

GSErrCode err;

paramOwner.libInd = 0; /* no library part */

paramOwner.type = API_ObjectID; /* object element */

paramOwner.guid = APINULLGuid; /* element default */

err = ACAPI_LibraryPart_OpenParameters (&paramOwner);

if (err == NoError) {

err = ACAPI_LibraryPart_GetActParameters (&getParams);

if (err == NoError) {

chgParam.index = 0;

CHCopyC ("zzyzx", chgParam.name);

chgParam.realValue = 2.0;

err = ACAPI_LibraryPart_ChangeAParameter (&chgParam);

if (err == NoError)

err = ACAPI_LibraryPart_GetActParameters (&getParams);

}

ACAPI_LibraryPart_CloseParameters ();

}

if (err == NoError) {

element.header.type = API_ObjectID;

element.object.xRatio = getParams.a;

element.object.yRatio = getParams.b;

ACAPI_ELEMENT_MASK_CLEAR (mask);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, xRatio);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, yRatio);

memo.params = getParams.params;

err = ACAPI_Element_ChangeDefaults (&element, &memo, &mask);

}

ACAPI_DisposeAddParHdl (&getParams.params);

◆ ACAPI_LibraryPart_CheckLibPartSubtypeOf()

GSErrCode ACAPI_LibraryPart_CheckLibPartSubtypeOf	(	const char *	successorUnIDStr,
		const char *	predecessorUnIDStr )

Checks whether a library part unique ID refers to a subtype of another.

Parameters

successorUnIDStr	[in] the unique ID of the subtype.
predecessorUnIDStr	[in] the unique ID of the expected ancestor.

Returns

NoError - The function has completed with success and the ancestry holds.
APIERR_NOTSUBTYPEOF - The function has completed with success but the first one is not a subtype of the second.
APIERR_BADPARS - any of the parameters are nullptr.

Remarks: This function is used to verify that a library part identified by its unique ID is a subtype of the other one. No existence check is performed for the predecessor. It checks for real ancestry so returns APIERR_NOTSUBTYPEOF for equal unique IDs as well.

◆ ACAPI_LibraryPart_CheckLibPartSubtypeOfbyMain()

GSErrCode ACAPI_LibraryPart_CheckLibPartSubtypeOfbyMain	(	const char *	successorUnIDStr,
		const char *	predecessorUnIDStr )

Checks whether a library part unique ID refers to a subtype of another.

Parameters

successorUnIDStr	[in] the unique ID of the subtype.
predecessorUnIDStr	[in] the unique ID of the expected ancestor.

Returns

NoError - The function has completed with success and the ancestry holds.
APIERR_NOTSUBTYPEOF - The function has completed with success but the first one is not a subtype of the second.
APIERR_BADPARS - any of the parameters are nullptr.

Remarks: This function is used to verify that a library part identified by its unique ID is a subtype of the other one identified only by the main part of its unique ID. No existence check is performed for the predecessor. It checks for real ancestry so returns APIERR_NOTSUBTYPEOF for equal unique IDs as well.

◆ ACAPI_LibraryPart_CloseParameters()

GSErrCode ACAPI_LibraryPart_CloseParameters ( )

Closes the Library Part parameter list opened for editing.

Returns

NoError - The function always returns NoError.

Remarks: This function is used to close the parameter list of a Library Part opened for editing. Refer to the ACAPI_LibraryPart_OpenParameters function to get more details on this topics.

Example: /* change parameter 'zzyzx' of the default object */

API_ParamOwnerType paramOwner {};

API_ChangeParamType chgParam {};

API_GetParamsType getParams {};

API_Element element {}, mask;

API_ElementMemo memo {};

GSErrCode err;

paramOwner.libInd = 0; /* no library part */

paramOwner.type = API_ObjectID; /* object element */

paramOwner.guid = APINULLGuid; /* element default */

err = ACAPI_LibraryPart_OpenParameters (&paramOwner);

if (err == NoError) {

err = ACAPI_LibraryPart_GetActParameters (&getParams);

if (err == NoError) {

chgParam.index = 0;

CHCopyC ("zzyzx", chgParam.name);

chgParam.realValue = 2.0;

err = ACAPI_LibraryPart_ChangeAParameter (&chgParam);

if (err == NoError)

err = ACAPI_LibraryPart_GetActParameters (&getParams);

}

ACAPI_LibraryPart_CloseParameters ();

}

if (err == NoError) {

element.header.type = API_ObjectID;

element.object.xRatio = getParams.a;

element.object.yRatio = getParams.b;

ACAPI_ELEMENT_MASK_CLEAR (mask);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, xRatio);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, yRatio);

memo.params = getParams.params;

err = ACAPI_Element_ChangeDefaults (&element, &memo, &mask);

}

ACAPI_DisposeAddParHdl (&getParams.params);

◆ ACAPI_LibraryPart_CompareLibPartUnIds()

GSErrCode ACAPI_LibraryPart_CompareLibPartUnIds	(	const char *	unIDStr1,
		const char *	unIDStr2 )

Compares two library part unique IDs.

Parameters

unIDStr1	[in] the first library part unique ID.
unIDStr2	[out] the second library part unuique ID.

Returns

NoError - The function has completed with success and the two unique IDs are equal.
APIERR_NOTEQUALREVISION - The function has completed with success and the main GUID parts of the unique IDs are equal but the revision IDs differ.
APIERR_NOTEQUALMAIN - The function has completed with success but even the main GUID parts of the unique IDs differ.
APIERR_BADPARS - any of the parameters are nullptr.

Remarks: This function is used to compare two library part unique IDs. Returns NoError if the IDs refer to the same library part with the same revision ID. APIERR_NOTEQUALREVISION is returned when the IDs still refer to the same library part with different revision IDs (different editions of the same library part). If the unique IDs refer to different library parts, APIERR_NOTEQUALMAIN is returned.

◆ ACAPI_LibraryPart_Create()

GSErrCode ACAPI_LibraryPart_Create ( const API_LibPart * libPart )

Starts to create a new Library Part from scratch.

Parameters

libPart [in] Parameters of the Library Part to create

Returns

NoError - The function has completed with success.
APIERR_NESTING - Recursive call, ACAPI_LibraryPart_Save was not called after the previous call
APIERR_BADPARS - The libPart parameter is nullptr, or holds invalid data
APIERR_BADID - No match found with the passed parentUnID
APIERR_NOLIB - No valid location was passed, and there is no active library also
APIERR_READONLY - The specified location is read-only

Remarks

This function is used to create a new empty Library Part from scratch. You have to specify the subtype of the Library Part in order to place it under the proper node in the ancestry hierarchy. For more information about subtypes see the Library Part Subtypes passage. By default, all new Library Parts are created into the active library folder, however you can specify any directory you want. If the location field describes a valid folder in the file system, the Library Part will be created there. Note that the name of the Library Part is determined by the docu_UName, so the file name itself is ignored both in the file_Name and location fields. This function creates an empty Library Part. The sections should be defined with subsequent function calls; basically there are two ways to create a section:

Write the section as a stream with the functions ACAPI_LibraryPart_NewSection, ACAPI_LibraryPart_WriteSection, and ACAPI_LibraryPart_EndSection
Create the section in one step by calling the ACAPI_LibraryPart_AddSection function. The Library Part itself will be created and registered upon the ACAPI_LibraryPart_Save function call. Do not forget to call this function in order to close the scratch file; even in case of any error encountered in the other function calls. Macros and pictures cannot be created in this way. Refer to the function ACAPI_LibraryPart_Register for more details. If the function has completed with success the index of the newly created library part is given by the index field of the API_LibPart structure. Do not forget to dispose of the used section handles.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_EndSection()

GSErrCode ACAPI_LibraryPart_EndSection ( void )

Closes the last opened section of the Library Part under creation.

Returns

NoError - The function has completed with success.
APIERR_GENERAL - No scratch file has been opened by the ACAPI_LibraryPart_Create function.

Remarks: This function is used to close the section recently opened with the ACAPI_LibraryPart_NewSection function. Data of the section should be filled by calling the ACAPI_LibraryPart_WriteSection function.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_Get()

GSErrCode ACAPI_LibraryPart_Get ( API_LibPart * libPart )

Returns the data of a registered Library Part.

Parameters

libPart [in/out] Definition of the library part.

Returns

NoError - The function has completed with success.
APIERR_MISSINGDEF - The originating library part file is missing. The document name is still filled.
APIERR_BADPARS - libPart is nullptr or the index is invalid.
APIERR_BADINDEX - libPart.index is not correct for the given typeID.

Remarks: This function is used to get the data of the requested Library Part defined by the index field. The other fields of the structure are returned by Archicad. You cannot use names here; first you have to find the library part with ACAPI_LibraryPart_Search function. After calling ACAPI_LibraryPart_Get please remember to free the location pointer allocated by the function if you do not need it any more.

Example: API_LibPart libPart;

Int32 i, count;

GSErrCode err;

err = ACAPI_LibraryPart_GetNum (&count);

if (!err) {

for (i = 1; i <= count; i++) {

libPart = {};

libPart.index = i;

err = ACAPI_LibraryPart_Get (&libPart);

if (!err) {

ACAPI_WriteReport ((const char *) GS::UniString (libPart.docu_UName).ToCStr (), false);

}

if (libPart.location != nullptr)

delete libPart.location;

}

}

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::LibraryManager::FindLibParts instead

◆ ACAPI_LibraryPart_GetActParameters()

GSErrCode ACAPI_LibraryPart_GetActParameters ( API_GetParamsType * theParams )

Returns the actual (edited) values of a Library Part parameter list opened to edit.

Parameters

theParams [out] the modified parameter list

Returns

NoError - The function has completed with success.
APIERR_BADPARS - theParams is nullptr
APIERR_NOTINIT - there is no parameter list opened

Remarks: This function is used to get the actual parameters modified by the ACAPI_LibraryPart_ChangeAParameter function. Refer to the API_GetParamsType structure to get further details. Do not forget to dispose the params handle when it is not needed any more. Refer to the ACAPI_DisposeAddParHdl to do that.

Example: /* change parameter 'zzyzx' of the default object */

API_ParamOwnerType paramOwner {};

API_ChangeParamType chgParam {};

API_GetParamsType getParams {};

API_Element element {}, mask;

API_ElementMemo memo {};

GSErrCode err;

paramOwner.libInd = 0; /* no library part */

paramOwner.type = API_ObjectID; /* object element */

paramOwner.guid = APINULLGuid; /* element default */

err = ACAPI_LibraryPart_OpenParameters (&paramOwner);

if (err == NoError) {

err = ACAPI_LibraryPart_GetActParameters (&getParams);

if (err == NoError) {

chgParam.index = 0;

CHCopyC ("zzyzx", chgParam.name);

chgParam.realValue = 2.0;

err = ACAPI_LibraryPart_ChangeAParameter (&chgParam);

if (err == NoError)

err = ACAPI_LibraryPart_GetActParameters (&getParams);

}

ACAPI_LibraryPart_CloseParameters ();

}

if (err == NoError) {

element.header.type = API_ObjectID;

element.object.xRatio = getParams.a;

element.object.yRatio = getParams.b;

ACAPI_ELEMENT_MASK_CLEAR (mask);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, xRatio);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, yRatio);

memo.params = getParams.params;

err = ACAPI_Element_ChangeDefaults (&element, &memo, &mask);

}

ACAPI_DisposeAddParHdl (&getParams.params);

◆ ACAPI_LibraryPart_GetBuiltInLibpartUnId()

GSErrCode ACAPI_LibraryPart_GetBuiltInLibpartUnId	(	short	templateFileResID,
		char *	lpfUnId )

Retrieves the GUID of a built-in library part.

Parameters

templateFileResID	[in] the library part template 'FILE' resource ID
lpfUnId	[out] the required unique ID in string format

Returns

NoError - The function has completed with success.
APIERR_BADPARS - lpfUnId is nullptr or templateFileResID contains invalid data.

Remarks: This function is used to get the GUID of a library part compiled into the add-on's module as 'FILE' resource. For more information about built-in library parts see ACAPI_AddOnIntegration_RegisterBuiltInLibrary.

◆ ACAPI_LibraryPart_GetDetails()

GSErrCode ACAPI_LibraryPart_GetDetails	(	Int32	libInd,
		API_LibPartDetails *	details )

Returns the detail parameters of a registered Library Part.

Parameters

libInd	[in] Index of the Library Part
details	[out] Detail parameter of the Library Part

Returns

NoError - The function has completed with success.
APIERR_BADPARS - any of the parameters are nullptr, or the addressed Library Part is a macro, picture file etc.

Remarks

This function is used to get the detail parameters of a Library Part. These parameters can be edited in Archicad by clicking the Details button on the parameter list editor dialog box. The function works only on real Library Parts. In the case the type of the target Library Part is not listed below, the function returns an error code. This is since other type of Library Parts are just simple picture or text files which are enumerated and registered from the active library folders; such a picture or macro. Applicable type of Library Parts are:

APILib_WindowID
APILib_DoorID
APILib_ObjectID
APILib_LampID
APILib_RoomID
APILib_LabelID To change the parameters refer to the ACAPI_LibraryPart_SetDetails_ParamDef function.

Example: API_LibPartDetails details;

API_LibPart libPart {};

GSErrCode err;

libPart.typeID = APILib_ObjectID;

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.index != 0) {

err = ACAPI_LibraryPart_GetDetails (libPart.index, &details);

}

◆ ACAPI_LibraryPart_GetElemLibPartUnId()

GSErrCode ACAPI_LibraryPart_GetElemLibPartUnId	(	API_Elem_Head *	elemHead,
		char *	lpfUnId )

Returns the library part unique identifier of the GDL based element (object/lamp/window/door).

Parameters

elemHead	[in] Head of the element. It is identified by the guid field.
lpfUnId	[out] The required unique ID in string format.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - One or both of the parameters is nullptr.
APIERR_DELETED - The element is deleted.
APIERR_BADID - The element is not GDL based.

Remarks: This function is used to get the library part unique ID in string format of the given element. The element is window, door, object or lamp.

◆ ACAPI_LibraryPart_GetHotspots()

GSErrCode ACAPI_LibraryPart_GetHotspots	(	Int32	libInd,
		const API_Guid &	instanceElemGuid,
		Int32 *	nHotspots,
		API_PrimHotspot ***	hotspots )

Retrieves the hotspots of a registered Library Part.

Parameters

libInd	[in] Index of the library part
instanceElemGuid	[in] Instance element GUID; if APINULLGuid, then the drawing parameters will be the default parameters of the library part (with no transformation, etc.), otherwise they are taken from the instance of the library part defined by this GUID.
nHotspots	[out] Numbers of hotspots.
hotspots	[out] Handle that contains the hotspot data on return.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - nHotspots or hotspots parameter is nullptr, or invalid libInd has been passed
APIERR_BADINDEX - Invalid instanceElemGuid for the element type that libInd implies

Remarks

This function is used to retrieve the hotspots of the Libpart Part. The library part is identified the same way as ACAPI_LibraryPart_ShapePrims does. The hotspots return in an array of API_PrimHotspot structures. The coordinate values in the loc field are interpreted in the local coordinate system of the library part, however if the referred element instance has been resized, the coordinates follow the scale. If you would like to get the actual position of a hotspot of the specified element instance, use the neig field to convert the coordinates. Do not forget to dispose the hotspots handle after the operation. The function works only on Library Parts that can be placed onto the floor plan. Applicable type of Library Parts are:

APILib_WindowID
APILib_DoorID
APILib_ObjectID
APILib_LampID
APILib_RoomID (zone stamp)
APILib_LabelID (symbol label)

Example: API_PrimHotspot** hotspots = nullptr;

Int32 nHotspots = 0;

Int32 libInd = 1990; /* a given library part index */

API_Guid instanceElemGuid = element.header.guid; /* GUID of an element placed on the floorplan with the corresponding libpart reference */

GSErrCode err = ACAPI_LibraryPart_GetHotspots (libInd, instanceElemGuid, &nHotspots, &hotspots);

if (err == NoError && hotspots != nullptr) {

API_Element element {};

element.header.type.typeID = API_HotspotID;

err = ACAPI_Element_GetDefaults (&element, nullptr);

if (err == NoError) {

short ind;

for (ind = 0; ind < nHotspots; ind++) { // draw hotspots in local coordinates

element.hotspot.pen = ind;

element.hotspot.pos = (*hotspots)[ind].loc;

ACAPI_Element_Create (&element, nullptr);

}

for (ind = 0; ind < nHotspots; ind++) { // draw hotspots according to the neigs

element.hotspot.pen = ind;

API_Coord3D pos {element.hotspot.pos.x, element.hotspot.pos.y, 0};

err = ACAPI_Element_NeigToCoord (&(*hotspots)[ind].neig, &pos);

if (err == NoError)

ACAPI_Element_Create (&element, nullptr);

}

}

}

BMKillHandle ((GSHandle*) &hotspots);

◆ ACAPI_LibraryPart_GetLastValidEmbeddedLPName()

GSErrCode ACAPI_LibraryPart_GetLastValidEmbeddedLPName	(	GS::UniString *	name,
		IO::Location *	location )

Retrieves the last valid embedded library location.

Parameters

name	[in] Library part name.
location	[out] The location of the last valid embedded libpart for the given libpart name.

Returns

NoError - The function has completed with success.

Remarks: This fuction is used to retrieve the last valid embedded library part location identified by its name.

◆ ACAPI_LibraryPart_GetLibPartLockStatus()

GSErrCode ACAPI_LibraryPart_GetLibPartLockStatus	(	const IO::Location *	location,
		API_LockableStatus *	status,
		IO::Location *	userCacheLibPartLocation = nullptr )

Returns the current lock status of the given library part.

Parameters

location	[in] The location of the library part.
status	[out] The Teamwork lock status of the library part.
userCacheLibPartLocation	[out] Location of the server library part file in the user cache (optional parameter).

Returns

NoError - The function has completed with success.

Remarks: The possible return values are the same as in ACAPI_Teamwork_GetLockableStatus. From Archicad 20 library parts from BIM server libraries can be locked and edited. When a server library part becomes editable, it is copied into a separate cache on the local machine, which is called user cache. This location can be retrieved with this function in the optional userCacheLibPartLocation parameter.

Warning: Legacy function - to be deleted in future versions, use ACAPI::Library::LibraryManager::GetTWID instead

◆ ACAPI_LibraryPart_GetLibPartRefGuid()

GSErrCode ACAPI_LibraryPart_GetLibPartRefGuid	(	const IO::Location *	location,
		API_Guid *	guid )

This function is used to obtain the reference guid of a library part.

Parameters

location	[in] The location of the library part.
guid	[out] The reference guid of the library part.

Returns

NoError - The function has completed with success.

Remarks: The function is used to obtain the reference guid of a library part using the library part's location.

Warning: Legacy function - to be deleted in future versions, use ACAPI::Library::GSMObject::GetUnID instead

◆ ACAPI_LibraryPart_GetLibPartToolVariation()

GSErrCode ACAPI_LibraryPart_GetLibPartToolVariation	(	API_LibPart *	libPart,
		API_ToolBoxItem *	toolboxItem )

Returns the library part's creator element type and variation ID.

Parameters

libPart	[in] Identifies the library part. A basic ACAPI_LibraryPart_Search is performed to extract the internal library part identifier.
toolboxItem	[out] The requested creator element type and variation ID.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Any of the parameters is nullptr.

Remarks: This function returns the element type and variation ID, retrieving it from the internal library part registry. This information is necessary when you want to place an object having a special variation ID.

◆ ACAPI_LibraryPart_GetLibPartUnIDStr()

GSErrCode ACAPI_LibraryPart_GetLibPartUnIDStr	(	const IO::Location *	location,
		char *	libPartUnId )

This function is used to obtain the given library part's own unique ID.

Parameters

location	[in] The location of the library part.
libPartUnId	[out] The unique ID of the library part.

Returns

NoError - The function has completed with success.

Remarks: The function is used to obtain the library part's own unique ID using the library part's location.

Warning: Legacy function - to be deleted in future versions, use ACAPI::Library::GSMObject::GetUnID instead

◆ ACAPI_LibraryPart_GetMarkerParent()

GSErrCode ACAPI_LibraryPart_GetMarkerParent	(	const API_ElemType &	elemType,
		API_LibPart &	libPart )

Returns the parent ID of the marker, in the parentUnID member of the libPart structure.

Since: Archicad 26

Parameters

elemType	[in] The element type.
libPart	[in] The library part.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Incorrect elemType or libPart was specified.

◆ ACAPI_LibraryPart_GetNum()

GSErrCode ACAPI_LibraryPart_GetNum ( Int32 * count )

Returns the number of registered library parts.

Parameters

count [out] number of Library Parts.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - count is nullptr

Remarks: This function is used to get the number of currently available library parts. The number of the different type of library parts can not be obtained with this function; you have to walk through all the library parts to get e.g. the number of windows in the library. Library Parts are referenced by indices. This function returns the maximal value such a reference; valid indices are in the [1? count ] range. The special value zero used some time to reference to an empty Library Part, as in case of an empty opening.

Example: API_LibPart libPart;

Int32 i, count;

GSErrCode err;

err = ACAPI_LibraryPart_GetNum (&count);

if (!err) {

for (i = 1; i <= count; i++) {

libPart = {};

libPart.index = i;

err = ACAPI_LibraryPart_Get (&libPart);

if (!err) {

ACAPI_WriteReport ((const char *) GS::UniString (libPart.docu_UName).ToCStr (), false);

}

if (libPart.location != nullptr)

delete libPart.location;

}

}

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::LibraryManager::FindLibParts instead

◆ ACAPI_LibraryPart_GetParams()

GSErrCode ACAPI_LibraryPart_GetParams	(	Int32	libInd,
		double *	a,
		double *	b,
		Int32 *	addParNum,
		API_AddParType ***	addPars )

Returns the default parameters of a registered Library Part.

Parameters

libInd	Index of the library part.
a	The A parameter of the the Library Part
b	The B parameter of the the Library Part
addParNum	The number of additive parameters; others than A and B
addPars	The additive parameters

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Invalid libInd, or any of the parameters are nullptr, or the addressed Library Part is a macro, picture file etc.
APIERR_MEMFULL - not enough memory to complete the operation

Remarks

This function is used to get the default parameters of the requested Library Part defined by libInd. In the a and b parameters, the values of the A and B variables are returned; in the addParNum and addPars parameters the additive parameter list is returned, the number of the parameters and the actual values, respectively. Refer to the API_AddParType to get more information on a Library Part parameter. It is absolutely important that the function returns a formalized data handle to describe the parameter list. The content is not equal to the section handle returned by the ACAPI_LibraryPart_GetSection function called with the API_SectParamDef argument. The function works only on real Library Parts. In the case the type of the target Library Part is not listed below, the function returns an error code. This is since other type of Library Parts are just simple picture or text files which are enumerated and registered from the active library folders; such a picture or macro. Applicable type of Library Parts which have parameter list are:

APILib_WindowID,
APILib_DoorID,
APILib_ObjectID,
APILib_LampID,
APILib_RoomID,
APILib_LabelID,
APILib_MacroObjID,
APILib_PropertyID Do not forget to dispose the additive parameter handle if it is not needed any more. Use the ACAPI_DisposeAddParHdl function for this purpose.

Example: // -----------------------------------------------------------------------------

// Write the additional parameters of an element into the file

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

void DumpWriter::WriteParams (API_AddParType **params)

{

double value;

Int32 i1, i2, ind;

if (params == nullptr || *params == nullptr)

return;

UInt32 addParNum = BMGetHandleSize (reinterpret_cast<GSHandle> (params)) / sizeof (API_AddParType);

for (UInt32 i = 0; i < addParNum; i++) {

if ((*params)[i].typeMod == API_ParSimple) {

GS::UniString valueStr ((*params)[i].value.uStr);

WriteParameter ((*params)[i].typeID, GS::UniString((*params)[i].name),

(*params)[i].value.real, valueStr,0,0);

} else {

if ((*params)[i].typeID == APIParT_Dictionary) {

DBBREAK_STR ("Dictionaries are not allowed in arrays.");

continue;

}

ind = 0;

WriteParameter ((*params)[i].typeID, (*params)[i].name,

0.0, "", -(*params)[i].dim1, -(*params)[i].dim2);

for (i1 = 1; i1 <= (*params)[i].dim1; i1++) {

for (i2 = 1; i2 <= (*params)[i].dim2; i2++) {

if ((*params)[i].typeID != APIParT_CString) {

value = (Int32) ((double *)

*(*params)[i].value.array) [ind];

ind++;

WriteParameter ((*params)[i].typeID, "", value, "", i1, i2);

} else {

value = 0.0;

GS::uchar_t* uValueStr = (reinterpret_cast<GS::uchar_t*>(*(*params)[i].value.array)) + ind;

ind += GS::ucslen32 (uValueStr) + 1;

WriteParameter ((*params)[i].typeID, "", value, GS::UniString (uValueStr), i1, i2);

}

}

}

}

}

} // WriteParams

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

// Write the additional parameters of an element into the file

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

void DumpWriter::WriteParams (const API_Element* elem)

{

GSErrCode err;

API_ElementMemo memo {};

err = ACAPI_Element_GetMemo (elem->header.guid, &memo);

if (err == NoError) {

Int32 libInd = DumpUtils::Element_To_LibPartIndex (elem);

API_AddParType** addPars;

double a, b;

Int32 addParNum;

err = ACAPI_LibraryPart_GetParams (libInd, &a, &b, &addParNum, &addPars);

if (err == NoError) {

WriteInt (addParNum, WithNewLine);

WriteParams (memo.params);

}

ACAPI_DisposeAddParHdl (&addPars);

}

ACAPI_DisposeElemMemoHdls (&memo);

return;

} // WriteParams

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject::GetParameters instead

◆ ACAPI_LibraryPart_GetParamValues()

GSErrCode ACAPI_LibraryPart_GetParamValues ( API_GetParamValuesType * getValues )

Returns the possible values defined for a Library Part parameter.

Parameters

getValues [out] the value list for the given parameter

Returns

NoError - The function has completed with success.
APIERR_BADPARS - theParams is nullptr
APIERR_BADNAME - The parameter specified by its name was not found in the open library part
APIERR_BADINDEX - The parameter specified by its index was not found in the open library part
APIERR_NOTINIT - No open parameter list

Remarks: This function is used to get the possible values for a given parameter. Refer to the API_GetParamValuesType structure to get further details. Do not forget to dispose the strValues and the realValues handles when they are not needed any more.

◆ ACAPI_LibraryPart_GetSect_2DDrawHdl()

GSErrCode ACAPI_LibraryPart_GetSect_2DDrawHdl ( GSHandle * sectionHdl )

Returns the 2D binary (drawing) section data created from API elements.

Parameters

sectionHdl [out] 2D binary section data

Returns

NoError - The function has completed with success.
APIERR_BADPARS - sectionHdl is nullptr
APIERR_GENERAL - No 2D drawing section has been opened with the ACAPI_LibraryPart_SetUpSect_2DDrawHdl function.

Remarks: This function is used to close and return the 2D binary (drawing) section of the library part, prepared to be used with ACAPI_LibraryPart_AddSection function. This function must be called to close the 2D binary section if the ACAPI_LibraryPart_SetUpSect_2DDrawHdl function has succeeded; even if any of the in-between function calls to ACAPI_Element_Create has failed. Refer to the ACAPI_LibraryPart_SetUpSect_2DDrawHdl function to get more details on this topics.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

◆ ACAPI_LibraryPart_GetSect_ParamDef()

GSErrCode ACAPI_LibraryPart_GetSect_ParamDef	(	const API_LibPart *	libPart,
		API_AddParType **	addPars,
		double *	a,
		double *	b,
		GSHandle	sect2DDrawHdl,
		GSHandle *	sectionHdl,
		GS::UniString *	password = nullptr )

Prepares the parameter section data to save into a Library Part.

Parameters

libPart	[in] The library part to work on
addPars	[in] Additive parameters of the Library Part
a	[in] the value of the A parameter
b	[in] the value of the B parameter
sect2DDrawHdl	[in] 2D binary section data
sectionHdl	[out] the prepared parameter section data
password	[in] The (optional) password that encrypted the section.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The libPart or the sectionHdl parameter is nullptr
APIERR_BADID - The function cannot work with library parts of type specified by libPart->typeID

Remarks: This function is used to prepare the parameter section of the Library Part, and return the prepared section handle in sectionHdl. The returned handle than can be supplied to the ACAPI_LibraryPart_AddSection or the ACAPI_LibraryPart_UpdateSection functions to put it into the Library Part. The a/b and sect2DDrawHdl parameters are exclusive, they are both used to calculate the bounding box of the symbol of the Library Part. Specifically, a and b should be defined only if sect2DDrawHdl is nullptr, otherwise their value will be calculated and returned.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_GetSection()

GSErrCode ACAPI_LibraryPart_GetSection	(	Int32	libInd,
		API_LibPartSection *	section,
		GSHandle *	sectionHdl,
		GS::UniString *	sectionStr,
		GS::UniString *	password = nullptr )

Returns an existing section of a registered Library Part.

Parameters

libInd	[in] Index of the library part
section	[in/out] Definition of the section. The section is defined by the sectType an the subIdent fields of the API_LibPartSection structure.
sectionHdl	[out] Section data.
sectionStr	[out] The content of textual sections as a Unicode string. Pass the address of an existing Unicode string if you need this data.
password	[in] The (optional) password that encrypted the section.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Invalid libInd, or any of the parameters are nullptr, or the addressed Library Part is a macro, picture file etc.
APIERR_NOLIBSECT - no such a section in the Library Part

Remarks

This function is used to get the data of the requested section from the Library Part. It returns the requested section of the Library Part defined by libInd in the sectionHdl. The section is defined by the sectType field of the API_LibPartSection structure. If it (a four-character case-sensitive identifier) is not any of the standard types, it is interpreted as a custom type. In this case you are responsible for the content and the management of this section. The description of the standard sections can be found in the Archicad Reference Manual. The function works only on real Library Parts. In the case the type of the target Library Part is not listed below, the function returns an error code. This is since other type of Library Parts are just simple picture or text files which are enumerated and registered from the active library folders; such a picture or macro. Applicable type of Library Parts are:

APILib_WindowID,
APILib_DoorID,
APILib_ObjectID,
APILib_LampID,
APILib_RoomID,
APILib_LabelID,
APILib_MacroObjID,
APILib_PropertyID Do not forget to dispose the data if it is not needed any more. From API 11, the textual section data is now stored as a GS::UniString in the library parts. You can also obtain the text in this format in the sectionStr parameter.

Example: Int32 nSection = 0;

API_LibPartSection **sectList;

GSHandle sectionHdl;

char buffer[128];

GSErrCode err = ACAPI_LibraryPart_GetSectionList (1, &nSection, &sectList);

if (err == NoError) {

for (Int32 i = 0; i < nSection; i++) {

API_LibPartSection* sectionPtr = *sectList + i;

err = ACAPI_LibraryPart_GetSection (1, sectionPtr, &sectionHdl, nullptr);

BMKillHandle (&sectionHdl);

sprintf (buffer, "sectType: %u, subIndent: %hu, version: %d", sectionPtr->sectType, sectionPtr->subIdent, sectionPtr->version);

ACAPI_WriteReport (buffer, false);

}

BMKillHandle ((GSHandle *) &sectList);

}

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject::GetCustomSection instead

◆ ACAPI_LibraryPart_GetSectionList()

GSErrCode ACAPI_LibraryPart_GetSectionList	(	Int32	libInd,
		Int32 *	nSection,
		API_LibPartSection ***	sections )

Returns the list of sections contained by a registered Library.

Parameters

libInd	[in] Index of the library part
nSection	[out] Number of the sections found
sections	[out] section data returned

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Invalid libInd, or any of the parameters are nullptr, or the addressed Library Part is a macro, picture file etc.

Remarks: This function is used to get the headers of the sections the library part is built from. The function works only on real Library Parts. In the case the type of the target Library Part is not listed below, the function returns an error code. This is since other type of Library Parts are just simple picture or text files which are enumerated and registered from the active library folders; such a picture or macro. Applicable type of Library Parts are: APILib_WindowID, APILib_DoorID, APILib_ObjectID, APILib_LampID, APILib_RoomID, APILib_LabelID, APILib_MacroObjID, APILib_PropertyID Do not forget to dispose the returned handle if it is not needed any more. Note, that it cannot be used between ACAPI_LibraryPart_Create and ACAPI_LibraryPart_Save functions.

Example: Int32 nSection = 0;

API_LibPartSection **sectList;

GSHandle sectionHdl;

char buffer[128];

GSErrCode err = ACAPI_LibraryPart_GetSectionList (1, &nSection, &sectList);

if (err == NoError) {

for (Int32 i = 0; i < nSection; i++) {

API_LibPartSection* sectionPtr = *sectList + i;

err = ACAPI_LibraryPart_GetSection (1, sectionPtr, &sectionHdl, nullptr);

BMKillHandle (&sectionHdl);

sprintf (buffer, "sectType: %u, subIndent: %hu, version: %d", sectionPtr->sectType, sectionPtr->subIdent, sectionPtr->version);

ACAPI_WriteReport (buffer, false);

}

BMKillHandle ((GSHandle *) &sectList);

}

◆ ACAPI_LibraryPart_GetUnloadedLibpartName()

GSErrCode ACAPI_LibraryPart_GetUnloadedLibpartName	(	const API_Guid *	guid,
		GS::UniString *	name )

Retrieves the name of a Libpart, even if the library is unloaded.

Parameters

guid	[in] the guid of the Object, Lamp, Window or Door element.
name	[out] the name of the Libpart

Returns

NoError - The function has completed with success.
APIERR_BADID - guid is nullptr

Remarks: This function is used to get the name of a library part even if the library is unloaded For more information about library parts see API_LibPart.

◆ ACAPI_LibraryPart_InstallESYMHandler()

GSErrCode ACAPI_LibraryPart_InstallESYMHandler	(	GSType	signature,
		APIESYMCommandProc *	handlerProc )

Installs a callback for handling external symbols.

Parameters

signature	[in] A four-character identifier of the external symbol.
handlerProc	[in] The callback function to handle the creation and the editing of the external symbol.

Returns

NoError - The function has completed with success.

Remarks: This function should be called in the Initialize function of your add-on.

Example: // -----------------------------------------------------------------------------

// Called when the add-on has been loaded into memory

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

GSErrCode Initialize (void)

{

GSErrCode err = NoError;

err = ACAPI_LibraryPart_InstallESYMHandler ('ABCD', CustomAPIESYMCommandProc);

return err;

}

◆ ACAPI_LibraryPart_NewSection()

GSErrCode ACAPI_LibraryPart_NewSection ( const API_LibPartSection * section )

Opens a new section to write into the Library Part under creation.

Parameters

section [in] Parameters of the new section.

Returns

NoError - The function has completed with success.
APIERR_GENERAL - No scratch file has been opened by the ACAPI_LibraryPart_Create function.

Remarks: This function is used to open a new section to write into the Library Part opened to create. This function is allowed to call between the ACAPI_LibraryPart_Create and ACAPI_LibraryPart_Save functions only, while creating a Library Part from scratch. The identifier of the section must be defined in the API_LibPartSection parameter. The section data is passed through the sectionHandle parameter. This is the other way to add sections to the library part, where the section is opened, then data is added with repetitive calls to the ACAPI_LibraryPart_WriteSection function, and finally it is closed with the ACAPI_LibraryPart_EndSection function call. Refer to the ACAPI_LibraryPart_AddSection to add a section in one step. Do not nest these function calls. Always close the opened section with ACAPI_LibraryPart_EndSection before you open an other.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_OpenParameters()

GSErrCode ACAPI_LibraryPart_OpenParameters ( API_ParamOwnerType * paramOwner )

Opens a Library Part parameter list to edit.

Parameters

paramOwner [in] Reference to the owner of the parameter handle which should be edited

Returns

NoError - The function has completed with success.
APIERR_BADPARS - paramOwner is nullptr or invalid parameters are passed
APIERR_GENERAL - the library part do not has parameters

Remarks

This function is used to prepare a parameter list to edit. Generally to change a parameter of a parameter list is a very complex task. It is because the API_AddParType structure is quite complex, especially in case of array parameters, however this problem can be handled. Another issue is the parameter script. This script sets up rules and links which must be followed to provide a consistent parameter set, while editing it. There is no possibility to handle this issue in an addon. The only way to ensure full parameter consistency while changing a value of a Library Part parameter is to use the functions provided for this operation. If you manipulate the API_AddParType handle directly, the parameter list may become invalid. The function set is:

ACAPI_LibraryPart_OpenParameters
ACAPI_LibraryPart_ChangeAParameter
ACAPI_LibraryPart_GetActParameters
ACAPI_LibraryPart_GetParamValues
ACAPI_LibraryPart_CloseParameters Once you want to change a parameter you should open the parameter list with the ACAPI_LibraryPart_OpenParameters function. You can specify here various targets to work on:
the parameters of a placed element (Library Part instance)
the default parameters of an element (default tool settings)
the default parameters of a Library Part itself Refer to the API_ParamOwnerType structure how to specify the required target of operation. After you opened the the parameter list to edit you can use the ACAPI_LibraryPart_ChangeAParameter function to change a value of a parameter. The reference to a variable can be either the name of the variable or its index. You can get the current (modified) parameter list in API form (API_AddParType handle) any time by calling the ACAPI_LibraryPart_GetActParameters function. You can check the possible values of a parameter (as defined in the Parameter Script of the Library Part) in API form (API_GetParamValuesType handle) any time by calling the ACAPI_LibraryPart_GetParamValues function. When you have finished working on a parameter list you should call the ACAPI_LibraryPart_CloseParameters function to free any associated resources allocated by the server application. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: /* change parameter 'zzyzx' of the default object */

API_ParamOwnerType paramOwner {};

API_ChangeParamType chgParam {};

API_GetParamsType getParams {};

API_Element element {}, mask;

API_ElementMemo memo {};

GSErrCode err;

paramOwner.libInd = 0; /* no library part */

paramOwner.type = API_ObjectID; /* object element */

paramOwner.guid = APINULLGuid; /* element default */

err = ACAPI_LibraryPart_OpenParameters (&paramOwner);

if (err == NoError) {

err = ACAPI_LibraryPart_GetActParameters (&getParams);

if (err == NoError) {

chgParam.index = 0;

CHCopyC ("zzyzx", chgParam.name);

chgParam.realValue = 2.0;

err = ACAPI_LibraryPart_ChangeAParameter (&chgParam);

if (err == NoError)

err = ACAPI_LibraryPart_GetActParameters (&getParams);

}

ACAPI_LibraryPart_CloseParameters ();

}

if (err == NoError) {

element.header.type = API_ObjectID;

element.object.xRatio = getParams.a;

element.object.yRatio = getParams.b;

ACAPI_ELEMENT_MASK_CLEAR (mask);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, xRatio);

ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, yRatio);

memo.params = getParams.params;

err = ACAPI_Element_ChangeDefaults (&element, &memo, &mask);

}

ACAPI_DisposeAddParHdl (&getParams.params);

◆ ACAPI_LibraryPart_PatternSearch()

GSErrCode ACAPI_LibraryPart_PatternSearch	(	const API_LibPart *	ancestor,
		const GS::UniString &	pattern,
		API_LibPart	result[50],
		Int32 *	numFound )

Searches for registered Library Parts in the loaded libraries.

Parameters

ancestor	[in] The library part type to search for
pattern	[in] Pattern to search for in the loaded librairies.
result	[out] Array to store the first 50 found library parts.
numFound	[out] Number of found library parts.

Returns

NoError - The function has completed with success, the Library Part has been found (or reference created successfully if createIfMissing is true)
APIERR_BADPARS - ancestor is nullptr, numFound is nullptr or pattern is empty
APIERR_BADID - no library part is found according to the given typeID or ownUnID as ancestor

Remarks: This function is used to search a Library Parts in the loaded libraries. The search pattern can be one or more words or expression(s) in quotes. Please remember that library parts are classified according to the subtype hierarchy as it is explained in the Library Part Subtypes chapter of this documentation. The expandable subtype system made the typeID based distinction of library parts obsolete, though you may use this field for searching by subtype instead of parentUnID for internal ancestor nodes (note that in this case APILib_ObjectID corresponds to Model Elements, and API_ZombieLibID marks the General Object subtype).

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::LibraryManager::FindLibParts instead

◆ ACAPI_LibraryPart_Register()

GSErrCode ACAPI_LibraryPart_Register ( API_LibPart * libPart )

Registers a Library Part.

Parameters

libPart [in/out] Parameters of the library part;

Returns

NoError - The function has completed with success.
APIERR_BADPARS - libPart is nullptr, or refers to invalid data

Remarks: This function is used to register a new Library Part. You can register any kind of Library Part, however this function basically implemented for handling macros and pictures. These type of Library Parts are simple text and picture files which can be created without any help of the API. If you want to create a new macro, you just have to create a simple text file somewhere in the file system, and register it as a macro. If the function has completed with success, the reference index is returned by Archicad in the libPart->index parameter. Use this value to reference to the registered Library Part in any subsequent operation. Creating real Archicad library parts are much more complicated. Although the file format is public, it is strongly recommended to use the API functions while creating an object, lamp, door etc. kind library part. In this case you do not have to register it, because the ACAPI_LibraryPart_Save function does it. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: IO::Location fileLoc ("C:\\temp\\MyLibpart.gsm");

API_LibPart libPart {};

libPart.typeID = APILib_ObjectID;

libPart.location = &fileLoc;

ACAPI_LibraryPart_Register (&libPart);

◆ ACAPI_LibraryPart_RegisterAll()

GSErrCode ACAPI_LibraryPart_RegisterAll ( GS::Array< API_LibPart > * libParts )

Registers an array of Library Parts.

Parameters

libParts [in/out] Parameters of the library parts; the type, the owner signature and the location of the library parts must be initialized, by setting the typeID, ownerID and the location fields respectively. Other values will be filled and returned by Archicad.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - libParts is nullptr, or any of its members refer to invalid data.

Remarks: This function is used to register an array of new library parts. During the time of the batch registration internal library part caching is disabled, providing better performance. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: GS::Array<API_LibPart> libParts;

for (int i = 0; i < 10; ++i) {

API_LibPart libPart;

// ... fill API_LibPart structure

libParts.Push (libPart);

}

GSErrCode err = ACAPI_LibraryPart_RegisterAll (&libParts);

◆ ACAPI_LibraryPart_RegisterESYM()

GSErrCode ACAPI_LibraryPart_RegisterESYM	(	GSType	signature,
		API_LibTypeID	typeID,
		short	stringResID )

Registers an external symbol type with Archicad.

Parameters

signature	[in] Unique identifier of the new symbol type (a four-character ID).
typeID	[in] Type of the new symbol (can be `API_ObjectID`, `API_LampID`, `API_WindowID`, or `API_DoorID`).
stringResID	[in] Resource containing the description of the new symbol type.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Invalid symbol type.

Remarks: This function should be called from your add-on's RegisterInterface routine. More than one external symbol can be registered from one add-on. After registration you should also install a callback function with ACAPI_LibraryPart_InstallESYMHandler in your Initialize function, which will handle the events coming from Archicad.

Example: //------------------------------------------------------

// Interface definitions

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

GSErrCode RegisterInterface (void)

{

GSErrCode err;

// Register ESYM

err = ACAPI_LibraryPart_RegisterESYM ('GRPH', APILib_LampID, 32611);

return err;

}

◆ ACAPI_LibraryPart_Save()

GSErrCode ACAPI_LibraryPart_Save ( API_LibPart * libPart )

Saves the Library Part has been created and registers it.

Parameters

libPart [in/out] Parameters of the library part to create

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The libPart parameter is nullptr
APIERR_GENERAL - No scratch file has been opened with the ACAPI_LibraryPart_Create function.

Remarks: This function is used to save the recently created library part by the ACAPI_LibraryPart_Create function. The same parameters should be passed in the API_LibPart structure as it was pass to the ACAPI_LibraryPart_Create function. In the index field, the library index of the currently created library part is returned, which you can use in subsequent operations. This function must be called to close the scratch if the ACAPI_LibraryPart_Create function has succeed; even if any of the in-between function calls have failed. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

◆ ACAPI_LibraryPart_Search()

GSErrCode ACAPI_LibraryPart_Search	(	API_LibPart *	ancestor,
		bool	createIfMissing,
		bool	onlyPlaceable = false )

Searches for a registered Library Part in the loaded libraries.

Parameters

ancestor	[in/out] The library part to search for
createIfMissing	[in] Set to true to create a reference if it is missing.
onlyPlaceable	[in] The search is limited to placeable library parts only. Optional parameter, can be omitted.

Returns

NoError - The function has completed with success, the Library Part has been found (or reference created successfully if createIfMissing is true)
APIERR_MISSINGDEF - The originating library part file is missing. The document name is still filled.
APIERR_BADPARS - ancestor is nullptr
APIERR_BADID - no library part is found according to the given ownUnID, parentUnID or typeID parameters
APIERR_BADNAME - no library part is found with the given document or file name
APIERR_MEMFULL - the reference cannot be created; only when createIfMissing is true

Remarks

This function is used to search a Library Part in the loaded libraries. The Library Part can be referenced by the following criteria:

the most exact identification of a library part is the global unique ID. You can copy the unique ID string of the requested library part into the ownUnID field of the API_LibPart structure. Since the revision part of the unique ID can be changed by minor modifications (see Library Part Subtypes for more details), only main GUID match can meet the condition. If you search by ownUnID, set the docu_Name and file_Name fields to empty string
if you leave the ownUnID and docu_Name fields blank, but file_Name is given, the function will search by the name of the library part file
if ownUnID and file_Name are not specified, or docu_Name is not an empty string if docu_Name is given, ACAPI_LibraryPart_Search tries to find a library part with that document name. Note that document names are not unique. You may reduce the chance of mismatch if you also specify the subtype parentUnID if parentUnID is given, but docu_UName is empty, the function retrieves the first library part in the enumerated libraries which is a descendant of the specified parent subtype
if docu_Name is given, ACAPI_LibraryPart_Search tries to find a library part with that document name. Note that document names are not unique. You may reduce the chance of mismatch if you also specify the subtype parentUnID
if parentUnID is given, but docu_UName is empty, the function retrieves the first library part in the enumerated libraries which is a descendant of the specified parent subtype Library Part Subtypes typeID parentUnID APILib_ObjectID API_ZombieLibID ACAPI_LibraryPart_Search can also create a virtual reference to a none existing library part (i.e. an index which can be referred to) if the library part has not found in the active libraries and createIfMissing was set true). Same effect appears when an opened plan refers to a library part which is not in the active libraries. In this case Archicad places a filled circle on the plan where a missing library part is referenced. On success ACAPI_LibraryPart_Search fills out all the fields of the API_LibPart structure, therefore remember to free the location pointer allocated by the function if you do not not need it any more.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::LibraryManager::FindLibParts instead

◆ ACAPI_LibraryPart_SetDetails_ParamDef()

GSErrCode ACAPI_LibraryPart_SetDetails_ParamDef	(	const API_LibPart *	libPart,
		GSHandle	paramHdl,
		const API_LibPartDetails *	details )

Sets the detail parameters of a Library Part parameter section handle.

Parameters

libPart	[in] The library part to work on.
paramHdl	[in/out] Parameter section data
details	[in] Detail parameters

Returns

NoError - The function has completed with success.
APIERR_BADPARS - any of the parameters are nullptr

Remarks

This function is used to store detail parameters in the parameter section handle. These parameters can be edited in Archicad by clicking the Details button on the parameter list editor dialog box. Applicable type of Library Parts are:

APILib_WindowID
APILib_DoorID
APILib_ObjectID
APILib_LampID
APILib_RoomID
APILib_LabelID To get the detail parameters of a registered Library Part refer to the ACAPI_LibraryPart_GetDetails function. Note, that the ACAPI_LibraryPart_GetDetails and ACAPI_LibraryPart_SetDetails_ParamDef functions are not symmetrical; it is shown in the function names too. Since the detail parameters are stored in the parameter section of the Library Part, this implementation interface is the most effective.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

◆ ACAPI_LibraryPart_SetUpSect_2DDrawHdl()

GSErrCode ACAPI_LibraryPart_SetUpSect_2DDrawHdl ( void )

Sets up an empty 2D binary (drawing) section to fill up from API elements.

Returns

NoError - The function has completed with success.
APIERR_NESTING - recursive call, ACAPI_LibraryPart_GetSect_2DDrawHdl was not called after the previous call
APIERR_MEMFULL - not enough memory

Remarks: This function is used to initialize the 2D binary (drawing) section of the library part. The subsequent calls to the element creation function ACAPI_Element_Create will be redirected. Instead of putting the created elements into the current database it will put them into the opened 2D symbol drawing, until the ACAPI_LibraryPart_GetSect_2DDrawHdl function is called. This is the only way to add a 2D binary drawing section to a Library Part. However the internal format of the section handle is public, it is a quite hard job to provide a full solution without this functionality.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

◆ ACAPI_LibraryPart_ShapePrims()

GSErrCode ACAPI_LibraryPart_ShapePrims	(	Int32	libInd,
		const API_Guid &	instanceElemGuid,
		short	gdlContext,
		ShapePrimsProc *	shapePrimsProc )

Virtually draws the shape of a registered Library Part.

Parameters

libInd [in] Index of the library part

instanceElemGuid [in] Instance element GUID; if APINULLGuid, then the drawing parameters will be the default parameters of the library part (with no transformation, etc.), otherwise they are taken from the instance of the library part defined by this GUID.

gdlContext

[in] The environment of the GDL object (sets GLOB_CONTEXT GDL Global parameter).

Context	Value
Default (depends on the current database)	`APIGdl_Default`
Library Part Editing Dialog (all windows within it)	`APIGdl_FromEdit`
Floor Plan Window	`APIGdl_FromFloor`
3D Window	`APIGdl_From3DWin`
Section/Elevation Windows	`APIGdl_FromSide`
Library Part Settings Dialog	`APIGdl_FromDial`
List generated about Library Part	`APIGdl_FromList`
Detail Windows	`APIGdl_FromDetail`
Layout Windows	`APIGdl_FromLayout`

shapePrimsProc [in] Callback function for catching the drawing primitives of the Libpart Part shape.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - shapePrimsProc is nullptr, or invalid libInd parameter has been passed.
APIERR_BADINDEX - Invalid instanceElemGuid for the element type that libInd implies.
APIERR_NESTING - The function was called from a ShapePrimsProc; recursion is not allowed.

Remarks: This function is used to draw the shape of the Libpart Part; as it would appear on the floor plan. The key point is the parameter values to use, since it absolutely determines how a Library Part looks like when it is placed. That's why the instanceElemGuid parameter should be passed; if it is zero the default parameter set, otherwise the parameter set of an already placed instance will be used. The shape will be passed to the callback function with the same drawing primitives would be drawn onto the display. Refer to he ShapePrimsProc to get further details. These drawing procedures cannot be nested. From the callback function it is not allowed to call the ACAPI_LibraryPart_ShapePrims function again. The function works only on Library Parts can be placed onto the floor plan. Applicable type of Library Parts are: APILib_WindowID, APILib_DoorID, APILib_ObjectID, APILib_LampID, APILib_RoomID (zone stamp), APILib_LabelID (symbol label). In order to get the hotspots of a library part or an object instance use the ACAPI_LibraryPart_GetHotspots function.

◆ ACAPI_LibraryPart_UpdateSection()

GSErrCode ACAPI_LibraryPart_UpdateSection	(	Int32	libInd,
		const API_LibPartSection *	section,
		GSHandle	sectionHdl,
		GS::UniString *	sectionStr,
		GS::UniString *	password = nullptr )

Updates a section of a registered Library Part.

Parameters

libInd	[in] Index of the Library Part
section	[in] Identifier of the section.
sectionHdl	[in] Section data.
sectionStr	[in] Optional Unicode content of any textual section.
password	[in] The (optional) password that encrypted the section.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Invalid libInd, or any of the parameters are nullptr, or the addressed Library Part is a macro, picture file etc.

Remarks: This function is used to update the requested section of the library part defined by libInd with the data in the supplied handle. In the case the identified section exists in the Library Part it will be updated; if the section is not found it will be created. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject::SetCustomSection instead

◆ ACAPI_LibraryPart_WriteSection()

GSErrCode ACAPI_LibraryPart_WriteSection	(	Int32	nByte,
		GSConstPtr	data )

Writes data into an opened section of the Library Part under creation.

Parameters

nByte	[in] Number of bytes.
data	[in] Data to be written.

Returns

NoError - The function has completed with success.
APIERR_GENERAL - No section has been opened with the ACAPI_LibraryPart_NewSection function.

Remarks: This function is used to write data into the section recently opened with ACAPI_LibraryPart_NewSection function. It writes the given data (nByte number of bytes addressed by data) to the section recently opened with ACAPI_LibraryPart_NewSection function. If you write the data to a textual section, don't forget to include the newline (+linefeed for Windows) character(s) in data.

Example: API_LibPartDetails details {};

API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;

API_LibPartSection section;

double a, b;

char buffer[256] = {};

GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype

GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)

delete libPart.location;

if (libPart.index != 0) {

ACAPI_WriteReport ("Test LibPart already exists", true);

return;

}

paramsHdl = nullptr;

draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */

b = 3.0;

if (err == NoError) {

err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);

if (err == NoError) {

details.object.fixSize = false;

details.object.autoHotspot = true;

err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);

}

}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */

if (err == NoError) {

/* ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);

Warning: Legacy function - to be deleted in future versions, use ACAPI::LM::GSMObject setters instead

Classes

Typedefs

Enumerations

Functions

Detailed Description

Library Part Overview

References to Library Part

Library Part types

Internal Structure

The 2D drawing section

The parameters section

The 3D binary sections

The Preview picture

Typedef Documentation

◆ APIESYMCommandProc

Enumeration Type Documentation

◆ API_LibTypeID

◆ API_LockableStatus

◆ API_PrimTypeID

Function Documentation

◆ ACAPI_DisposeAddParHdl()

◆ ACAPI_LibraryManagement_DeleteEmbeddedLibItem()

◆ ACAPI_LibraryManagement_DeleteEmbeddedLibItems()

◆ ACAPI_LibraryPart_AddSection()

◆ ACAPI_LibraryPart_ChangeAParameter()

◆ ACAPI_LibraryPart_CheckLibPartSubtypeOf()

◆ ACAPI_LibraryPart_CheckLibPartSubtypeOfbyMain()

◆ ACAPI_LibraryPart_CloseParameters()

◆ ACAPI_LibraryPart_CompareLibPartUnIds()

◆ ACAPI_LibraryPart_Create()

◆ ACAPI_LibraryPart_EndSection()

◆ ACAPI_LibraryPart_Get()

◆ ACAPI_LibraryPart_GetActParameters()

◆ ACAPI_LibraryPart_GetBuiltInLibpartUnId()

◆ ACAPI_LibraryPart_GetDetails()

◆ ACAPI_LibraryPart_GetElemLibPartUnId()

◆ ACAPI_LibraryPart_GetHotspots()

◆ ACAPI_LibraryPart_GetLastValidEmbeddedLPName()

◆ ACAPI_LibraryPart_GetLibPartLockStatus()

◆ ACAPI_LibraryPart_GetLibPartRefGuid()

◆ ACAPI_LibraryPart_GetLibPartToolVariation()

◆ ACAPI_LibraryPart_GetLibPartUnIDStr()

◆ ACAPI_LibraryPart_GetMarkerParent()

◆ ACAPI_LibraryPart_GetNum()

◆ ACAPI_LibraryPart_GetParams()

◆ ACAPI_LibraryPart_GetParamValues()

◆ ACAPI_LibraryPart_GetSect_2DDrawHdl()

◆ ACAPI_LibraryPart_GetSect_ParamDef()

◆ ACAPI_LibraryPart_GetSection()

◆ ACAPI_LibraryPart_GetSectionList()

◆ ACAPI_LibraryPart_GetUnloadedLibpartName()

◆ ACAPI_LibraryPart_InstallESYMHandler()

◆ ACAPI_LibraryPart_NewSection()

◆ ACAPI_LibraryPart_OpenParameters()

◆ ACAPI_LibraryPart_PatternSearch()

◆ ACAPI_LibraryPart_Register()

◆ ACAPI_LibraryPart_RegisterAll()

◆ ACAPI_LibraryPart_RegisterESYM()

◆ ACAPI_LibraryPart_Save()

◆ ACAPI_LibraryPart_Search()

◆ ACAPI_LibraryPart_SetDetails_ParamDef()

◆ ACAPI_LibraryPart_SetUpSect_2DDrawHdl()

◆ ACAPI_LibraryPart_ShapePrims()

◆ ACAPI_LibraryPart_UpdateSection()

◆ ACAPI_LibraryPart_WriteSection()