casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
DisplayEvents.h
Go to the documentation of this file.
00001 //# DisplayEvents.h: The DisplayEvents module - display event handling
00002 //# Copyright (C) 1999,2000
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_DISPLAYEVENTS_H
00029 #define TRIALDISPLAY_DISPLAYEVENTS_H
00030 
00031 #include <display/DisplayEvents/WCRTZoomer.h>
00032 
00033 namespace casa { //# NAMESPACE CASA - BEGIN
00034 
00035 // <module>
00036 //
00037 // <summary>
00038 // A module providing event handling for the DisplayCanvases
00039 // </summary>
00040 //
00041 // <use visibility=export>
00042 //
00043 // <reviewed reviewer="None yet" date="yyyy/mm/dd" demos="">
00044 // </reviewed>
00045 //
00046 // <prerequisite>
00047 // <li> DisplayCanvas
00048 // </prerequisite>
00049 //
00050 // <etymology>
00051 // The module provides various classes that are responsible for
00052 // "handling" "events"
00053 // </etymology>
00054 //
00055 // <synopsis> 
00056 // This module contains classes which are used to handle
00057 // position, motion and refresh events that occur on PixelCanvases and
00058 // WorldCanvases.  Position events occur when the user presses or
00059 // releases a keyboard key or a mouse button when the window input
00060 // focus is over a PixelCanvas or WorldCanvas.  Motion events occur
00061 // when the user moves the mouse over a PixelCanvas or a WorldCanvas.
00062 // Refresh events occur for a variety of reasons, and arise when
00063 // PixelCanvases or WorldCanvases need to redraw their contents.
00064 //
00065 // The lowest level of event classes are those which describe the
00066 // various events on the PixelCanvas.  These comprise PCPositionEvent,
00067 // PCMotionEvent and PCRefreshEvent.  All of the information
00068 // pertaining to a particular event will be stored in one of these
00069 // classes.  To receive these type of events, the programmer must
00070 // register a class derived from PCPositionEH, PCMotionEH or
00071 // PCRefreshEH (where the "EH" stands for Event Handler) with the
00072 // appropriate PixelCanvas.  Then any events of that type (Position,
00073 // Motion or Refresh) will be distributed to the class that the
00074 // programmer registered.  The WorldCanvas has equivalent event
00075 // storage classes in WCPositionEvent, WCMotionEvent and
00076 // WCRefreshEvent, and equivalent event handling classes in
00077 // WCPositionEH, WCMotionEH and WCRefreshEH.
00078 //
00079 // It is important to note that none of the event handlers "consume"
00080 // events.  This means that all PixelCanvas events occuring on a
00081 // particular PixelCanvas wil be distributed to all the event handlers
00082 // registered on that PixelCanvas.  Likewise, all WorldCanvas events
00083 // for a particular WorldCanvas are distributed to all WorldCanvas
00084 // event handlers registered on that WorldCanvas.
00085 // 
00086 // It is also critical for the programmer to be aware that in general,
00087 // the WorldCanvas registers one instance of each of the PCPositionEH,
00088 // PCMotionEH and PCRefreshEH type handler classes for its own use.
00089 // These event handlers are responsible for constructing WorldCanvas
00090 // event information objects (WCPositionEvent, WCMotionEvent and
00091 // WCRefreshEvent) from the corresponding PixelCanvas events, and then
00092 // call the appropriate handlers on the WorldCanvas.  So the
00093 // programmer must be careful that they handle each event once and
00094 // only once - either on the PixelCanvas, or on the WorldCanvas, but
00095 // not on both.  There will be rare instances where handling events on
00096 // both the WorldCanvas and its underlying PixelCanvas is necessary.
00097 // </synopsis>
00098 //
00099 // <example>
00100 // </example>
00101 //
00102 // <motivation>
00103 // Any interactive display library must provide methods for the 
00104 // programmer to respond to user input.  That is the reason for this
00105 // module.
00106 // </motivation>
00107 //
00108 // <todo asof="1999/02/10">
00109 //   <li> None known
00110 // </todo>
00111 //
00112 // </module>
00113 
00114 
00115 } //# NAMESPACE CASA - END
00116 
00117 #endif
00118