ACAPI_​LibPart_​Create

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

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:

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, &paramsHdl);
    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 (&section, sizeof (API_LibPartSection));
    section.sectType = API_SectParamDef;
    err = ACAPI_LibPart_AddSection (&section, paramsHdl, nullptr);   /* Add parameters section */
}
if (err == NoError) {
    BNZeroMemory (&section, sizeof (API_LibPartSection));
    section.sectType = API_Sect2DDraw;
    err = ACAPI_LibPart_AddSection (&section, draw2DHdl, nullptr);   /* Add 2D binary section */
}
if (err == NoError) {
    BNZeroMemory (&section, sizeof (API_LibPartSection));
    section.sectType = API_Sect2DScript;
    err = ACAPI_LibPart_NewSection (&section);              /* 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 (&paramsHdl);
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