## Preferences

Object Hierarchy | Related C++ Class: Preferences

### Inheritance

###

SIObject

Preferences

### Introduced

v4.0

### Description

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.

### Methods

Export | GetPreferenceValue | Import | IsClassOf
IsEqualTo | RestoreDefault | SaveChanges | SetPreferenceValue

### Properties

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

### Examples

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

    app.LogMessage(oPrefs.Categories("scripting").Language.Value)

    # 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

    oPrefs.RestoreDefault("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.Preferences.SetPreferenceValue(

    	"Interaction.autoinspect",

    	!app.Preferences.GetPreferenceValue("Interaction.autoinspect")

    );

    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

    Next

    Next

    ' 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