casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Attribute.h
Go to the documentation of this file.
00001 //# Attribute.h: arbitrary name-value pairs used in the display classes
00002 //# Copyright (C) 1996,1997,1999,2000,2001,2002
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef TRIALDISPLAY_ATTRIBUTE_H
00029 #define TRIALDISPLAY_ATTRIBUTE_H
00030 
00031 #include <casa/aips.h>
00032 #include <display/Display/AttValBase.h>
00033 
00034 namespace casa { //# NAMESPACE CASA - BEGIN
00035 
00036 class String;
00037 
00038 // <summary> 
00039 // Arbitrary name-value pairs used in the display classes.
00040 // </summary>
00041 
00042 // <use visibility=export>
00043  
00044 // <reviewed reviewer="" date="yyyy/mm/dd" tests="tAttribute" demos="">
00045 // </reviewed>
00046  
00047 // <prerequisite>
00048 // <li> <linkto class="AttributeValueBase">AttributeValueBase</linkto>
00049 // <li> <linkto class="AttributeValue">AttributeValue</linkto>
00050 // <li> <linkto class="AttributeValueTol">AttributeValueTol</linkto>
00051 // </prerequisite>
00052 
00053 // <etymology> 
00054 // An Attribute characterises something by associating a value with a
00055 // name.
00056 // </etymology>
00057 
00058 // <synopsis>
00059 // An Attribute is the combination of a name and a value.  The name is
00060 // a String, while the value can be of any of the types Int, Float,
00061 // Double, Bool, String or <linkto class=Quantum>Quantum</linkto>,
00062 // or a <linkto class=Vector>Vector</linkto> of any of these types.
00063 //
00064 // Attributes can be compared to see if they match.  They can also be
00065 // made "fuzzy" by providing a user-specified tolerance, and then
00066 // matching means <src>abs(val1-val2) <= tol</src>.  An Attribute can
00067 // also be "strict" if required: if so, then Attributes with Vector
00068 // values are deemed to match if their values match element-wise.
00069 // Otherwise, the Attributes match if any one element in one
00070 // Attribute's value matches any one element in the other Attribute's
00071 // value.  In the latter case, the Attribute Vector values do not have 
00072 // to be conformant.
00073 // </synopsis>
00074 //
00075 // <example>
00076 // The following example shows the construction and retrieval of an
00077 // Attribute.
00078 // <srcblock>
00079 // Attribute att("axisname", "Right ascension (J2000)");
00080 // ...
00081 //
00082 // AttributeValue<String>* pAv = dynamic_cast<AttributeValue<String>*>(att.getAttributeValue());
00083 // String axisname = pAv->getValue()(0);
00084 // if (axisname == "Right ascension (J2000)") {
00085 //   ...
00086 // } else {
00087 //   throw(AipsError("Doing nothing because axisname Attribute unsuitable"));
00088 // }
00089 // </srcblock>
00090 //
00091 // The following example uses the Attribute equality operator to 
00092 // determine some state.
00093 // <srcblock>
00094 // /* "itsAxisName" is some private String */
00095 // Attribute att("axisname", itsAxisName);
00096 // ...
00097 // Attribute currentAtt("axisname", "Stokes");
00098 // if (currentAtt == att) {
00099 //   ...
00100 // } else {
00101 //   ...
00102 // }
00103 // </srcblock>
00104 //
00105 // A more complete example, exhibiting the Attribute interface to a
00106 // specific display class, the <linkto
00107 // class=WorldCanvas>WorldCanvas</linkto>, follows.
00108 // <srcblock>
00109 // /* assume we are working on a WorldCanvas "wcanvas" */
00110 // /* at some point, an Attribute has been set elsewhere like this:
00111 //    wcanvas.setAttribute("ColorModel", "RGB");
00112 // */
00113 // ... 
00114 // /* somewhere later in the program ... */
00115 // if (wcanvas.existsAttribute("ColorModel")) {
00116 //   String colormodel;
00117 //   wcanvas.getAttribute("ColorModel", colormodel);
00118 //   if (colormodel == "RGB") {
00119 //     ...
00120 //   } else {
00121 //     ...
00122 //   }
00123 // } else {
00124 //   ...
00125 // }
00126 // </srcblock>
00127 // </example>
00128 
00129 // <motivation>
00130 // The main motivation for introducing Attributes is to be able to
00131 // attach arbitrary name-value pairs to various objects in the display
00132 // classes.  This allows the storage, retrieval and comparison of
00133 // arbitrary information from the various display objects.
00134 // </motivation>
00135 
00136 // <todo asof="2000/01/17">
00137 // <li> Re-write <src>setValue</src> function.
00138 // </todo>
00139  
00140 class Attribute {
00141 
00142  public: 
00143 
00144   // Constructor taking an AttributeValueBase.  By inheriting from
00145   // AttributeValueBase, additional types of Attributes can be 
00146   // supported. 
00147   Attribute(const String &name, const AttributeValueBase& value);
00148 
00149   // Copy constructor.
00150   Attribute(const Attribute& other);
00151 
00152   // Constructors that take a single value.  The value stored in an
00153   // Attribute can be made fuzzy by giving some tolerance
00154   // <src>tol</src>, and when the values can be compared to see if
00155   // they match, the tolerance is taken into account where it makes
00156   // sense.  The parameter <src>strict</src> determines how the
00157   // matching is done for the values.  If <src>strict == True</src>,
00158   // the values have to match elementwise (a single value is
00159   // considered a Vector of length 1).  If <src>strict == False</src>,
00160   // the values match if any one element in one value matches any one
00161   // elemnt in the other value.
00162   // <group>
00163   Attribute(const String &name, const uInt value, 
00164             const uInt tolerance = 0, const Bool strict = False);
00165   Attribute(const String &name, const Int value, 
00166             const Int tolerance = 0, const Bool strict = False);
00167   Attribute(const String &name, const Float value, 
00168             const Float tolerance = 0.0, const Bool strict = False);
00169   Attribute(const String &name, const Double value, 
00170             const Double tolerance = 0.0, const Bool strict = False);
00171   Attribute(const String &name, const Quantity value,
00172             const Bool strict = False);
00173   Attribute(const String &name, const Quantity value,
00174             const Quantity tolerance, Bool strict = False);
00175   Attribute(const String &name, const Bool value, 
00176             const Bool strict = False);
00177   Attribute(const String &name, const String value, 
00178             const Bool strict = False);
00179   // </group>
00180 
00181   // Contructors that take a <src>Vector</src> of the various
00182   // types. Once again, the value stored in an Attribute can be made
00183   // fuzzy by specifying <src>tol</src> or strict by putting
00184   // <src>strict = True</src>.
00185   // <group>
00186   Attribute(const String &name, const Vector<uInt> value, 
00187             const uInt tolerance = 0, const Bool strict = False);
00188   Attribute(const String &name, const Vector<Int> value, 
00189             const Int tolerance = 0, const Bool strict = False);
00190   Attribute(const String &name, const Vector<Float> value, 
00191             const Float tolerance = 0.0, const Bool strict = False);
00192   Attribute(const String &name, const Vector<Double> value, 
00193             const Double tolerance = 0.0, const Bool strict = False);
00194   Attribute(const String &name, const Vector<Quantity> value,
00195             const Bool strict = False);
00196   Attribute(const String &name, const Vector<Quantity> value,
00197             const Quantity tolerance, const Bool strict = False);
00198   Attribute(const String &name, const Vector<Bool> value, 
00199             const Bool strict = False);
00200   Attribute(const String &name, const Vector<String> value, 
00201             const Bool strict = False);
00202   //</group>
00203  
00204   // Constructors that take a pointer to a variable. This makes the
00205   // Attribute an alias for the variable, changing the variable
00206   // changes the value of the Attribute and vice versa.  Other
00207   // functionality the same as for the other constructors.
00208  // <group>
00209   Attribute(const String &name, uInt *value, 
00210             const uInt tolerance = 0, const Bool strict = False);
00211   Attribute(const String &name, Int *value, 
00212             const Int tolerance = 0, const Bool strict = False);
00213   Attribute(const String &name, Float *value, 
00214             const Float tolerance = 0.0, const Bool strict = False);
00215   Attribute(const String &name, Double  *value, 
00216             const Double tolerance = 0.0, const Bool strict = False);
00217   Attribute(const String &name, Bool *value, 
00218             const Bool strict = False);
00219   Attribute(const String &name, String *value, 
00220             const Bool strict = False);
00221   Attribute(const String &name, Quantity *value,
00222             const Bool strict = False);
00223   Attribute(const String &name, Quantity *value,
00224             const Quantity tolerance, const Bool strict = False);
00225   // </group>
00226 
00227   // Constructors that take a pointer to a Vector.  This again makes
00228   // the Attribute an alias for the Vector: changing the Vector
00229   // changes the value of the Attribute, and vice versa.  Other
00230   // functionality is the same as for the non-aliasing constructors.
00231   // <group>
00232   Attribute(const String &name,  Vector<uInt> *value, 
00233             const uInt tolerance = 0, const Bool strict = False);
00234   Attribute(const String &name,  Vector<Int> *value, 
00235             const Int tolerance = 0, const Bool strict = False);
00236   Attribute(const String &name,  Vector<Float> *value, 
00237             const Float tolerance = 0.0, const Bool strict = False);
00238   Attribute(const String &name,  Vector<Double>  *value, 
00239             const Double tolerance = 0.0, const Bool strict = False);
00240   Attribute(const String &name, Vector<Quantity> *value,
00241             const Bool strict = False);
00242   Attribute(const String &name, Vector<Quantity> *value,
00243             const Quantity tolerance, const Bool strict = False);
00244   Attribute(const String &name,  Vector<Bool> *value, 
00245             const Bool strict = False);
00246   Attribute(const String &name, Vector<String> *value,
00247             const Bool strict = False);
00248   //</group>
00249 
00250   // Destructor.
00251   virtual ~Attribute();
00252 
00253   // Create a new copy of the Attribute and return a pointer to the
00254   // copy (virtual constructor).
00255   virtual Attribute* clone() const;
00256 
00257   // Attribute matching: returns <src>True</src> if <src>*this</src>
00258   // and <src>other</src> match, otherwise returns <src>False</src>.
00259   // <note role=caution>Two Attributes match if their names are
00260   // different.  If two Attributes have the same name, but the values
00261   // stored in the Attributes have different types, they do not match.
00262   // An Attribute of a single value and an Attribute of a Vector of
00263   // values of the same type are considered to have the same type, so
00264   // under certain circumstances (based on the strictness of the
00265   // Attributes) two such Attributes may match.</note>
00266   virtual Bool operator==(const Attribute &other) const;
00267 
00268   // The opposite of the Attribute matching.
00269   Bool operator!=(const Attribute &other) const;
00270 
00271   // Attribute addition ... add the value of <src>other</src> to
00272   // the value of <src>*this</src>.
00273   virtual void operator+=(const Attribute &other);
00274     
00275   // Set the value of this Attribute to that of the <src>other</src>
00276   // Attribute, if, and only if, they have the same value type.  <note
00277   // role=caution> This method makes an important assumption, namely
00278   // that all AttributeValues that return AttValue::AtInt,
00279   // AttValue::AtFloat or AttValue::AtDouble are derived from
00280   // AttributeValueTol and that return AttValue::AtBool,
00281   // AttValue::AtString or AttValue::AtQuantity are derived from
00282   // AttributeValue (ie they are like they are created by
00283   // Attribute). This is ok for <src>*this</src>, but there is no
00284   // guarantee that it is correct for <src>other</src>.  This
00285   // assumption was not needed until the AttributeValuePoi class was
00286   // written.  AttributeValues were not supposed to change but were
00287   // supposed to be replaced.  Now this is very ugly and should be
00288   // rewritten.  Indeed, it fails now for Quantities, since both with
00289   // and without tols are used at the moment. </note>
00290   virtual void setValue(const Attribute &other);
00291     
00292   // Returns a pointer to the AttributeValue base class object.  You must cast
00293   // it to AttributeValue<T> and invoke function <src>getValue</src> to 
00294   // get the value of the attribute
00295   AttributeValueBase* getAttributeValue() const;
00296 
00297   // Return the name of the Attribute.
00298   String getName() const;
00299 
00300   // Return the DataType of the value of the Attribute.
00301   AttValue::ValueType getType() const;
00302 
00303 private:
00304 
00305   // The name of the Attribute.
00306   String itsAttributeName;
00307 
00308   // Pointer to the attribute base class
00309   AttributeValueBase* itsAttributeValue;
00310 
00311   // (Required) default constructor.
00312   Attribute();
00313 
00314   // Copy assignment.  <note role=caution>This allows the type of the
00315   // AttributeValue to change, so it is private.</note>
00316   virtual const Attribute &operator=(const Attribute &other);
00317 
00318 };
00319 
00320 ostream &operator<<(ostream &os, Attribute &a);
00321 
00322 
00323 } //# NAMESPACE CASA - END
00324 
00325 #endif
00326