Custom Preferences (XSISDK)
Custom Preferences are a special usage of Custom Properties.
They have the advantage of:
- Persisting any value change automatically
- Not appearing as part of the Scene - the custom property appears in the Preference.
- Initial values can be set by setting preference values in the factory location.
To get an idea about how to use a Custom Preference in your tool check out the XSI_UserNormalEditing example in the SDK example workgroup (starting with XSI v5.0).
|Table of contents|
Limited Parameter Types
Custom Preferences only support a small subset of the different parameter types supported on a normal Custom Property. For example GridData, FCurves, and Floats are not supported. XSI will give an script error message if InstallCustomPreferences is called with a custom property that has unsupported parameters.
'ERROR : The Custom Property C:\users\askowron\Softimage\XSI_5.0\Data\Preferences\MyProperty.Preset cannot be installed as a Custom Preference 'because it contains unsupported parameter types. 'Currently the only supported types are siString,siDouble,siInt4 and siBool.
Most preference values are booleans (to toggle features on or off) so it is often possible to use this feature even with its limited set of supported parameter types.
Creating a Custom Preference
The best way to create a custom preference is to build a self-installed custom property. Make sure to only add siString, siDouble, siInt4 and siBool as the parameter types. It can be tested as a normal custom property, then installed as a custom preference when the tool is mostly complete.
There is a command named InstallCustomPreferences but normally you will NOT use this command to install your custom preference. Instead you should save a preset file for the preference in the ..\..\Data\Preferences directory relative to the Self-installed Custom Property.
For example if you custom property is at "c:\myworkgroup\Addons\CoolUITool\Application\Plugins\CoolUIToolConfigDialog.js" then you should save the preference at "c:\myworkgroup\Addons\CoolUITool\Data\Preferences\CoolUIToolConfigDialog.Preset"
XSI scans the \Data\Preferences directories at startup to find all custom preferences, so if the Preset file is located at the correct location it will automatically appear.
The problem with InstallCustomPreferences is that it saves the preset in the \Data\Preference directory under the user location. This is not desirable if the custom preference is associated with a tool that is part of an Addon, Workgroup or Workgroup Addon location.
At anytime XSI can be forced to rescan for Custom Prefences by calling RefreshCustomPreferences.
The following code demonstrates how to inspect a custom preference called "CustomPreferenceName". It uses RefreshCustomPreferences to ensure that the preference is installed.
set oProperty = Application.Preferences.Categories( "CustomPreferenceName" ) if TypeName( oProperty ) = "Nothing" then 'The .Preset file for the preference may not yet be loaded. Get XSI 'to rescan. This is necessary if the tool is part of a workgroup 'and XSI has not been restarted since first connecting to the workgroup RefreshCustomPreferences set oProperty = Application.Preferences.Categories( "CustomPreferenceName" ) end if if TypeName( oProperty ) = "Nothing" then 'If we get here then the custom preference is not working properly 'We revert to using a instance of the custom property, but this means that 'any changes will not be persisted ' Add custom property under the scene root set oProperty = ActiveSceneRoot.AddProperty( "CustomPreferenceName" ) end if Application.InspectObj oProperty,,, siLock
Updating a Custom Preference
As mentioned previously the Custom Preference feature relies on a .Preset file. If the custom property definition is changed in the self-installed plugin (new parameters added, parameters deleted, parameter ranges changed etc) then the .Preset file will get out of date. So it is necessary to recreate the preset file any time the Custom Property parameter definitions change.
To do this just add the property to the scene root, inspect it and then use the "Save" button on the Property Page to save a new .Preset.
As mentioned previously the best way to install the preference is to locate it in the \Data\Preference location relative to the plug-in containing the Custom Property. If this guideline is followed then:
- If the custom preference is on a workgroup then disconnecting from the workgroup will uninstall it.
- If the custom preference is part of an Addon then uninstalling the .xsiaddon or deleting the Addon subdirectory will uninstall it.
- If the custom preference is part of the user location then the Preset file must be deleted. This can be done manually or via scripting.
In all of these scenarios the Custom Preference will not disappear until RefreshCustomPreferences is called or XSI is restarted.