Project Settings

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	ACAPI_ProjectSetting_GetOffset (API_Coord *offset)
	Returns the offset of origin of the virtual coordinate system.
GSErrCode	ACAPI_ProjectSetting_GetLast3DDefLevels (const GS::Array< API_ElemType > &elemTypes, GS::Array< double > &levels)
	Retrieves the 3D default levels for the construction elems.
GSErrCode	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	ACAPI_ProjectSetting_GetProjectNotes (API_ProjectNoteInfo *projectNoteInfo)
	Returns information about the 'Project Info' dialog.
GSErrCode	ACAPI_ProjectSetting_ChangeProjectNotes (API_ProjectNoteInfo *projectNoteInfo)
	Changes the data of the 'Project Info' dialog.
GSErrCode	ACAPI_ProjectSetting_GetStorySettings (API_StoryInfo *storyInfo, UInt32 mask=0)
	Returns the data of the installed stories.
GSErrCode	ACAPI_ProjectSetting_ChangeStorySettings (API_StoryCmdType *storyCmd)
	Modifies the story structure.
GSErrCode	ACAPI_ProjectSetting_GetPreferences (void *prefs, API_PrefsTypeID prefsTypeID)
	Returns the preferences data.
GSErrCode	ACAPI_ProjectSetting_SetPreferences (void *prefs, API_PrefsTypeID prefsTypeID)
	Adjusts the preferences.
GSErrCode	ACAPI_ProjectSetting_GetExportTolerance (double *arcDiff)
	Returns information on curve tracing parameters.
GSErrCode	ACAPI_ProjectSettings_GetSpecFolder (API_SpecFolderID *specFolderID, IO::Location *location)
	Returns the location of special folders.
GSErrCode	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 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 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 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 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 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 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 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);

ACAPI_ProjectSetting_GetSplineMaxDist()

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