Settings object¶
app.settings
Description
The Settings object provides an easy way to manage settings for third-party scripts. The settings are saved in the main After Effects preferences file, and are persistent between application sessions.
Settings are identified by section and key within the file, and each key name is associated with a value.
In the settings file, section names are enclosed in brackets and quotation marks, and key names are listing in quotation marks below the sectionname. All values are strings.
You can create new settings with this object, as well as accessing existing settings.
As of Version 12/CC, preferences and settings methods now take a third argument to specify the target preferences file if Section/Key is not in the main preferences file. See Preferences object for more info.
Note
These values aren’t shared between versions of AE; each new install brings new settings files, and so these prefs won’t carry over.
Internally, all saved settings have their section name preprended with
"Settings_"
If you’re looking to get or set internal AE preferences, see Preferences object
Tip
It’s best practice to use one
sectionName
per script; this keeps your settings organized and easy to find & work with.There isn’t really any benefit in saving your settings to a specific preferences file; omitting the third argument and using the default is likely all you’ll need.
Methods¶
Settings.getSetting()¶
app.settings.getSetting(sectionName, keyName[, prefType])
Description
Retrieves a script settings item value from the preferences file.
Warning
If the value is greater than 1999 bytes, getSetting
that item will throw an error (seen in AE 15.0.1)
Parameters
|
A string containing the name of a settings section. |
|
A string containing the key name of the setting item. |
|
Optional, an enum indicating which preference file to use. |
Returns
String.
Example
If you have saved a setting named with the key name “trimPrecomps” in a section called “Precomp Cropper”, you can retrieve the value by:
var trimPrecompsSetting = app.settings.getSetting("Precomp Cropper", "trimPrecomps");
alert("The setting is: " + trimPrecompsSetting);
Settings.haveSetting()¶
app.settings.haveSetting(sectionName, keyName[, prefType])
Description
Returns true if the specified script settings item exists and has a value.
Parameters
|
A string containing the name of a settings section. |
|
A string containing the key name of the setting item. |
|
Optional, an enum indicating which preference file to use. |
Returns
Boolean.
Settings.saveSetting()¶
app.settings.saveSetting(sectionName, keyName, value[, prefType])
Description
Saves a value for a script settings item.
Warning
If the value is greater than 1999 bytes, saveSetting
that item will throw an error (seen in AE 15.0.1)
Parameters
|
A string containing the name of a settings section. |
|
A string containing the key name of the setting item. |
|
A string containing the new value. |
|
Optional, an enum indicating which preference file to use. |
Returns
Nothing.
Example
If you want to save a setting called “trimPrecomps” for a script named “Precomp Cropper”, you could save that setting via
var trimPrecompsSetting = true;
app.settings.saveSetting("Precomp Cropper", "trimPrecomps", trimPrecompsSetting);
Note that the setting will be saved as a string. You’ll want to parse it into a bool later, if needed.