AttributeBuffer.h

Go to the documentation of this file.

//# AttributeBuffer.h: Buffer to store Attributes 
//# Copyright (C) 1996,1997,1999,2000,2001,2002
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef TRIALDISPLAY_ATTRIBUTEBUFFER_H
#define TRIALDISPLAY_ATTRIBUTEBUFFER_H

#include <casa/aips.h>
#include <casa/Containers/Block.h>
#include <casa/Arrays/Vector.h>
#include <display/Display/AttValBase.h>

namespace casa { //# NAMESPACE CASA - BEGIN

class String;
class AttValBase;
class Attribute;


// <summary> Buffer for storing Attributes </summary>
// <use visibility=local>
// 
// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
// </reviewed>
// 
// <prerequisite>
//   <li> Attributes
// </prerequisite>
//
// <etymology>
//  <em>Buffer</em> for storing <em>Attributes</em>
// </etymology>
//
// <synopsis>
//
// A number of classes in the Display Library have Attributes (ie. 'things'
// that have a name and a value). An AttributeBuffer can be used to store
// these Attributes internally and do some simple operations, like checking if
// a certain Attribute exists etc. An AttributeBuffer has a 'fat' interface
// for creating Attributes and getting the value of them that hides most of
// the type issues and should make it less work for a programmer to handle
// Attributes.
//
// AttributeBuffers can be used for a number of things. First, of course, they
// can be used to store and organize information. For example, a class can
// store its state parameters in an AttributeBuffer for its own
// convenience. By creating a userinterface to its AttributeBuffer, a class
// can create a standard interface to its state. One possibility here is that
// by using Attributes that are constructed using a pointer (see
// AttributeValuePoi or AttributeValuePoiTol) and by defining a userinterface
// in the class to modify the Attributes of that class, one automatically
// creates a <em>direct</em> userinterface to (some of) the internal variables
// of that class. This is used for example in the WorldCanvas. Another point
// is that Attributes can be defined with arbitrary name and on several types,
// so if a class has a userinterface to its AttributeBuffer, a programmer who
// uses that class can define what information is stored in the class at run
// time. For example, if one can register an event handler in a class A, one
// can store information in class A using the Attribute interface of class A.
// The event handler knows where to look for the information (namely in the
// object of class A it is registered in) so it can find it, while the
// class  A does not have to know what kind (name, type,...) information
// is needed by the event handler, but it can still store it.
//
// Another use of AttributeBuffer is that one can use it to store the state of
// something. Later in the program the new state can be compared with the old
// state using the <src>matches</src> member function of AttributeBuffer and
// the appropriate action can be taken. This is for example used in the
// ImageDDImage to decide whether a cache should be flushed or
// not. AttributeBuffers match if all their Attributes match. For the logic of
// matching Attributes, see Attributes. An example may make this clearer:
//
// <srcblock>
//
// // We have an AttributeBuffer to store the old state:
// AttributeBuffer oldState;
// // and store some state information
// oldState.add("stateVar1", state1);
// oldState.add("stateVar2", state2);
// oldState.add("stateVar3", state3);
//        .
//        .
//        .
// // later in the program we want to check if the current state matches the
// // old state
//
// // AttributeBuffer for the new state
// AttributeBuffer newState;
// // and store state (state1, state2 or state3 may have changed)
// newState.add("stateVar1", state1);
// newState.add("stateVar2", state2);
// newState.add("stateVar3", state3);
//
// // now the new an old state can be compared
// if { newState.matches(oldState) }
//   use my cache
// } else {
//   delete the cache and make new one
// }
// </srcblock>
//
// A similar application of AttributeBuffers is the way they are used by the
// WorldCanvasHolder and the DisplayData (and Animator) to define what data is
// displayed on a canvas. To define what is displayed, one sets a number of
// Attributes on the WorldCanvasHolder (where they are called restrictions and
// they are stored in an AttributeBuffer) and possibly a number of Attributes
// on the DisplayData (where they are also called restrictions and also stored
// in an AttributeBuffer). Some DisplayData have already pre-defined
// restrictions (like the ImageDisplayData), but the program can add to these
// at run time. When a refresh of the WorldCanvas happens, only those data are
// displayed for which the buffer of the DisplayData matches that of the
// WorldCanvasHolder. This gives a very easy to use way of defining what is
// displayed, and this is how for example the Animator works (one simply
// changes some restrictions and do a refresh). See Animator for examples.
//
//
// AttributeBuffers can also be used for passing information in a compact and
// generic way. This is used eg. by the WorldCanvasHolder in the sizeControl
// event handling. The WorldCanvasHolder does not have to know what
// information is passed and eg. what type it is. The code there looks like:
//
// <srcblock>
// Bool WorldCanvasHolder::sizeControlEH(WorldCanvas *wCanvas) 
//
//   AttributeBuffer sizeControlAtts; 
//
//    // rewind the List of DisplayDatas registered withe this WorldCanvasHolder
//    displayListIter->toStart();
//  
//    // temp
//    DisplayData *dData;
//
//    // loop over DisplayDatas that are registered
//    while ( !displayListIter->atEnd() ) {
//      // get DisplayData from List and let this displaydata do its sizeControl
//      dData = (DisplayData *) displayListIter->getRight();
//      if ( !dData->sizeControl(*this, sizeControlAtts)) {
//        // something is very wrong so abort refresh
//        return False;
//      }
//      // next DisplayData
//      displayListIter++;
//    }
//
//    // copy the Attributes set by the DisplayData to the WorldCanvas
//    // We don't know what is being set, but we can still set it....
//    wCanvas->setAttributes(sizeControlAtts);
//
//    // things went ok
//    return True;
//  }  
// </srcblock>
// </synopsis>
//
// <example>
// <srcBlock>
// </srcBlock>
// </example>
//
// <motivation> 
//
// For efficient handling of all the Attributes that a class in the Display
// Library can have, a buffer is needed, with an interface that makes handling
// of Attributes relatively easy.
//
// </motivation>
//
 

class AttributeBuffer {

 public:

  // Constructor of empty buffer
  AttributeBuffer();

  // Copy constructor. Copy semantics.
  AttributeBuffer(const AttributeBuffer& other);

  // Assignement operator
  const AttributeBuffer& operator=(const AttributeBuffer& other);
  
  // Destructor
  ~AttributeBuffer();

  // Return number of Attributes in the buffer
  Int  nelements() const;
  
  // Define  new Attributes. If an Attribute of the same name exists, nothing
  // happens. If <src>permanent == True</src>, the Attribute cannot be deleted
  // from the Buffer.
  // <group>
  void add(const AttributeBuffer& otherBuf);
  void add(const Attribute& newAttribute, const Bool permanent = False);
  //</group>

  // Add new Attributes. For type uInt, Int, Float and Double, the Attribute
  // has tolerance (see AttributeValueTol), for Bool and String it has not
  // (obviously). <src>strict</src> defines how Attribute match. See
  // AttributeValue for the explanation of <src>strict</src> <group>
  void add(const String& name, const uInt newValue, 
           const uInt tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Int newValue, 
           const Int tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Float newValue, 
           const Float tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Double newValue, 
           const Double tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Bool newValue, 
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, const String& newValue, 
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, const Quantity newValue,
           const Bool strict = False, const Bool permanent = False);


  void add(const String& name, const Vector<uInt>& newValue, 
           const uInt tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Vector<Int>& newValue, 
           const Int tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Vector<Float>& newValue, 
           const Float tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Vector<Double>& newValue, 
           const Double tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, const Vector<Bool>& newValue,
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, const Vector<String>& newValue,
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, const Vector<Quantity>& newValue,
           const Bool strict = False, const Bool permanent = False);

  // </group>

  // Add new Attributes. These are the pointer versions. Using these members
  // will create Attributes based on AttributeValueTol or
  // AttributeValuePoiTol. This means that if the Attribute is modified, the
  // variable used to define the Attribute also changes and vice versa.
  // <group>
  void add(const String& name,  uInt *newValue, 
           const uInt tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name,  Int *newValue, 
           const Int tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, Float *newValue, 
           const Float tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, Double  *newValue, 
           const Double tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, Bool *newValue, 
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, String *newValue, 
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, Quantity *newValue,
           const Bool strict = False, const Bool permanent = False);
  

  void add(const String& name, Vector<uInt> *newValue, 
           const uInt tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name, Vector<Int> *newValue, 
           const Int tolerance = 0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name,  Vector<Float> *newValue, 
           const Float tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name,  Vector<Double> *newValue, 
           const Double tolerance = 0.0, const Bool strict = False, 
           const Bool permanent = False);

  void add(const String& name,  Vector<Bool> *newValue, 
           const Bool strict = False, const Bool permanent = False);

  void add(const String& name, Vector<String> *newValue,
           const Bool strict = False, const Bool permanent = False);
  
  void add(const String& name, Vector<Quantity> *newValue,
           const Bool strict = False, const Bool permanent = False);

  // </group>


  // Set the value of an Attribute. If the Attribute does not exist, it is
  // created (using the corresponding add function with permanent set to
  // False), otherwise the value of the existing Attribute, if it is of the
  // correct type) will be changed. If the Attribute has a different type than
  // the variable used in the set function, nothing happens (but I may change
  // my mind and  throw an exception).
  // <group>
  void set(const AttributeBuffer& otherBuf);
  void set(const Attribute& newAttribute);

  void set(const String& name, const uInt newValue, 
           const uInt tolerance = 0, const Bool strict = False);

  void set(const String& name, const Int newValue, 
           const Int tolerance = 0, const Bool strict = False);

  void set(const String& name, const Float newValue, 
           const Float tolerance = 0.0, const Bool strict = False);

  void set(const String& name, const Double newValue, 
           const Double tolerance = 0.0, const Bool strict = False);

  void set(const String& name, const Bool newValue, 
           const Bool strict = False);

  void set(const String& name, const String& newValue, 
           const Bool strict = False);

  void set(const String& name, const Quantity newValue,
           const Bool strict = False);


  void set(const String& name, const Vector<uInt>& newValue, 
           const uInt tolerance = 0, const Bool strict = False);

  void set(const String& name, const Vector<Int>& newValue, 
           const Int tolerance = 0, const Bool strict = False);

  void set(const String& name, const Vector<Float>& newValue, 
           const Float tolerance = 0.0, const Bool strict = False);

  void set(const String& name, const Vector<Double>& newValue, 
           const Double tolerance = 0.0, const Bool strict = False);

  void set(const String& name, const Vector<Bool>& newValue,
           const Bool strict = False);

  void set(const String& name, const Vector<String>& newValue,
           const Bool strict = False);

  void set(const String& name, const Vector<Quantity>& newValue,
           const Bool strict = False);

  // </group>

  // Get tha value of the named Attribute.  Returns <src>True</src> for
  // success, and <src>False</src> for failure.  This can happen if the
  // caller asked for the wrong type.
  template <class T> Bool getValue(const String &name, Vector<T> &value) const;
  template <class T> Bool getValue(const String &name, T &value) const;

  // Get the pointer to the Attribute if it exists, else get 0
  Attribute *getAttribute(const String& name) const;
  
  // Get pointer to the AttributeValue if it exists, else get 0
  AttributeValueBase *getAttributeValue(const String& name) const;
  
  // Get the data type of the Attribute
  AttValue::ValueType getDataType(const String& name) const;
  
  // Function to see if Attribute res matches any Attribute in the
  // AttributeBuffer *this. 
  Bool matches(const Attribute& res) const;

  // Function to see if  every Attribute in the AttributeBuffer resBuf
  // matches every Attribute in the AttributeBuffer *this. Returns
  // True if this is the case, returns False if for at least one Attribute
  // in resBuf there is a mismatch.
  Bool matches(const AttributeBuffer& resBuf) const;

  // AttributeBuffer addition arithmetic.  Go through <src>*this</src>
  // buffer, and for those Attributes who have equivalents in
  // <src>other</src>, sum the values.
  void operator+=(const AttributeBuffer &other);

  // Remove Attributes from the AttributeBuffer. Only works on Attributes that
  // are not permanent
  // <group>
  void remove(const String& name);
  void clear();
  // </group>

  // Check if an Attribute with name name exists
  Bool exists(const String& name) const;

  // Add the Attributes of *this to other
  void addBuff(AttributeBuffer& other) const;

  // Set the Attributes of *this to other
  void setBuff(AttributeBuffer& other) const;

 private:

  friend ostream &operator<<(ostream &, AttributeBuffer &);

  // PtrBlock for the Attributes. Should change this to a list
  PtrBlock<Attribute *> attributes;

  // Store if an Attribute is permamnent or not
  Block<Bool> nonDeletable;
  
  // Internal routine to add an Attribute to the Buffer
  void addAttributeToBuffer(Attribute *newAttribute, const Bool permanent);

  // Check if an Attribute exists and return the index in the PtrBlock
  Bool exists(const String& name, Int& found) const;

  // Remove Attributes from the AttributeBuffer. Also erases  Attributes that
  // are permanent. Only used in operator=.
  void erase();
  
};

ostream &operator<<(ostream &os, AttributeBuffer &ab);


} //# NAMESPACE CASA - END

#ifndef AIPS_NO_TEMPLATE_SRC
#include <display/Display/AttBufferTemplates.tcc>
#endif

#endif