settings: Save/access tool interface values

settings: Save/access tool interface values

Basic Usage

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.

Example

setup

use

saving

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 their 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:

  1. The default value.

  2. A function to convert text to the value, or an object that can convert the text into the needed value by following the Annotation abstract class protocol.

  3. A function that converts a value to text.

There are many Annotation subclasses in the cli module that can be used as the second argument to Value() and that also perform range checking.

Advanced Usage

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 configfile documentation.

class Settings(session, tool_name, version='1')

Bases: ConfigFile

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 settings module documentation.

Parameters:

  • session – The ChimeraX session object

  • tool_name (str) – The name of the tool

  • version (str, 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 settings module documentation.

AUTO_SAVE

Class dictionary containing setting names and default values. Such settings will be saved to disk immediately when changed.

Type:

Dict

EXPLICIT_SAVE

Class dictionary containing setting names and default values. Such settings will be saved to disk only when the save() method is called.

Type:

Dict

triggers

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.

Type:

TriggerSet

reset()

Supported API . Reset (revert to default) all settings.

restore()

Supported API . Restore (revert to saved) all settings.

save(setting=None, *, settings=None)

Supported API . Save settings to disk. Only needed for EXPLICIT_SAVE settings. AUTO_SAVE settings are immediately saved to disk when changed.

If ‘setting’ or ‘settings’ is specified, save only those settings (don’t change saved value of any other setting. Otherwise, save all settings.

update(*args, **kw)

Experimental API . Update all corresponding items from dict or iterator or keywords.

Treat preferences as a dictionary and update() them.

Parameters:

  • dict_iter (dict/iterator)

  • **kw (optional name, value items)