casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
MultiWCHolder.h
Go to the documentation of this file.
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