Add-On Preferences

Functions for creating, handling and deleting custom (Add-On specific) preferences, which get stored in the project file. Useful for storing Work Environment settings or some inner states of the Add-On which can be read at the next opening of the project. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_SetPreferences (Int32 version, GSSize nByte, const void *data)
	Saves custom preferences data into the preferences file.
GSErrCode __ACENV_CALL	ACAPI_GetPreferences (Int32 *version, GSSize *nByte, void *data)
	Returns the stored preferences of the add-on.
GSErrCode __ACENV_CALL	ACAPI_Preferences_Platform (Int32 *version, GSSize *nByte, void *data, unsigned short *platformSign)
	Returns the stored preferences of the add-on.
GSErrCode __ACENV_CALL	ACAPI_Preferences_OldVersion (Int32 version, GSSize nByte, const void *data, unsigned short platformSign, API_FTypeID oldPlanFileID)
	Defines custom preferences data to be saved into older project file versions.

Detailed Description

Functions for creating, handling and deleting custom (Add-On specific) preferences, which get stored in the project file. Useful for storing Work Environment settings or some inner states of the Add-On which can be read at the next opening of the project.

Saving Add-On data into the Preferences and the Project File

This paper give hints on how to save own data into the preferences and the actual project file.

Possibilities

You are allowed to save an unlimited number of bytes into the preferences file. The preferences data is also stored in in all project files.

Preferences data saved into a project makes it possible to open a saved project file with the same working environment. It is also used to open dialog boxes with the same settings as they had when they were closed, even if you do not quit the application.

If your add-on uses settings which should be preserved, please use this feature.

You can save your data into the preferences file using the ACAPI_SetPreferences function and retrieve the stored preferences with ACAPI_GetPreferences.

When the server application starts with a new plan, the preferences data of the add-on is available previously saved into the preferences file of the application. If you open a plan file which has preferences data stored into it by your add-on, this data overwrites the current preferences of the add-on, that is, the add-on preferences can be changed after opening a project. Remember this if you need to maintain preferences data consistency in your add-on.

If your add-on has different versions of preferences data in different program releases, it is recommended to set the preferences of the older formats as well in order to ensure backward compatibility. Use the ACAPI_Preferences_OldVersion function (Archicad only) to define your data to be saved into the specified (and earlier) plan versions instead of saving the current preferences version.

It is also important to handle platform specific data if the preferences can come from a plan file saved on the other platform. Use the ACAPI_Preferences_Platform function instead of ACAPI_GetPreferences to retrieve the platform information too. If the platform identifier of the stored preferences does not match the actual platform, convert the data to the appropriate format.

Notes

Please study the source code of the DG Test example to see the suggested way of handling the preferences data.

Function Documentation

ACAPI_GetPreferences()

GSErrCode __ACENV_CALL ACAPI_GetPreferences	(	Int32 *	version,
		GSSize *	nByte,
		void *	data
	)

Returns the stored preferences of the add-on.

Parameters

version	[out] On return contains the version of the stored preferences, or 0 if no preferences were found.
nByte	[out] On return contains the size of the stored preferences in bytes, or 0 if no preferences were found.
data	[in/out] On return contains the stored preferences. This parameter can be nullptr.

Returns

• NoError - For common API errors see the API Errors document.

Remarks

1. You can retrieve the stored preferences of your add-on. This information was previously passed onto the add-on as a parameter of the DoCommand function.
2. Setting the last parameter to nullptr means the API will return only the version number and the size of the preferences data. If the size or the version number is 0, then no preferences were stored.
3. Version information can be used to convert older preferences to the current format. In Archicad use ACAPI_Preferences_Platform instead of ACAPI_GetPreferences in order to get the platform identifier of the preferences data.

Example

    Int32       version;
    GSSize      nBytes;
    GSPtr       pref;
 
    ACAPI_GetPreferences (&version, &nBytes, nullptr);             // (2) get version and size
    if (version == MY_PREFERENCES_VERSION) {                    // (3) check version
        pref = BMAllocatePtr (nBytes, ALLOCATE_CLEAR, 0);       // allocate memory for preferences
        if (pref != nullptr) {
            ACAPI_GetPreferences (&version, &nBytes, pref);     // get actual preferences
            // do something with the preferences data
 
            BMKillPtr (&pref);                                  // dispose allocated pointer
        }
    }

ACAPI_Preferences_OldVersion()

GSErrCode __ACENV_CALL ACAPI_Preferences_OldVersion	(	Int32	version,
		GSSize	nByte,
		const void *	data,
		unsigned short	platformSign,
		API_FTypeID	oldPlanFileID
	)

Defines custom preferences data to be saved into older project file versions.

Parameters

version	[in] The version of the data to be stored.
nByte	[in] The size of the data to be stored.
data	[in] The preferences data you would like to store for the specified plan version.
platformSign	[in] The platform identifier of the data (GS::Win_Platform_Sign, GS::Mac_Platform_Sign, GS::Mactel_Platform_Sign
oldPlanFileID	[in] The plan file format associated with the preferences data when saving the project into this plan version. The value of this parameter can be:

Returns

• NoError - For common API errors see the API Errors document.

Remarks

This function is used to save your own options or preferences into the preferences file of the server application or into the project file to be saved. This information can be later retrieved with ACAPI_GetPreferences and ACAPI_Preferences_Platform. You can define different preferences to be saved into different plan file formats. Use this function if your add-on had incompatible preferences format in the previous versions of Archicad. Store the data in that format too indicating which plan version should use it. When the user chooses to save the plan into an older plan format, the appropriate preferences data will be stored. For more details see the Saving Add-On data into the Preferences and the Project File section.

Example

const Int32 ActVersion = 3;
const Int32 Version_in_AC8 = 2;
const Int32 Version_in_AC7 = 1;
 
struct MyPrefs          prefsData;
struct MyPrefs_in_AC8   dataForAC8;
struct MyPrefs_in_AC7   dataForAC7;
// construct the preferences data...
 
// store the actual preferences
ACAPI_SetPreferences (ActVersion, sizeof (MyPrefs), &prefsData);
 
// specify preferences to be saved into older plan file versions
ACAPI_Preferences_OldVersion (Version_in_AC8, sizeof (MyPrefs_in_AC8), &dataForAC8, GS::Act_Platform_Sign, APIFType_PlanFile800);
ACAPI_Preferences_OldVersion (Version_in_AC7, sizeof (MyPrefs_in_AC7), &dataForAC7, GS::Act_Platform_Sign, APIFType_PlanFile700);

ACAPI_Preferences_Platform()

GSErrCode __ACENV_CALL ACAPI_Preferences_Platform	(	Int32 *	version,
		GSSize *	nByte,
		void *	data,
		unsigned short *	platformSign
	)

Returns the stored preferences of the add-on.

Parameters

version	[out] On return contains the version of the stored preferences, or 0 if no preferences were found.
nByte	[out] On return contains the size of the stored preferences in bytes, or 0 if no preferences were found.
data	[in/out] On return contains the stored preferences.
platformSign	[out] On return contains the platform identifier of the stored preferences.

Returns

• NoError - For common API errors see the API Errors document.

Remarks

Use this function to retrieve the preferences data stored into the preferences or the plan file currently opened. The preferences could have been saved into the plan on the other platform; in this case it is your responsibility to convert data structures stored in opposite byte order. All the parameters can be nullptr. The data pointer should be allocated and disposed by the add-on, thus first you should call this function to retrieve only the version number and the size of the preferences data.

Example

Int32           version = 0;
GSSize          nBytes = 0;
GSPtr           pref;
unsigned short  platformSign = GS::Act_Platform_Sign;
 
ACAPI_Preferences_Platform (&version, &nBytes, nullptr, nullptr);      // get version and size
if (version == MY_PREFERENCES_VERSION) {                            // check version
    pref = BMAllocatePtr (nBytes, ALLOCATE_CLEAR, 0);               // allocate memory for preferences
    if (pref != nullptr) {
        ACAPI_Preferences_Platform (&version, &nBytes, pref, &platformSign);     // get actual preferences
        if (platformSign != GS::Act_Platform_Sign) {
            // swap the necessary bytes
        }
 
        // do something with the preferences data
        BMKillPtr (&pref);                                          // dispose the allocated pointer
    }
}

ACAPI_SetPreferences()

GSErrCode __ACENV_CALL ACAPI_SetPreferences	(	Int32	version,
		GSSize	nByte,
		const void *	data
	)

Saves custom preferences data into the preferences file.

Parameters

version	[in] The version of the data to be stored.
nByte	[in] The size of the data to be stored.
data	[in] The preferences data you would like to store.

Returns

Remarks

This function is used to save your own options or preferences into the preferences file of the server application, and can be later retrieved with ACAPI_GetPreferences. If you store incompatible versions of preferences data in different Archicad releases, use the ACAPI_Preferences_OldVersion function to define preferences to be saved into the older project file formats.