settings: Save/access tool interface values¶
This module provides a convenient way for tools to remember preferred settings.
To do so you create a subclass of this module’s
Settings class and
populate it with setting names and default values. There are two varieties of
settings, ones that are automatically saved to disk when they’re set, and ones
that only save to disk when the Settings.save() method is called. The former
might be used for minor conveniences in the interface, like remembering which
file format the user last used, whereas the latter would be used if a tool
presents an explicit Save button for preserving configuration information.
The settings are presented as attributes of the Settings instance, so therefore the setting name has to be legal as an attribute, i.e. no spaces, just alphanumeric characters plus underscore. Also, leading underscores are not allowed.
As mentioned above, the AUTO_SAVE/EXPLICIT_SAVE keys have to be legal to use
as attribute names. The values can be just plain Python values, in which case
repr() will be saved to disk, or they can be more complex
entities, like enumerations or class instances. In the latter case you have
to use the
Value class to tell the settings
mechanism how to save and restore the value and perhaps check that the value is
within its legal range of values. The three arguments to Value() are:
The default value.
A function to convert text to the value, or an object that can convert the text into the needed value by following the
Annotationabstract class protocol.
A function that converts a value to text.
There are many Annotation subclasses in the
module that can be used as the second argument to Value() and that also
perform range checking.
- Adding a setting
One simply adds the definition into the appropriate dictionary, and increases the minor part of the Settings version number. The version number is provided as a keyword argument (named version) to the Settings constructor. It defaults to “1”.
- Moving/deleting settings
This involves adding properties to your Settings subclass and is discussed in detail in the
Settings(session, tool_name, version='1')¶
Supported API. Save/remember tool interface settings
A tool remembers interface setting across tool invocations with this class. There are two types of settings supported: ones that save to disk immediately when changed, and ones that are saved to disk only when the
save()method is called.
A tools uses Settings by subclassing and defining class dictionaries named AUTO_SAVE and EXPLICIT_SAVE containing the names of the settings and their default values. This is explained in detail in the
The ChimeraX session object
The name of the tool
- versionstr, optional
The version number for the settings, which should be increased if settings are added, deleted, or modified. Discussed in the Advanced Usage section of the
Class dictionary containing setting names and default values. Such settings will be saved to disk immediately when changed.
Class dictionary containing setting names and default values. Such settings will be saved to disk only when the
save()method is called.
- triggers: TriggerSet
When a setting changes its current value, the ‘setting changed’ trigger will be activated with (attr_name, prev_val, new_val) as the data provided with the trigger.
Save settings to disk. Only needed for EXPLICIT_SAVE settings. AUTO_SAVE settings are immediately saved to disk when changed.
save(self, setting=None, *, settings=None)¶
Supported API . If ‘setting’ or ‘settings’ is specified, save only those settings (don’t change saved value of any other setting. Otherwise, save all settings.