casa
$Rev:20696$
|
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