= 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.