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_Environment 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_Register_BuiltInLibrary).

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_LibPart_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_LibPart_GetSectionList function.

If you are interested in the data of any section, you can get it by simply calling the ACAPI_LibPart_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_LibPart_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_LibPart_SetUpSect_2DDrawHdl ();
ACAPI_Element_Create()
...
ACAPI_Element_Create()
err = ACAPI_LibPart_GetSect_2DDrawHdl (&bin2DHdl);

BNZeroMemory (&section, sizeof (API_LibPartSection));
section.sectType = API_Sect2DDraw;
err = ACAPI_LibPart_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_LibPart_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_LibPart_GetSect_ParamDef (APILib_ObjectID, addParHdl,
                                      &a, &b, bin2DHdl,
                                      &paramsHdl);

BNZeroMemory (&section, sizeof (API_LibPartSection));
section.sectType = API_SectParamDef;
err = ACAPI_LibPart_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.

 

 


Modified on April 17, 2007