Issue management

Functions exposing the Issue management and BCF import-export functionalities. More...

Classes
struct	API_MarkUpType
	Represents a Mark-Up entry. More...
struct	API_MarkUpCommentType
	Represents a comment attached to a Mark-Up entry. More...

Enumerations
enum	API_MarkUpCommentStatusID { APIComment_Error = 0 , APIComment_Warning , APIComment_Info , APIComment_Unknown }
	Describes the various options for Mark-Up comment status. More...
enum	API_MarkUpComponentTypeID { APIMarkUpComponent_Creation = 0 , APIMarkUpComponent_Highlight , APIMarkUpComponent_Deletion , APIMarkUpComponent_Modification }
	Describes the type of a component attached to a Mark-Up entry. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_Markup_Create (API_MarkUpType &markUp)
	Creates new Mark-Up entry.
GSErrCode __ACENV_CALL	ACAPI_Markup_GetList (const API_Guid &elemGuid, GS::Array< API_MarkUpType > *markUpList, bool *asCorrected=nullptr)
	Returns the existing Mark-Up entries which the given element is attached to.
GSErrCode __ACENV_CALL	ACAPI_Markup_Delete (const API_Guid &markUpGuid, bool acceptAllElements=false)
	Deletes an existing Issue.
GSErrCode __ACENV_CALL	ACAPI_Markup_AttachElements (const API_Guid &markUpGuid, const GS::Array< API_Guid > &elemList, API_MarkUpComponentTypeID type, GS::HashTable< API_Guid, API_Guid > *modificationElemTable=nullptr)
	Attach elements to an existing Mark-Up as corrected or highlighted elements.
GSErrCode __ACENV_CALL	ACAPI_Markup_DetachElements (const API_Guid &markUpGuid, const GS::Array< API_Guid > &elemList)
	Detach elements from an existing Mark-Up.
GSErrCode __ACENV_CALL	ACAPI_Markup_GetAttachedElements (const API_Guid &markUpGuid, API_MarkUpComponentTypeID type, GS::Array< API_Guid > &attachedElements)
	Returns the corrected and highlighted elements of the given Mark-Up.
GSErrCode __ACENV_CALL	ACAPI_Markup_AddComment (const API_Guid &markUpGuid, API_MarkUpCommentType &comment)
	Adds a new comment to the given Mark-Up.
GSErrCode __ACENV_CALL	ACAPI_Markup_GetComments (const API_Guid &markUpGuid, GS::Array< API_MarkUpCommentType > *commentList)
	Returns the comments attached to the given Mark-Up entry.
GSErrCode __ACENV_CALL	ACAPI_Markup_ExportToBCF (const IO::Location &fileLoc, const GS::Array< API_Guid > &markupEntryIds, const bool useExternalId=false, const bool alignBySurveyPoint=true)
	Exports a BCF file to specified location.
GSErrCode __ACENV_CALL	ACAPI_Markup_ImportFromBCF (const IO::Location &fileLoc, const bool silentMode, APIIFCRelationshipDataProc *ifcRelationshipDataProc, const void *par1, const bool openMarkUpPalette=false, const bool alignBySurveyPoint=true)
	Imports a BCF file.

Detailed Description

Functions exposing the Issue management and BCF import-export functionalities.

Enumeration Type Documentation

API_MarkUpCommentStatusID

enum API_MarkUpCommentStatusID

Describes the various options for Mark-Up comment status.

Remarks

API_MarkUpCommentType structure uses this enum.

API_MarkUpComponentTypeID

enum API_MarkUpComponentTypeID

Describes the type of a component attached to a Mark-Up entry.

Since

Archicad 25

Remarks

ACAPI_Markup_AttachElements and ACAPI_Markup_GetAttachedElements functions use this enum.

Function Documentation

ACAPI_Markup_AddComment()

GSErrCode __ACENV_CALL ACAPI_Markup_AddComment	(	const API_Guid &	markUpGuid,
		API_MarkUpCommentType &	comment
	)

Adds a new comment to the given Mark-Up.

Parameters

markUpGuid	[in] GUID of the existing Mark-Up.
comment	[in/out] The parameters of the new comment. The guid and creaTime will be filled by this function.

Returns

• NoError - The function has completed with success.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADPARS - The passed markUpGuid parameter was incorrect.

Remarks

A new comment can be added to an existing Mark-Up entry using this function. Use ACAPI_Markup_GetList function to return the list of all Mark-Up entries and ACAPI_Markup_GetComments function to get the previously added comments.

Example

Mark-Up related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_AttachElements()

GSErrCode __ACENV_CALL ACAPI_Markup_AttachElements	(	const API_Guid &	markUpGuid,
		const GS::Array< API_Guid > &	elemList,
		API_MarkUpComponentTypeID	type,
		GS::HashTable< API_Guid, API_Guid > *	modificationElemTable = nullptr
	)

Attach elements to an existing Mark-Up as corrected or highlighted elements.

Since

Archicad 25

Parameters

markUpGuid	[in] GUID of the existing Mark-Up.
elemList	[in] The list of elements to attach.
type	[in] Attach the elements with the given Component type.
modificationElemTable	[in/out] Optional parameter, used only when APIMarkUpComponent_Modification is passed in type parameter. The table of the original and the modified element pairs.

Returns

• NoError - The function has completed with success.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADPARS - The passed markUpGuid parameter or at least one of the given element GUIDs was incorrect.

Remarks

Using this function an existing element can be attached to an existing Mark-Up entry. Note that an element can be attached to only one Mark-Up as creation or deletion, but it can be attached to more Mark-Ups as highlighted and cannot be attached as highlighted and creation/deletion simultaneously. If the requested attachment would violate these rules than APIERR_BADPARS error code will be returned. Use ACAPI_Markup_GetAttachedElements function to return the already attached elements of the Mark-Up entry and ACAPI_Markup_DetachElements function to detach previously added elements.

Example

Mark-Up related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_Create()

GSErrCode __ACENV_CALL ACAPI_Markup_Create

(

API_MarkUpType &

markUp

)

Creates new Mark-Up entry.

Parameters

markUp

[in/out] The parameters of the new Mark-Up. The GUID and time stamp typed fields will be filled by this function.

Returns

• NoError - The function has completed with success.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.

Remarks

Using this function a new Mark-Up entry can be created. Use ACAPI_Markup_Change function to change and ACAPI_Markup_Delete function to delete an existing Mark-Up entry. Elements can be attached to the Mark-Up using ACAPI_Markup_AttachElements and comment can be added with ACAPI_Markup_AddComment function.

Example

bool hasRight = false;
ACAPI_Environment (APIEnv_GetTWAccessRightID, (void*) APIMarkupEntryCreate, &hasRight);
if (!hasRight)
    return APIERR_NOACCESSRIGHT;
 
API_MarkUpType markUp (/*name:*/ "- Test MarkUp -");
markUp.tagText = "MarkUp API";
 
GSErrCode err = ACAPI_Markup_Create (markUp);

ACAPI_Markup_Delete()

GSErrCode __ACENV_CALL ACAPI_Markup_Delete	(	const API_Guid &	markUpGuid,
		bool	acceptAllElements = false
	)

Deletes an existing Issue.

Since

Archicad 25

Parameters

markUpGuid	[in] GUID of an existing Issue.
acceptAllElements	[in] Accept all entry suggestions before the delete operation.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no opened project.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - Issue not found with the given guid.
• APIERR_NOACCESSRIGHT - The current user doesn't have the right to delete the Issue in the teamwork project.
• APIERR_BADPARS - Failed to accept all entry suggestions.

Remarks

Use this function to delete an existing Issue. If the Issue has any attached suggestion element, then depending on the value of the acceptAllElements parameter, the suggestion elements will be deleted or kept after the deletion of the owner Issue. Use ACAPI_Markup_Create function to create and ACAPI_Markup_Delete function to delete an Issue. Use ACAPI_Markup_GetAttachedElements function to return the attached elements of the Issue.

Example

Issue related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_DetachElements()

GSErrCode __ACENV_CALL ACAPI_Markup_DetachElements	(	const API_Guid &	markUpGuid,
		const GS::Array< API_Guid > &	elemList
	)

Detach elements from an existing Mark-Up.

Parameters

markUpGuid	[in] GUID of the existing Mark-Up.
elemList	[in] The list of elements to detach.

Returns

• NoError - The function has completed with success.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADPARS - The passed markUpGuid parameter or at least one of the given element GUIDs was incorrect.

Remarks

Using this function (corrected or highlighted) elements can be detached from an existing Mark-Up entry. Use ACAPI_Markup_GetAttachedElements function to return the already attached elements of the Mark-Up entry and ACAPI_Markup_AttachElements function to attach elements.

Example

Mark-Up related code samples can be found in the
MarkUp_Manager
 
example add-on.

ACAPI_Markup_ExportToBCF()

GSErrCode __ACENV_CALL ACAPI_Markup_ExportToBCF	(	const IO::Location &	fileLoc,
		const GS::Array< API_Guid > &	markupEntryIds,
		const bool	useExternalId = false,
		const bool	alignBySurveyPoint = true
	)

Exports a BCF file to specified location.

Since

Archicad 25

Parameters

fileLoc	[in] The location of the BCF file.
markupEntryIds	[in] An Array containing the MarkUp Entry identifiers to export.
useExternalId	[in] Use external IFC ID or Archicad IFC ID as referenced in BCF topics.
alignBySurveyPoint	[in] Align BCF views by Archicad Survey Point or Archicad Project Origin.

Returns

• NoError - The function has completed with success.

Remarks

Use this function to export BCF files. For deatails about External IFC ID and Archicad IFC ID see: ACAPI_Element_GetIFCIdentifier.

Example

GSErrCode DoBCFExport ()
{
    GS::Array<API_MarkUpType> markUps;
    GS::Array<API_Guid> markupEntryIds;
 
    GSErrCode err = ACAPI_Markup_GetList (APINULLGuid, &markUps);
 
    for (const auto& markUp : markUps)
        markupEntryIds.Push (markUp.guid);
 
    if (err == NoError) {
        DG::FileDialog exporteDLG (DG::FileDialog::Type::OpenFile);
        if (exporteDLG.Invoke ())
            err = ACAPI_Markup_ExportToBCF (exporteDLG.GetSelectedFile (), markupEntryIds, false, true);
    }
 
    if (err != NoError)
        ErrorBeep ("ACAPI_Markup_ExportToBCF failed", err);
 
    return err;
}

ACAPI_Markup_GetAttachedElements()

GSErrCode __ACENV_CALL ACAPI_Markup_GetAttachedElements	(	const API_Guid &	markUpGuid,
		API_MarkUpComponentTypeID	type,
		GS::Array< API_Guid > &	attachedElements
	)

Returns the corrected and highlighted elements of the given Mark-Up.

Since

Archicad 26

Parameters

markUpGuid	[in] GUID of the existing Mark-Up.
type	[in] Return the attached elements with the given Component type.
attachedElements	[out] The list of the attachedElements elements of the Mark-Up.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed markUpGuid parameter was incorrect.

Remarks

Using this function the corrected and highlighted elements of an existing Mark-Up entry can be listed. ACAPI_Markup_GetList returns the list of the existing Mark-Ups. Use ACAPI_Markup_AttachElements function to attach and ACAPI_Markup_AttachElements function to detach elements.

Example

Mark-Up related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_GetComments()

GSErrCode __ACENV_CALL ACAPI_Markup_GetComments	(	const API_Guid &	markUpGuid,
		GS::Array< API_MarkUpCommentType > *	commentList
	)

Returns the comments attached to the given Mark-Up entry.

Parameters

markUpGuid	[in] GUID of the existing Mark-Up.
commentList	[out] The list of the comments.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed markUpGuid parameter was incorrect or the passed commentList is nullptr.

Remarks

Using this function the comments attached to an existing Mark-Up entry can be listed. Use ACAPI_Markup_GetList function to return the list of all Mark-Up entries and ACAPI_Markup_AddComment function to add new comment to the Mark-Up.

Example

Mark-Up related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_GetList()

GSErrCode __ACENV_CALL ACAPI_Markup_GetList	(	const API_Guid &	elemGuid,
		GS::Array< API_MarkUpType > *	markUpList,
		bool *	asCorrected = nullptr
	)

Returns the existing Mark-Up entries which the given element is attached to.

Parameters

elemGuid	[in] The GUID of the element or APINULLGuid to list all Mark-Ups.
markUpList	[out] The list of Mark-Up(s).
asCorrected	[out] Returns whether the given element is a corrected or highlighted element in the listed Mark-Up(s).

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed elemGuid parameter was invalid or the passed markUpList is nullptr.

Remarks

Use this function to list which Mark-Ups is the given element attached to. To list all the existing Mark-Ups pass APINULLGuid to the elemGuid parameter. Use ACAPI_Markup_Create function to create and ACAPI_Markup_Delete function to delete Mark-Up entries. Note that an element can be attached to only one Mark-Up as corrected, but it can be attached to more Mark-Ups as highlighted and cannot be corrected and highlighted simultaneously. So if true was returned in asCorrected output parameter, then the size of the retuned markUpList array must be 1.

Example

Mark-Up related code samples can be found in the MarkUp_Manager
 
example add-on.

ACAPI_Markup_ImportFromBCF()

GSErrCode __ACENV_CALL ACAPI_Markup_ImportFromBCF	(	const IO::Location &	fileLoc,
		const bool	silentMode,
		APIIFCRelationshipDataProc *	ifcRelationshipDataProc,
		const void *	par1,
		const bool	openMarkUpPalette = false,
		const bool	alignBySurveyPoint = true
	)

Imports a BCF file.

Since

Archicad 25

Parameters

fileLoc	[in] The location of the BCF file.
silentMode	[in] Execute the import in silent mode, if its value is true then there will be no error or warning dialogs.
ifcRelationshipDataProc	[in] Optional user defined callback function which will supply API_IFCRelationshipData needed by BCF import when topics refers to element components like IFCBuildingElementParts. For more details see APIIFCRelationshipDataProc.
par1	[in] Optional parameter what will be passed for ifcRelationshipDataProc callback function.
openMarkUpPalette	[in] Open MarkUp Palette after import or not.
alignBySurveyPoint	[in] Align BCF views by Archicad Survey Point or Archicad Project Origin.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed fileLoc is not a valid BCF file.

Remarks

Use this function to import a BCF file. This api command is already part of an Undoable session and should not be called inside of ACAPI_CallUndoableCommand. Example For detailed examples, please see the MarkUp_Manager add-on.

Example

GSErrCode GetIFCRelationshipData (GS::HashTable* apiIfcRelationshipDataTable, const void* par1) {...}
 
const CustomData* GetCustomData () {...}
        
GSErrCode DoBCFImport ()
{
    GSErrCode err = NoError;
 
    const CustomData* data = GetCustomData ();
    
    DG::FileDialog openFileDLG (DG::FileDialog::Type::OpenFile);
    if (openFileDLG.Invoke ())
        err = ACAPI_Markup_ImportFromBCF (openFileDLG.GetSelectedFile (), true, &GetIFCRelationshipData , data);
        
    return err;
}