casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
PlotMSWatchedParameters.h
Go to the documentation of this file.
00001 //# PlotMSWatchedParameters.h: Classes for watched/synchronized parameters.
00002 //# Copyright (C) 2009
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 #ifndef PLOTMSWATCHEDPARAMETERS_H_
00028 #define PLOTMSWATCHEDPARAMETERS_H_
00029 
00030 #include <casa/BasicSL/String.h>
00031 
00032 #include <vector>
00033 
00034 #include <casa/namespace.h>
00035 using namespace std;
00036 
00037 namespace casa {
00038 
00039 //# Forward Declarations
00040 class PlotMSWatchedParameters;
00041 
00042 
00043 // Interface for classes that wish to be notified when PlotMSWatchedParameters
00044 // have changed.  This watching system is used to keep the different aspects of
00045 // PlotMS synchronized with parameters that could potentially come from many
00046 // different sources.
00047 class PlotMSParametersWatcher {
00048 public:
00049     // Constructor.
00050     PlotMSParametersWatcher() { }
00051     
00052     // Destructor.
00053     virtual ~PlotMSParametersWatcher() { }
00054     
00055     
00056     // This method is called whenever the watched parameters have been changed.
00057     // This can either happen immediately after any change or, if notification
00058     // has been held via PlotMSWatchedParameters::holdNotification, when
00059     // notification is released via
00060     // PlotMSWatchedParameters::releaseNotification.  If this watcher is the
00061     // watcher that was holding notifications, this method is NOT called.
00062     // The updateFlag parameter lets the watcher know which categories the
00063     // changes were in.
00064     virtual void parametersHaveChanged(const PlotMSWatchedParameters& params,
00065             int updateFlag) = 0;
00066 };
00067 
00068 
00069 // Abstract class for parameters that may be watched by one or more interested
00070 // classes.  Any subclass is assumed to have different properties in one or
00071 // more of the update categories defined different update flag values which
00072 // must be registered with the public static methods in
00073 // PlotMSWatchedParameters.  Using this system, any classes watching the
00074 // parameters for changes can be notified which categories the changes occurred
00075 // in.
00076 class PlotMSWatchedParameters {
00077 public:
00078     // Static //
00079     
00080     // "Base", or no updates, flag.
00081     static const int NO_UPDATES;
00082     
00083     
00084     // Registers an update flag with the given name (if it is not already
00085     // registered) and returns its flag value.
00086     static int REGISTER_UPDATE_FLAG(const String& name);
00087     
00088     // Unregisters the given update flag, if it is registered.
00089     // <group>
00090     static void UNREGISTER_UPDATE_FLAG(const String& name);
00091     static void UNREGISTER_UPDATE_FLAG(int flag);
00092     // </group>
00093     
00094     // Converts between an update flag's name and value, if valid.
00095     // <group>
00096     static int UPDATE_FLAG(const String& name);
00097     static String UPDATE_FLAG(int flag);
00098     // </group>
00099     
00100     // Returns all registered update flags.
00101     // <group>
00102     static vector<int> UPDATE_FLAGS();
00103     static vector<String> UPDATE_FLAG_NAMES();
00104     // </group>
00105     
00106     // Returns all registered update flags as one or-ed value.
00107     static int ALL_UPDATE_FLAGS();
00108     
00109     // Returns all registered update flags that were turned on in the given
00110     // flags value.
00111     // <group>
00112     static vector<int> UPDATE_FLAGS(int value);
00113     static vector<String> UPDATE_FLAG_NAMES(int value);
00114     // </group>
00115     
00116     
00117     // Non-Static //
00118     
00119     // Constructor.
00120     PlotMSWatchedParameters();
00121     
00122     // Destructor.
00123     virtual ~PlotMSWatchedParameters();
00124     
00125     
00126     // Adds/Removes the given watcher for this PlotMSParameters.
00127     // <group>
00128     void addWatcher(PlotMSParametersWatcher* watcher);
00129     void removeWatcher(PlotMSParametersWatcher* watcher);
00130     // </group>
00131     
00132     // Holds update notifications for any registered watchers.  Notifications
00133     // will not be sent out until releaseNotification() is called.  If a
00134     // non-NULL watcher is given, it will be excluded from notifications when
00135     // releaseNotification() is called.
00136     void holdNotification(PlotMSParametersWatcher* updater = NULL);
00137     
00138     // Releases update notification; notifies all watchers of an update except
00139     // for the one (if any) that called holdNotification.
00140     void releaseNotification();
00141     
00142     // Equality operators.
00143     // <group>
00144     virtual bool operator==(const PlotMSWatchedParameters& other) const {
00145         return equals(other, ALL_UPDATE_FLAGS()); }
00146     virtual bool operator!=(const PlotMSWatchedParameters& other) const {
00147         return !(operator==(other)); }
00148     // </group>
00149     
00150     
00151     // ABSTRACT METHODS //
00152     
00153     // Returns true if this PlotMSParameters equals the other, in the given
00154     // update categories flag.
00155     virtual bool equals(const PlotMSWatchedParameters& other,
00156                         int updateFlags) const = 0;    
00157 
00158 protected:
00159     // Returns the current update flag.
00160     int currentUpdateFlag() const;
00161     
00162     // Provides access to children to indicate whether the given update flag
00163     // should be turned on or off.  This should be used by setter functions to
00164     // classify the changes appropriately.  If update notifications are NOT
00165     // being held, any watchers will immediately be notified of the change.
00166     // <group>
00167     void updateFlag(int updateFlag, bool on = true);
00168     void updateFlag(const String& updateFlagName, bool on = true);
00169     // </group>
00170     
00171     // Provides access to children to indicate which update flags are on.
00172     // The given value should be a bit-wise or of one or more UpdateFlag
00173     // enum values.
00174     void updateFlags(int updateFlags);
00175     
00176 private:
00177     // Current update flags.
00178     int itsUpdateFlags_;
00179     
00180     // Watchers.
00181     vector<PlotMSParametersWatcher*> itsWatchers_;
00182     
00183     // Flag for whether notifications are currently being held or not.
00184     bool isHolding_;
00185     
00186     // Watcher that is currently holding notifications, or NULL for none.
00187     PlotMSParametersWatcher* itsUpdater_;
00188     
00189     
00190     // Static //
00191     
00192     // Registered flags.
00193     static vector<int> FLAGS;
00194     
00195     // Registered flag names.
00196     static vector<String> NAMES;
00197 };
00198 
00199 }
00200 
00201 #endif /* PLOTMSWATCHEDPARAMETERS_H_ */