==========================================================================
Unit Schemes -- NOTES for Review of the Slot Hierarchy Changes / 8-01-2011
==========================================================================

(1) Slot base class mechanisms to support Unit Schemes, 
 using virtual method implementations in ScalarSlot, SeriesSlot,
 AggSeriesSlot and TableSlot.

(2) In the Slot Classes, EACH USE of Display Attribute values
 (direct evaluations AND calls to "getter" methods) needed to be changed 
 to retrieve either the "Local" display attributes OR the "Unit Scheme 
 switched" display attributes. 

 Generally, within the Slot classes, "Local" semantics are needed for 
 "Getters" used in:
  (a) Copy/Clone Methods
  (b) Editing configuration settings
  (c) Comparing configuration settings.
  (d) Computations in "No Convert" unit changes.
  (e) Persistence operations.
  
 Other uses of "User Unit" and Formatting attributes, e.g. when handling
 display values, need to be based on the "Unit Scheme switched" display
 attributes.
 
 All uses of display attribute "SETTERS" remain unchanged. Those always 
 write to the "Local" attributes, and their side-effect of generating 
 callbacks is still very much desired.

 In terms of Unit TYPES, there is never any danger of referring to the 
 "wrong" domain of attributes (Local vs. "Unit Scheme switched").  
 Unit Types of Slots or Slot Columns are NOT EFFECTED by Unit Scheme 
 switching. (We DID NOT attempt to use Unit Schemes for any sort of 
 "Alt Units" switching -- though that was an interesting possibility).
 For efficiency, it's slightly better to query Unit Types via the "Local" 
 accessors.

 Note: I'm not just delegating the correctness of THESE matters to Bill
 (i.e. all uses of "Getters" accessing the right domain).  This will be 
 the big issue in final testing.  I will probably want to try to 
 systematically devise testing sequences to touch "all" this code (as
 best I can).
 
======================================================
(1) Slot base class mechanisms to support Unit Schemes
======================================================

This mechanism had previously been reviewed and checked in, with STUB
implementations in the Slot subclasses to return "NumDisplayAttribs"
values built from the discrete "legacy" display attribute data members.

HERE IS the important part of Slot.hpp. (Discussion resumes below).

>   // *****************************
>   // ***  Unit Scheme Support  ***
>   // *****************************
>
> private:
>   class MappedUnitSchemeAttribCache
>   {
>      private:
>        const Slot* const _slot;  // owner slot
>        int _mappedSchemeSerialNum;
>        QVector<NumDisplayAttribs> _colAttribsList_prim; // primary
>        QVector<NumDisplayAttribs> _colAttribsList_alt;  // alt units
>
>      public:
>        MappedUnitSchemeAttribCache (Slot* s);
>        const NumDisplayAttribs& colAttribsRef_prim (int col); // primary
>        const NumDisplayAttribs& colAttribsRef_alt  (int col); // alt units
>
>      private:
>        void checkCurrent();
>   };
>
> private:
>   mutable MappedUnitSchemeAttribCache _mappedUnitSchemeAttribCache;
>   bool _unitSchemeLocalOverride;
>
> private:
>   // Return the cached numeric display attributes for the specified slot
>   // column which were computed using the current (or recently current)
>   // Mapped Unit Scheme.
>   const NumDisplayAttribs& mappedNumDisplayAttribs_prim (int col=0) const;
>   const NumDisplayAttribs& mappedNumDisplayAttribs_alt (int col=0) const;
>
> public:
>   // Return the numeric display attributes for the specified slot column,
>   // configured on the slot (i.e. "Local Unit Scheme").
>   virtual const NumDisplayAttribs&
>      localNumDisplayAttribs_prim (int col=0) const;
>   virtual const NumDisplayAttribs&
>      localNumDisplayAttribs_alt (int col=0) const;
>
>   // Return the numeric value display attributes for the specified slot
>   // column depending on the globally active (Local or Mapped) Unit Scheme.
>   const NumDisplayAttribs& activeNumDisplayAttribs_prim (
>           int col, bool considerLocalSlotOverride=false) const;
>   const NumDisplayAttribs& activeNumDisplayAttribs_alt (
>           int col, bool considerLocalSlotOverride=false) const;
>
>   // Individual Slot Override of Active Unit Scheme with Local Scheme
>   bool unitSchemeLocalOverride() const { return _unitSchemeLocalOverride; }
>   void setUnitSchemeLocalOverride (bool override, bool doNotify=true);
>
>   // Virtual Slot Column Attribute Methods
>   virtual int  colCount() const { return (1); }
>   virtual bool supportsAltUnits() const { return false; }
>   virtual unit_type primUnitType (int /*col*/=0) const { return NOUNITS; }
>   virtual unit_type altUnitType  (int /*col*/=0) const { return NOUNITS; }
>
>   // -----------------------------------------------------

Note: the "LocalOverride" provisions are not yet used, but are in place
in _anticipation_ of the "Open Slot Dialog Unit Scheme Local Override Mode".
That's still wet.

Relevant overrides to the virtual methods above are in the following classes:

 (1) ScalarSlot
 (2) SeriesSlot
 (3) TableSlot
 (4) AggSeriesSlot. Actually, the "stub" implementations for this class
      are actually complete, and had already been checked in to the trunk.
      No display attribute data actually resides ON AggSeriesSlot, and this 
      class _always_ defers to SeriesSlot for that stuff. 

SEE FILE: Sim/Slot.UnitScheme.cpp for Slot class implementations of  
 the MappedUnitSchemeAttribCache inner class and related Slot class
 (base class) functions.


=======================================================
(2) Slot Subclass Modifications to Support Unit Schemes
=======================================================

(See also "overview" comments in the introduction, above).

Display attribute data fields -- previously consisting of a ScaledUnitPtr,
a Display Format (2-character QString) and a Display Precision (int) --
reside on these Slot subclasses:

  (1) Scalar Slot:  One Set
  (2) Series Slot:  Two Sets (primary and "alt")
  (3) Table Slot:   One Set for Each Column
 
These "sets" of attributes are now represented with "NumDisplayAttrib"
instances incorporate all three fields (but the Display Format is encoded 
as a 'char' and the Display Precision is a 'short' -- the whole 
NumDisplayAtrib record is only 8 bytes).

Each of these three Slot classes have public getters and private 
setters.  The setters DO NOT generate callbacks, and should generally
be called only from the legacy setters which DO generate callbacks (if 
they should, e.g. not during model loading) and from constructors.
HOWEVER, the logic of when callbacks are called was NOT MODIFIED in
this work -- calls to the "setLocal" methods (see below) simply replaced
the assignments of the old (removed) display attribute data members. 
(And remember, "setting" is not "switched" -- set operations of display 
attributes ALWAYS effect the "LOCAL" attributes).

SeriesSlot has "localPrim" and "localAlt" sets of accessors for the
NumDisplayAttrib fields, for primary and alternate units.  The similar
accessors in ScalarSlot and TableSlot are also called "localPrim", for 
consistency. Only the TableSlot methods include a "col" parameter.

Here are the NumDisplayAttribs data field and accessors for in ScalarSlot:

 private:
   // Numeric Display Attributes
   NumDisplayAttribs _localNumDispAttribs;

 public:
   ScaledUnitPtr  localPrim_scaledUnit()    const;
   unit_type      localPrim_unitType()      const;
   QString        localPrim_unitName()      const;
   double         localPrim_scale()         const;
   inline QString localPrim_usrFormatStr()  const;
   inline char    localPrim_usrFormatChar() const;
   inline int     localPrim_usrPrecision()  const;

 private:
   // Generally, these "setLocal" methods should be called only from
   // constructors and setter methods which issue "change" callbacks.
   //
   inline void setLocalPrim_scaledUnit    (ScaledUnitPtr);
   inline void setLocalPrim_usrFormatStr  (const QString&);
   inline void setLocalPrim_usrFormatChar (char);
   inline void setLocalPrim_usrPrecision  (int);

ALSO: Some work was done to recode the 2-character QString Format codes 
to directly access the single-char Format codes.  Translation from 
the 2-character codes to the single character codes is safely implemented
(but liberally defaulting to "Float") in both NumDisplayAttribs and in 
this utility method (in Utils/cwFormat.cpp):

  char cwFormatCharOfFormatString (const QString& fmt);

The most fundamental Slot subclass changes to be reviewed are in these
files:

  Sim/ScalarSlot.cpp
  Sim/ScalarSlot.hpp
  Sim/SeriesSlot.cpp
  Sim/SeriesSlot.hpp
  Sim/TableSlot.cpp
  Sim/TableSlot.hpp

There are also changes in these files:

  Sim/MultiSlot.cpp
  Sim/PeriodicSlot.DMI.cpp
  Sim/PeriodicSlot.cpp
  Sim/PeriodicSlot.hpp

--- (end) ---