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

    GSErrCode ACAPI_Interface (
        APIIo_ObjectSettingsID,
        API_ObjectSettingsPars*     objectSettingsPars
    );

 

Parameters

objectSettingsPars

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

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

objectSettingsPars is nullptr.

APIERR_BADID

objectSettingsPars contains invalid data.

For other common API errors see the API Errors document.

 

Remarks

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

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

 

Example

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

    BNZeroMemory (&api_objSetPars, sizeof (API_ObjectSettingsPars));

    api_objSetPars.elemDef.object.head.type = 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;
}

 

Requirements

Version: API 4.1 or later

Header: APIdefs_Interface.h

 

See Also

API_ObjectSettingsPars
ACAPI_Interface
API Functions