Attendees

Eric, TomG, Scooter, Conrad

Agenda

• Preferences API and UI

Discussion

• Preferences are parameters that are persistent across multiple Chimera sessions. There are three types of parameters that a user may see in a UI:
  • volatile: parameters that are never saved across session;
  • sticky: parameters that are saved whenever their values change; and
  • save-on-demand: parameters that are saved at user request (e.g., when user clicks on a Save Settings button).
• There are three possible values for each parameter:
  • factory: the value used if there is no user selected value at all;
  • user: the value that the user has selected and saved; and
  • current: the value that the tools is currently using.
• Sticky parameters always have the same user and current values, which may differ from the factory value.
• Save-on-demand parameters may have all three values being different.
• Volatile parameters do not have user values, only factory and current values, which may differ.
• There are two major areas of consideration: how can we implement this (the API) and how do we present it to the user (the UI).
• (For the purposes of these discussions, we treat the Chimera 2 core the same as a tool.)

Application Programming Interface

• We need to manage three types of parameter values (factory, user and current) for two types of parameters (sticky and save-on-demand). Since volatile parameters are never saved, they may simply be normal variables or attributes.
• A preferences module only needs to save user values. It may need to know factory values so that parameters whose user value matches its factory value are not saved to disk. This is to make it possible for tools to change parameter factory values and have them be used for parameters that the user did not explicitly change.
• Sometimes, a tool writer may want to use a common interface for accessing sticky and save-on-demand parameters. This may be accomplished using a settings class which offers a dictionary-style key-value interface to parameters, and also knows how to save the parameter values using the preferences module. When a settings instance is created, it is initialized with the list of sticky parameter keys. When values for these sticky parameters keys are changed, the appropriate preferences methods/functions are called. When non-sticky (therefore presumably save-on-demand) parameters are changed, no preferences methods/functions are called. A settings method provides the functionality to explicitly push save-on-demand parameters through to preferences.

User Interface

• Neither the preferences nor the settings module provides any user interface. It is up to tools to provide the appropriate UI for their parameters. For example, the Chimera 2 core may provide a menu bar entry that brings up a dialog for changing core parameters such as background color or lighting parameters. This dialog is explicitly not part of either preferences or settings even though both may be used to implement core parameters.
• For tools that only use sticky and/or volatile parameters, there is no need for extra user interface elements since parameter values are either always or never saved. For tools that have save-on-demand parameters, there should be a Save Settings button to allow users to save the values of parameters that they have changed.
• A Save Settings button should save only parameters in the same dialog/panel/window/tab as the button; parameters on other dialogs/panels/windows/tabs should not be saved as a side effect. A Save All Settings menu item may be offered to save all tool parameters. There should be buttons to change to either user or factory values.
• An (unrecommended) alternative is to use a Save All Settings button to save all parameters in all dialogs/panels/windows/tabs.
• Ideally, there should be some way for users to tell the difference among the three different types of parameters (volatile, sticky and save-on-demand). Conrad proposed a simple icon indicator as part of the parameter description (like the small question mark, magnifier glass or link-out icons on an PDB entry page) but TomG and Eric were against. For the December release, no attempt will be made to distinguish the three parameter types.

Guidelines

• The preferences module will be initialized with factory default values and read user preference values from disk. It will not keep track of current values at all. It is up to tools to call the preferences modules to change values, which are written to disk immediately. (There may be a mechanism for batching multiple changes so that only one disk write is done at the end.)
• The settings module is a layer above preferences and offers a dictionary-style interface. A settings instance is initialized with knowledge of which keys refer to sticky parameters and which to save-on-demand parameters. Tools can use settings instances just like dictionaries to set either type of parameter. settings will ensure that changing sticky parameters will result in immediate calls to preferences while changes to save-on-demand parameters are pending until the tool explicitly tells settings to save those parameters.
• Tools (including the core) are responsible for presenting user interfaces that allow users to change parameter values. There is no "preferences panel" as in Chimera 1, where parameters for many tools may also be found. The intent is that a preferences item in the main Chimera 2 menu bar will bring up a dialog for setting core parameters only, with no tool parameters listed at all. All tool parameters are presented in tool user interfaces. Tools should also follow conventions for CLI so that commands for setting tool parameters are similar across tools.