casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
AttributeBuffer.h
Go to the documentation of this file.
1 //# AttributeBuffer.h: Buffer to store Attributes
2 //# Copyright (C) 1996,1997,1999,2000,2001,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TRIALDISPLAY_ATTRIBUTEBUFFER_H
29 #define TRIALDISPLAY_ATTRIBUTEBUFFER_H
30 
31 #include <casa/aips.h>
32 #include <casa/Containers/Block.h>
33 #include <casa/Arrays/Vector.h>
35 
36 namespace casacore{
37 
38  class String;
39 }
40 
41 namespace casa { //# NAMESPACE CASA - BEGIN
42 
43  class AttValBase;
44  class Attribute;
45 
46 
47 // <summary> Buffer for storing Attributes </summary>
48 // <use visibility=local>
49 //
50 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
51 // </reviewed>
52 //
53 // <prerequisite>
54 // <li> Attributes
55 // </prerequisite>
56 //
57 // <etymology>
58 // <em>Buffer</em> for storing <em>Attributes</em>
59 // </etymology>
60 //
61 // <synopsis>
62 //
63 // A number of classes in the Display Library have Attributes (ie. 'things'
64 // that have a name and a value). An AttributeBuffer can be used to store
65 // these Attributes internally and do some simple operations, like checking if
66 // a certain Attribute exists etc. An AttributeBuffer has a 'fat' interface
67 // for creating Attributes and getting the value of them that hides most of
68 // the type issues and should make it less work for a programmer to handle
69 // Attributes.
70 //
71 // AttributeBuffers can be used for a number of things. First, of course, they
72 // can be used to store and organize information. For example, a class can
73 // store its state parameters in an AttributeBuffer for its own
74 // convenience. By creating a userinterface to its AttributeBuffer, a class
75 // can create a standard interface to its state. One possibility here is that
76 // by using Attributes that are constructed using a pointer (see
77 // AttributeValuePoi or AttributeValuePoiTol) and by defining a userinterface
78 // in the class to modify the Attributes of that class, one automatically
79 // creates a <em>direct</em> userinterface to (some of) the internal variables
80 // of that class. This is used for example in the WorldCanvas. Another point
81 // is that Attributes can be defined with arbitrary name and on several types,
82 // so if a class has a userinterface to its AttributeBuffer, a programmer who
83 // uses that class can define what information is stored in the class at run
84 // time. For example, if one can register an event handler in a class A, one
85 // can store information in class A using the Attribute interface of class A.
86 // The event handler knows where to look for the information (namely in the
87 // object of class A it is registered in) so it can find it, while the
88 // class A does not have to know what kind (name, type,...) information
89 // is needed by the event handler, but it can still store it.
90 //
91 // Another use of AttributeBuffer is that one can use it to store the state of
92 // something. Later in the program the new state can be compared with the old
93 // state using the <src>matches</src> member function of AttributeBuffer and
94 // the appropriate action can be taken. This is for example used in the
95 // ImageDDImage to decide whether a cache should be flushed or
96 // not. AttributeBuffers match if all their Attributes match. For the logic of
97 // matching Attributes, see Attributes. An example may make this clearer:
98 //
99 // <srcblock>
100 //
101 // // We have an AttributeBuffer to store the old state:
102 // AttributeBuffer oldState;
103 // // and store some state information
104 // oldState.add("stateVar1", state1);
105 // oldState.add("stateVar2", state2);
106 // oldState.add("stateVar3", state3);
107 // .
108 // .
109 // .
110 // // later in the program we want to check if the current state matches the
111 // // old state
112 //
113 // // AttributeBuffer for the new state
114 // AttributeBuffer newState;
115 // // and store state (state1, state2 or state3 may have changed)
116 // newState.add("stateVar1", state1);
117 // newState.add("stateVar2", state2);
118 // newState.add("stateVar3", state3);
119 //
120 // // now the new an old state can be compared
121 // if { newState.matches(oldState) }
122 // use my cache
123 // } else {
124 // delete the cache and make new one
125 // }
126 // </srcblock>
127 //
128 // A similar application of AttributeBuffers is the way they are used by the
129 // WorldCanvasHolder and the DisplayData (and Animator) to define what data is
130 // displayed on a canvas. To define what is displayed, one sets a number of
131 // Attributes on the WorldCanvasHolder (where they are called restrictions and
132 // they are stored in an AttributeBuffer) and possibly a number of Attributes
133 // on the DisplayData (where they are also called restrictions and also stored
134 // in an AttributeBuffer). Some DisplayData have already pre-defined
135 // restrictions (like the ImageDisplayData), but the program can add to these
136 // at run time. When a refresh of the WorldCanvas happens, only those data are
137 // displayed for which the buffer of the DisplayData matches that of the
138 // WorldCanvasHolder. This gives a very easy to use way of defining what is
139 // displayed, and this is how for example the Animator works (one simply
140 // changes some restrictions and do a refresh). See Animator for examples.
141 //
142 //
143 // AttributeBuffers can also be used for passing information in a compact and
144 // generic way. This is used eg. by the WorldCanvasHolder in the sizeControl
145 // event handling. The WorldCanvasHolder does not have to know what
146 // information is passed and eg. what type it is. The code there looks like:
147 //
148 // <srcblock>
149 // casacore::Bool WorldCanvasHolder::sizeControlEH(WorldCanvas *wCanvas)
150 //
151 // AttributeBuffer sizeControlAtts;
152 //
153 // // rewind the casacore::List of DisplayDatas registered withe this WorldCanvasHolder
154 // displayListIter->toStart();
155 //
156 // // temp
157 // DisplayData *dData;
158 //
159 // // loop over DisplayDatas that are registered
160 // while ( !displayListIter->atEnd() ) {
161 // // get DisplayData from casacore::List and let this displaydata do its sizeControl
162 // dData = (DisplayData *) displayListIter->getRight();
163 // if ( !dData->sizeControl(*this, sizeControlAtts)) {
164 // // something is very wrong so abort refresh
165 // return false;
166 // }
167 // // next DisplayData
168 // displayListIter++;
169 // }
170 //
171 // // copy the Attributes set by the DisplayData to the WorldCanvas
172 // // We don't know what is being set, but we can still set it....
173 // wCanvas->setAttributes(sizeControlAtts);
174 //
175 // // things went ok
176 // return true;
177 // }
178 // </srcblock>
179 // </synopsis>
180 //
181 // <example>
182 // <srcBlock>
183 // </srcBlock>
184 // </example>
185 //
186 // <motivation>
187 //
188 // For efficient handling of all the Attributes that a class in the Display
189 // Library can have, a buffer is needed, with an interface that makes handling
190 // of Attributes relatively easy.
191 //
192 // </motivation>
193 //
194 
195 
197 
198  public:
199 
200  // Constructor of empty buffer
201  AttributeBuffer();
202 
203  // Copy constructor. Copy semantics.
204  AttributeBuffer(const AttributeBuffer& other);
205 
206  // Assignement operator
207  const AttributeBuffer& operator=(const AttributeBuffer& other);
208 
209  // Destructor
211 
212  // Return number of Attributes in the buffer
213  casacore::Int nelements() const;
214 
215  // Define new Attributes. If an Attribute of the same name exists, nothing
216  // happens. If <src>permanent == true</src>, the Attribute cannot be deleted
217  // from the Buffer.
218  // <group>
219  void add(const AttributeBuffer& otherBuf);
220  void add(const Attribute& newAttribute, const casacore::Bool permanent = false);
221  //</group>
222 
223  // Add new Attributes. For type casacore::uInt, casacore::Int, casacore::Float and casacore::Double, the Attribute
224  // has tolerance (see AttributeValueTol), for casacore::Bool and casacore::String it has not
225  // (obviously). <src>strict</src> defines how Attribute match. See
226  // AttributeValue for the explanation of <src>strict</src> <group>
227  void add(const casacore::String& name, const casacore::uInt newValue,
228  const casacore::uInt tolerance = 0, const casacore::Bool strict = false,
229  const casacore::Bool permanent = false);
230 
231  void add(const casacore::String& name, const casacore::Int newValue,
232  const casacore::Int tolerance = 0, const casacore::Bool strict = false,
233  const casacore::Bool permanent = false);
234 
235  void add(const casacore::String& name, const casacore::Float newValue,
236  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false,
237  const casacore::Bool permanent = false);
238 
239  void add(const casacore::String& name, const casacore::Double newValue,
240  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false,
241  const casacore::Bool permanent = false);
242 
243  void add(const casacore::String& name, const casacore::Bool newValue,
244  const casacore::Bool strict = false, const casacore::Bool permanent = false);
245 
246  void add(const casacore::String& name, const casacore::String& newValue,
247  const casacore::Bool strict = false, const casacore::Bool permanent = false);
248 
249  void add(const casacore::String& name, const casacore::Quantity newValue,
250  const casacore::Bool strict = false, const casacore::Bool permanent = false);
251 
252 
253  void add(const casacore::String& name, const casacore::Vector<casacore::uInt>& newValue,
254  const casacore::uInt tolerance = 0, const casacore::Bool strict = false,
255  const casacore::Bool permanent = false);
256 
257  void add(const casacore::String& name, const casacore::Vector<casacore::Int>& newValue,
258  const casacore::Int tolerance = 0, const casacore::Bool strict = false,
259  const casacore::Bool permanent = false);
260 
261  void add(const casacore::String& name, const casacore::Vector<casacore::Float>& newValue,
262  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false,
263  const casacore::Bool permanent = false);
264 
265  void add(const casacore::String& name, const casacore::Vector<casacore::Double>& newValue,
266  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false,
267  const casacore::Bool permanent = false);
268 
269  void add(const casacore::String& name, const casacore::Vector<casacore::Bool>& newValue,
270  const casacore::Bool strict = false, const casacore::Bool permanent = false);
271 
272  void add(const casacore::String& name, const casacore::Vector<casacore::String>& newValue,
273  const casacore::Bool strict = false, const casacore::Bool permanent = false);
274 
275  void add(const casacore::String& name, const casacore::Vector<casacore::Quantity>& newValue,
276  const casacore::Bool strict = false, const casacore::Bool permanent = false);
277 
278  // </group>
279 
280  // Add new Attributes. These are the pointer versions. Using these members
281  // will create Attributes based on AttributeValueTol or
282  // AttributeValuePoiTol. This means that if the Attribute is modified, the
283  // variable used to define the Attribute also changes and vice versa.
284  // <group>
285  void add(const casacore::String& name, casacore::uInt *newValue,
286  const casacore::uInt tolerance = 0, const casacore::Bool strict = false,
287  const casacore::Bool permanent = false);
288 
289  void add(const casacore::String& name, casacore::Int *newValue,
290  const casacore::Int tolerance = 0, const casacore::Bool strict = false,
291  const casacore::Bool permanent = false);
292 
293  void add(const casacore::String& name, casacore::Float *newValue,
294  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false,
295  const casacore::Bool permanent = false);
296 
297  void add(const casacore::String& name, casacore::Double *newValue,
298  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false,
299  const casacore::Bool permanent = false);
300 
301  void add(const casacore::String& name, casacore::Bool *newValue,
302  const casacore::Bool strict = false, const casacore::Bool permanent = false);
303 
304  void add(const casacore::String& name, casacore::String *newValue,
305  const casacore::Bool strict = false, const casacore::Bool permanent = false);
306 
307  void add(const casacore::String& name, casacore::Quantity *newValue,
308  const casacore::Bool strict = false, const casacore::Bool permanent = false);
309 
310 
311  void add(const casacore::String& name, casacore::Vector<casacore::uInt> *newValue,
312  const casacore::uInt tolerance = 0, const casacore::Bool strict = false,
313  const casacore::Bool permanent = false);
314 
315  void add(const casacore::String& name, casacore::Vector<casacore::Int> *newValue,
316  const casacore::Int tolerance = 0, const casacore::Bool strict = false,
317  const casacore::Bool permanent = false);
318 
319  void add(const casacore::String& name, casacore::Vector<casacore::Float> *newValue,
320  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false,
321  const casacore::Bool permanent = false);
322 
323  void add(const casacore::String& name, casacore::Vector<casacore::Double> *newValue,
324  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false,
325  const casacore::Bool permanent = false);
326 
327  void add(const casacore::String& name, casacore::Vector<casacore::Bool> *newValue,
328  const casacore::Bool strict = false, const casacore::Bool permanent = false);
329 
330  void add(const casacore::String& name, casacore::Vector<casacore::String> *newValue,
331  const casacore::Bool strict = false, const casacore::Bool permanent = false);
332 
333  void add(const casacore::String& name, casacore::Vector<casacore::Quantity> *newValue,
334  const casacore::Bool strict = false, const casacore::Bool permanent = false);
335 
336  // </group>
337 
338 
339  // Set the value of an Attribute. If the Attribute does not exist, it is
340  // created (using the corresponding add function with permanent set to
341  // false), otherwise the value of the existing Attribute, if it is of the
342  // correct type) will be changed. If the Attribute has a different type than
343  // the variable used in the set function, nothing happens (but I may change
344  // my mind and throw an exception).
345  // <group>
346  void set(const AttributeBuffer& otherBuf);
347  void set(const Attribute& newAttribute);
348 
349  void set(const casacore::String& name, const casacore::uInt newValue,
350  const casacore::uInt tolerance = 0, const casacore::Bool strict = false);
351 
352  void set(const casacore::String& name, const casacore::Int newValue,
353  const casacore::Int tolerance = 0, const casacore::Bool strict = false);
354 
355  void set(const casacore::String& name, const casacore::Float newValue,
356  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false);
357 
358  void set(const casacore::String& name, const casacore::Double newValue,
359  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false);
360 
361  void set(const casacore::String& name, const casacore::Bool newValue,
362  const casacore::Bool strict = false);
363 
364  void set(const casacore::String& name, const casacore::String& newValue,
365  const casacore::Bool strict = false);
366 
367  void set(const casacore::String& name, const casacore::Quantity newValue,
368  const casacore::Bool strict = false);
369 
370 
371  void set(const casacore::String& name, const casacore::Vector<casacore::uInt>& newValue,
372  const casacore::uInt tolerance = 0, const casacore::Bool strict = false);
373 
374  void set(const casacore::String& name, const casacore::Vector<casacore::Int>& newValue,
375  const casacore::Int tolerance = 0, const casacore::Bool strict = false);
376 
377  void set(const casacore::String& name, const casacore::Vector<casacore::Float>& newValue,
378  const casacore::Float tolerance = 0.0, const casacore::Bool strict = false);
379 
380  void set(const casacore::String& name, const casacore::Vector<casacore::Double>& newValue,
381  const casacore::Double tolerance = 0.0, const casacore::Bool strict = false);
382 
383  void set(const casacore::String& name, const casacore::Vector<casacore::Bool>& newValue,
384  const casacore::Bool strict = false);
385 
386  void set(const casacore::String& name, const casacore::Vector<casacore::String>& newValue,
387  const casacore::Bool strict = false);
388 
389  void set(const casacore::String& name, const casacore::Vector<casacore::Quantity>& newValue,
390  const casacore::Bool strict = false);
391 
392  // </group>
393 
394  // Get tha value of the named Attribute. Returns <src>true</src> for
395  // success, and <src>false</src> for failure. This can happen if the
396  // caller asked for the wrong type.
397  template <class T> casacore::Bool getValue(const casacore::String &name, casacore::Vector<T> &value) const;
398  template <class T> casacore::Bool getValue(const casacore::String &name, T &value) const;
399 
400  // Get the pointer to the Attribute if it exists, else get 0
401  Attribute *getAttribute(const casacore::String& name) const;
402 
403  // Get pointer to the AttributeValue if it exists, else get 0
405 
406  // Get the data type of the Attribute
408 
409  // casacore::Function to see if Attribute res matches any Attribute in the
410  // AttributeBuffer *this.
411  casacore::Bool matches(const Attribute& res) const;
412 
413  // casacore::Function to see if every Attribute in the AttributeBuffer resBuf
414  // matches every Attribute in the AttributeBuffer *this. Returns
415  // true if this is the case, returns false if for at least one Attribute
416  // in resBuf there is a mismatch.
417  casacore::Bool matches(const AttributeBuffer& resBuf) const;
418 
419  // AttributeBuffer addition arithmetic. Go through <src>*this</src>
420  // buffer, and for those Attributes who have equivalents in
421  // <src>other</src>, sum the values.
422  void operator+=(const AttributeBuffer &other);
423 
424  // Remove Attributes from the AttributeBuffer. Only works on Attributes that
425  // are not permanent
426  // <group>
427  void remove(const casacore::String& name);
428  void clear();
429  // </group>
430 
431  // Check if an Attribute with name name exists
432  casacore::Bool exists(const casacore::String& name) const;
433 
434  // Add the Attributes of *this to other
435  void addBuff(AttributeBuffer& other) const;
436 
437  // Set the Attributes of *this to other
438  void setBuff(AttributeBuffer& other) const;
439 
440  private:
441 
442  friend std::ostream &operator<<(std::ostream &, AttributeBuffer &);
443 
444  // casacore::PtrBlock for the Attributes. Should change this to a list
446 
447  // Store if an Attribute is permamnent or not
449 
450  // Internal routine to add an Attribute to the Buffer
451  void addAttributeToBuffer(Attribute *newAttribute, const casacore::Bool permanent);
452 
453  // Check if an Attribute exists and return the index in the PtrBlock
454  casacore::Bool exists(const casacore::String& name, casacore::Int& found) const;
455 
456  // Remove Attributes from the AttributeBuffer. Also erases Attributes that
457  // are permanent. Only used in operator=.
458  void erase();
459 
460  };
461 
462  std::ostream &operator<<(std::ostream &os, AttributeBuffer &ab);
463 
464 
465 } //# NAMESPACE CASA - END
466 
467 #ifndef AIPS_NO_TEMPLATE_SRC
468 #include <display/Display/AttBufferTemplates.tcc>
469 #endif
470 
471 #endif
void setBuff(AttributeBuffer &other) const
Set the Attributes of *this to other.
void addAttributeToBuffer(Attribute *newAttribute, const casacore::Bool permanent)
Internal routine to add an Attribute to the Buffer.
int Int
Definition: aipstype.h:50
const AttributeBuffer & operator=(const AttributeBuffer &other)
Assignement operator.
friend std::ostream & operator<<(std::ostream &, AttributeBuffer &)
casacore::Bool exists(const casacore::String &name) const
Check if an Attribute with name name exists.
AttributeBuffer()
Constructor of empty buffer.
ostream & operator<<(ostream &os, const PageHeaderCache &cache)
casacore::Int nelements() const
Return number of Attributes in the buffer.
Buffer for storing Attributes.
AttValue::ValueType getDataType(const casacore::String &name) const
Get the data type of the Attribute.
casacore::PtrBlock< Attribute * > attributes
casacore::PtrBlock for the Attributes.
ABSTRACT CLASSES Abstract class for colors Any implementation of color should be able to provide a hexadecimal form of the if a human readable name(i.e."black").In many places throughout the plotter
Arbitrary name-value pairs used in the display classes.
Definition: Attribute.h:144
ValueType
The possible value types.
Definition: AttValBase.h:82
Attribute * getAttribute(const casacore::String &name) const
Get the pointer to the Attribute if it exists, else get 0.
void operator+=(const AttributeBuffer &other)
AttributeBuffer addition arithmetic.
casacore::Bool matches(const Attribute &res) const
casacore::Function to see if Attribute res matches any Attribute in the AttributeBuffer *this...
~AttributeBuffer()
Destructor.
double Double
Definition: aipstype.h:55
void erase()
Remove Attributes from the AttributeBuffer.
AttributeValueBase * getAttributeValue(const casacore::String &name) const
Get pointer to the AttributeValue if it exists, else get 0.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Base class for values of Attributes used in the display classes.
Definition: AttValBase.h:182
float Float
Definition: aipstype.h:54
void set(const AttributeBuffer &otherBuf)
Set the value of an Attribute.
A drop-in replacement for Block&lt;T*&gt;.
Definition: WProjectFT.h:54
void add(const AttributeBuffer &otherBuf)
Define new Attributes.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void addBuff(AttributeBuffer &other) const
Add the Attributes of *this to other.
casacore::Block< casacore::Bool > nonDeletable
Store if an Attribute is permamnent or not.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:51
casacore::Bool getValue(const casacore::String &name, casacore::Vector< T > &value) const
Get tha value of the named Attribute.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42