AttributeBuffer.h

Classes

AttributeBuffer -- Buffer for storing Attributes (full description)

class AttributeBuffer

Interface

Public Members
AttributeBuffer()
AttributeBuffer(const AttributeBuffer& other)
const AttributeBuffer& operator=(const AttributeBuffer& other)
~AttributeBuffer()
Int nelements() const
void add(const AttributeBuffer& otherBuf)
void add(const Attribute& newAttribute, const Bool permanent = False)
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)
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)
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)
template <class T> Bool getValue(const T &name, String<T> &value) const
template <class T> Bool getValue(const T &name, T &value) const
Attribute *getAttribute(const String& name) const
AttributeValueBase *getAttributeValue(const String& name) const
AttValue::ValueType getDataType(const String& name) const
Bool matches(const Attribute& res) const
Bool matches(const AttributeBuffer& resBuf) const
void operator+=(const AttributeBuffer &other)
void remove(const String& name)
void clear()
Bool exists(const String& name) const
void addBuff(AttributeBuffer& other) const
void setBuff(AttributeBuffer& other) const
Private Members
friend ostream &operator<<(ostream &, AttributeBuffer &)
void addAttributeToBuffer(Attribute *newAttribute, const Bool permanent)
Bool exists(const String& name, Int& found) const
void erase()

Description

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

Etymology

Buffer for storing Attributes

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 direct 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 matches 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: 

    
    // 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
    }

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: 

    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;
     }

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.


 







Member Description


AttributeBuffer()

 Constructor of empty buffer

AttributeBuffer(const AttributeBuffer& other)



 Copy constructor. Copy semantics.

const AttributeBuffer& operator=(const AttributeBuffer& other)



 Assignement operator

~AttributeBuffer()



 Destructor

Int nelements() const



 Return number of Attributes in the buffer


void add(const AttributeBuffer& otherBuf)

void add(const Attribute& newAttribute, const Bool permanent = False)




 Define  new Attributes. If an Attribute of the same name exists, nothing
 happens. If permanent == True, the Attribute cannot be deleted
 from the Buffer.
 


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)




 Add new Attributes. For type uInt, Int, Float and Double, the Attribute
 has tolerance (see AttributeValueTol), for Bool and String it has not
 (obviously). strict defines how Attribute match. See
 AttributeValue for the explanation of strict 


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)






 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.
 


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)








 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).
 

template <class T> Bool getValue(const T &name, String<T> &value) const





 Get tha value of the named Attribute.  Returns True for
 success, and False for failure.  This can happen if the
 caller asked for the wrong type.

template <class T> Bool getValue(const T &name, T &value) const


Attribute *getAttribute(const String& name) const



 Get the pointer to the Attribute if it exists, else get 0

AttributeValueBase *getAttributeValue(const String& name) const



 Get pointer to the AttributeValue if it exists, else get 0

AttValue::ValueType getDataType(const String& name) const



 Get the data type of the Attribute

Bool matches(const Attribute& res) const



 Function to see if Attribute res matches any Attribute in the
 AttributeBuffer *this. 

Bool matches(const AttributeBuffer& resBuf) 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.

void operator+=(const AttributeBuffer &other)



 AttributeBuffer addition arithmetic.  Go through *this
 buffer, and for those Attributes who have equivalents in
 other, sum the values.


void remove(const String& name)

void clear()




 Remove Attributes from the AttributeBuffer. Only works on Attributes that
 are not permanent
 

Bool exists(const String& name) const



 Check if an Attribute with name name exists

void addBuff(AttributeBuffer& other) const



 Add the Attributes of *this to other

void setBuff(AttributeBuffer& other) const



 Set the Attributes of *this to other

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


void addAttributeToBuffer(Attribute *newAttribute, const Bool permanent)



 Internal routine to add an Attribute to the Buffer

Bool exists(const String& name, Int& found) const



 Check if an Attribute exists and return the index in the PtrBlock

void erase()



 Remove Attributes from the AttributeBuffer. Also erases  Attributes that
 are permanent. Only used in operator=.