Methods (documented in current Doxygen)

For Validation: 

• Params::Validate(bool default);
  • If default is true, all values in the Params instance are set to the defaults associated with the current Data Manager.
  • If default is false, all values in the Params instance are checked, and modified if necessary to conform to the current Data Manager.

For UndoRedo:

• Params::CaptureSetLong(), CaptureSetDouble(), CaptureSetString(), CaptureSetStringVec(): 
  
  • These methods are used by SetValue()'s in a Params instance.  They perform the SetValue and also call Params::Validate and perform insertion in the UndoRedo queue
• ParamsBase::CaptureSetLong(), CaptureSetDouble(),CaptureSetString(), CaptureSetStringVec():
  • These methods are similar to the above methods on Params.  They are used when the SetValue()'s are issued in a ParamsBase instance that is contained in a Params instance, e.g. a SetValue in a Box or a TransferFunction. They have a Params* argument that is used to identify the Params instance that is changed.
• Command::CaptureStart(), CaptureEnd()
  • These methods are used when more than one SetValue is to be captured as a single entry in the UndoRedo queue.  CaptureStart() is called to capture the state before any changes, CaptureEnd() is called after all changes are complete.  CaptureStart calls blockCapture() and CaptureEnd calls unblockCapture(), so that only one entry is added to the UndoRedo queue.  Users must call Validate and CaptureEnd after CaptureStart is called.
• Command::blockCapture(), Command::unblockCapture()
  • These methods are used to turn on and off the capturing of commands in the Undo/Redo queue.  It is not expected that implementers will need to use these methods, so they are not currently available in the public API.  However it is possible that we may want to expose these for a script interface.

Usage of the above methods (Responsibilities of  Params implementers):

• Implementers should implement SetValue methods for all values in a Params instance.  These SetValue methods should do the following:
  
  • If the value is to be set, issue Params::CaptureSetLong(), CaptureSetDouble(), CaptureSetString(), or CaptureSetStringVec().  These methods set the value, call Validate(false) to ensure the value is valid, capture the event and provide a description to be used to identify the change in the undo/redo queue.  They return -1 (and do not capture) if the value cannot be set.
  • If the SetValue is setting a value in a contained ParamsBase instance (e.g. a Box or a TransferFunction inside a Params instance), then the ParamsBase instance performs the Validation, based on the Params validation mode.
    • If the value is OK it should be set using ParamsBase::CaptureSetLong(), CaptureSetDouble(), CaptureSetString(), or CaptureSetStringVec() methods.  These methods are just like the corresponding Params methods, except they also pass in the containing Params* instance (which will be used when it’s inserted in the command queue).
      
      
  • Whenever multiple values (associated with different tags or even different Params) are being set in one user action:
    • Command::CaptureStart() and Command::CaptureEnd() must be invoked before and after the changes to make all the changes occur as one entry in the undo/redo queue.
    • Implementer can use the Params::Validate() method to perform validation.  This is currently how multiple text changes are validated.  In this case, the implementer should perform the following sequence:
      
      • Issue Command::CaptureStart()
      • Issue all the desired SetValues
      • issue Validate(false) to make all corrections needed.
      • Issue Command::CaptureEnd()
        
        
• Implementers must implement the pure virtual method Params::Validate(bool default) for each Params class.  When invoked, this should perform the following:
  
  • When Validate is invoked, insertion in the UndoRedo queue should already be disabled (it is appropriate to issue assert(!Command::isRecording()) )
  • If  the ‘default’ argument is true, Validate must set all values in the Params to the default values associated with the current DataMgr.
  • If ‘default’ is false, set values as necessary to make the Params instance conform to the current DataMgr.
    
    
• Params::Validate() can be used as follows:
  • Whenever multiple values are being set in one user action, Validate() can be used to make the collection of values being set consistent with the DataMgr;   This for example is appropriate when the user has changed a number of text boxes and then presses ‘enter’, to set all of the values.  In general it appears that Validate(false) is always invoked with captureEnd() so we may decide to include it there rather than asking programmer-users to remember to call it.
  • Validate is always invoked whenever a new DataMgr (or VDC) is loaded.
  • However, note that Validate() can change other values in the Params (that are not being set by the user), and it will not respect the order in which values are being set by the user.  For that reason it is appropriate to combine dependent SetValues into one method that performs a single Validation and a single Capture.
    
    

Use cases:

1. Issue a simple SetValue of a long value (e.g. resulting from the user clicking on a widget in the GUI).

The SetValue will call Params::CaptureSetLong(tag, description, value);

CaptureSetLong calls:

Command::captureStart(), creating a command with a clone of the Params that owns the value

ParamNode::SetValueLong() changing the associated value

Params::Validate(), correcting the value if it is not OK

Command::captureEnd, saving the final state of the Params, and inserting the change in the Undo/Redo queue.

2.  User changes one or more text values in the GUI and presses "enter"

1. GUI issues Command::captureStart
2. All of the text boxes in the gui are read, and a SetValue() is issued for each value.
3. Each SetValue invokes Params::CaptureSet().
4. Params::CaptureSet merely issues SetValue (captureStart(), captureEnd(), and Validate() are not invoked because captureStart is already active.
5. Validate() is invoked, ensuring the Params is in a valid state
6. Command::captureEnd() is invoked, saving the final state of the Params, inserting the Command into the Command queue.

3.  Two or more SetValue's (in the same Params instance) are combined because they are interdependent.

1. Programmer creates a single method "SetMultipleValues(A,B,C)" that takes arguments for all the values that are to be set
2. In SetMultipleValues() the following occurs:

1. 1. Command::CaptureStart captures the state of the Params before the values are set.
   2. Params::CaptureSet() is invoked for each of the values to be set (however the command will not be captured since it is already inside the CaptureStart()
   3. Params::Validate is invoked, ensuring the values are valid.
   4. Command::CaptureEnd() captures the final state of the Params after the changes.
      
      

Other Use Cases we may want to consider:

• Issuing SetValues from a Script, and how validation and errors would be controlled or reported
• Setting multiple values in different Params instances.