Opens the Object/Lamp(/Window/Door) Settings dialog.

    GSErrCode ACAPI_Interface (
        API_ObjectSettingsPars*     objectSettingsPars



[in/out] The parameters to open the dialog with. Also contains the selected object on return.


Return Values

The function has completed with success.
objectSettingsPars is nullptr.
objectSettingsPars contains invalid data.

For other common API errors see the API Errors document.



The Settings dialog may show only library parts with a given subtype. The default library part’s library index can also be passed onto this function.

It returns the parameters set in the Settings dialog, and also the additional parameters of the selected library part.

If subtypeID is an empty string, then the passed typeID and variationID will be used to identify the tool whose subtype will serve as a filter.

If libIndex is 0 (i.e. you haven’t used ACAPI_LibPart_Search to find an appropriate library item), then the function tried to find the first item in the loaded libraries, whose subtype matches the passed subTypeID (or typeID and variationID).

6.1 The linked properties information specified on the Listing and Labeling page returns in the propIndivLibInd and propCriteria fields. These properties should be linked to the element you would create after calling the Object Settings dialog (see ACAPI_Element_SetLinkedPropertyObjects).



GSErrCode SelectObject (void)
    GSErrCode    err = NoError;
    API_ObjectSettingsPars api_objSetPars;

    BNZeroMemory (&api_objSetPars, sizeof (API_ObjectSettingsPars));

    api_objSetPars.elemDef.object.head.typeID = API_ObjectID;    // this tells the API which dialog it should bring up
    CHCopyC ("{D65FA25D-A6D4-48A4-BD9B-2DFE16D58297}-{0D053320-4961-4B12-A2C3-BEA101B0E56F}", api_objSetPars.subtypeID);
    // GUID of Gas Supply Terminal subtype                       // the appropriate subtype should be copied here; it'll be used for filtering

    err = ACAPI_Interface (APIIo_ObjectSettingsID, &api_objSetPars, nullptr);
    if (err == NoError) {
        char msgStr[256];
        sprintf (msgStr, "Object #%d was selected!", api_objSetPars.elemDef.object.libInd);
        ACAPI_WriteReport (msgStr, true);

        // Create an object element:
            API_Element     element;
            API_ElementMemo memo;
            BNZeroMemory (&element, sizeof (API_Element));
            BNZeroMemory (&memo, sizeof (API_ElementMemo));

            element.object = api_objSetPars.elemDef.object;
            element.object.pos.x = ...x...;
            element.object.pos.y = ...y...;
            element.header.floorInd = ...story...;
            memo.params = api_objSetPars.addPars;

            err = ACAPI_CallUndoableCommand ("...",
                [&] () -> GSErrCode {
                    GSErrCode err1 = ACAPI_Element_Create (&element, &memo);
                    if (err1 == NoError)
                        err1 = ACAPI_Element_SetLinkedPropertyObjects (&element.header, api_objSetPars.propCriteria, api_objSetPars.propIndivLibInd);
                    return err1;

    if (api_objSetPars.addPars != nullptr)
        ACAPI_DisposeAddParHdl (&api_objSetPars.addPars);    // do not forget to dispose the handle

    return err;



Version: API 4.1 or later
Header: APIdefs_Interface.h


See Also

API Functions