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.type 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.type 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 type 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.type`	`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`	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. 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`	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`	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.
`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`	required (polyline)
`API_RailingID`	required (polyline)
`API_OpeningID`		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

Parameters

Return Values

Remarks

Requirements

See Also