If the given key does not appear in the metadata given at construction time, then undefined is returned. Otherwise, if the key has had a value associated with it via a previous call to set(), then we return that value. Otherwise, we return the default value given in the metadata for the given key.

A settings object has a key if and only if that key appears as part of its metadata, which was given at construction time. Even if no value has been assigned for the key, the settings object still has it, associated with its default value. Even if other keys have been set, we ignore them because they do not appear in the schema given at construction time.

This should be viewed as the set of allowed keys for this app's settings. They are the keys that show up in the metadata, and are thus the only keys that this object pays attention to (even if you add settings with other names).

Load from the browser's localStorage all settings whose names show up in this object's metadata, and convert them to the appropriate types using that metadata. For any value not in localStorage, fill this object with its default value instead (as given by the metadata).

A "hidden" setting is one that will not show up in the settings dialog, but will still be stored in the user's local storage. This can be used when some other part of the application wants to store a value that is determined by user preference, but its purpose and/or type make it not very sensible to add to the settings dialog.

This function can be used to read such hidden settings, and the corresponding setHiddenSetting() to write them.

Note that this function does police its parameters in one way, that the key for the setting must not be the key for a non-hidden setting. Other than that, it can be anything the caller desires. That way, it ensures that the caller does not accidentally write code that behaves as if a setting is hidden when it is not.

This does not clear only this object, but also erases all the user's saved settings. It should be used if the user wants to reset the application to its default settings by erasing any customization they have made so far, so that every setting returns to its default value.

For every setting that is stored in this object and whose key is allowed, according to this object's metadata, save the key-value pair into the browser's localStorage object.

A "hidden" setting is one that will not show up in the settings dialog, but will still be stored in the user's local storage. This can be used when some other part of the application wants to store a value that is determined by user preference, but its purpose and/or type make it not very sensible to add to the settings dialog.

This function can be used to write such hidden settings, and the corresponding loadHiddenSetting() to read them.

Note that this function does police its parameters in one way, that the key for the setting must not be the key for a non-hidden setting. Other than that, it can be anything the caller desires. That way, it ensures that the caller does not accidentally overwrite a non-hidden setting with a hidden setting.

When a user attempts to take a dangerous action (e.g., delete something important) the application may need to pop up a warning asking whether the user really meant to take that action, so that the application does not take the action if it was an accident on the user's part. This function makes that easy.

First, the application settings metadata must contain a setting corresponding to the warning we want to display, for the reasons described in the ShowWarningSettingMetadata class. (See that link for details.)

Second, the client can call this function and pass the name of the warning setting in question and the editor over which to pop up the warning dialog if one is needed. The client receives a promise in return that resolves if the user wants to proceed and rejects otherwise. The user also has the opportunity to say they always want to proceed, which will tweak the corresponding warning setting in this object appropriately.

Example use:

settings.showWarning( 'warn before delete files', editor ).then( () => {
    // put here the code that deletes the files
} ).catch( () => { } ) // to ensure no errors if they say no

Show to the user a dialog box for editing this settings object. If the user clicks OK, any changes they made will be saved back into this object. If the user clicks cancel, no changes they made in the dialog will be retained or stored in this object or anywhere else.

Returns a promise as described below. Note that if the user edits the settings and closes the dialog, that impacts the contents of this object, but not the contents of the browser's localStorage. If the client wishes the new settings to be saved, they should call this object's save() function when the promise resolves.

The promise resolves whether the user clicks OK or cancel, but in the case of cancel, an empty array is passed (no settings changed). The promise rejects only if some unexpected error occurs; that would be considered a bug, so the intent is for the promise to always resolve.