To do the administration of a number of DisplayDatas on one WorldCanvas, a bookkeeping class is needed, this is the WorldCnvasHolder.
Some DisplayData will consist of a sequence of display object (eg a set of channels in a data cube). The DisplayData are build with sequences in mind (as is clear from the interface), and the Display Library is designed very strongly with movies in mind. The programmer is free to define what a sequence really means, but it is probably best to keep the structure of the sequence in a DisplayData fairly logical. But there is not requirement on the structure of the sequence.
Before a display object is displayed (ie when a refresh happens), a size control step is performed. The WorldCanvas call a sizeControl event handler. Normally this will be a handler that is installed by the WorldCanvasHolder. All the WorldCanvasHolder does is to call the sizeControl member function of all displayData registered with the WorldCanvasHolder to do the sizeControl. The purpose of the size control is to put the WorldCanvas in a correct state before the objects are actually drawn. For example, for images there can be restrictions on the size of the output array (eg the image is expanded using pixelreplication which means that the draw area of the WorldCanvas must by an integral of the size of the image). For each DisplayData the WorldCanvasHolder calls the sizeControl function, supplying an AttributeBuffer where the DisplayData should set the Attributes it needs to be set. THERE IS ONE IMPORTANT RULE IN THIS: a DisplayData should never overwrite an Attribute that is already set in this buffer. If the WorldCanvas cannot be put in a correct state during the size control, a DisplayData should turn itself off. DisplayData are also responsible for the linear coordinate system of the WorldCanvas and usually setting that up will be done in this step.
(dk 6/04 note on 'size control'). The important WC state set during sizeControl() defines a series of coordinate transformations, ultimately between screen (PixelCanvas) pixels and coordinates in world space. First, there are the limits of the WC's 'draw area', inside the labelling margins, on the PC ('canvasDraw{X,Y}{Size,Offset}' WC Attributes). Second is the 'zoom window': the area of 'linear coordinate' space currently mapped to the draw area ('lin{X,Y}{Min,Max}' WC Attributes). Also stored in linear terms are the maximum extents of the data ('lin{X,Y}{Min,Max}Limit' Attributes), which are used to set the zoom window initially or when 'unzoom' (zoom-to-extent) is requested. 'Linear coordinates' often correspond to indices within the data being displayed, although in principle this is not necessary. They serve to isolate the simple linear scaling/translation (zoom and pan) transformations from the final transformation (often a nonlinear sky projection) between 'linear coordinates' and world space (which is changed less often).
This final transformation makes use of the Coordinate classes (which ultimately use wcslib for any needed sky projection). It defines the current 2D surface on display within some nD world space, as parameterized by the X and Y linear coordinates. State for this purpose includes the 'WorldCanvas CoordinateSystem' or 'WC CS' (WorldCanvas::itsCoordinateSystem) plus 'axis codes' (which have the odd Attribute names '{x,y}axiscode (required match)'). These are intended to define coordinates of the world space currently of interest.
This transformation is not as simple or well-defined as it might appear, however (and in my opinion this area still needs work). First of all, the WC CS is a rather late addition to WC interface, and in most cases is _not even used_ to do WC linear-to-world transformations. Instead, this chore is handed off (via the older WCCoordinateHandler interface) to one of the DDs currently registered on WC's companion object, WorldCanvasHolder. Also, the axis codes do not always provide enough information about the current world space for DDs to determine whether they are designed to draw in that space (which, in my opinion, should be their purpose). They also implicitly assume a 1-to-1 correspondence between linear and world coordinates, which is not very general.
Back to how it works now, though. During the 'sizeControl' step of refresh, the WCH will attempt to determine a 'CS master DD'. (Usually the same DD will remain 'in charge' as long as it is registered). Within the sizeControl routine, DDs should test isCSMaster(wch) to determine whether they have permission to become the CS master. If so, and if they are willing and able to become CS master, they must set all of the WC state above and return True; in all other cases they should return False. Only the CSmaster should set the WC CS or axis codes, and it will be responsible for performing the WC's linToWorld, etc. transformation chores. In other words, it is entirely in charge of the final transformation to world coordinates. In principle, other DDs may perform certain 'slave sizeControl' tweaks (such as aligning the zoom window on data pixel boundaries or redefining maximum zoom extents). No current implementations do anything but return False if they are not the master, however.
Major implementation examples for sizeControl() can be found in the ActiveCaching2dDD and PrincipalAxesDD classes. They should be consulted as well for the conventions for processing WC 'zoom/unzoom' order attributes, another CSmaster responsibility.
The control of what is displayed in a display application is done with setting restrictions on the WorldCanvasHolder (and possibly on the Displaydata). Restrictions are implemented as Attributes and stored in AttributeBuffers. To define what is displayed, one sets one or more restrictions on the WorldCanvasHolder and calls a refresh on the WorldCanvas. Most DisplayData will have pre-defined restrictions, for example in an ImageDisplayData each image has defined the restriction zIndex (set to the pixelindex of the 'third' axis in the data set) and zValue (set to the 'third' worldcoordinate of the image). So to display channel 13 of a data cube, one only has to set on the WorldCanvasHolder a restriction called zIndex with value 13 and call refresh:
worldCanvasHolder.setRestriction("zIndex", 13);
worldCanvas.refresh();
Movies can be made using the Animator class. One way it to use indices, but there is a generic way of defining movies using restrictions. So a sequence does not have to correspond to a 'logical' or 'physical' sequence in some datastructure (channels in a cube for example), but can be made of images from different datasets (e.g. blinking) and display data in different forms. This system is very flexible and there are no real limits to what a movie really means.
The DisplayData also define the coordinate system of the WorldCanvas. If the WorldCanvas has to do a coordinate transformation, it asks a coordinate handler to do this. When a WorldCanvasHolder is created for a WorldCanvas, the WorldCanvasHolder install a coordinate handler on the WorldCanvas. What this coordinate handlers does is to ask the DisplayData that is first in the list of the WorldcanvasHolder to do the transformation. This is quite an indirect way of doing the transformation, but it is very flexible (and the WorldCanvas does not have to know what an Aips++ coordinate system is, or what a DisplayData is, , which makes the WorldCanvas more generic). Most DisplayData will use the coordinate system of the data belonging to this DisplayData to do the transformation, but this is not a requirement. As long as you produce something that can be used as a coordinate system, it does not matter how you compute it. The most important thing is that the DisplayData are responsible for this. At the moment, only the Vector version should be implemented, since efficient transformation of a series of positions is not available in AIPS++. The Matrix versions are handled at the WorldCanvas level at the moment. Most DisplayData will assume that the linear coordinate system of the WorldCanvas corresponds to some underlying pixel array. The way the linear coordinate system is used is that it is the input for the coordinate transformation to world coordinates. The DisplayData are responsible for keeping the linear system correct.
Other event handlers that the DisplayData have to implement are the position- and the motion event handlers. (PositionEH and MotionEH). These are called by the WorldCanvasHolder in response to an event on the WorldCanvas. It is up to the DisplayData what to do with these events.
One can also register position- and motion event handlers on a DisplayData. What kind of event a DisplayData generates in response to an event on the WorldCanvas (passed to the DisplayData by the WorldCanvasHolder by calling PositionEH/MotionEH) is entirely up to the DisplayData, as long as the handlers are derived from WCPositionEH or WCMotionEH. One can also install a refresh handler on a DisplayData, although I have not thought of any use for that (but allowed for it to keep symmetry with the other events).
(1/02) DisplayEH interface has also been added for handling generic DisplayEvents through handleEvent(). It is expected that DDs will handle these events themselves, as needed, or pass them on in an ad-hoc manner. However, nothing prevents implementing a dispatching list for passing on these events too, if needed.
(3/03) One can also register itself as a DisplayEventHandler on a DisplayData. The handleEvent function of DisplayEH is implemented to forward any DisplayEvents its receives to these handlers. Therefore, all DisplayDatas that overide the handleEvent function, should call the handleEvent function of its super class so this forwarding can take place.
A DisplayData also has to implement a refreshEH. This function is called by the WorldCanvasHolder in response to a refresh request of the WorldCanvas. This is a very important function: here the actual drawing has to happen, using the draw primitives of the WorldCanvas. It is a good idea to check the state of the WorldCanvas before the draw is actually done, and decide not to draw if the state (for whatever reason) is not ok. Also be aware that it is a requirement that one DisplayData can work for more than one WorldCanvasHolders at a time, so the DisplayData has to do some administration for that (which WorldCanvasHolders am I working for and which one am I drawing on at the moment, things like that). See ImageDisplayData for an example of that.
DisplayData also have Attributes. These can be used to store whatever information on a DisplayData. The Attributes give a standard interface to do this.
required destructor
Coordinate transformations, called by WorldCanvasHolder (Matrix versions not implemented)
Format a string containing coordinate information at the given world coordinate
Format a string containing value information at the given world coordinate
Some routines that give info on the axes names, units etc. I am not sure this is the right way of doing it. Specifically I am not sure dataUnit belongs in this list (data units may not make sense for some kinds of DisplayData...).
Returns the number of elements in this DisplayData (mainly for movie purposes). First one is no. of elements for specific WCanvas.
Add general restrictions or a restriction for item itemNum of this DisplayData. Note that the item versions of the restriction interface are not implemented. I am not sure the item versions belong in DisplayData and instead they should only appear in some derived classes.
Set general restrictions or a restriction for item itemNum of this DisplayData. Note that the item versions of the restriction interface are not implemented.
Remove a general restriction or a restriction from item itemNum
Clear all general restrictions or all restrictions of item itemNum (except the ones that are permanent of course...)
Check if a general restriction or a restriction for item itemNum with name name exists.
Get a handle to the buffer of general restrictions or of the buffer of restrictions for item itemNum
Check whether the DD is is compatible with all WC[H] state, including its coordinate state, restrictions, and zIndex (if any). It also assures that the DD is 'focused' on this WC[H] and its zindex for purposes of drawing or event handling.
Determine whether DD restrictions are in conformance with restrictions on the given WCH. (Note: this will include blink index, if any, but _not_ zIndex. zIndex is an individual DM restriction, not an overall DD restriction).
Determine whether DD is compatible with the WC[H]'s current world coordinates. Derived DDs can override according to their individual capabilities (PADD and ACDD match axis codes). Overriding DDs should set csConformed_ to the value returned.
Determine whether DD is compatible with the current canvas animation (zIndex) position. (This usually means that it lies within the current number of DD animation frames). (Generally, DDs should probably override setActiveZIndex() rather than this method).
DDs may override to adjust the internal stored current animation index (activeZIndex_) if necessary, and to set return value False iff the passed zindex won't work for the DD. zIndexConformed_ should be set to the value returned; activeZIndex_ should also be set appropriately.
Set firstZIndex to minimum zIndex setting from all canvases where this DD is registered. (In the usual case where the DD is registered on one [multi]panel, this will return its animator 'frame #' setting). The routine will return false (and firstZIndex remain unchanged) if there are no registered canvases with zIndex below axZrng--the total number of frames on the Z axis. axZrng can be supplied; the default means 'use nelements()'. (Note: to get the zindex from the 'currently active' wch instead, a DD should check activeZIndex_. Or, if the desired wch is known, it can retrieve the zIndex itself from wch.restrictionBuffer()).
Add event handlers on the DisplayData. I am not sure there is also a need for a refresh handler on a DisplayData, but allowing for it makes things 'symmetric'. These member functions throw an AipsError if a null pointer is passed.
Remove eventhandlers
Set/remove/get a ColourMap (sorry, ColorMap) for this DisplayData setColormap() throw an AipsError is a null pointer is passed. colormap() returns 0 if no Colormap is registered.
set an Attribute or Attributes
User interface to get value from the attribute buffer
Check if a certain Attribute exists
Remove an Attribute
Get the type of the Attribute
Set an attribute on any WorldCanvas for which this DD is CS master
ignoreRefresh tells the DD not to refresh just to clean up DMs
remove this DD everywhere--will stop any more refresh handling by the DD. It is a good idea for top-level DDs to call this first in their destructor.
install the default options for this DisplayData
apply options stored in val to the DisplayData; return value True means a refresh is needed...
retrieve the current and default options and parameter types.
an explicit refresh: should be called if the DisplayData is changed such that drawing is required. If clean is True, the DD is totally rebuilt, in practice. This is provided for higher level control, even explicit control of refresh where necessary.
an explicit request to draw the axes and/or labels. Returns True if axes were drawn, otherwise False;
Return the class name of this DisplayData; useful mostly for debugging purposes, and perhaps future use in the glish widget interface.
Return the DisplayData type; used by the WorldCanvasHolder to determine the order of drawing.
Identify the WorldCanvasHolder for the given WorldCanvas. Return 0 if the DisplayData does not know of a WorldCanvasHolder for the WorldCanvas.
Return a sorted Block of all animation frame numbers currently set onto all WCHs where this DD is registered. The frame numbers returned are guaranteed to be in the range 0 <= zIndex < axZrng, where axZrng is the total number of frames on the Z axis. axZrng can be supplied; the default is nelements().
Will be called just before registering the [GTk]DD on a [GTk]PanelDisplay which has none registered on it yet. The DD can set the initial animator position in this case by overriding this method to set preferredZIndex and return True.
Overide DisplayEH::handleEvent. This base class on forwards the event on to listeners
Is this DD the CS master of the passed WCH? Defaulting wch to 0 asks whether this DD is CS master of _some_ WCH on which it is registered. (That option is mostly a kludge, since the DD may be CS master of some WCHs and not others).
Returns result of last call to conformsTo(WCH&). Methods like showValue() which don't have access to the wch can use it instead, but that shifts the burden elsewhere of being sure that conformsTo() was called for the current WCH. When possible, it is generally better and safer to call conformsTo(wch) directly when needed, rather than querying this.
Set (coordinate) state of WCH's WC. Called by WCH::executeSizeControl(). (See important notes on interface and implementation of this function in the class synopsis above).
Retrieve position, motion, refresh and display event handler lists.
Position, motion and refresh event handlers that will generally be called by a WorldCanvasHolder.
clean up the memory used by this DisplayData
(Required) copy constructor.
(Required) copy assignment.