Object Hierarchy | Related C++ Class: Preferences







The Preferences object can be used to manage preferences in Softimage. Each preference is in a category which is represented by a node under the Preferences object under the Application. To identify a preference the category must be specified: (category.preference) Ex: "scripting.language".

There are 2 kinds of preferences: native and custom. Native preferences come with Softimage and can be viewed with the File->Preferences dialog. Initially all preference values are set to the factory defaults. When the user changes the value of a preference the new value is stored in the default.xsipref file found in the \Data\Preference directory, and this value overrides the factory setting.

For custom preferences, you can create new preferences in an .xsipref file. However, preferences created this way have no UI and can only be accessed via scripting.

You can also create custom preferences by creating a CustomProperty object and calling InstallCustomPreferences. The only way to delete such a custom preference is to delete the associated Preset file that is found in the \Data\Preferences directory.

Note: Unlike native preferences, custom preferences created in this fashion are also loaded from the Workgroup location.

Only a subset of parameter types are supported for Custom Preferences, they are siInt4, siString, siBool and siDouble (see siVariantType).

Many custom plug-ins use a CustomProperty as a way of providing a user interface. For example, a plug-in that exports data may ask the user to choose the output file and other configuration settings by calling InspectObj with a CustomProperty. Installing such a CustomProperty as a custom preference can be useful because the values are not forgotten from one session to the next, the object does not clutter the current scene and the information is centralized in the Preferences section of the Scene Explorer. However, because of the limitations of supported parameter types it can often be more flexible to achieve the same thing by calling SavePreset and LoadPreset directly from within the plug-in.


Export GetPreferenceValue Import IsClassOf operator
IsEqualTo operator RestoreDefault SaveChanges SetPreferenceValue


Application Categories Categories FullName operator
Help Name operator NestedObjects Origin
OriginPath Parent Type operator  


1. Python Example

from win32com.client import constants as cns
app = Application
# Get the preferences object on the application
oPrefs = app.Preferences
# Show the current language
app.LogMessage(oPrefs.GetPreferenceValue ("scripting.language"))
# or
# Export all data_management preferences
oPrefs.Export( XSIUtils.BuildPath(app.InstallationPath(cns.siFactoryPath), "myDMprefs.xsipref"), "data_management")
# Now reset all preferences of the category data_management
# Expected results:
# INFO : Python
# INFO : Python

2. JScript Example

        This example demonstrates how to temporarily change the user's
        AutoInspect preference (if enabled, property pages always pop
        up for objects newly created via command). It also illustrates
        how Softimage automatically reverts any scripting change to this 
        preference after the script runs.
var app = Application;
// Current value of AutoInspect
app.LogMessage( app.Preferences.GetPreferenceValue("Interaction.autoinspect") );
// Toggle the orginal value and re-log the value
app.LogMessage( app.Preferences.GetPreferenceValue("Interaction.autoinspect") );
// If your AutoInspect preference was enabled originally, the History Log 
// would display the following:
// INFO : True
// INFO : False
// VERBOSE : Restoring preference changed by script: Interaction.autoinspect
// If your AutoInspect preference was disabled originally, the History Log 
// would display the following:
// INFO : False
// INFO : True
// VERBOSE : Restoring preference changed by script: Interaction.autoinspect

3. VBScript Example

' This example show how to navigate in preferences object
' All categories and all preferences in each category will be printed.
set oPrefs = Application.Preferences
set oCategories = oPrefs.categories
For each oCategory in oCategories
Application.LogMessage "The preferences for category " & oCategory & " are:"
set oPreferences = oCategory.Parameters
For each oPref in oPreferences
Application.LogMessage "   -" & oPref & " = " & oPref.Value
' The script logs information like the following:
' ....
' INFO : The preferences for category preferences.units are:
' INFO :    -preferences.units.colorspace = 1
' INFO :    -preferences.units.length = 2
' INFO :    -preferences.units.angle = 2
' INFO :    -preferences.units.time = 2
' INFO :    -preferences.units.mass = 2
' ....

See Also

XSIApplication.Preferences InstallCustomPreferences SetUserPref GetUserPref UserPreference Working with User Preferences Property Editor Automatic Inspection