ACAPI_​Element_​Create

Places a new element into current database.

    GSErrCode  ACAPI_Element_Create (
        API_Element*         element,
        API_ElementMemo*     memo
    );

 

Parameters

element
[in/out] The desired element will be created in the pointed structure. The element->header.typeID must specify the type of the element to be created.
memo
[in] The memo field of the desired element will be created from the pointed structure (if the memo field is needed).

 

Return Values

NoError
The function has completed with success.
APIERR_BADDATABASE
The current database is not proper for the operation.
APIERR_BADPARS
The passed parameter is nullptr; element
APIERR_BADID
The element type is invalid, or
the element type is not supported by the server application
APIERR_REFUSEDPAR
The element->header.typeID parameter was incorrect. It might happen if you want to create something in a window not capable to display it, for example a wall in a section window.
APIERR_INVALFLOOR
The element->header.floorInd parameter is out of range.
APIERR_IRREGULARPOLY
Input polygon or polyline is irregular.
 

For other common API errors see the API Errors document.

 

Remarks

The type of the element to be created is defined by typeID in the element header. On return, the guid field of the header is filled in. Don’t forget to call ACAPI_DisposeElemMemoHdls to dispose the handles when you’re done.

The meaning of the different parameters is explained in the table below:

element->header.typeID

memo fields

📝 Notes

API_WallID

optional/required

The gables are optional, the coords, pends, and parcs are required only for walls of type APIWtyp_Poly (polygon-based walls)

API_ColumnID

optional (gables, assemblySegmentProfiles)
required (columnSegments, assemblySegmentCuts, assemblySegmentSchemes)

 

API_BeamID

optional (gables, beam holes, assemblySegmentProfiles)
required (beamSegments, assemblySegmentCuts, assemblySegmentSchemes)

 

API_WindowID
API_DoorID

required (params)

See also ACAPI_Element_CreateExt.

API_SkylightID Featuring API 15

required (params)

See also ACAPI_Element_CreateExt.

API_ObjectID
API_LampID

required

 

API_SlabID

required/optional

The slab polygon is required; the edgeTrims and sideMaterials are optional.

API_RoofID

required/optional

The roof polygon is required; the edgeTrims, roofEdgeTypes and sideMaterials are optional.
Featuring API 15 Besides these parameters for Multi-plane roofs the pivotPolyCoords, pivotPolyPends and pivotPolyParcs are also required; the pivotPolyEdges are optional.

API_MeshID

required/optional

The mesh polygon is required, the meshPolyZ (mesh points’ Z coordinates), the meshLevelCoords (level line coordinates), and the meshLevelEnds (level lines’ endpoints) fields are optional.

API_ShellID Featuring API 15

required/optional

Shell shape data is required (first record of shellShapes for extruded and revolved shells, both records for ruled shells; shellContours are optional.

API_MorphID Featuring API 16

required/optional

The morphBody field is required and the morphMaterialMapTable field is optional.

API_DimensionID

required (dimension data)

 

API_RadialDimensionID
API_AngleDimensionID

 

 

API_LevelDimensionID

 

If the ceilNum is set to 0, the level dimension’s reference is the floor, otherwise the given ceiling.

API_TextID

required (content)

optional (paragraphs) for multistyle content

 

API_LabelID

optional (content) for textual labels

optional (paragraphs) for multistyle content

required (parameters) for symbol labels

The API_LabelType::parent member determines whether an independent or an associative Label will be created.
  • Set this member to APINULLGuid to create an independent Label.
  • Set this member to the GUID of the owner element (a labelable element) to create an associative Label. For the list of labelable elements see ACAPI_Element_GetConnectedElements.

API_ZoneID

required (polygon and parameters)

 

API_HatchID

required (fill polygon)

If the hatchGlobal field is set to false (the fill is linked to an element), the refPos and refAngle fields are used to calculate the orientation, otherwise the global origin is used for this. If the showArea field is set to true, the note and the noteC fields are used for the appearance of the area, otherwise these fields are ignored.

API_LineID
API_ArcID
API_CircleID

 

 

API_PolyLineID

required (polygon)

 

API_SplineID

required/optional

The curve point coordinates are required. If the bezierDirs field is nullptr (autoSmooth is true), the direction parameters are automatically calculated from the first two points’ relative position (the autoSmooth field must be set to true in this case).

API_HotspotID

 

 

API_PictureID

required (picture content)

 

API_DrawingID

optional (polygon, drawing data)

 

API_CutPlaneID

required

The cutplane coordinates are required.
See also ACAPI_Element_CreateExt.

API_ChangeMarkerID

optional (polygon)

See also ACAPI_Element_CreateExt.

API_DetailID
API_WorksheetID

optional (polygon)

See also ACAPI_Element_CreateExt.

API_CameraID

optional (linklist)

Optional for panoramic cameras only.

API_CamSetID

 

 

API_SectElemID

 

This type of element cannot be created.

API_StairID New in API 21

required (polyline)

 

API_RailingID New in API 21

required (polyline)

 

API_OpeningID 21

Extrusion base plane (extrusionGeometryData.frame) and owner element required.

The creation process for elements follows the same process as the one you use for creating elements graphically in Archicad. This means for example, that you have to create a wall for windows and doors, etc. The API always checks for the presence of the necessary information, and returns with an error code if something is missing.

The created element may be redirected into the 2D binary section of a Library Part. Refer to the ACAPI_LibPart_SetUpSect_2DDrawHdl function for details. In these case no information is returned, what indices, guids were generated. In this environment only 2D drawing elements can be generated.

The element also can be clipped by a clipping region. Refer to the APIDb_StartClippingSessionID function for details. In these case no information is returned, what indices, guids were generated, since more parts may be generated.

 

Requirements

Version: API 1.3 or later
Header: ACAPinc.h

 

See Also

API_Element, API_ElementMemo, ACAPI_Element_CreateExt
ACAPI_LibPart_SetUpSect_2DDrawHdl, APIDb_StartClippingSessionID, ACAPI_DisposeElemMemoHdls
Element Manager, API Functions