Settings Interface
The collection of Settings that supply the run-time configuration of a Workspace.
The Settings object comprises a collection of named SettingsDictionary objects.
Methods like getSetting, getString, and getArray provide access to the value of an individual Setting by searching
the dictionaries in order by their SettingsPriority to find the highest-priority setting with the requested SettingName.
Most methods that retrieve Setting values validate them against their SettingSchemas to ensure that they are of the correct type.
A SettingsDictionary can be added or removed using addDictionary and dropDictionary.
Because Settings can change at any time during the session, you should avoid caching their values wherever possible.
If you must cache them (for example, to display in a user interface), you should listen for the onSettingsChanged event to be
notified of potential changes.
Settings are accessed via settings. They are defined at the application level by appWorkspace, but individual iModels may supply
additional iModel-specific settings or overrides for application-level settings. When working in the context of a specific iModel, use workspace's settings
property. Any settings not overridden by the iModel will fall back to the settings defined in appWorkspace.
Application settings are loaded into appWorkspace when the session begins (i.e., when startup is invoked), and unloaded when it ends (in shutdown). They are read from JSON5 files delivered with the application. The application should register any additional SettingsDictionary's '(and their corresponding SettingGroupSchemas) at this time.
iModel-specific settings are stored in the iModel's property table and loaded into workspace when the iModel is first opened. You can add and remove a SettingsDictionary from the property table using saveSettingDictionary and deleteSettingDictionary.
See the learning article for a detailed overiew and examples.
@see appWorkspace application-wide settings, and workspace for settings specific to a given iModel.
Methods
| Name | Description | |
|---|---|---|
| addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void | Add a new SettingsDictionary with the priority, name, and WorkspaceDb specified by props and setting values supplied by settings. |
|
| addDirectory(directory: string, priority: number): void | Invokes addFile for all files in directory with the extension ".json" or ".json5". |
|
| addFile(fileName: string, priority: number): void | Parses the contents of a local JSON5 file as a SettingsContainer and invokes addDictionary to | |
| addJson(props: SettingsDictionaryProps, settingsJson: string): void | Parses settingsJson as a SettingsContainer and invokes addDictionary to add a SettingsDictionary with the specified props. |
|
| dropDictionary(props: SettingsDictionarySource): void | Removes a previously-added SettingsDictionary. | |
| getArray<T extends JSONSchemaType>(settingName: string): undefined | T[] | ||
| getArray<T extends JSONSchemaType>(settingName: string, defaultValue: T[]): T[] | Look up the value of an array Setting named settingName, returning defaultValue if no such value is defined. |
|
| getBoolean(settingName: string, defaultValue?: boolean): undefined | boolean | ||
| getBoolean(settingName: string, defaultValue: boolean): boolean | Look up the value of a boolean Setting named settingName, returning defaultValue if no such value is defined. |
|
| getDictionary(source: SettingsDictionarySource): undefined | SettingsDictionary | Find a SettingsDictionary with the same name and WorkspaceDb as source. |
|
| getNumber(settingName: string): undefined | number | ||
| getNumber(settingName: string, defaultValue: number): number | Look up the value of a numeric Setting named settingName, returning defaultValue if no such value is defined. |
|
| getObject<T extends object>(settingName: string): undefined | T | ||
| getObject<T extends object>(settingName: string, defaultValue: T): T | Look up the value of an object Setting named settingName, returning defaultValue if no such value is defined. |
|
| getSetting<T extends JSONSchemaType>(settingName: string, defaultValue?: T): undefined | T | Looks up the highest priority setting value for a SettingName, falling back to a default value if no value for the setting is found. | |
| getSettingEntries<T extends JSONSchemaType>(settingName: string): Iterable<{ dictionary: SettingsDictionary, value: T }, any, any> | Obtain an iterator over all of the values in the dictionaries for the Setting identified by settingName, ordered by SettingsPriority. |
|
| getSettingValues<T extends JSONSchemaType>(settingName: string): Iterable<T, any, any> | Obtain an iterator over all of the values in the dictionaries for the Setting identified by settingName, ordered by SettingsPriority. |
|
| getString(settingName: string, defaultValue?: string): undefined | string | ||
| getString(settingName: string, defaultValue: string): string | Look up the value of a string Setting named settingName, returning defaultValue if no such value is defined. |
Properties
| Name | Type | Description | |
|---|---|---|---|
| dictionaries Readonly | ReadonlyArray<SettingsDictionary> | The set of settings dictionaries from which Setting values are obtained, sorted by SettingsPriority. | |
| onSettingsChanged Readonly | BeEvent<() => void> | Event raised whenever a SettingsDictionary is added or removed. |
Defined in
Last Updated: 21 November, 2024