casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
DisplayParameter.h
Go to the documentation of this file.
00001 //# DisplayParameter.h: base class for storing and parsing parameters 
00002 //# Copyright (C) 2000,2001
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_DISPLAYPARAMETER_H
00029 #define TRIALDISPLAY_DISPLAYPARAMETER_H
00030 
00031 #include <casa/aips.h>
00032 #include <casa/Containers/Record.h>
00033 #include <display/Utilities/DisplayOptions.h>
00034 
00035 namespace casa { //# NAMESPACE CASA - BEGIN
00036 
00037 // <summary>
00038 // Base class for storing and parsing of parameters for display classes.
00039 // </summary>
00040 
00041 // <use visibility=local>
00042 
00043 // <reviewed reviewer="" date="" test="" demos="">
00044 // </reviewed>
00045 
00046 // <prerequisite>
00047 // <li> <linkto class=DisplayOptions>DisplayOptions</linkto>
00048 // </prerequisite>
00049 
00050 // <etymology>
00051 // DisplayParameter is a base class which provides services for
00052 // conveniently storing and parsing parameters relevant to the display
00053 // classes.
00054 // </etymology>
00055 
00056 // <synopsis>
00057 // DisplayParameter defines a relatively simple interface for writing
00058 // small containers for the various types of parameters used
00059 // throughout the display classes.  The required interface consists of
00060 // methods to update the parameter value from an incoming
00061 // <src>RecordInterface</src>-type object, and to add the description
00062 // of the parameter to a provided <src>RecordInterface</src> object.
00063 //
00064 // Other than this, all parameters share these common elements: 
00065 //
00066 // <li> <src>name</src>, a short <src>String</src> uniquely
00067 // identifiying the parameter.
00068 //
00069 // <li> <src>description</src>, a slightly longer <src>String</src>
00070 // which offers a description of the parameter, suitably short for
00071 // display in a graphical user interface, for example.
00072 //
00073 // <li> <src>help</src>, an even longer <src>String</src> (!) which
00074 // should be filled in with text describing the option in more detail
00075 // than can be given in <src>description</src>
00076 //
00077 // <li> <src>context</src>, which if provided (ie. <src>context !=
00078 // String("")</src>) gives a category name for this parameter, and is
00079 // used, for example, by the autogui to place the parameter in an 
00080 // appropriately named roll-up.
00081 //
00082 // <li> <src>allowunset</src>, which indicates whether this parameter
00083 // can be "unset" or not.  An "unset" parameter is one for which a
00084 // sensible (perhaps context sensitive) default can be determined and
00085 // used.  Derived classes need not provide this option in their
00086 // constructor.
00087 //
00088 // <li> <src>editable</src>, which indicates whether this parameter is
00089 // allowed to be modified by the user.
00090 //
00091 // DisplayParameter makes use of the <linkto
00092 // class=DisplayOptions>DisplayOptions</linkto> class to parse Records
00093 // containing parameter descriptions.  Derived classes must implement
00094 // the two virtual methods <src>toRecord</src> and
00095 // <src>fromRecord</src>, which respectively store a description of
00096 // the DisplayParameter in a sub-field of the provided
00097 // RecordInterface, and extract the value of the DisplayParameter from
00098 // a sub-field in the provided record.  The sub-field is identified by
00099 // the <src>name</src> of the DisplayParameter.
00100 //
00101 // Derived classes should also add utility functions which return the
00102 // various aspects of the DisplayParameter to the programmer.  Most
00103 // importantly, a <src>value()</src> function should be provided to
00104 // enable the user to easily retrieve the current value of the
00105 // parameter.
00106 // </synopsis>
00107 
00108 // <motivation> 
00109 // To avoid littering many of the display classes with code fragments
00110 // for constructing and parsing Records.
00111 // </motivation>
00112 
00113 // <thrown>
00114 // <li> None.
00115 // </thrown>
00116 
00117 // <todo asof="2000/01/28">
00118 // <li> Provide base class support for unset values.
00119 // </todo>
00120 
00121 class DisplayParameter {
00122 
00123  public:
00124 
00125   // Destructor.
00126   virtual ~DisplayParameter();
00127 
00128   // Parse <src>record</src>, and update this parameter if a field
00129   // exists whose name matches that of this parameter.  Return
00130   // <src>True</src> if the parameter is changed, otherwise return
00131   // <src>False</src>.
00132   virtual Bool fromRecord(const RecordInterface &record) = 0;
00133 
00134   // Place a record describing this parameter in a sub-field of
00135   // <src>record</src> with name matching that of this parameter.  If
00136   // <src>overwrite</src> is <src>True</src>, then any existing field
00137   // with matching name will be overwritten.  If <src>fullrecord</src>
00138   // is <src>True</src>, then a complete description of the parameter
00139   // is given, otherwise just its current value is stored in
00140   // <src>record</src>.
00141   virtual void toRecord(RecordInterface &record, const Bool fullrecord = True,
00142                         const Bool overwrite = False) = 0;
00143 
00144   // Return the name of this parameter.
00145   String name() const 
00146     { return itsName; }
00147 
00148   // Return the description of this parameter.
00149   String description() const 
00150     { return itsDescription; }
00151 
00152   // Return the help for this parameter.
00153   String help() const 
00154     { return itsHelp; }
00155 
00156   // Return the context of this parameter.
00157   String context() const
00158     { return itsContext; }
00159 
00160   // Return whether this parameter can be unset.
00161   Bool allowUnset() const
00162     { return itsAllowUnset; }
00163 
00164   // Return whether this parameter is editable.
00165   Bool editable() const
00166     { return itsEditable; }
00167 
00168   // Set or change the name of this parameter to that specified.
00169   void setName(const String name)
00170     { itsName = name; }
00171 
00172   // Set or change the description of this parameter to what is
00173   // specified.
00174   void setDescription(const String description)
00175     { itsDescription = description; }
00176 
00177   // Set or change the help for this parameter to what is specified.
00178   void setHelp(const String help) 
00179     { itsHelp = help; }
00180 
00181   // Set or change the context of this parameter to what is specified.
00182   void setContext(const String context) 
00183     { itsContext = context; }
00184 
00185   // Set or change whether this parameter may be unset, according to
00186   // the function argument value.
00187   void setAllowUnset(const Bool allowunset) 
00188     { itsAllowUnset = allowunset; }
00189 
00190   // Set or change whether this parameter is editable according to
00191   // the function argument.
00192   void setEditable(const Bool editable) 
00193     { itsEditable = editable; }
00194 
00195  protected:
00196 
00197   // Constructor taking the name of the parameter, a short
00198   // description, some help text, and flags indicating whether the
00199   // parameter can be unset and is editable.
00200   DisplayParameter(const String name, const String description,
00201                    const String help, const String context = "",
00202                    const Bool allowunset = False, 
00203                    const Bool editable = True);
00204 
00205   // Copy constructor using copy semantics.
00206   DisplayParameter(const DisplayParameter &other);
00207 
00208   // Default constructor yielding a useless DisplayParameter.
00209   DisplayParameter();
00210 
00211   // Copy assignment.
00212   DisplayParameter &operator=(const DisplayParameter &other);
00213 
00214   // Return a basic description of this parameter; used by virtual
00215   // implementations of <src>toRecord</src> method to fill out
00216   // a Record describing this DisplayParameter.
00217   Record baseDescription();
00218 
00219   // Return the DisplayOptions to use for parsing Records.
00220   const DisplayOptions &displayOptions() const 
00221     { return itsDisplayOptions; }
00222 
00223  private:
00224 
00225   // Store for the name of this parameter.
00226   String itsName;
00227 
00228   // Store for the description of this parameter.
00229   String itsDescription;
00230 
00231   // Store for the help for this parameter.
00232   String itsHelp;
00233 
00234   // Store for the context of this parameter.
00235   String itsContext;
00236 
00237   // Store for whether this parameter can be unset.
00238   Bool itsAllowUnset;
00239 
00240   // Store for whether this parameter is editable.
00241   Bool itsEditable;
00242 
00243   // Store for a DisplayOptions object for parsing Records.
00244   DisplayOptions itsDisplayOptions;
00245 
00246 };
00247 
00248 
00249 } //# NAMESPACE CASA - END
00250 
00251 #endif