casa
$Rev:20696$
|
00001 //# MultiWCHolder.h: Holder of multiple WorldCanvasHolders for panelling 00002 //# Copyright (C) 2000,2001,2003 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_MULTIWCHOLDER_H 00029 #define TRIALDISPLAY_MULTIWCHOLDER_H 00030 00031 #include <casa/aips.h> 00032 #include <casa/Containers/List.h> 00033 #include <display/Display/DisplayEnums.h> 00034 #include <display/Display/AttributeBuffer.h> 00035 00036 namespace casa { //# NAMESPACE CASA - BEGIN 00037 00038 class WorldCanvasHolder; 00039 class DisplayData; 00040 class AttributeBuffer; 00041 class String; 00042 00043 // <summary> 00044 // A holder of WorldCanvasHolders to use for panelling applications. 00045 // </summary> 00046 // 00047 // <use visibility=export> 00048 // 00049 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos=""> 00050 // </reviewed> 00051 // 00052 // <prerequisite> 00053 // <li><linkto class="WorldCanvasHolder">WorldCanvasHolder</linkto> 00054 // <li><linkto class="DisplayData">DisplayData</linkto> 00055 // <li><linkto class="Attribute">Attribute</linkto> 00056 // <li><linkto class="AttributeBuffer">AttributeBuffer</linkto> 00057 // </prerequisite> 00058 // 00059 // <etymology> 00060 // The MultiWCHolder holds a number of WorldCanvasHolders to simplify 00061 // panelling operations. 00062 // </etymology> 00063 // 00064 // <synopsis> 00065 // This class is a holder of <linkto 00066 // class=WorldCanvasHolder>WorldCanvasHolder</linkto> objects. It 00067 // exists to facilitate the management of multiple WorldCanvasHolders 00068 // having in common a set of restrictions, which for example may be 00069 // for controlling animation, and on which a common set of 00070 // DisplayDatas may be registered and displayed. 00071 // 00072 // The basic interface to the MultiWCHolder provides methods for 00073 // adding and removing individual WorldCanvasHolder objects, for 00074 // globally registering and unregistering DisplayData objects for 00075 // display on the WorldCanvasHolder objects, and for applying a set 00076 // of restrictions to the WorldCanvasHolder objects. 00077 // 00078 // At a more advanced level, functions exist to distribute varying 00079 // restrictions across all the WorldCanvasHolder objects. For 00080 // example, the programmer can use 00081 // <src>linearDistributeRestriction</src> to apply a restriction to 00082 // each WorldCanvasHolder, where the value of the restriction is 00083 // incremented by a fixed amount between each WorldCanvasHolder. This 00084 // would be useful, for example, to easily display a set of planes 00085 // from a multi-frequency image on a number of WorldCanvases whose 00086 // WorldCanvasHolders have been added to a MultiWCHolder. 00087 // </synopsis> 00088 // 00089 // <example> 00090 // </example> 00091 // 00092 // <motivation> 00093 // </motivation> 00094 00095 class MultiWCHolder { 00096 00097 public: 00098 00099 // Constructor which makes an empty MultiWCHolder. 00100 MultiWCHolder(); 00101 00102 // Constructor which makes a MultiWCHolder containing the single 00103 // specified WorldCanvasHolder. 00104 MultiWCHolder(WorldCanvasHolder& holder); 00105 00106 // Destructor. 00107 virtual ~MultiWCHolder(); 00108 00109 // Add or remove a WorldCanvasHolder, or remove all 00110 // WorldCanvasHolders on this MultiWCHolder. <src>holder</src> is 00111 // added at the end of the list. When a new WorldCanvasHolder is 00112 // added, it will automatically have all registered DisplayDatas 00113 // added to it. 00114 // <group> 00115 virtual void addWCHolder(WorldCanvasHolder& holder); 00116 virtual void removeWCHolder(WorldCanvasHolder& holder); 00117 virtual void removeWCHolders(); 00118 // </group> 00119 00120 // Add or remove a DisplayData, or remove all DisplayDatas on this 00121 // MultiWCHolder. 00122 // <group> 00123 virtual void addDisplayData(DisplayData& displaydata, int position = -1); 00124 virtual void removeDisplayData(DisplayData& displaydata); 00125 virtual void removeDisplayDatas(); 00126 // </group> 00127 00128 // Install or remove a single restriction, or a buffer of 00129 // restrictions, on all of the WorldCanvasHolders managed by this 00130 // MultiWCHolder. 00131 // <group> 00132 virtual void setRestriction(const Attribute& restriction); 00133 virtual void setRestrictions(const AttributeBuffer& restrictions); 00134 virtual void removeRestriction(const String& name); 00135 virtual void removeRestrictions(); 00136 // </group> 00137 00138 // Incrementally distribute restrictions to all of the 00139 // WorldCanvasHolders. The value of the restrictions are 00140 // incremented by the given amount for each holder beyond the first 00141 // one. The given restrictions may have tolerances, and the base 00142 // types of each restriction and increment must be identical. That 00143 // is, <src>restriction.getType() == increment.getType()</src>. 00144 // Other methods to distribute restrictions in other ways are easily 00145 // imagined, eg. a vector of Attributes is given. After being 00146 // called, <src>restrictions</src> are equal to the values set on 00147 // the final WorldCanvasHolder in the list. 00148 00149 //# DK note: only this routine and removeRestriction() should be used 00150 //# with the 'bIndex' restriction; none of the other restriction routines 00151 //# have yet been modified to add an ID to the 'bIndex' restriction name. 00152 //# (The routines are normally called simply using the unmodified name 00153 //# 'bIndex'). 00154 virtual void setLinearRestrictions(AttributeBuffer &restrictions, 00155 const AttributeBuffer &increments); 00156 00157 // Hold and release response to refreshes requested with the 00158 // <src>refresh()</src> member function. Multiple calls to 00159 // <src>hold()</src> can be made, and refreshes will not resume 00160 // until the same number of calls have been made to 00161 // <src>release()</src>. Note that these functions do not affect 00162 // whether internally (implicitly) generated refreshes continue to 00163 // occur. That is, refresh events due to PixelCanvas resize events, 00164 // or Colormap changes, for example, will continue to be acted upon. 00165 // <group> 00166 virtual void hold(); 00167 virtual void release(); 00168 // </group> 00169 00170 // Distribute a refresh event to all the held WorldCanvasHolders. 00171 virtual void refresh(const Display::RefreshReason &reason = 00172 Display::UserCommand); 00173 00174 virtual uInt zLength(); 00175 00176 // These orrespond to 'zIndex, zLength' for animator's 'blink mode'. 00177 virtual Int bLength(); 00178 virtual Int bIndex(); 00179 00180 //Sets whether the viewer is in blink mode. 00181 void setBlinkMode( bool blinkMode ); 00182 00183 // Determines which DDs will be restricted, which are always active. 00184 virtual Bool isBlinkDD(DisplayData *dd); 00185 00186 // Test conformance of a DD to a WCH of this MWCH (by default, test 00187 // against the first one (WCH 0), which always exists). 00188 // The three aspects of conformance can be selectively tested. 00189 virtual Bool conforms(DisplayData* dd, 00190 Bool testRstrs=True, Bool testCS=True, Bool testZ=True, 00191 Int wchIndex=0); 00192 00193 // Return number of WCHs (subpanels). 00194 virtual Int nWCHs() { return Int(itsWCHList.len()); } 00195 00196 // Clear PC in MWCH's area (not implemented on this level). 00197 virtual void clear() { } 00198 00199 // Added to collect region statistics from MultiRectTool::update_stats( )... 00200 List<DisplayData*> *displayDatas( ) { return &itsDDList; } 00201 00202 protected: 00203 00204 // Copy constructor - construct a new MultiWCHolder from 00205 // <src>other</src>. 00206 // MultiWCHolder(const MultiWCHolder &other); 00207 00208 // Copy assignment using copy semantics. 00209 // MultiWCHolder &operator==(const MultiWCHolder &other); 00210 00211 // (permanently) sets itsBIndexName (below). Called only in constructor. 00212 virtual void setBIndexName(); 00213 00214 // Adjust name of "bIndex" Attribute (if any) to indlude ID of this MWCH. 00215 virtual void adjustBIndexName(AttributeBuffer& rstrs); 00216 00217 00218 00219 private: 00220 00221 // The list of WorldCanvasHolders that are managed by this 00222 // MultiWCHolder. 00223 List<WorldCanvasHolder *> itsWCHList; 00224 00225 // The list of DisplayDatas that are managed by this MultiWCHolder. 00226 List<DisplayData *> itsDDList; 00227 00228 // Subset of above DDs which will have blinking restrictions added 00229 // (Countour plots, e.g., do not; they always display). This should 00230 // actually be a Block<DisplayData*>. 00231 Block<void*> itsBlinkDDs; 00232 00233 // Number of DDs above. 00234 Int itsBLength; 00235 00236 // Index of DD to show in first WCH when blink mode is active (it is 00237 // kept up-to-date in any case). 00238 Int itsBIndex; 00239 00240 // The (unchanging) name of the blink restriction: "bIndex" followed by 00241 // an ID unique to this MWCH. The ID is because DDs can be registered on 00242 // more than one MWCH and need a different "bIndex" restriction on each one. 00243 // Note, however, that when setLinearRestrictions() is used externally to 00244 // set the blink restriction onto the WCHs, it simply uses the name 00245 // "bIndex". 00246 String itsBIndexName; 00247 00248 // The buffer of attributes which are presently installed on the 00249 // registered WorldCanvasHolders. 00250 AttributeBuffer itsAttributes; 00251 00252 // The current hold count of this MultiWCHolder. Whenever new 00253 // WCHolders are added, their count is increased to this value. 00254 // Calls to hold() and release() modify this count as well as 00255 // those per canvas. 00256 Int itsHoldCount; 00257 00258 // The current state of whether a refresh was held up or not. 00259 Bool itsRefreshHeld; 00260 00261 // The reason for the held-up refresh event 00262 Display::RefreshReason itsHeldReason; 00263 00264 // Do we already have this WorldCanvasHolder/DisplayData registered? 00265 // <group> 00266 const Bool isAlreadyRegistered(const WorldCanvasHolder &holder); 00267 const Bool isAlreadyRegistered(const DisplayData &displaydata); 00268 // </group> 00269 00270 // Add/remove all the DisplayDatas to/from a WorldCanvasHolder. 00271 // <group> 00272 void addAllDisplayDatas(WorldCanvasHolder &holder); 00273 void removeAllDisplayDatas(WorldCanvasHolder &holder, 00274 const Bool& permanent = False); 00275 // </group> 00276 00277 // Add/remove a DisplayData to/from all WorldCanvasHolders. 00278 // <group> 00279 void addToAllWorldCanvasHolders(DisplayData &displaydata); 00280 void removeFromAllWorldCanvasHolders(DisplayData &displaydata); 00281 // </group> 00282 00283 // Distribute restrictions to all WorldCanvasHolders. 00284 void distributeRestrictions(); 00285 00286 // Set restrictions on a particular WorldCanvasHolder. 00287 void installRestrictions(WorldCanvasHolder &holder); 00288 00289 00290 }; 00291 00292 00293 } //# NAMESPACE CASA - END 00294 00295 #endif