Module userparams

Helpers to create user preferences for class attribute defaults and
editing widgets for user modification of preferences.

This module is used to create preferences that can be easily saved to
configuration files.  It is designed to be class-based, not instance
based.

Classes need to inherit from ClassPrefs and then define a class
attribute called default_classprefs that is a tuple of Param objects.
Subclasses will inherit the preferences of their parent classes, and
can either redefine the defaults or add new parameters.  For example:

  class Vehicle(ClassPrefs):
      default_classprefs = (
          IntParam('wheels', 0, 'Number of wheels on the vehicle'),
          IntParam('doors', 0, 'Number of doors on the vehicle'),
          BoolParam('operational', True, 'Is it running?'),
          BoolParam('engine', False, 'Does it have a motor?'),
          )

  class Car(Vehicle):
      default_classprefs = (
          IntParam('wheels', 4),
          IntParam('doors', 4),
          BoolParam('engine', True),
          StrParam('license_state', '', 'State in which registered'),
          StrParam('license_plate', '', 'License plate number'),
          )

  class WxCar(wx.Window, Car):
      default_classprefs = (
          IntParam('pixel_height', 400),
          IntParam('pixel_width', 600),
          )

The metaclass for ClassPrefs processes the default_classprefs and adds
another class attribute called classprefs that is a proxy object into
a global preferences object.

The global preferences object GlobalPrefs uses the ConfigParser module
to serialize and unserialize user preferences.  Since the user
preferences are stored in text files, the Param objects turn the user
text into the expected type of the Param so that your python code only
has to deal with the expected type and doesn't have to do any conversion
itself.

The user configuration for the above example could look like this:

  [Vehicle]
  operational = False
  
  [Car]
  license_state = CA
  doors = 2
  
  [WxCar]
  pixel_width = 300
  pixel_height = 200

and the GlobalPrefs.readConfig method will parse the file,
interpreting the section name as the class.  It will set
Vehicle.classprefs.operational to be the boolean value False,
Car.classprefs.license_state to the string 'CA', Car.classprefs.doors to
the integer value 2, etc.

Your code doesn't need to know anything about the conversion from the
string to the expected type -- it's all handled by the ClassPrefs and
GlobalPrefs.

The PrefDialog class provides the user interface dialog to modify
class parameters.  It creates editing widgets that correspond to the
Param class -- for BoolParam it creates a checkbox, IntParam a text
entry widget, ChoiceParam a pulldown list, etc.  The help text is
displayed as a tooltip over the editing widget.  User subclasses of
Param are possible as well.