Functions for managing project settings, such as Grid, Project Notes, tolerances, etc. More...

Classes
struct	API_GridType
	The grid parameters. More...

struct	API_ProjectNoteInfo
	Project note information parameters. More...

struct	API_WorkingUnitPrefs
	The representation of the Preferences / Units tab page. More...

struct	API_DimensionPrefs
	The representation of the Project Preferences / Dimensions tab page. More...

struct	API_CalcLengthFormat
	The API_CalcUnitPrefs structure contains this structure. More...

struct	API_CalcAreaFormat
	The API_CalcUnitPrefs structure contains this structure. More...

struct	API_CalcVolumeFormat
	The API_CalcUnitPrefs structure contains this structure. More...

struct	API_CalcAngleFormat
	The API_CalcUnitPrefs structure contains this structure. More...

struct	API_CalcUnitPrefs
	The representation of the Project Preferences / Calculation Units Rules tab page. More...

struct	API_ConditionalElementRule
	The representation of a conditional element rule on the Preferences / Calculation Rules tab page. More...

struct	API_CalcRulesPrefs
	The representation of the Calculation Rules on the Preferences / Calculation Units Rules tab page. More...

struct	API_LegacyPrefs
	The representation of the Preferences / Legacy tab page. More...

struct	API_ZonePrefs
	The representation of the Preferences / Zones tab page. More...

struct	API_SafetyPrefs
	The representation of the Preferences / Miscellaneous tab page. More...

struct	API_RefLevelsPrefs
	The representation of the Reference Levels on the Preferences / Working Units Levels tab page. More...

struct	API_ImagingAndCalcPrefs
	The representation of the Imaging and Calculation tab page of the Work Environment dialog. More...

struct	API_FloorPlanCutDefinition
	Parameters of the Floor Plan Cut Plane Settings dialog. More...

struct	API_LayoutsPrefs
	The representation of the Layouts page of the Project Preferences. More...

struct	API_SunInfo
	Parameters of the sunlight. More...

struct	API_TestSplineFit
	Contains parameters to calculate the maximal distance of a spline segment and a set of coordinates. More...

Enumerations
enum class	API_VolumeTypeID { CubicMeter , CubicKiloMeter , Liter , CubicCentimeter , CubicMillimeter , CubicFoot , CubicInch , CubicYard , Gallon }
	Possible values for volume unit preferences.

enum	API_ConditionalElementPropertyTypeID { APIConditionalElementPropertyType_Volume , APIConditionalElementPropertyType_Surface , APIConditionalElementPropertyType_Length }
	Property type of an element used in conditional calculation element rules. More...

enum	API_PrefsTypeID { APIPrefs_WorkingUnitsID , APIPrefs_ReferenceLevelsID , APIPrefs_DimensionsID , APIPrefs_CalcUnitsID , APIPrefs_CalcRulesID , APIPrefs_LegacyID , APIPrefs_ZonesID , APIPrefs_DataSafetyID , APIPrefs_ImagingAndCalcID , APIPrefs_FloorPlanCutPlaneDef , APIPrefs_LayoutsID }
	The enumeration of the available preferences tab page types. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetOffset (API_Coord *offset)
	Returns the offset of origin of the virtual coordinate system.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetLast3DDefLevels (const GS::Array< API_ElemType > &elemTypes, GS::Array< double > &levels)
	Retrieves the 3D default levels for the construction elems.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_SetLast3DDefLevels (const GS::Array< API_ElemType > &elemTypes, const GS::Array< double > &levels)
	Sets the 3D default levels for the passed construction element types.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetProjectNotes (API_ProjectNoteInfo *projectNoteInfo)
	Returns information about the 'Project Info' dialog.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_ChangeProjectNotes (API_ProjectNoteInfo *projectNoteInfo)
	Changes the data of the 'Project Info' dialog.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetStorySettings (API_StoryInfo *storyInfo, UInt32 mask=0)
	Returns the data of the installed stories.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_ChangeStorySettings (API_StoryCmdType *storyCmd)
	Modifies the story structure.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetPreferences (void *prefs, API_PrefsTypeID prefsTypeID)
	Returns the preferences data.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_SetPreferences (void *prefs, API_PrefsTypeID prefsTypeID)
	Adjusts the preferences.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetExportTolerance (double *arcDiff)
	Returns information on curve tracing parameters.

GSErrCode __ACENV_CALL	ACAPI_ProjectSettings_GetSpecFolder (API_SpecFolderID specFolderID, IO::Location location)
	Returns the location of special folders.

GSErrCode __ACENV_CALL	ACAPI_ProjectSetting_GetSplineMaxDist (API_TestSplineFit splinePars, double distance)
	Returns the maximal distance of a spline segment and a set of coordinates.

Detailed Description

Functions for managing project settings, such as Grid, Project Notes, tolerances, etc.

Enumeration Type Documentation

◆ API_ConditionalElementPropertyTypeID

enum API_ConditionalElementPropertyTypeID

Property type of an element used in conditional calculation element rules.

Since: Archicad 25

◆ API_PrefsTypeID

enum API_PrefsTypeID

The enumeration of the available preferences tab page types.

Remarks: Use this enum as a selector to the ACAPI_ProjectSetting_GetPreferences function to get data of the different tab pages of the Preferences and the Work Environment dialog.

Function Documentation

◆ ACAPI_ProjectSetting_ChangeProjectNotes()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_ChangeProjectNotes ( API_ProjectNoteInfo * projectNoteInfo )

Changes the data of the 'Project Info' dialog.

Parameters

projectNoteInfo [in] project note data

Returns

NoError - The function has completed with success.
APIERR_BADPARS - noteInfo is nullptr
APIERR_NOPLAN - There are no project loaded.

Remarks: This function is used to change the project info parameters. It can be set in the 'Project Info...' dialog box in the File/Info menu. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example: See the example of the APIEnv_GetProjectNotesID

function.

◆ ACAPI_ProjectSetting_ChangeStorySettings()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_ChangeStorySettings ( API_StoryCmdType * storyCmd )

Modifies the story structure.

Parameters

storyCmd [in] Action parameters to change the story settings.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - storyCommand is nullptr or contains invalid value:

the index is out of the range of existing stories,
the action field is invalid.
- APIERR_NOPLAN - No open project.
- APIERR_MEMFULL - Low memory condition.
  Remarks
  This function is used to perform story settings related commands. The command is specified by the action field of the storyCommand parameter. Possible values and the required parametrization are described at the API_StoryCmdID structure. If this function is called with APIStory_Delete parameter, it performs complete operations. Otherwise this function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

◆ ACAPI_ProjectSetting_GetExportTolerance()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetExportTolerance ( double * arcDiff )

Returns information on curve tracing parameters.

Parameters

arcDiff [out] Distance between arc and line when segmenting the arc.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - arcDiff is nullptr.
APIERR_NOTSUPPORTED - Not at export.

Remarks: Return the arc differecnes at export.

Example: double arcDiff;

GSErrCode err;

err = ACAPI_Environment (GetExportToleranceID, &arcDiff, nullptr);

◆ ACAPI_ProjectSetting_GetLast3DDefLevels()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetLast3DDefLevels	(	const GS::Array< API_ElemType > &	elemTypes,
		GS::Array< double > &	levels
	)

Retrieves the 3D default levels for the construction elems.

Since: Archicad 26

Parameters

elemTypes	[in] The elem types for which you want to obtain the 3D default levels.
levels	[out] The 3D default levels for the elem types given in the elemIDs array.

Returns

NoError - The function has completed with success.

Remarks: Retrieves the 3D default levels for the types passed in the elemIDs array. Possible elem types: Wall, Column, Beam, Symbol, Light, Slab, Roof, Mesh.

◆ ACAPI_ProjectSetting_GetOffset()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetOffset ( API_Coord * offset )

Returns the offset of origin of the virtual coordinate system.

Parameters

offset the offset of the origin of the virtual coordinate system

Returns

NoError - The function has completed with success.
APIERR_BADPARS - offset is nullptr
APIERR_BADDATABASE - the command was called for a non-2D window

Remarks: This function is used to get the offset of the origin of the virtual coordinate system from the origin of the world coordinate system. This origin was introduced in Archicad 9 to reduce the inaccuracies, which could happen if the model was far away from the origin of the world coordinate system. This offset is set after a file is opened, if the so called 'weight point' of the model is far enough from the origin of the world coordinate system. After that all coordinates coming from the API are measured from this origin.

◆ ACAPI_ProjectSetting_GetPreferences()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetPreferences	(	void *	prefs,
		API_PrefsTypeID	prefsTypeID
	)

Returns the preferences data.

Parameters

prefs	[out] Data of a preferences tab page. The content depends on the prefsType parameter.
prefsTypeID	[in] The type of the preferences you want to get.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - prefs is nullptr
APIERR_BADID - prefsTypeID is invalid.
APIERR_NOPLAN - No open project.
APIERR_MEMFULL - Low memory condition.

Remarks: Many switches and values are returned which appear on the different tab pages of the Project Preferences dialog and the Work Environment settings. Usable structures of preference types (for prefs) are: API_WorkingUnitPrefs API_RefLevelsPrefs API_DimensionPrefs API_CalcUnitPrefs API_CalcRulesPrefs API_LegacyPrefs API_ZonePrefs API_SafetyPrefs API_ImagingAndCalcPrefs API_FloorPlanCutDefinition API_LayoutsPrefs Note: prefsTypeID should be passed as a value instead of a pointer. See the example codes for details.

◆ ACAPI_ProjectSetting_GetProjectNotes()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetProjectNotes ( API_ProjectNoteInfo * projectNoteInfo )

Returns information about the 'Project Info' dialog.

Parameters

projectNoteInfo [out] project note data

Returns

NoError - The function has completed with success.
APIERR_BADPARS - projectNoteInfo is nullptr
APIERR_NOPLAN - There are no project loaded.

Remarks: This function is used to get the project info parameters. It can be set in the 'Project Info...' dialog box in the File/Info menu.

Example: API_ProjectNoteInfo noteInfo;

ACAPI_Environment (APIEnv_GetProjectNotesID, &noteInfo, nullptr);

CHCopyC ("John Miller", noteInfo.client);

ACAPI_Environment (APIEnv_ChangeProjectNotesID, &noteInfo, nullptr);

API_ProjectNoteInfo
Project note information parameters.
Definition: APIdefs_Environment.h:493

API_ProjectNoteInfo::client
char client[256]
The name of the client.
Definition: APIdefs_Environment.h:497

◆ ACAPI_ProjectSetting_GetSplineMaxDist()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetSplineMaxDist	(	API_TestSplineFit *	splinePars,
		double *	distance
	)

Returns the maximal distance of a spline segment and a set of coordinates.

Parameters

splinePars	[in] the coordinates and the parameters of the spline to test.
distance	[out] the maximal distance of the coordinates from the requested segment of the spline.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - any of the parameters are nullptr, or the passed handles have wrong sizes.

Remarks: This function is used to determine the maximal distance of a segment of a bezier curve and a set of coordinates. Refer to the API_TestSplineFit structure for the parametrization.

◆ ACAPI_ProjectSetting_GetStorySettings()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_GetStorySettings	(	API_StoryInfo *	storyInfo,
		UInt32	mask = `0`
	)

Returns the data of the installed stories.

Parameters

storyInfo	[out] parameters of the actual stories.
mask	Can be `APIElemMask_FromFloorplan` or nullptr.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - storyInfo is nullptr.
APIERR_NOPLAN - No open project.
APIERR_MEMFULL - Low memory condition.

Remarks: The API_StoryInfo structure contains an array of information to each story (index, level, and name); and also the active one. Do not forget to dispose the data handle if it is not needed any more.

◆ ACAPI_ProjectSetting_SetLast3DDefLevels()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_SetLast3DDefLevels	(	const GS::Array< API_ElemType > &	elemTypes,
		const GS::Array< double > &	levels
	)

Sets the 3D default levels for the passed construction element types.

Since: Archicad 26

Parameters

elemTypes	[in] Elem types for which you want to set the 3D default levels.
levels	[in] The default 3D level values.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The size of elemTypes differes from the size of levels.

Remarks: Sets the 3D default levels for the given elemtypes. Possible elemtypes: Wall, Column, Beam, Symbol, Light, Slab, Roof, Mesh.

◆ ACAPI_ProjectSetting_SetPreferences()

GSErrCode __ACENV_CALL ACAPI_ProjectSetting_SetPreferences	(	void *	prefs,
		API_PrefsTypeID	prefsTypeID
	)

Adjusts the preferences.

Parameters

prefs	[in] Data of a preferences tab page. The content depends on the prefsType parameter.
prefsTypeID	[in] The type of the preferences you want to set.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - prefs is nullptr, or calculation rules are invalid, or the given dimensioning standard index is invalid.
APIERR_BADID - prefsTypeID is invalid (for example, you cannot set Data Safety preferences)
APIERR_NOPLAN - No open project.
APIERR_GENERAL - No dimensioning standards in the project.

Remarks: Many switches and values (except Data Safety) can be set that appear on the different tab pages of the Project Preferences dialog and the Work Environment settings. Usable structures of preference types (for prefs) are: API_WorkingUnitPrefs API_RefLevelsPrefs API_DimensionPrefs API_CalcUnitPrefs API_CalcRulesPrefs API_LegacyPrefs API_ZonePrefs API_SafetyPrefs API_ImagingAndCalcPrefs API_FloorPlanCutDefinition API_LayoutsPrefs Note: prefsType should be passed as a value instead of a pointer. See the example. This is an undoable operation, so be careful!

◆ ACAPI_ProjectSettings_GetSpecFolder()

GSErrCode __ACENV_CALL ACAPI_ProjectSettings_GetSpecFolder	(	API_SpecFolderID *	specFolderID,
		IO::Location *	location
	)

Returns the location of special folders.

Parameters

specFolderID	[in] A pointer to the type of the folder you are interested in.
location	[out] The file system location of the required folder.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - specFolderID contains invalid data, or the location parameter is nullptr
APIERR_REFUSEDPAR - The requested special folder is not initialized or missing

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ API_ConditionalElementPropertyTypeID

◆ API_PrefsTypeID

Function Documentation

◆ ACAPI_ProjectSetting_ChangeProjectNotes()

◆ ACAPI_ProjectSetting_ChangeStorySettings()

◆ ACAPI_ProjectSetting_GetExportTolerance()

◆ ACAPI_ProjectSetting_GetLast3DDefLevels()

◆ ACAPI_ProjectSetting_GetOffset()

◆ ACAPI_ProjectSetting_GetPreferences()

◆ ACAPI_ProjectSetting_GetProjectNotes()

◆ ACAPI_ProjectSetting_GetSplineMaxDist()

◆ ACAPI_ProjectSetting_GetStorySettings()

◆ ACAPI_ProjectSetting_SetLast3DDefLevels()

◆ ACAPI_ProjectSetting_SetPreferences()

◆ ACAPI_ProjectSettings_GetSpecFolder()