Starts to create a new Library Part from scratch.
GSErrCode ACAPI_LibPart_Create ( const API_LibPart* libPart );
Parameters
- libPart
- [in] Parameters of the Library Part to create
Return Values
NoError
- The function has completed with success.
APIERR_NESTING
- Recursive call, ACAPI_LibPart_Save was not called after the previous call
APIERR_BADPARS
- The
libPart
parameter isnullptr
, 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
For other common API errors see the API Errors.
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_LibPart_NewSection, ACAPI_LibPart_WriteSection, and ACAPI_LibPart_EndSection
- Create the section in one step by calling the ACAPI_LibPart_AddSection function.
The Library Part itself will be created and registered upon the ACAPI_LibPart_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_LibPart_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; BNClear (libPart); CHCopyC ("{57B7C584-5C0D-11D6-A0D8-036F034B6792}-{00000000-0000-0000-0000-000000000000}", libPart.parentUnID); // General Stair subtype GS::ucscpy (libPart.docu_UName, L("Test LibPart")); err = ACAPI_LibPart_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_LibPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, ¶msHdl); if (err == NoError) { BNZeroMemory (&details, sizeof (API_LibPartDetails)); details.object.fixSize = false; details.object.autoHotspot = true; err = ACAPI_LibPart_SetDetails_ParamDef (&libPart, paramsHdl, &details); } } err = ACAPI_LibPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */ if (err == NoError) { /* ... */ /* ... ACAPI_Element_Create ... */ /* ... ACAPI_Element_Create ... */ /* ... ACAPI_Element_Create ... */ /* ... */ err = ACAPI_LibPart_GetSect_2DDrawHdl (&draw2DHdl); } if (err == NoError) err = ACAPI_LibPart_Create (&libPart); /* Create the Library Part from scratch */ if (err == NoError) { BNZeroMemory (§ion, sizeof (API_LibPartSection)); section.sectType = API_SectParamDef; err = ACAPI_LibPart_AddSection (§ion, paramsHdl, nullptr); /* Add parameters section */ } if (err == NoError) { BNZeroMemory (§ion, sizeof (API_LibPartSection)); section.sectType = API_Sect2DDraw; err = ACAPI_LibPart_AddSection (§ion, draw2DHdl, nullptr); /* Add 2D binary section */ } if (err == NoError) { BNZeroMemory (§ion, sizeof (API_LibPartSection)); section.sectType = API_Sect2DScript; err = ACAPI_LibPart_NewSection (§ion); /* Open the 2D Script section */ if (err == NoError) { CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */ err = ACAPI_LibPart_WriteSection (strlen (buffer), buffer); } err = ACAPI_LibPart_EndSection (); /* ...close it */ } err = ACAPI_LibPart_Save (&libPart); /* Save and register the Library Part */ BMKillHandle (¶msHdl); BMKillHandle (&draw2DHdl)
Requirements
- Version: API 1.3 or later
- Header: ACAPinc.h
See Also
API_LibPart
ACAPI_LibPart_NewSection
ACAPI_LibPart_WriteSection
ACAPI_LibPart_EndSection
ACAPI_LibPart_AddSection
ACAPI_LibPart_Save
ACAPI_LibPart_Register
ACAPI_LibPart_RegisterAll
LibPart Manager
Library Part Subtypes
API Functions