Redirects element creation into a temporary database for creating drawing data.

    GSErrCode ACAPI_Database (
        APIDb_StartDrawingDataID,
        double*           dScale,
        API_PenType**     api_pens
    );

 

Parameters

dScale

[in] optional parameter (the default value is 1.0); defines the scaling from paper to model. For example, for 1:100 scaling, pass 100.

api_pens

[in] optional parameter (the default pen table is coming from the current workspace (layout or model)); defines the pen table to use for this drawing data.
  It should contain exactly 255 API_PenType records, starting from the first (index 0) record.

 

Return Values

NoError

The function has completed with success.

APIERR_NESTING

Calls to this function cannot be nested; you have to finish the previous drawing data with APIDb_StopDrawingDataID.

For other common API errors see the API Errors document.

 

Remarks

This function opens an internal store for the drawing data (the internal data of a drawing element). Further element creation functions will put the created elements into this store. Only 2D elements (including figures/pictures) are allowed. This drawing data can be passed later in the drawingData member of the API_ElementMemo to ACAPI_Element_Create.

The pens have to be passed upfront in the api_pens parameter, and you cannot modify them later. This restriction is coming from the internal setup of the data store.

 

Example

// -----------------------------------------------------------------------------
// Wraps importing data into IDF
// -----------------------------------------------------------------------------

class IDFSession {

private:
    bool    inited;

public:
    explicit IDFSession () {
        inited = (ACAPI_Database (APIDb_StartDrawingDataID, nullptr, nullptr) == NoError);
    }

    ~IDFSession () {
        if (inited) {
            GSPtr outIDFData = nullptr;
            if (GetIDFData (&outIDFData, nullptr))
                BMKillPtr (&outIDFData);
        }
    }

    bool GetIDFData (GSPtr *outIDFData, API_Box *bounds) {
        if (!inited || outIDFData == nullptr)
            return false;

        bool ret = (ACAPI_Database (APIDb_StopDrawingDataID, outIDFData, bounds) == NoError);

        inited = false;
        return ret;
    }
};

GSErrCode Import::Do ()
{
    IDFSession  idfSession;                                    // 1

    GSErrCode   ret = this->ReadAction::Do ();              // 2

    if (ret == NoError) {
        API_Box bounds  = { 0.0, 0.0, 0.0, 0.0 };
        GSPtr   idfData = nullptr;

        if (idfSession.GetIDFData (&idfData, &bounds)) {    // 3
            PlaceDrawing (idfData, bounds);                   // 4
        }
    }

    return ret;
}

Comments:

1. Initiates an IDF session; it redirects further element creation to the drawing data
2. Reads the elements from an external file into the drawing data
3. Stops the IDF session, fetches the drawing data & its bounds (calculated internally)
4. Places the drawing element into the current database (internally calls ACAPI_Element_Create)

 

Requirements

Version: API 10 or later

Header: APIdefs_Database.h

 

See Also

API_PenType
APIDb_StopDrawingDataID
ACAPI_Element_Create, API_ElementMemo
ACAPI_Database
API Functions