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 
00149                 // Return the description of this parameter.
00150                 String description() const {
00151                         return itsDescription;
00152                 }
00153 
00154                 // Return the help for this parameter.
00155                 String help() const {
00156                         return itsHelp;
00157                 }
00158 
00159                 // Return the context of this parameter.
00160                 String context() const {
00161                         return itsContext;
00162                 }
00163 
00164                 // Return whether this parameter can be unset.
00165                 Bool allowUnset() const {
00166                         return itsAllowUnset;
00167                 }
00168 
00169                 // Return whether this parameter is editable.
00170                 Bool editable() const {
00171                         return itsEditable;
00172                 }
00173 
00174                 // Set or change the name of this parameter to that specified.
00175                 void setName(const String name) {
00176                         itsName = name;
00177                 }
00178 
00179                 // Set or change the description of this parameter to what is
00180                 // specified.
00181                 void setDescription(const String description) {
00182                         itsDescription = description;
00183                 }
00184 
00185                 // Set or change the help for this parameter to what is specified.
00186                 void setHelp(const String help) {
00187                         itsHelp = help;
00188                 }
00189 
00190                 // Set or change the context of this parameter to what is specified.
00191                 void setContext(const String context) {
00192                         itsContext = context;
00193                 }
00194 
00195                 // Set or change whether this parameter may be unset, according to
00196                 // the function argument value.
00197                 void setAllowUnset(const Bool allowunset) {
00198                         itsAllowUnset = allowunset;
00199                 }
00200 
00201                 // Set or change whether this parameter is editable according to
00202                 // the function argument.
00203                 void setEditable(const Bool editable) {
00204                         itsEditable = editable;
00205                 }
00206 
00207         protected:
00208 
00209                 // Constructor taking the name of the parameter, a short
00210                 // description, some help text, and flags indicating whether the
00211                 // parameter can be unset and is editable.
00212                 DisplayParameter(const String name, const String description,
00213                                  const String help, const String context = "",
00214                                  const Bool allowunset = False,
00215                                  const Bool editable = True);
00216 
00217                 // Copy constructor using copy semantics.
00218                 DisplayParameter(const DisplayParameter &other);
00219 
00220                 // Default constructor yielding a useless DisplayParameter.
00221                 DisplayParameter();
00222 
00223                 // Copy assignment.
00224                 DisplayParameter &operator=(const DisplayParameter &other);
00225 
00226                 // Return a basic description of this parameter; used by virtual
00227                 // implementations of <src>toRecord</src> method to fill out
00228                 // a Record describing this DisplayParameter.
00229                 Record baseDescription();
00230 
00231                 // Return the DisplayOptions to use for parsing Records.
00232                 const DisplayOptions &displayOptions() const {
00233                         return itsDisplayOptions;
00234                 }
00235 
00236         private:
00237 
00238                 // Store for the name of this parameter.
00239                 String itsName;
00240 
00241                 // Store for the description of this parameter.
00242                 String itsDescription;
00243 
00244                 // Store for the help for this parameter.
00245                 String itsHelp;
00246 
00247                 // Store for the context of this parameter.
00248                 String itsContext;
00249 
00250                 // Store for whether this parameter can be unset.
00251                 Bool itsAllowUnset;
00252 
00253                 // Store for whether this parameter is editable.
00254                 Bool itsEditable;
00255 
00256                 // Store for a DisplayOptions object for parsing Records.
00257                 DisplayOptions itsDisplayOptions;
00258 
00259         };
00260 
00261 
00262 } //# NAMESPACE CASA - END
00263 
00264 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1