marmoire

 marmoire - class constructor for marmoire container type
 FORMAT [o, others] = marmoire(params, varargin)
  
 the marmoire object is to store various bits of stuff
 (armoire is the French for cupboard).
 This cupboard is to put items which I will want to fish out 
 from time to time.
 
 The items may well be associated with a filename
 If they are associated with a filename when set, they 
 are assumed to have been saved already.
 If not, they are flagged as awaiting a save

 If the data changes, you can indicate this with the 
 update method, which changes the data, and flags for a save

 The permissable actions are:

 add_item         - add an item to the armoire
 item_exists      - ask if there an exists an item of given name
 add_if_absent    - adds item if it does not yet exist
 set_item_data    - sets data for item 
 get_item_data    - gets data from item
 set_item_data_ui - sets data, getting via UI
 save_item_data   - save data for item, if required
 save_item_data_ui - saves, using GUI to ask for filename
 update_item_data  - updates data, sets flag to show change
 clear_item_data   - clears data for item
 isempty_item_data - returns 1 if no data for item
 item_needs_save   - returns 1 if this item needs a save

 Each item is stored in a field 'items' in the object

 The name of item is the same as the name of the field in the items field
 of the object, and this is the 'item' argument to the various methods.

 Each item field cotains a structure, widh the data contained in a field
 'data'. The rest of the fields in the structure are parameters telling
 the object how to deal with the various manipulations of the data.  So,
 each item requires the following fields:
                 
 data            - the data 
                   (or a filename which loads as the data - see the
                   char_is_filename field)
 has_changed     - flag, if set, means data has changed since first set
 save_if_changed - flag, if set, will try to save changed data when a
                   save is requested.  Saves can also be forced.
 leave_as_file   - flag, if set, will attempt to leave the data, defined
                   by the filename, on the disk, not in memory, and only
                   load the data for a 'get'.  
                   Otherwise, if a set occurs, and the data field is
                   empty, will load data into the global variable when
                   'set'ing field and leave it there.
                   If the data changes, and requires a save, this field
                   has no function, until the next save.
 file_name       - file name of .mat file containing data
                   If data is empty, and file_name is not, 
                   an attempt to 'get' data will load contents of
                   file_name
 default_file_name - default filename offered for save 
 file_type       - type of file to load ('mat' or 'ascii')
 char_is_filename - flag, if set, char data is assumed to be a filename
 filter_spec     - filter spec for uigetfile (see help uigetfile)
 prompt          - prompt for uigetfile
 verbose         - flag, if set, displays more information during
                   processing
 set_action      - actions to perform when item is set
                   in form of callback string.  This is executed
                   in the 'i_set' subfunction, and can use all
                   variables functions defined therein.  See programmers
                   notes in the function for callback format
 set_action_if_update - flag, if set, applied set_action for 'update' as
                   well as 'set'
 set_action_if_clear - flag, if set, applied set_action for 'clear' as
                   well as 'set'

 $Id$

0001 function [o, others] = marmoire(params, varargin)
0002 % marmoire - class constructor for marmoire container type
0003 % FORMAT [o, others] = marmoire(params, varargin)
0004 %
0005 % the marmoire object is to store various bits of stuff
0006 % (armoire is the French for cupboard).
0007 % This cupboard is to put items which I will want to fish out
0008 % from time to time.
0009 %
0010 % The items may well be associated with a filename
0011 % If they are associated with a filename when set, they
0012 % are assumed to have been saved already.
0013 % If not, they are flagged as awaiting a save
0014 %
0015 % If the data changes, you can indicate this with the
0016 % update method, which changes the data, and flags for a save
0017 %
0018 % The permissable actions are:
0019 %
0020 % add_item         - add an item to the armoire
0021 % item_exists      - ask if there an exists an item of given name
0022 % add_if_absent    - adds item if it does not yet exist
0023 % set_item_data    - sets data for item
0024 % get_item_data    - gets data from item
0025 % set_item_data_ui - sets data, getting via UI
0026 % save_item_data   - save data for item, if required
0027 % save_item_data_ui - saves, using GUI to ask for filename
0028 % update_item_data  - updates data, sets flag to show change
0029 % clear_item_data   - clears data for item
0030 % isempty_item_data - returns 1 if no data for item
0031 % item_needs_save   - returns 1 if this item needs a save
0032 %
0033 % Each item is stored in a field 'items' in the object
0034 %
0035 % The name of item is the same as the name of the field in the items field
0036 % of the object, and this is the 'item' argument to the various methods.
0037 %
0038 % Each item field cotains a structure, widh the data contained in a field
0039 % 'data'. The rest of the fields in the structure are parameters telling
0040 % the object how to deal with the various manipulations of the data.  So,
0041 % each item requires the following fields:
0042 %
0043 % data            - the data
0044 %                   (or a filename which loads as the data - see the
0045 %                   char_is_filename field)
0046 % has_changed     - flag, if set, means data has changed since first set
0047 % save_if_changed - flag, if set, will try to save changed data when a
0048 %                   save is requested.  Saves can also be forced.
0049 % leave_as_file   - flag, if set, will attempt to leave the data, defined
0050 %                   by the filename, on the disk, not in memory, and only
0051 %                   load the data for a 'get'.
0052 %                   Otherwise, if a set occurs, and the data field is
0053 %                   empty, will load data into the global variable when
0054 %                   'set'ing field and leave it there.
0055 %                   If the data changes, and requires a save, this field
0056 %                   has no function, until the next save.
0057 % file_name       - file name of .mat file containing data
0058 %                   If data is empty, and file_name is not,
0059 %                   an attempt to 'get' data will load contents of
0060 %                   file_name
0061 % default_file_name - default filename offered for save
0062 % file_type       - type of file to load ('mat' or 'ascii')
0063 % char_is_filename - flag, if set, char data is assumed to be a filename
0064 % filter_spec     - filter spec for uigetfile (see help uigetfile)
0065 % prompt          - prompt for uigetfile
0066 % verbose         - flag, if set, displays more information during
0067 %                   processing
0068 % set_action      - actions to perform when item is set
0069 %                   in form of callback string.  This is executed
0070 %                   in the 'i_set' subfunction, and can use all
0071 %                   variables functions defined therein.  See programmers
0072 %                   notes in the function for callback format
0073 % set_action_if_update - flag, if set, applied set_action for 'update' as
0074 %                   well as 'set'
0075 % set_action_if_clear - flag, if set, applied set_action for 'clear' as
0076 %                   well as 'set'
0077 %
0078 % $Id$
0079   
0080 % Programmers' notes
0081 % ------------------
0082 % set_action callbacks
0083 % callbacks should in the following formats;
0084 %
0085 % [o errf msg] = my_function(args)
0086 %
0087 %  The return argument 'o' is the modified whole object. If
0088 % 'errf' is set, the routine warns, and aborts the set action with the
0089 % 'msg'.
0090 %
0091 % The preferred args will give a format of are:
0092 % [o errf msg] = my_function(o, item, old_o)
0093 %
0094 % where o is the object after the data has been set, item is the name of
0095 % the item which has just been set, and old_o is the object before the
0096 % data was set.
0097 %
0098 % The available args are:
0099 % o               - the whole object with new data set
0100 % item            - the name of the item which has been set
0101 % old_o           - the object before the data was set.
0102 %
0103 % as well as:
0104 %
0105 % item_struct     - proposed whole item field contents
0106 % data            - proposed data to be inserted
0107 % passed_filename - filename passed to function
0108 %
0109 % and anything else you can see in context, for the line containing the
0110 % 'eval' statement in the do_set method
0111   
0112 myclass = 'marmoire';
0113 defstruct = struct('items', []);
0114 
0115 if nargin < 1
0116   params = [];
0117 end
0118 if isa(params, myclass)
0119   o = params;
0120   return
0121 end
0122 
0123 % fill with defaults, parse into fields for this object, children
0124 [pparams, others] = mars_struct('ffillsplit', defstruct, params);
0125 
0126 % add version tag (was CVS; now marsbar version)
0127 pparams.cvs_version = marsbar('ver');
0128 
0129 % Set as object
0130 o  = class(pparams, myclass);