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	ACAPI_SetPreferences (Int32 version, GSSize nByte, const void *data)
	Saves custom preferences data into the preferences file.
GSErrCode	ACAPI_GetPreferences (Int32 *version, GSSize *nByte, void *data)
	Returns the stored preferences of the add-on.
GSErrCode	ACAPI_Preferences_Platform (Int32 *version, GSSize *nByte, void *data, unsigned short *platformSign)
	Returns the stored preferences of the add-on.
GSErrCode	ACAPI_Preferences_SetOldVersion (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_SetOldVersion 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 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 zero if no preferences were found.
nByte	[out] On return, contains the size of the stored preferences in bytes, or zero if no preferences were found.
data	[in/out] the stored preferences are stored on return. This parameter can be nullptr.

Returns

• NoError - See the API Errors document for common API errors.

Remarks

1. You can retrieve the stored preferences of your add-on. This information was previously passed to 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. No preferences were stored if the size or the version number is 0.
3. Version information can convert older preferences to the current format. In Archicad, use ACAPI_Preferences_Platform instead of ACAPI_GetPreferences 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_Platform()

GSErrCode 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 zero if no preferences were found.
nByte	[out] On return, contains the size of the stored preferences in bytes, or zero if no preferences were found.
data	[in/out] contains the stored preferences on return.
platformSign	[out] On return, the platform identifier of the stored preferences is contained.

Returns

• NoError - See the API Errors document for common API errors.

Remarks

Use this function to retrieve the preferences data stored in the preferences or the plan file currently opened. The preferences could have been saved in the plan on the other platform; in this case, you are responsible for converting data structures stored in the opposite byte order. All the parameters can be nullptr. The add-on should allocate and dispose of the data pointer; 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_Preferences_SetOldVersion()

GSErrCode ACAPI_Preferences_SetOldVersion	(	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 data size to be stored.
data	[in] The preferences data you want 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 - See the API Errors document for common API errors.

Remarks

This function is used to save your options or preferences into the preferences file of the server application or 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 has an incompatible preferences format with 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_SetOldVersion (Version_in_AC8, sizeof (MyPrefs_in_AC8), &dataForAC8, GS::Act_Platform_Sign, APIFType_PlanFile800);
ACAPI_Preferences_SetOldVersion (Version_in_AC7, sizeof (MyPrefs_in_AC7), &dataForAC7, GS::Act_Platform_Sign, APIFType_PlanFile700);

ACAPI_SetPreferences()

GSErrCode 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 data size to be stored.
data	[in] The preferences data you want to store.

Returns

Remarks

This function saves your options or preferences into the server application's preferences file, which can be later retrieved with ACAPI_GetPreferences. If you store incompatible versions of preferences data in different Archicad releases, use the ACAPI_Preferences_SetOldVersion function to define preferences to be saved into the older project file formats.