Annotations.h

Go to the documentation of this file.

//# Annotations.h : Control class for DisplayShape
//# Copyright (C) 1998,1999,2000,2001,2002,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_ANNOTATIONS_H
#define TRIALDISPLAY_ANNOTATIONS_H

#include <casa/aips.h>

#include <display/DisplayEvents/PCPositionEH.h>
#include <display/DisplayEvents/PCMotionEH.h>
#include <display/DisplayEvents/PCRefreshEH.h>
#include <display/DisplayEvents/WCRefreshEH.h>
#include <casa/OS/Timer.h>

#include <display/Display/WorldCanvas.h>
#include <casa/Containers/List.h>

#include <casa/Containers/Record.h>
#include <casa/Arrays/Matrix.h>
#include <casa/Arrays/Vector.h>

namespace casa { //# NAMESPACE CASA - BEGIN

class DisplayShape; 
class PanelDisplay;


// <summary>
// Control class for a collection of DisplayShapeInterfaces. 
// </summary>
//
// <prerequisite>
// <li> <linkto class="DisplayShapeInterface">DisplayShapeInterface</linkto>
// </prerequisite>
//
// <etymology>
// Annotations is a method by which a collection of shapes can be managed
// on a pixel canvas.
// </etymology>
//
// <synopsis>
// Annotations registers itself as an event handler on whichever pixelcanvas
// it is supplied. It can then add, delete or modify shapes based on function
// calls and user mouse input.
// 
// The class is essentially a PtrBlock of DisplayShapeInterfaces, with
// pixelcanvas event handling to control them.
// </synopsis>
//
// <motivation>
// To allow a collection of shapes to be displayed and cotrolled by one class.
// </motivation>
//
// <example>
// <srcblock>
// </srcblock>
// </example>


class Annotations : public PCPositionEH,
                    public PCMotionEH,
                    public PCRefreshEH,
                    public WCRefreshEH {
  
public:
  // Used to determine the state of the class. The state may change due
  // to mouse events, or function calls.
  enum State {Nothing, Creation, WcCreation, Handle, OtherHandle, Move, 
              OtherMove}; 

  // This is used to handle the creation of shapes by mouse events. Some
  // types of shapes require special treatment when constructed with
  // the mouse.
  enum CreationType {Normal, Arrow, Polygon, PolyLine, Marker};

  // Destructor, and constructor, taking the panelDisplay to which the 
  // Annotator will attach itself to, and which mouse button to listen to.
  // <group>
  Annotations(PanelDisplay* panDisp, 
              const Display::KeySym& keysym = Display::K_Pointer_Button1,
              const Bool useEH = True);
  virtual ~Annotations();
  // </group>

  // The event handlers.
  // <group>
  virtual void operator()(const PCPositionEvent& ev);
  virtual void operator()(const PCMotionEvent& ev);
  virtual void operator()(const PCRefreshEvent& ev); 
  virtual void operator()(const WCRefreshEvent& ev);
  // </group>

  // Redraw all the shapes. Turns all handles off if noHandles is True
  virtual void draw(PixelCanvas* pc, const Bool noHandles = False);
  
  // Instantly creates a shape on screen, and hence requires 
  // certain information in its record such as the center of the 
  // new object on screen. Refresh == False can be used to surpress a 
  // refresh.
  virtual void newShape(Record& settings, const Bool& refresh = True);

  // Set the key assigned to control shapes.
  virtual void setKey(const Display::KeySym& newKey);

  // Create a shape, based on the information contained in the record.
  // This function does not require the center to be specified, as once 
  // createShape is called, the user can "drag" out the shape required.
  // If createShape is called, and the shape is no longer required, 
  // the function 'cancelShapes' can be used to reset the state of the
  // annotator.
  virtual void createShape(Record& settings);

  // Disable event handling (with the exception of refresh calls). This stops
  // the user from moving shapes etc via the mouse motion / position event 
  // handlers. These do not recognize nested calls (e.g. two disables, 
  // followed by an enable will enable the handlers).
  // <group>
  virtual void enable();
  virtual void disable();
  // </group>

  // Cancels creation of any pending shapes, unselects all shapes and
  // turns off drawing of all handles.
  virtual void cancelShapes();

  // Delete the shape at the specified point in the collection of shapes
  // The current (selected) shape can be determined by using the 
  // activeShape() function.
  virtual Bool deleteShape(const uInt& toDel);

  // These allow shapes to be "locked" together. Adding a locked shape
  // to the current shape means that whenever the current shape
  // moves, so too will the specified shape. removeLockedFromCurrent
  // can be used to remove this effect.
  // <group>
  virtual void removeLockedFromCurrent(const uInt& removeMe);
  virtual void addLockedToCurrent(const uInt& addMe);
  // </group>

  // Return the currently selected shapes' index
  virtual Int activeShape();

  // Return a brief summary of all current shapes
  virtual Record shapesSummary();

  // Set the options for the specified shape. The user selected shape
  // can be determined by call the 'activeShape' method. To see a list of 
  // available options for different types of shapes / objects, see their 
  // individual documentation.
   virtual void setShapeOptions(const uInt& whichShape, 
                               const Record& newOptions);
  
  // Returns a record containing the options for the specified shape.
  // The user selected shape can be determined by calling the 'activeShape'
  // method. To see a list of the options returned by shapes / objects,
  // see their individual documentation.
  virtual Record getShapeOptions(const uInt& whichShape);

  // Returns a record which contains a sub record (containing options) for 
  // each shape. e.g. To obtain options for the first shape:
  // <srcblock>
  // Record all = myAnnotator.getAllOptions();
  // Record shape = all.subRecord(0);
  // </srcblock>
  virtual Record getAllOptions();
  
  // Deletes all existing shapes, and rebuilds new shapes based on records 
  // in sub records of the supplied record. A record returned from 
  // getAllOptions() can therefore be used to copy a set of shapes.
  virtual void setAllOptions(const Record& newSettings);

  // Called when a refresh is required. It copies back to front buffer,
  // then causes a refresh with reason = backCopiedToFront.
  virtual void update(PixelCanvas* pc);
  
  // Overwrite this to fire glish events.
  virtual void annotEvent(const String& /*event*/) {};

  // Functions for changing the co-ords system of a shape
  // <group>  
  virtual Bool revertToPix(const Int& whichOne);
  virtual Bool revertToFrac(const Int& whichOne);
  virtual Bool lockToWC(const Int& whichOne);  
  // </group>
  
  // Returns a list of shapes annotations knows about
  virtual Record availableShapes();
  

protected:

private:

  // My private variables...

  // The PanelDisplay I was given on construction and some stuff I got out 
  // of it
  // <group>
  PanelDisplay* itsPanelDisplay;
  PixelCanvas* itsPC;
  // </group>
  
  // My copy of the list of Worldcanvases. I can check this against 
  // itsPanelDisplay to see if anything has changed. 
  ListIter<WorldCanvas* >* itsWCLI;  
  List<WorldCanvas* > itsWCs;  
  
  // List of shapes
  PtrBlock<DisplayShape*> itsShapes;

  // Some overall settings
  // <group>
  Display::KeySym itsKey;
  Bool itsUseEH;
  // </group>
  
  // Stuff to remember my current state: 
  // <group>
  Annotations::State itsState;
  Annotations::CreationType itsCreation;
  Bool itsShapeMoved;
  Int itsActiveShape;
  Int itsActiveHandle;
  uInt itsX, itsY; 
  Bool itsEnabled;
  Bool itsRefreshedYet;
  // </group>
  //


  // Internal functions
  // <group>
  Bool changeCoordSys(const Int shapeIndex, const String& type,
                       const String& currentCoords, const String& toCoords);

  DisplayShape* constructShape(const Record& settings);
  void handleKeyUp();
  void handleCreation(const PCPositionEvent& ev);
  void handleNormalCreation(const Vector<Float>& createPix);
  void handleMarkerCreation(const Vector<Float>& createPix);
  void handlePolyLineCreation(const Vector<Float>& createPix);
  void handlePolygonCreation(const Vector<Float>& createPix);
  void handleArrowCreation(const Vector<Float>& createPix);
  void select(const Int i);
  Bool determineState(const PCPositionEvent& ev);
  void registerToWCs();
  Bool validateWCs();
  void changedWC();
  Bool validShape(const Record& shape);
  void polyLineToPolygon(const Int whichShape);
  // </group>
}; 

// Ostream, mainly for debugging the state of the annotator.
ostream& operator << (ostream& os, Annotations::State st);


} //# NAMESPACE CASA - END

#endif