MultiWCHolder.h

Go to the documentation of this file.

//# MultiWCHolder.h: Holder of multiple WorldCanvasHolders for panelling
//# Copyright (C) 2000,2001,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef TRIALDISPLAY_MULTIWCHOLDER_H
#define TRIALDISPLAY_MULTIWCHOLDER_H

#include <casa/aips.h>
#include <casa/Containers/List.h>
#include <display/Display/DisplayEnums.h>
#include <display/Display/AttributeBuffer.h>

namespace casa { //# NAMESPACE CASA - BEGIN

        class WorldCanvasHolder;
        class DisplayData;
        class AttributeBuffer;
        class String;

// <summary>
// A holder of WorldCanvasHolders to use for panelling applications.
// </summary>
//
// <use visibility=export>
//
// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
// </reviewed>
//
// <prerequisite>
//   <li><linkto class="WorldCanvasHolder">WorldCanvasHolder</linkto>
//   <li><linkto class="DisplayData">DisplayData</linkto>
//   <li><linkto class="Attribute">Attribute</linkto>
//   <li><linkto class="AttributeBuffer">AttributeBuffer</linkto>
// </prerequisite>
//
// <etymology>
// The MultiWCHolder holds a number of WorldCanvasHolders to simplify
// panelling operations.
// </etymology>
//
// <synopsis>
// This class is a holder of <linkto
// class=WorldCanvasHolder>WorldCanvasHolder</linkto> objects.  It
// exists to facilitate the management of multiple WorldCanvasHolders
// having in common a set of restrictions, which for example may be
// for controlling animation, and on which a common set of
// DisplayDatas may be registered and displayed.
//
// The basic interface to the MultiWCHolder provides methods for
// adding and removing individual WorldCanvasHolder objects, for
// globally registering and unregistering DisplayData objects for
// display on the WorldCanvasHolder objects, and for applying a set
// of restrictions to the WorldCanvasHolder objects.
//
// At a more advanced level, functions exist to distribute varying
// restrictions across all the WorldCanvasHolder objects.  For
// example, the programmer can use
// <src>linearDistributeRestriction</src> to apply a restriction to
// each WorldCanvasHolder, where the value of the restriction is
// incremented by a fixed amount between each WorldCanvasHolder.  This
// would be useful, for example, to easily display a set of planes
// from a multi-frequency image on a number of WorldCanvases whose
// WorldCanvasHolders have been added to a MultiWCHolder.
// </synopsis>
//
// <example>
// </example>
//
// <motivation>
// </motivation>

        class MultiWCHolder {

        public:

                // Constructor which makes an empty MultiWCHolder.
                MultiWCHolder();

                // Constructor which makes a MultiWCHolder containing the single
                // specified WorldCanvasHolder.
                MultiWCHolder(WorldCanvasHolder& holder);

                // Destructor.
                virtual ~MultiWCHolder();

                // Add or remove a WorldCanvasHolder, or remove all
                // WorldCanvasHolders on this MultiWCHolder.  <src>holder</src> is
                // added at the end of the list.  When a new WorldCanvasHolder is
                // added, it will automatically have all registered DisplayDatas
                // added to it.
                // <group>
                virtual void addWCHolder(WorldCanvasHolder& holder);
                virtual void removeWCHolder(WorldCanvasHolder& holder);
                virtual void removeWCHolders();
                // </group>

                // Add or remove a DisplayData, or remove all DisplayDatas on this
                // MultiWCHolder.
                // <group>
                virtual void addDisplayData(DisplayData& displaydata, int position = -1);
                virtual void removeDisplayData(DisplayData& displaydata);
                virtual void removeDisplayDatas();
                // </group>

                // Install or remove a single restriction, or a buffer of
                // restrictions, on all of the WorldCanvasHolders managed by this
                // MultiWCHolder.
                // <group>
                virtual void setRestriction(const Attribute& restriction);
                virtual void setRestrictions(const AttributeBuffer& restrictions);
                virtual void removeRestriction(const String& name);
                virtual void removeRestrictions();
                // </group>

                // Incrementally distribute restrictions to all of the
                // WorldCanvasHolders.  The value of the restrictions are
                // incremented by the given amount for each holder beyond the first
                // one.  The given restrictions may have tolerances, and the base
                // types of each restriction and increment must be identical.  That
                // is, <src>restriction.getType() == increment.getType()</src>.
                // Other methods to distribute restrictions in other ways are easily
                // imagined, eg. a vector of Attributes is given.  After being
                // called, <src>restrictions</src> are equal to the values set on
                // the final WorldCanvasHolder in the list.

                //# DK note: only this routine and removeRestriction() should be used
                //# with the 'bIndex' restriction; none of the other restriction routines
                //# have yet been modified to add an ID to the 'bIndex' restriction name.
                //# (The routines are normally called simply using the unmodified name
                //# 'bIndex').
                virtual void setLinearRestrictions(AttributeBuffer &restrictions,
                                                   const AttributeBuffer &increments);

                // Hold and release response to refreshes requested with the
                // <src>refresh()</src> member function.  Multiple calls to
                // <src>hold()</src> can be made, and refreshes will not resume
                // until the same number of calls have been made to
                // <src>release()</src>.  Note that these functions do not affect
                // whether internally (implicitly) generated refreshes continue to
                // occur.  That is, refresh events due to PixelCanvas resize events,
                // or Colormap changes, for example, will continue to be acted upon.
                // <group>
                virtual void hold();
                virtual void release();
                // </group>

                // Distribute a refresh event to all the held WorldCanvasHolders.
                virtual void refresh(const Display::RefreshReason &reason =
                                         Display::UserCommand);

                virtual uInt zLength();

                // These orrespond to 'zIndex, zLength' for animator's 'blink mode'.
                virtual Int bLength();
                virtual Int bIndex();

                //Sets whether the viewer is in blink mode.
                void setBlinkMode( bool blinkMode );

                // Determines which DDs will be restricted, which are always active.
                virtual Bool isBlinkDD(DisplayData *dd);

                // Test conformance of a DD to a WCH of this MWCH (by default, test
                // against the first one (WCH 0), which always exists).
                // The three aspects of conformance can be selectively tested.
                virtual Bool conforms(DisplayData* dd,
                                      Bool testRstrs=True, Bool testCS=True, Bool testZ=True,
                                      Int wchIndex=0);

                // Return number of WCHs (subpanels).
                virtual Int nWCHs() {
                        return Int(itsWCHList.len());
                }

                // Clear PC in MWCH's area (not implemented on this level).
                virtual void clear() {  }

                // Added to collect region statistics from MultiRectTool::update_stats( )...
                List<DisplayData*> *displayDatas( ) {
                        return &itsDDList;
                }

        protected:

                // Copy constructor - construct a new MultiWCHolder from
                // <src>other</src>.
                // MultiWCHolder(const MultiWCHolder &other);

                // Copy assignment using copy semantics.
                // MultiWCHolder &operator==(const MultiWCHolder &other);

                // (permanently) sets itsBIndexName (below).  Called only in constructor.
                virtual void setBIndexName();

                // Adjust name of "bIndex" Attribute (if any) to indlude ID of this MWCH.
                virtual void adjustBIndexName(AttributeBuffer& rstrs);



        private:

                // The list of WorldCanvasHolders that are managed by this
                // MultiWCHolder.
                List<WorldCanvasHolder *> itsWCHList;

                // The list of DisplayDatas that are managed by this MultiWCHolder.
                List<DisplayData *> itsDDList;

                // Subset of above DDs which will have blinking restrictions added
                // (Countour plots, e.g., do not; they always display).  This should
                // actually be a Block<DisplayData*>.
                Block<void*> itsBlinkDDs;

                // Number of DDs above.
                Int itsBLength;

                // Index of DD to show in first WCH when blink mode is active (it is
                // kept up-to-date in any case).
                Int itsBIndex;

                // The (unchanging) name of the blink restriction: "bIndex" followed by
                // an ID unique to this MWCH.  The ID is because DDs can be registered on
                // more than one MWCH and need a different "bIndex" restriction on each one.
                // Note, however, that when setLinearRestrictions() is used externally to
                // set the blink restriction onto the WCHs, it simply uses the name
                // "bIndex".
                String itsBIndexName;

                // The buffer of attributes which are presently installed on the
                // registered WorldCanvasHolders.
                AttributeBuffer itsAttributes;

                // The current hold count of this MultiWCHolder.  Whenever new
                // WCHolders are added, their count is increased to this value.
                // Calls to hold() and release() modify this count as well as
                // those per canvas.
                Int itsHoldCount;

                // The current state of whether a refresh was held up or not.
                Bool itsRefreshHeld;

                // The reason for the held-up refresh event
                Display::RefreshReason itsHeldReason;

                // Do we already have this WorldCanvasHolder/DisplayData registered?
                // <group>
                Bool isAlreadyRegistered(const WorldCanvasHolder &holder);
                Bool isAlreadyRegistered(const DisplayData &displaydata);
                // </group>

                // Add/remove all the DisplayDatas to/from a WorldCanvasHolder.
                // <group>
                void addAllDisplayDatas(WorldCanvasHolder &holder);
                void removeAllDisplayDatas(WorldCanvasHolder &holder,
                                           const Bool& permanent = False);
                // </group>

                // Add/remove a DisplayData to/from all WorldCanvasHolders.
                // <group>
                void addToAllWorldCanvasHolders(DisplayData &displaydata, int position);
                void removeFromAllWorldCanvasHolders(DisplayData &displaydata);
                // </group>

                // Distribute restrictions to all WorldCanvasHolders.
                void distributeRestrictions();

                // Set restrictions on a particular WorldCanvasHolder.
                void installRestrictions(WorldCanvasHolder &holder);


        };


} //# NAMESPACE CASA - END

#endif