Drawing Manager

Functions related to the Database Manager, creating, manupulating and switching between different Drawing databases. More...

Classes
struct	API_DrawingLinkInfo
	Parameters of a drawing link. More...
struct	API_NumberingGridLine
	Represents a drawing numbering grid line of the layout. More...

Typedefs
typedef GSErrCode	APINumberingGridLineProc(const API_NumberingGridLine *gridLine)
	User supplied callback function for processing the drawing numbering grid lines.

Enumerations
enum	API_DrawingLinkTypeID {   API_DrawingLink_UnknownID = 0 , API_DrawingLink_InternalViewID , API_DrawingLink_ExternalViewID , API_DrawingLink_DrawingID ,   API_DrawingLink_DXF_DWGID , API_DrawingLink_PDFID , API_DrawingLink_ImageID , API_DrawingLink_PMKID ,   API_DrawingLink_APIID , API_DrawingLink_InfoID , API_DrawingLink_OtherID }
	Type of the drawing link. More...
enum	API_ViewNodeTypeID {   API_ViewNodeUndefined = 0 , API_ViewNodeStory = 1 , API_ViewNodeSection = 2 , API_ViewNodeDetailDrawing = 3 ,   API_ViewNodePerspective = 4 , API_ViewNodeAxonometry = 5 , API_ViewNodeList = 6 , API_ViewNodeSchedule = 7 ,   API_ViewNodeToc = 8 , API_ViewNodeCamera = 9 , API_ViewNodeCameraSet = 10 , API_ViewNodeElevation = 11 ,   API_ViewNodeInteriorElevation = 12 , API_ViewNodeWorksheetDrawing = 13 , API_ViewNodeDocumentFrom3D = 14 , API_ViewNodeAPIList = 15 }
	Type of the view nodes. More...

Functions
GSErrCode	ACAPI_Drawing_GetDrawingScale (double *scale)
	Returns the drawing scale of the current database.
GSErrCode	ACAPI_Drawing_ChangeDrawingScale (double *scale, bool zoom=false)
	Changes the drawing scale.
GSErrCode	ACAPI_Drawing_StartDrawingData (double *dScale=nullptr, const GS::Array< API_Pen > *api_pens=nullptr)
	Redirects element creation into a temporary database for creating drawing data.
GSErrCode	ACAPI_Drawing_StopDrawingData (GSPtr *idfMem=nullptr, API_Box *api_boundBox=nullptr)
	Finalizes the direct creation of drawing elements.
GSErrCode	ACAPI_Drawing_GetDrawingLink (const API_Guid *guid, API_DrawingLinkInfo *drawingLinkInfo)
	Returns various information on a drawing link.
GSErrCode	ACAPI_Drawing_CheckDrawingStatus (API_Guid *guid, Int32 *status)
	Checks whether the given drawing is up-to-date.
GSErrCode	ACAPI_Drawing_GetFullDrawingContentBox (API_Box *api_box, const API_Guid *drawingGuid)
	Returns the full boundary box of an IDF database.
GSErrCode	ACAPI_Drawing_GetNumberingGridLines (APINumberingGridLineProc *gridLineProc)
	Retrieves the lines of the grid-based drawing numbering system.
GSErrCode	ACAPI_Drawing_IsMarkerDrawingEnabled (bool *enabled)
	Checks whether attached objects (window/door markers, drawing titles, etc.) are processed and returned during primitive decomposition.
GSErrCode	ACAPI_Drawing_ChangeMarkerDrawingEnabled (bool enabled)
	Sets whether attached objects (window/door markers, drawing titles, etc.) should be processed and returned during primitive decomposition.
GSErrCode	ACAPI_Drawing_Update_Drawings (const GS::Array< API_Guid > &drawingsToUpdate)
	Triggers a manual update of the specified drawings.

Detailed Description

Functions related to the Database Manager, creating, manupulating and switching between different Drawing databases.

Typedef Documentation

APINumberingGridLineProc

typedef GSErrCode APINumberingGridLineProc(const API_NumberingGridLine *gridLine)

User supplied callback function for processing the drawing numbering grid lines.

Parameters

gridLine

[in] This structure contains parameters (coordinates, pen color, line type) of the current drawing numbering grid lines

Returns

• NoError - The callback function is expected to return NoError.

Remarks

This callback function is used with the ACAPI_Drawing_GetNumberingGridLines function to get the lines of the drawing numbering grid of the current Archicad layout database.

Enumeration Type Documentation

API_DrawingLinkTypeID

enum API_DrawingLinkTypeID

Type of the drawing link.

Remarks

These drawing link type values are used in the API_DrawingLinkInfo structure.

API_ViewNodeTypeID

enum API_ViewNodeTypeID

Type of the view nodes.

Remarks

These view type values are used in the API_DrawingLinkInfo structure.

Function Documentation

ACAPI_Drawing_ChangeDrawingScale()

GSErrCode ACAPI_Drawing_ChangeDrawingScale	(	double *	scale,
		bool	zoom = false
	)

Changes the drawing scale.

Parameters

scale	[in] The new scale for the drawing.
zoom	[in] Perform a rebuild command after changing the scale.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dScale is nullptr or contains wrong value.

Remarks

This function is used to change the drawing scale of the plan. The scale has to be greater than 1 and smaller than 30000.

ACAPI_Drawing_ChangeMarkerDrawingEnabled()

GSErrCode ACAPI_Drawing_ChangeMarkerDrawingEnabled

(

bool

enabled

)

Sets whether attached objects (window/door markers, drawing titles, etc.) should be processed and returned during primitive decomposition.

Parameters

enabled

[in] True if attached objects should be processed.

Returns

• NoError - The function has completed with success.

Remarks

In most cases you should query the value first with ACAPI_Drawing_IsMarkerDrawingEnabled, then change it for your code, then change it back to it's original value, as the example shows.

Example

bool markerDrawingEnabled = false;
ACAPI_Environment (APIEnv_IsMarkerDrawingEnabledID, &markerDrawingEnabled, nullptr);
ACAPI_Environment (APIEnv_ChangeMarkerDrawingEnabledID, reinterpret_cast<void*> (static_cast<Int32> (true)), nullptr);
 
// ... your code
 
ACAPI_Environment (APIEnv_ChangeMarkerDrawingEnabledID, reinterpret_cast<void*> (static_cast<Int32> (markerDrawingEnabled)), nullptr);

ACAPI_Drawing_CheckDrawingStatus()

GSErrCode ACAPI_Drawing_CheckDrawingStatus	(	API_Guid *	guid,
		Int32 *	status
	)

Checks whether the given drawing is up-to-date.

Parameters

guid	[in] The GUID of the drawing element
status	[out] 1 if the drawing is up-to-date, 0 if modified, -1 otherwise

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The status parameter is nullptr, or the drawing contains invalid link ID.
• APIERR_BADINDEX - The guid is not valid, or the drawing comes from a master layout.

Remarks

Call this function to check the status of a drawing quickly (as seen on the Drawing Link Manager palette).

ACAPI_Drawing_GetDrawingLink()

GSErrCode ACAPI_Drawing_GetDrawingLink	(	const API_Guid *	guid,
		API_DrawingLinkInfo *	drawingLinkInfo
	)

Returns various information on a drawing link.

Parameters

guid	[in] get information for drawing link identified with drawing's guid
drawingLinkInfo	[out] the drawing link's type, guid, etc.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The drawing link is not valid.

Remarks

This function is used to get basic information about a drawing link identified by the linkUID parameter. Remember to release the linkPath location and the viewPath pointer dynamically allocated by the function, as it is shown in the example below.

Example

Int32 IsExternalView (API_DrawingType* drawing)
{
    API_DrawingLinkInfo drawingLinkInfo;
    BNZeroMemory (&drawingLinkInfo, sizeof (API_DrawingLinkInfo));
 
    GSErrCode err = ACAPI_Database (APIDb_GetDrawingLinkID, (void *) (&drawing->head.guid), &drawingLinkInfo);
    if (drawingLinkInfo.linkPath != nullptr)
        delete drawingLinkInfo.linkPath;
    if (drawingLinkInfo.viewPath != nullptr)
        BMKillPtr (&drawingLinkInfo.viewPath);
 
    if (err != NoError)
        return -1;
    else if (drawingLinkInfo.linkTypeID == API_DrawingLink_ExternalViewID)
        return 1;
 
    return 0;
}

ACAPI_Drawing_GetDrawingScale()

GSErrCode ACAPI_Drawing_GetDrawingScale

(

double *

scale

)

Returns the drawing scale of the current database.

Parameters

scale

[out] the drawing scale

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dScale is nullptr

Remarks

This function returns the drawing scale of the current database, as each database may have different scale. Note: for 1:100 drawings 100.0 is returned, for 1:20 drawings 20.0 is returned etc. For layouts, the return value is always 1.0.

ACAPI_Drawing_GetFullDrawingContentBox()

GSErrCode ACAPI_Drawing_GetFullDrawingContentBox	(	API_Box *	api_box,
		const API_Guid *	drawingGuid
	)

Returns the full boundary box of an IDF database.

Parameters

api_box	[out] The bounding box of the drawing's IDF.
drawingGuid	[in] The guid of the drawing contains the IDF.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The drawingGuid parameter is invalid.

Remarks

This function is used to get the bounding box of drawing's IDF.

ACAPI_Drawing_GetNumberingGridLines()

GSErrCode ACAPI_Drawing_GetNumberingGridLines

(

APINumberingGridLineProc *

gridLineProc

)

Retrieves the lines of the grid-based drawing numbering system.

Parameters

gridLineProc

The callback function to be called to process the lines of the drawing numbering grid.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - gridLineProc is nullptr
• APIERR_BADDATABASE - The current database is not layout type

Remarks

Use this function to enumerate the lines of the grid if the current layout uses grid-based drawing numbering. The user-defined callback function gridLineProc is called for each line of the grid.

Example

See a sample callback function at the description of APINumberingGridLineProc
.

ACAPI_Drawing_IsMarkerDrawingEnabled()

GSErrCode ACAPI_Drawing_IsMarkerDrawingEnabled

(

bool *

enabled

)

Checks whether attached objects (window/door markers, drawing titles, etc.) are processed and returned during primitive decomposition.

Parameters

enabled

[out] True if attached objects are processed.

Returns

• NoError - The function has completed with success.

Remarks

Use this function to query the flag set by ACAPI_Drawing_ChangeMarkerDrawingEnabled. In most cases you should query the value first, then change it for your code, then change it back to it's original value, as the example shows.

Example

bool markerDrawingEnabled = false;
ACAPI_Environment (APIEnv_IsMarkerDrawingEnabledID, &markerDrawingEnabled, nullptr);
ACAPI_Environment (APIEnv_ChangeMarkerDrawingEnabledID, reinterpret_cast<void*> (static_cast<Int32> (true)), nullptr);
 
// ... your code
 
ACAPI_Environment (APIEnv_ChangeMarkerDrawingEnabledID, reinterpret_cast<void*> (static_cast<Int32> (markerDrawingEnabled)), nullptr);

ACAPI_Drawing_StartDrawingData()

GSErrCode ACAPI_Drawing_StartDrawingData	(	double *	dScale = nullptr,
		const GS::Array< API_Pen > *	api_pens = nullptr
	)

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

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.

Returns

• 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 ACAPI_Drawing_StopDrawingData.

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;
}

ACAPI_Drawing_StopDrawingData()

GSErrCode ACAPI_Drawing_StopDrawingData	(	GSPtr *	idfMem = nullptr,
		API_Box *	api_boundBox = nullptr
	)

Finalizes the direct creation of drawing elements.

Parameters

idfMem	[out] an opaque data stream containing the drawing database in a serialized form
api_boundBox	[out] optional parameter; if not nullptr then on return contains the bounding box of the created elements

Returns

• NoError - The function has completed with success.

Remarks

This function finalizes the database started with ACAPI_Drawing_StartDrawingData. The returned database can be used to create a drawing element on the layout or in the model; pass the idfMem pointer in the drawingData member of API_ElementMemo.

Example

See the Example section of APIDb_StartDrawingDataID
.

ACAPI_Drawing_Update_Drawings()

GSErrCode ACAPI_Drawing_Update_Drawings

(

const GS::Array< API_Guid > &

drawingsToUpdate

)

Triggers a manual update of the specified drawings.

Since

Archicad 27

Parameters

drawingsToUpdate

[in] List of the drawings to be updated.

Returns

• NoError - The function has been completed with success.