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