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