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

enum	API_IDFTypeID { API_IDFTypeUndefined = 0 , API_IDFTypeDrawing = 1 , API_IDFTypeImage = 2 , API_IDFTypePdf = 3 }
	Type of content. 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.

Example: // ============================================================================

// Retrieving Drawing Numbering Grid Lines

// ============================================================================

GSErrCode CustomNumberingGridLineProc (API_NumberingGridLine *gridLine)

{

char msgStr[256];

sprintf (msgStr, "Grid line coordinates: (%e, %e), (%e, %e)",

gridLine->begC.x, gridLine->begC.y, gridLine->endC.x, gridLine->endC.y);

ACAPI_WriteReport (msgStr, false);

return NoError;

}

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.

Enumerator
API_DrawingLink_UnknownID	Unknown link type
API_DrawingLink_InternalViewID	Link to an internal view
API_DrawingLink_ExternalViewID	Link to an external view
API_DrawingLink_DrawingID	Link to a general drawing node
API_DrawingLink_DXF_DWGID	Link to a drawing imported from DXF/DWG file
API_DrawingLink_PDFID	Link to a PDF drawing
API_DrawingLink_ImageID	Link to an image type drawing
API_DrawingLink_PMKID	Link to a drawing imported from PlotMaker file
API_DrawingLink_APIID	Link to a drawing created by an API add-on
API_DrawingLink_InfoID	Embedded drawing (broken link)
API_DrawingLink_OtherID	Not used

◆ API_IDFTypeID

enum API_IDFTypeID

Type of content.

Enumerator
API_IDFTypeUndefined	Undefined content type
API_IDFTypeDrawing	Drawing content type
API_IDFTypeImage	Image content type
API_IDFTypePdf	PDF content type

◆ API_ViewNodeTypeID

enum API_ViewNodeTypeID

Type of the view nodes.

Remarks: These view type values are used in the API_DrawingLinkInfo structure.

Enumerator
API_ViewNodeUndefined	Undefined node type
API_ViewNodeStory	Story view node
API_ViewNodeSection	Section/Elevation view node
API_ViewNodeDetailDrawing	Detail Drawing view node
API_ViewNodePerspective	Perspective 3D Model view node
API_ViewNodeAxonometry	Axonometric 3D Model view node
API_ViewNodeList	List type view node
API_ViewNodeSchedule	Schedule view node
API_ViewNodeToc	Index (Table Of Content) view node
API_ViewNodeCamera	Camera view node
API_ViewNodeCameraSet	Camera Set view node
API_ViewNodeElevation	Elevation view node
API_ViewNodeInteriorElevation	Interior Elevation view node
API_ViewNodeWorksheetDrawing	Worksheet Drawing view node
API_ViewNodeDocumentFrom3D	Document from 3D view node
API_ViewNodeAPIList	Listing window node, created via the API

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_Drawing_IsMarkerDrawingEnabled (&markerDrawingEnabled);

ACAPI_Drawing_ChangeMarkerDrawingEnabled (true);

// ... your code

ACAPI_Drawing_ChangeMarkerDrawingEnabled (markerDrawingEnabled);

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

GSErrCode err = ACAPI_Drawing_GetDrawingLink (&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: // ============================================================================

// Retrieving Drawing Numbering Grid Lines

// ============================================================================

GSErrCode CustomNumberingGridLineProc (API_NumberingGridLine *gridLine)

{

char msgStr[256];

sprintf (msgStr, "Grid line coordinates: (%e, %e), (%e, %e)",

gridLine->begC.x, gridLine->begC.y, gridLine->endC.x, gridLine->endC.y);

ACAPI_WriteReport (msgStr, false);

return NoError;

}

◆ 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_Drawing_IsMarkerDrawingEnabled (&markerDrawingEnabled);

ACAPI_Drawing_ChangeMarkerDrawingEnabled (true);

// ... your code

ACAPI_Drawing_ChangeMarkerDrawingEnabled (markerDrawingEnabled);

◆ 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_Drawing_StartDrawingData () == 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_Drawing_StopDrawingData (outIDFData, bounds) == NoError);

inited = false;

return ret;

}

};

GSErrCode DoReadAction ()

{

// Read data from somewhere

return NoError;

}

GSErrCode Do ()

{

IDFSession idfSession; // 1

GSErrCode ret = DoReadAction (); // 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: // -----------------------------------------------------------------------------

// Wraps importing data into IDF

// -----------------------------------------------------------------------------

class IDFSession {

private:

bool inited;

public:

explicit IDFSession () {

inited = (ACAPI_Drawing_StartDrawingData () == 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_Drawing_StopDrawingData (outIDFData, bounds) == NoError);

inited = false;

return ret;

}

};

GSErrCode DoReadAction ()

{

// Read data from somewhere

return NoError;

}

GSErrCode Do ()

{

IDFSession idfSession; // 1

GSErrCode ret = DoReadAction (); // 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_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.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ APINumberingGridLineProc

Enumeration Type Documentation

◆ API_DrawingLinkTypeID

◆ API_IDFTypeID

◆ API_ViewNodeTypeID

Function Documentation

◆ ACAPI_Drawing_ChangeDrawingScale()

◆ ACAPI_Drawing_ChangeMarkerDrawingEnabled()

◆ ACAPI_Drawing_CheckDrawingStatus()

◆ ACAPI_Drawing_GetDrawingLink()

◆ ACAPI_Drawing_GetDrawingScale()

◆ ACAPI_Drawing_GetFullDrawingContentBox()

◆ ACAPI_Drawing_GetNumberingGridLines()

◆ ACAPI_Drawing_IsMarkerDrawingEnabled()

◆ ACAPI_Drawing_StartDrawingData()

◆ ACAPI_Drawing_StopDrawingData()

◆ ACAPI_Drawing_Update_Drawings()