casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
PlotCanvas.h
Go to the documentation of this file.
00001 //# PlotCanvas.h: Main drawing area for different plot items to be attached.
00002 //# Copyright (C) 2008
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 #ifndef PLOTCANVAS_H_
00028 #define PLOTCANVAS_H_
00029 
00030 #include <graphics/GenericPlotter/Plot.h>
00031 #include <graphics/GenericPlotter/PlotAnnotation.h>
00032 #include <graphics/GenericPlotter/PlotEventHandler.h>
00033 #include <graphics/GenericPlotter/PlotItem.h>
00034 #include <graphics/GenericPlotter/PlotLogger.h>
00035 #include <graphics/GenericPlotter/PlotOperation.h>
00036 #include <graphics/GenericPlotter/PlotOptions.h>
00037 #include <graphics/GenericPlotter/PlotShape.h>
00038 #include <graphics/GenericPlotter/PlotTool.h>
00039 
00040 #include <casa/BasicSL/String.h>
00041 
00042 #include <casa/namespace.h>
00043 
00044 namespace casa {
00045 
00046 //# Forward Declarations
00047 class PlotFactory;
00048 
00049 
00050 // Abstract parent for any class that wants to be notified when the canvas
00051 // is about to start drawing.  This class is needed because a canvas could
00052 // start redrawing for a number of reasons (user-requested, items changing the
00053 // scale, resizing, ...) and instead of forcing applications to catch all cases
00054 // this class can be used to notify when a drawing has begun for any reason.
00055 class PlotDrawWatcher {
00056 public:
00057     // Constructor.
00058     PlotDrawWatcher() { }
00059     
00060     // Destructor.
00061     virtual ~PlotDrawWatcher() { }
00062     
00063     
00064     // This method should be called by the canvas whenever drawing is about to
00065     // begin.  The watcher is given:
00066     // * A pointer to the PlotOperation object which is updated with progress
00067     //   information,
00068     // * A flag indicating whether the drawing will happen in its own thread or
00069     //   not,
00070     // * A flag indicating which layers are going to be drawn (bitwise-or of
00071     //   PlotCanvasLayer values).
00072     // The method should return true UNLESS the watcher wants to stop the
00073     // canvas from drawing.  For example, if a canvas does not have threaded
00074     // drawing, the watcher may want to stop drawing initially in order to
00075     // spawn a new thread and then redraw.
00076     virtual bool canvasDrawBeginning(PlotOperationPtr drawOperation,
00077             bool drawingIsThreaded, int drawnLayersFlag) = 0;
00078 };
00079 typedef CountedPtr<PlotDrawWatcher> PlotDrawWatcherPtr;
00080 
00081 
00082 // PlotCanvas is an area for different PlotItems to be attached and drawn.  It
00083 // also has axes and other properties.  It's one of the more important plotting
00084 // classes.
00085 class PlotCanvas {
00086 public:
00087     // Static //
00088     
00089     // Position that the legend can be in, relative to the canvas.
00090     enum LegendPosition {
00091         INT_URIGHT, // inside the canvas, on the upper right
00092         INT_LRIGHT, // inside the canvas, on the lower right
00093         INT_ULEFT,  // inside the canvas, on the upper left
00094         INT_LLEFT,  // inside the canvas, on the lower left
00095         EXT_RIGHT,  // outside the canvas, on the right
00096         EXT_TOP,    // outside the canvas, on the top
00097         EXT_LEFT,   // outside the canvas, on the left
00098         EXT_BOTTOM  // outside the canvas, on the bottom
00099     };
00100     
00101     // Returns all legend positions.
00102     // <group>
00103     static vector<LegendPosition> allLegendPositions(); 
00104     static vector<String> allLegendPositionStrings();
00105     // </group>
00106     
00107     // Converts between legend positions and their String representations.
00108     // <group>
00109     static String legendPosition(LegendPosition p); 
00110     static LegendPosition legendPosition(String p, bool* ok = NULL);
00111     // </group>
00112     
00113     // Indicates whether the given legend position is internal to the canvas or
00114     // not.
00115     static bool legendPositionIsInternal(LegendPosition p);
00116     
00117     // Returns a vector containing all values in the PlotAxis enum, ordered
00118     // from lowest value to highest value.
00119     static vector<PlotAxis> allAxes();
00120     
00121     // Returns the or'ed value of all PlotAxis enum values.
00122     static int allAxesFlag();
00123     
00124     // Returns a vector containing all values in the PlotCanvasLayer enum,
00125     // ordered from lowest value to highest value.
00126     static vector<PlotCanvasLayer> allLayers();
00127     
00128     // Returns the or'ed value of all PlotCanvasLayer enum values.
00129     static int allLayersFlag();
00130     
00131     // Convenient access to operation names.
00132     // <group>
00133     static const String OPERATION_DRAW;
00134     static const String OPERATION_EXPORT;
00135     // </group>
00136     
00137     
00138     // Non-Static //
00139     
00140     // Constructor.
00141     PlotCanvas();
00142     
00143     // Destructor.
00144     virtual ~PlotCanvas();
00145 
00146     
00147     // Support Methods //
00148     
00149     // See PlotFactory::canvasHasThreadedDrawing().
00150     // DEFAULT IMPLEMENTATION.
00151     virtual bool hasThreadedDrawing() const;
00152     
00153     // See PlotFactory::canvasHasCachedLayerDrawing().
00154     // DEFAULT IMPLEMENTATION.
00155     virtual bool hasCachedLayerDrawing() const;
00156     
00157     // See PlotFactory::hasCachedAxesStack().
00158     // DEFAULT IMPLEMENTATION.
00159     virtual bool hasCachedAxesStack() const;
00160     
00161     
00162     // GUI Methods //
00163     
00164     // Returns the canvas size in pixels (width x height).
00165     virtual pair<int, int> size() const = 0;
00166     
00167     // Returns the text of the canvas title, or an empty String if none is
00168     // shown.  The title is shown above the plotting area.
00169     virtual String title() const = 0;
00170     
00171     // Sets the text of the canvas title to the given.  Setting the title to an
00172     // empty string should remove the title from the canvas.
00173     virtual void setTitle(const String& title) = 0;
00174     
00175     // Returns a copy of the font used for the canvas title.  If no title is
00176     // shown this behavior is undefined.
00177     virtual PlotFontPtr titleFont() const = 0;
00178     
00179     // Set the font of the canvas title to the given.
00180     virtual void setTitleFont(const PlotFont& font) = 0;
00181     
00182     // Convenience method for setting title font.
00183     // DEFAULT IMPLEMENTATION.
00184     virtual void setTitleFont(const PlotFontPtr font);
00185     
00186     // Returns a copy of the canvas background.
00187     virtual PlotAreaFillPtr background() const = 0;
00188     
00189     // Sets the background of the canvas to the given.
00190     virtual void setBackground(const PlotAreaFill& areaFill) = 0;
00191     
00192     // Convenience methods for setting background.
00193     // DEFAULT IMPLEMENTATION.
00194     // <group>
00195     virtual void setBackground(const PlotAreaFillPtr areaFill);
00196     virtual void setBackground(const String& color,
00197             PlotAreaFill::Pattern pattern = PlotAreaFill::FILL);
00198     // </group>
00199     
00200     // Gets/sets the cursor for this canvas.
00201     // <group>
00202     virtual PlotCursor cursor() const = 0;
00203     virtual void setCursor(PlotCursor cursor) = 0;
00204     // </group>    
00205     
00206     // Refreshes the GUI, which includes redrawing plot items as needed even if
00207     // drawing is currently being held.
00208     virtual void refresh() = 0;
00209     
00210     // Refreshes the GUI, ONLY for the layers as indicated by the flag.  The
00211     // flag should be a bitwise-or of PlotCanvasLayer values.
00212     virtual void refresh(int drawLayersFlag) = 0;
00213     
00214     // Indicates whether a cast to QWidget would succeed for this object.
00215     virtual bool isQWidget() const = 0;
00216     
00217     
00218     // Axes Methods //
00219     
00220     // Returns a bitwise-or of PlotAxis values corresponding to which sides are shown
00221     virtual PlotAxisBitset  shownAxes() const = 0;
00222     
00223     // Shows/Hides axes based on the given bitset, which should be a bitwise-or
00224     // of PlotAxis values.
00225     virtual void showAxes(PlotAxisBitset axes) = 0;
00226     
00227     
00228     #if (0)  // checking hypothesis: this is not used anywhere
00229     // Returns true if the given axis is shown, false otherwise.
00230     // DEFAULT IMPLEMENTATION.
00231     virtual bool isAxisShown(PlotAxis axis) const;
00232     #endif 
00233     
00234     
00235     // Shows/hides the given axis.
00236     // DEFAULT IMPLEMENTATION.
00237     virtual void showAxis(PlotAxis axis, bool show = true);
00238     
00239     // Convenience method for showing/hiding two axes at once.
00240     // DEFAULT IMPLEMENTATION.
00241     virtual void showAxes(PlotAxis xAxis, PlotAxis yAxis, bool show = true);
00242     
00243     // Convenience method for showing/hiding all four axes at once.
00244     // DEFAULT IMPLEMENTATION.
00245     virtual void showAllAxes(bool show);
00246     
00247     // Returns the scale for the given axis.
00248     virtual PlotAxisScale axisScale(PlotAxis axis) const = 0;
00249     
00250     // Sets the scale for the given axis and rescales accordingly.  May reset
00251     // tool stacks.
00252     virtual void setAxisScale(PlotAxis axis, PlotAxisScale scale) = 0;
00253     
00254     // Convenience method for setting the axis scale for two axes at once.  May
00255     // reset tool stacks.
00256     // DEFAULT IMPLEMENTATION.
00257     virtual void setAxesScales(PlotAxis xAxis, PlotAxisScale xScale,
00258             PlotAxis yAxis, PlotAxisScale yScale);
00259     
00260     // Gets/Sets the reference values for the given axis.  If a reference value
00261     // is set for an axis, its tick labels use an offset from that value
00262     // instead of the actual tick value.  For example, if a reference value is
00263     // set to 15, instead of ticks reading "14 15 16" they would read "-1 0 1".
00264     // <group>
00265     virtual bool axisReferenceValueSet(PlotAxis axis) const = 0;
00266     virtual double axisReferenceValue(PlotAxis axis) const = 0;
00267     virtual void setAxisReferenceValue(PlotAxis axis, bool on,
00268                 double value = 0) = 0;
00269     // </group>
00270     
00271     // Returns whether the given Cartesian axis is shown or not.  (See
00272     // showCartesianAxis().)
00273     virtual bool cartesianAxisShown(PlotAxis axis) const = 0;
00274     
00275     // Show or hide the given Cartesian axis.  A Cartesian axis is different
00276     // from a normal axis in that it is inside the graph, corresponding to the
00277     // (0,0) location of the plot(s), rather than outside the graph.  The
00278     // secondary axis is the axis at which the mirrored axis will be placed at
00279     // the 0 value of.  For example, to show the Cartesian X_BOTTOM axis you'd
00280     // likely want to mirror the axis at Y_LEFT = 0, so that would be the
00281     // secondary axis.  If hideNormalAxis is true, it is equivalent to
00282     // showAxis(mirrorAxis, !hideNormalAxis).
00283     virtual void showCartesianAxis(PlotAxis mirrorAxis, PlotAxis secondaryAxis,
00284             bool show = true, bool hideNormalAxis = true) = 0;
00285     
00286     // Convenience methods for most common Cartesian axes cases.
00287     // DEFAULT IMPLEMENTATION.
00288     // <group>
00289     virtual void showCartesianAxis(PlotAxis mirrorAxis, bool show = true,
00290                                    bool hideNormalAxis = true);
00291     virtual void showCartesianAxes(bool show = true, bool hideNormal = true);
00292     // </group>
00293     
00294     // Returns the label for the given axis, or an empty String if none is
00295     // shown.
00296     virtual String axisLabel(PlotAxis axis) const = 0;
00297     
00298     // Sets the label of an axis title to the given.  Setting the title to an
00299     // empty string should remove the title from the axis.
00300     virtual void setAxisLabel(PlotAxis axis, const String& title) = 0;
00301     
00302     // Convenience method for clearing labels from all axes.
00303     // DEFAULT IMPLEMENTATION.
00304     virtual void clearAxesLabels();
00305     
00306     // Returns a copy of the font used for the given axis label.  If no title
00307     // is shown this behavior is undefined.
00308     virtual PlotFontPtr axisFont(PlotAxis axis) const = 0;
00309     
00310     // Set the font of the axis title to the given.
00311     virtual void setAxisFont(PlotAxis axis, const PlotFont& font) = 0;
00312     
00313     // Convenience method for setting axis font.
00314     // DEFAULT IMPLEMENTATION.
00315     virtual void setAxisFont(PlotAxis axis, const PlotFontPtr font);
00316     
00317     // Returns true if a color bar is shown on the given axis, false otherwise.
00318     // A color bar should only be shown when one of more of the items on the
00319     // canvas is a RasterPlot or a SpectrogramPlot.  If there are multiple
00320     // raster or spectrograms, behavior is undefined.
00321     virtual bool colorBarShown(PlotAxis axis = Y_RIGHT) const = 0;
00322     
00323     // Shows/hides a color bar is shown on the given axis.  (See
00324     // colorBarShown().)
00325     virtual void showColorBar(bool show = true, PlotAxis axis = Y_RIGHT) = 0;
00326     
00327     
00328     // Axes Range Methods //
00329     
00330     // Returns the displayed range of the given axis, in world coordinates.
00331     virtual prange_t axisRange(PlotAxis axis) const = 0;
00332     
00333     // Returns the displayed ranges of the given axes, in world coordinates.
00334     // DEFAULT IMPLEMENTATION.
00335     virtual PlotRegion axesRanges(PlotAxis xAxis, PlotAxis yAxis) const;
00336     
00337     // Sets the displayed range of the given axis, in world coordinates.
00338     // Implies setAxesAutoRescale(false), and does NOT reset tool stacks since
00339     // the tools may be using this method.
00340     virtual void setAxisRange(PlotAxis axis, double from, double to) = 0;
00341     
00342     // See setAxisRange(PlotAxis, double, double).
00343     // DEFAULT IMPLEMTNATION.
00344     virtual void setAxisRange(PlotAxis axis, const prange_t& range);
00345     
00346     // Sets the displayed ranges of the given axes, in world coordinates.
00347     // Implies setAxesAutoRescale(false), and does NOT reset tool stacks since
00348     // the tools may be using this method.  It is recommended that subclasses
00349     // reimplement this to be more efficient.
00350     // DEFAULT IMPLEMENTATION.
00351     // <group>
00352     virtual void setAxesRanges(PlotAxis xAxis, double xFrom, double xTo,
00353                                PlotAxis yAxis, double yFrom, double yTo);    
00354     virtual void setAxesRanges(PlotAxis xAxis, const prange_t& xRange,
00355             PlotAxis yAxis, const prange_t& yRange);
00356     // </group>
00357     
00358     // Sets the displayed range of the given axes. Implies
00359     // setAxesAutoRescale(false),  and does NOT reset tool stacks since the
00360     // tools may be using this method.
00361     // DEFAULT IMPLEMENTATION.
00362     virtual void setAxesRegion(PlotAxis xAxis, PlotAxis yAxis,
00363             const PlotRegion& region);
00364     
00365     // Moves (pans) the axes range by the given delta, in world coordinates.
00366     // Implies setAxesAutoRescale(false), and does NOT reset tool stacks since
00367     // the tools may be using these methods.
00368     // DEFAULT IMPLEMENTATION.
00369     // <group>
00370     virtual void moveAxisRange(PlotAxis axis, double delta);
00371     virtual void moveAxesRanges(PlotAxis xAxis, double xDelta,
00372                                 PlotAxis yAxis, double yDelta);
00373     // </group>
00374     
00375     // Returns true if the axes are set to autorescale when a new plot item is
00376     // added, false otherwise.
00377     virtual bool axesAutoRescale() const = 0;
00378     
00379     // Sets auto-rescaling for future plot items.  If autoRescale is true,
00380     // implies setAxesRatioLocked(false).
00381     virtual void setAxesAutoRescale(bool autoRescale = true) = 0;
00382     
00383     // Rescales the axis to show all plot items on the canvas.  Implies
00384     // setAxesAutoRescale(false), and may reset PlotTools.
00385     virtual void rescaleAxes() = 0;
00386     
00387     // Returns true if the axes ratio is locked, false otherwise.  If the
00388     // ratio is locked, resizing one axis will resize the others
00389     // proportionally.
00390     virtual bool axesRatioLocked() const = 0;
00391     
00392     // Sets whether the axes ratio is locked or not.
00393     virtual void setAxesRatioLocked(bool locked = true) = 0;
00394     
00395     
00396     // Stack Methods //
00397     
00398     // Returns a single PlotAxesStack associated with this canvas.  Note that
00399     // the canvas itself doesn't modify/use this stack AT ALL; it is expressly
00400     // for outside tools/classes/etc to have a single stack per canvas.
00401     // DEFAULT IMPLEMENTATION.
00402     // <group>
00403     virtual PlotAxesStack& axesStack();
00404     virtual const PlotAxesStack& axesStack() const;
00405     // </group>
00406     
00407     // Convenience method to move along the PlotAxesStack associated with this
00408     // canvas (see axesStack()).  Calls the stack's moveAndReturn method, and
00409     // then sets the axes ranges to the returned PlotRegion.  If delta is 0,
00410     // the stack is moved to its base; otherwise it moves forward or backward
00411     // from the current stack index (see PlotAxesStack::moveAndReturn()).
00412     // Returns true if the operation succeeded, false otherwise (for invalid
00413     // delta).
00414     // DEFAULT IMPLEMENTATION.
00415     virtual bool axesStackMove(int delta);
00416     
00417     // Gets/Sets the length limit on the PlotAxesStack associated with this
00418     // canvas.  See PlotAxesStack::lengthLimit() and
00419     // PlotAxesStack::setLengthLimit().
00420     // DEFAULT IMPLEMENTATION.
00421     // <group>
00422     virtual int axesStackLengthLimit() const;
00423     virtual void setAxesStackLengthLimit(int lengthLimit);
00424     // </group>
00425     
00426     // Gets/Sets the size limit, in kilobytes, on the draw cache for the axes
00427     // stack associated with this canvas (see
00428     // PlotFactory::canvasHasCachedAxesStack()).  A zero or negative value
00429     // means no limit.  NOTE: Only valid for implementations that supports a
00430     // cached axes stack.
00431     // <group>
00432     virtual int cachedAxesStackSizeLimit() const = 0;
00433     virtual void setCachedAxesStackSizeLimit(int sizeInKilobytes) = 0;
00434     // </group>
00435     
00436     // Gets/Sets the size of the image used for the cached axes stack, in
00437     // pixels.  The default implementation is set to (-1, -1) which means that
00438     // the images are set to the current size of the canvas.  It could be
00439     // useful to set this value to a large size so that, for example, resizing
00440     // wouldn't require a redraw of the whole canvas but rather just resizing
00441     // the larger image to a smaller one.
00442     // DEFAULT IMPLEMENTATION.
00443     // <group>
00444     virtual pair<int, int> cachedAxesStackImageSize() const;
00445     virtual void setCachedAxesStackImageSize(int width, int height);
00446     // </group>
00447     
00448     
00449     // Plot Methods //
00450     
00451     // Adds the given plot item to this canvas, if not null or otherwise
00452     // invalid.  Returns whether the adding succeeded or not.  May reset
00453     // registered PlotTools.
00454     virtual bool plotItem(PlotItemPtr item, PlotCanvasLayer layer = MAIN) = 0;
00455     
00456     // Item-specific add methods.
00457     // DEFAULT IMPLEMENTATION.
00458     // <group>
00459     virtual bool plot(PlotPtr plot, bool overplot = true);
00460     virtual bool plotPoint(PlotPointPtr point);
00461     virtual bool drawShape(PlotShapePtr shape);
00462     virtual bool drawAnnotation(PlotAnnotationPtr annotation);
00463     // </group>
00464     
00465     // Returns all plot items currently on the canvas.
00466     virtual vector<PlotItemPtr> allPlotItems() const = 0;
00467     
00468     // Item-specific all methods.
00469     // DEFAULT IMPLEMENTATION.
00470     // <group>
00471     virtual vector<PlotPtr> allPlots() const;
00472     virtual vector<PlotPointPtr> allPoints() const;
00473     virtual vector<PlotShapePtr> allShapes() const;
00474     virtual vector<PlotAnnotationPtr> allAnnotations() const;
00475     // </group>
00476     
00477     // Returns the number of plot items currently on the canvas.
00478     // DEFAULT IMPLEMENTATION.
00479     virtual unsigned int numPlotItems() const;
00480     
00481     // Item-specific num methods.
00482     // DEFAULT IMPLEMENTATION.
00483     // <group>
00484     virtual unsigned int numPlots() const;
00485     virtual unsigned int numPoints() const;
00486     virtual unsigned int numShapes() const;
00487     virtual unsigned int numAnnotations() const;
00488     // </group>
00489     
00490     // Returns all plot items currently on the given layer of the canvas.
00491     virtual vector<PlotItemPtr> layerPlotItems(PlotCanvasLayer layer) const= 0;
00492     
00493     // Item-specific layer methods.
00494     // DEFAULT IMPLEMENTATION.
00495     // <group>
00496     virtual vector<PlotPtr> layerPlots(PlotCanvasLayer layer) const;
00497     virtual vector<PlotPointPtr> layerPoints(PlotCanvasLayer layer) const;
00498     virtual vector<PlotShapePtr> layerShapes(PlotCanvasLayer layer) const;
00499     virtual vector<PlotAnnotationPtr> layerAnnotations(PlotCanvasLayer l)const;
00500     // </group>
00501     
00502     // Returns the number of plot items currently on the given layer of the
00503     // canvas.
00504     // DEFAULT IMPLEMENTATION.
00505     virtual unsigned int numLayerPlotItems(PlotCanvasLayer layer) const;
00506     
00507     // Item-specific layer num methods.
00508     // DEFAULT IMPLEMENTATION.
00509     // <group>
00510     virtual unsigned int numLayerPlots(PlotCanvasLayer layer) const;
00511     virtual unsigned int numLayerPoints(PlotCanvasLayer layer) const;
00512     virtual unsigned int numLayerShapes(PlotCanvasLayer layer) const;
00513     virtual unsigned int numLayerAnnotations(PlotCanvasLayer layer) const;
00514     // </group>    
00515     
00516     // Removes the given item from this canvas (if valid) and updates the GUI.
00517     // May reset registered PlotTools.
00518     // DEFAULT IMPLEMENTATION.
00519     virtual void removePlotItem(PlotItemPtr item);
00520     
00521     // Item-specific remove methods.
00522     // DEFAULT IMPLEMENTATION.
00523     // <group>
00524     virtual void removePlot(PlotPtr plot);
00525     virtual void removePoint(PlotPointPtr point);
00526     virtual void removeShape(PlotShapePtr shape);
00527     virtual void removeAnnotation(PlotAnnotationPtr annotation);
00528     // </group>
00529     
00530     // Removes the given items from this canvas (if valid) and updates the GUI.
00531     // May reset registered PlotTools.
00532     virtual void removePlotItems(const vector<PlotItemPtr>& items) = 0;
00533     
00534     // Removes the last plot item added to the canvas and updates the GUI.  May
00535     // reset registered PlotTools.
00536     // DEFAULT IMPLEMENTATION.
00537     virtual void removeLastPlotItem();
00538     
00539     // Item-specific remove last methods.
00540     // DEFAULT IMPLEMENTATION.
00541     // <group>
00542     virtual void removeLastPlot();
00543     virtual void removeLastPoint();
00544     virtual void removeLastShape();
00545     virtual void removeLastAnnotation();
00546     // </group>
00547     
00548     // Clears all plot items from this canvas and updates the GUI.  May reset
00549     // registered PlotTools.
00550     // DEFAULT IMPLEMENTATION.
00551     virtual void clearItems();
00552     
00553     // Item-specific clear methods.
00554     // DEFAULT IMPLEMENTATION.
00555     // <group>
00556     virtual void clearPlots();
00557     virtual void clearPoints();
00558     virtual void clearShapes();
00559     virtual void clearAnnotations();
00560     // </group>
00561     
00562     // Clears all plot items from the given layer on this canvas and updates
00563     // the GUI.  May reset registered PlotTools.
00564     // DEFAULT IMPLEMENTATION.
00565     virtual void clearLayer(PlotCanvasLayer layer);
00566     
00567     
00568     // Draw Methods //
00569     
00570     // Hold or release drawing of plot items on the canvas.  This can be used,
00571     // for example, when adding many items to a canvas to avoid redrawing the
00572     // canvas until all items are on.  Hold/release are NOT recursive.
00573     // <group>
00574     virtual void holdDrawing() = 0;
00575     virtual void releaseDrawing() = 0;
00576     virtual bool drawingIsHeld() const = 0;
00577     // </group>
00578     
00579     // Registers/Unregisters the given draw watcher for this canvas.  See
00580     // documentation for PlotDrawWatcher.
00581     // DEFAULT IMPLEMENTATION.
00582     // <group>
00583     virtual void registerDrawWatcher(PlotDrawWatcherPtr watcher);    
00584     virtual void unregisterDrawWatcher(PlotDrawWatcherPtr watcher);
00585     // </group>
00586     
00587     // Returns a PlotOperation object that can be used to track drawing
00588     // progress across threads.  There must be one PlotOperation for drawing
00589     // per canvas.
00590     // DEFAULT IMPLEMENTATION.
00591     // <group>
00592     virtual PlotOperationPtr operationDraw();
00593     virtual PlotOperationPtr operationDraw(PlotMutexPtr mutex);
00594     // </group>
00595     
00596     
00597     // Selection Methods //
00598     
00599     // Returns true if a line is shown for the selection tool, false otherwise.
00600     // DEFAULT IMPLEMENTATION.
00601     virtual bool selectLineShown() const;
00602     
00603     // Sets whether a line is shown for the selection tool.
00604     virtual void setSelectLineShown(bool shown = true) = 0;
00605     
00606     // returns a copy of the line for the selection tool
00607     virtual PlotLinePtr selectLine() const = 0;
00608     
00609     // set the line for the selection tool
00610     virtual void setSelectLine(const PlotLine& line) = 0;
00611     
00612     // Convenience methods for setting selection line.
00613     // DEFAULT IMPLEMENTATION.
00614     // <group>
00615     virtual void setSelectLine(const PlotLinePtr line);
00616     virtual void setSelectLine(const String& color,
00617                                PlotLine::Style style = PlotLine::SOLID,
00618                                double width = 1.0);
00619     // </group>
00620     
00621     
00622     // Grid Methods //
00623     
00624     // Returns true if any grid lines are shown, false otherwise.  If bool
00625     // parameters are given, they will be set for if each line group is shown
00626     // or not.
00627     virtual bool gridShown(bool* xMajor = NULL, bool* xMinor = NULL,
00628             bool* yMajor = NULL, bool* yMinor = NULL) const = 0;
00629     
00630     // Sets whether the grid is shown, for each of the given line groups.
00631     virtual void showGrid(bool xMajor, bool xMinor, bool yMajor,bool yMinor)=0;
00632     
00633     // Convenience methods for showing/hiding the grid.
00634     // DEFAULT IMPLEMENTATION.
00635     // <group>
00636     virtual void showGrid(bool showAll = true);
00637     virtual void showGridMajor(bool show = true);
00638     virtual void showGridMinor(bool show = true);
00639     // </group>
00640     
00641     // Gets/Sets whether major grid lines are shown for the x-axis.
00642     // DEFAULT IMPLEMENTATION.
00643     // <group>
00644     virtual bool gridXMajorShown() const;
00645     virtual void showGridXMajor(bool s = true);
00646     // </group>
00647     
00648     // Gets/Sets  whether minor grid lines are shown for the x-axis.
00649     // DEFAULT IMPLEMENTATION.
00650     // <group>
00651     virtual bool gridXMinorShown() const;
00652     virtual void showGridXMinor(bool s = true);
00653     // </group>
00654     
00655     // Gets/Sets whether major grid lines are shown for the y-axis.
00656     // DEFAULT IMPLEMENTATION.
00657     // <group>
00658     virtual bool gridYMajorShown() const;
00659     virtual void showGridYMajor(bool s = true);
00660     // </group>
00661 
00662     // Gets/Sets whether minor grid lines are shown for the y-axis.
00663     // DEFAULT IMPLEMENTATION.
00664     // <group>
00665     virtual bool gridYMinorShown() const;
00666     virtual void showGridYMinor(bool s = true);
00667     // </group>
00668     
00669     // Returns a copy of the line used to draw the major grid lines.
00670     virtual PlotLinePtr gridMajorLine() const = 0;
00671     
00672     // Sets the line used to draw the major grid lines.
00673     virtual void setGridMajorLine(const PlotLine& line) = 0;
00674     
00675     // Returns a copy of the line used to draw the minor grid lines.
00676     virtual PlotLinePtr gridMinorLine() const = 0;
00677     
00678     // Sets the line used to draw the minor grid lines.
00679     virtual void setGridMinorLine(const PlotLine& line) = 0;
00680     
00681     // Convenience methods for setting major/minor grid lines.
00682     // DEFAULT IMPLEMENTATION.
00683     // <group>
00684     virtual void setGridMajorLine(const PlotLinePtr line);
00685     virtual void setGridMajorLine(const String& color,
00686             PlotLine::Style style = PlotLine::SOLID, double width = 1.0);
00687     virtual void setGridMinorLine(const PlotLinePtr line);
00688     virtual void setGridMinorLine(const String& color,
00689             PlotLine::Style style = PlotLine::SOLID, double width = 1.0);
00690     // </group>
00691     
00692     
00693     // Legend Methods //
00694     
00695     // Returns whether the legend is shown or not
00696     virtual bool legendShown() const = 0;
00697     
00698     // Show/hide the legend.  If on is true, show the legend in the given
00699     // position.
00700     virtual void showLegend(bool on = true,
00701                             LegendPosition position = EXT_BOTTOM) = 0;
00702     
00703     // Returns the position of the legend.  Note: if the legend is hidden,
00704     // this behavior is undefined.
00705     virtual LegendPosition legendPosition() const = 0;
00706     
00707     // Sets the position of the legend, if it is shown.
00708     virtual void setLegendPosition(LegendPosition position) = 0;
00709     
00710     // Returns a copy of the line used to outline the legend.
00711     virtual PlotLinePtr legendLine() const = 0;
00712     
00713     // Sets the line used to outline the legend.
00714     virtual void setLegendLine(const PlotLine& line) = 0;
00715     
00716     // Convenience methods for setting legend line.
00717     // DEFAULT IMPLEMENTATION.
00718     // <group>
00719     virtual void setLegendLine(const PlotLinePtr line);
00720     virtual void setLegendLine(const String& color,
00721             PlotLine::Style style = PlotLine::SOLID, double width = 1.0);
00722     // </group>
00723     
00724     // Returns a copy of the area fill used for the legend background
00725     virtual PlotAreaFillPtr legendFill() const = 0;
00726     
00727     // Sets the area fill used for the legend background
00728     virtual void setLegendFill(const PlotAreaFill& area) = 0;
00729     
00730     // Convenience methods for setting legend background.
00731     // DEFAULT IMPLEMENTATION.
00732     // <group>
00733     virtual void setLegendFill(const PlotAreaFillPtr area);
00734     virtual void setLegendFill(const String& color,
00735             PlotAreaFill::Pattern pattern = PlotAreaFill::FILL);
00736     // </group>
00737     
00738     // Returns a copy of the font used for the legend text.
00739     virtual PlotFontPtr legendFont() const = 0;
00740     
00741     // Sets the font used for the legend text.
00742     virtual void setLegendFont(const PlotFont& font) = 0;
00743     
00744     // Convenience method for setting legend font.
00745     // DEFAULT IMPLEMENTATION.
00746     virtual void setLegendFont(const PlotFontPtr font);
00747 
00748 
00749     // Miscellaneous Plotting Functionality //
00750     
00751     // Returns true if autoincrementcolors is on, false otherwise.  (See
00752     // setAutoIncrementColors().)
00753     virtual bool autoIncrementColors() const = 0;
00754     
00755     // Sets whether adding new overplotted plots should automatically
00756     // "increment" colors or not.  If this property is true, each new
00757     // overplotted plot should have a different color.  The specific handling
00758     // of this behavior is left up to the implementation.
00759     virtual void setAutoIncrementColors(bool autoInc = true) = 0;
00760 
00761     // Exports this canvas to the given format and returns true on success.
00762     virtual bool exportToFile(const PlotExportFormat& format) = 0;
00763     
00764     // Returns a PlotOperation object that can be used to track export
00765     // progress across threads.  There must be one PlotOperation for export
00766     // per canvas.
00767     // DEFAULT IMPLEMENTATION.
00768     // <group>
00769     virtual PlotOperationPtr operationExport();
00770     virtual PlotOperationPtr operationExport(PlotMutexPtr mutex);
00771     // </group>
00772     
00773     // Shows a file chooser dialog and return the absolute filename that the
00774     // user chooses.  If a directory is given, start the dialog there.  If the
00775     // user cancels the dialog, an empty String should be returned.
00776     virtual String fileChooserDialog(const String& title = "File Chooser",
00777                                      const String& directory = "") = 0;
00778     
00779     // Gets/Sets the date format for this canvas.  See Plotter::dateFormat().
00780     // <group>
00781     virtual const String& dateFormat() const = 0;
00782     virtual void setDateFormat(const String& dateFormat) = 0;
00783     // </group>
00784     
00785     // Gets/Sets the date format for values relative to a reference value for
00786     // this canvas.  See Plotter::relativeDateFormat().
00787     // <group>
00788     virtual const String& relativeDateFormat() const = 0;
00789     virtual void setRelativeDateFormat(const String& dateFormat) = 0;
00790     // </group>
00791 
00792     // Converts the given coordinate into a coordinate with the given system.
00793     virtual PlotCoordinate convertCoordinate(const PlotCoordinate& coord,
00794            PlotCoordinate::System newSystem = PlotCoordinate::WORLD) const = 0;
00795     
00796     // Converts the given region into a region with the given system.
00797     // DEFAULT IMPLEMENTATION.
00798     virtual PlotRegion convertRegion(const PlotRegion& region,
00799                                      PlotCoordinate::System newSystem) const;
00800     
00801     // Returns the width, height, and descent for the given text in the given
00802     // font.  Note: this was put into place for use in a matplotlib backend,
00803     // but probably doesn't have much use outside that.
00804     virtual vector<double> textWidthHeightDescent(const String& text,
00805             PlotFontPtr font) const = 0;
00806     
00807     // Returns the width, height, and descent for the given annotation.  Note:
00808     // this was put into place for use in a matplotlib backend, but probably
00809     // doesn't have much use outside that.
00810     // DEFAULT IMPLEMENTATION.
00811     virtual vector<double> annotationWidthHeightDescent(
00812             const PlotAnnotationPtr annot) const;
00813     
00814     // Returns the implementation of this canvas as a Plotter::Implementation
00815     // value.
00816     virtual int implementation() const = 0;
00817     
00818     // Returns a new instance of a PlotFactory that can create plot items for
00819     // this implementation.  It is the caller's responsibility to delete the
00820     // PlotFactory when finished.
00821     virtual PlotFactory* implementationFactory() const = 0;
00822     
00823     // Returns a mutex appropriate for this implementation.
00824     // DEFAULT IMPLEMENTATION.
00825     virtual PlotMutexPtr mutex() const;
00826     
00827     // Locate data indices that have values within the given region such that:
00828     // x >= region.upperLeft().x() && x <= region.lowerRight().x() &&
00829     // y <= region.upperLeft().y() && y >= region.lowerRight().y().
00830     // The returned vector has length equal to allPlots().size() (in other
00831     // words, each plot on the canvas has an index in the returned vector).
00832     // Each element of the returned vector is a list of all the data indices
00833     // that are in the region.  Each element in this list is a range of indices.
00834     // For plots that have no data in the region, the list is empty.
00835     // 
00836     // For example, say there are two plots on the canvas.  In the first plot,
00837     // indices 1, 2, 3, 7, and 10 are in the region; in the second plot,
00838     // indices 6 and 7 are in the region.  The returned value would be a vector
00839     // of size 2.  The first element would be the list [(1, 3), (7, 7),
00840     // (10, 10)] while the second element would be the list [(6, 7)].
00841     // DEFAULT IMPLEMENTATION.
00842     virtual vector<vector<pair<unsigned int, unsigned int> > >* locate(
00843             const PlotRegion& region) const;
00844     
00845     // Calls locate() and posts the result to the given log.
00846     // DEFAULT IMPLEMENTATION.
00847     virtual void locateAndLog(const PlotRegion& region,
00848             PlotLoggerPtr logger) const;
00849     
00850     
00851     // Tool Methods //
00852     
00853     // Manage mouse tools.
00854     // DEFAULT IMPLEMENTATION.
00855     // <group>
00856     virtual void registerMouseTool(PlotMouseToolPtr tool, bool activate = true,
00857             bool blocking = false);
00858     virtual vector<PlotMouseToolPtr> allMouseTools() const;
00859     virtual vector<PlotMouseToolPtr> activeMouseTools() const;
00860     virtual void unregisterMouseTool(PlotMouseToolPtr tool);
00861     // </group>
00862     
00863     // Returns the standard mouse tools associated with this canvas.  If none
00864     // is associated, creates and associates one that is non-active.
00865     // DEFAULT IMPLEMENTATION.
00866     virtual PlotStandardMouseToolGroupPtr standardMouseTools();
00867     
00868     
00869     // Event Handler Methods //
00870     
00871     // Manage select handlers.
00872     // DEFAULT IMPLEMENTATION.
00873     // <group>
00874     virtual void registerSelectHandler(PlotSelectEventHandlerPtr handler,
00875             PlotCoordinate::System system = PlotCoordinate::WORLD);
00876     virtual vector<PlotSelectEventHandlerPtr> allSelectHandlers() const;
00877     virtual void unregisterSelectHandler(PlotSelectEventHandlerPtr handler);
00878     // </group>
00879     
00880     // Manage click handlers.
00881     // DEFAULT IMPLEMENTATION.
00882     // <group>
00883     virtual void registerClickHandler(PlotClickEventHandlerPtr handler,
00884             PlotCoordinate::System system = PlotCoordinate::WORLD);
00885     virtual vector<PlotClickEventHandlerPtr> allClickHandlers() const;
00886     virtual void unregisterClickHandler(PlotClickEventHandlerPtr handler);
00887     // </group>
00888     
00889     // Manage mouse press handlers.
00890     // DEFAULT IMPLEMENTATION.
00891     // <group>
00892     virtual void registerMousePressHandler(PlotMousePressEventHandlerPtr hndlr,
00893             PlotCoordinate::System system = PlotCoordinate::WORLD);
00894     virtual vector<PlotMousePressEventHandlerPtr>
00895             allMousePressHandlers() const;
00896     virtual void unregisterMousePressHandler(
00897             PlotMousePressEventHandlerPtr handler);
00898     // </group>
00899     
00900     // Manage mouse release handlers.
00901     // DEFAULT IMPLEMENTATION.
00902     // <group>
00903     virtual void registerMouseReleaseHandler(
00904             PlotMouseReleaseEventHandlerPtr handler,
00905             PlotCoordinate::System system = PlotCoordinate::WORLD);
00906     virtual vector<PlotMouseReleaseEventHandlerPtr>
00907             allMouseReleaseHandlers() const;
00908     virtual void unregisterMouseReleaseHandler(
00909             PlotMouseReleaseEventHandlerPtr handler);
00910     // </group>
00911     
00912     // Manage mouse drag handlers.
00913     // DEFAULT IMPLEMENTATION.
00914     // <group>
00915     virtual void registerMouseDragHandler(PlotMouseDragEventHandlerPtr h,
00916             PlotCoordinate::System system = PlotCoordinate::WORLD);
00917     virtual vector<PlotMouseDragEventHandlerPtr> allMouseDragHandlers() const;
00918     virtual void unregisterMouseDragHandler(PlotMouseDragEventHandlerPtr h);
00919     // </group>
00920     
00921     // Manage mouse move handlers.  NOTE: since this can be costly, it should
00922     // be avoided if possible.  Implementation canvases are expected to
00923     // conserve resources if no move handlers are registered.
00924     // DEFAULT IMPLEMENTATION.
00925     // <group>
00926     virtual void registerMouseMoveHandler(PlotMouseMoveEventHandlerPtr h,
00927             PlotCoordinate::System system = PlotCoordinate::WORLD);
00928     virtual vector<PlotMouseMoveEventHandlerPtr> allMouseMoveHandlers() const;
00929     virtual void unregisterMouseMoveHandler(PlotMouseMoveEventHandlerPtr h);
00930     // </group>
00931     
00932     // Manage wheel handlers.
00933     // DEFAULT IMPLEMENTATION.
00934     // <group>
00935     virtual void registerWheelHandler(PlotWheelEventHandlerPtr handler,
00936             PlotCoordinate::System system = PlotCoordinate::WORLD);
00937     virtual vector<PlotWheelEventHandlerPtr> allWheelHandlers() const;
00938     virtual void unregisterWheelHandler(PlotWheelEventHandlerPtr handler);
00939     // </group>
00940     
00941     // Manage key handlers.
00942     // DEFAULT IMPLEMENTATION.
00943     // <group>
00944     virtual void registerKeyHandler(PlotKeyEventHandlerPtr handler);
00945     virtual vector<PlotKeyEventHandlerPtr> allKeyHandlers() const;
00946     virtual void unregisterKeyHandler(PlotKeyEventHandlerPtr handler);
00947     // </group>
00948     
00949     // Manage resize handlers.
00950     // DEFAULT IMPLEMENTATION.
00951     // <group>
00952     virtual void registerResizeHandler(PlotResizeEventHandlerPtr handler);
00953     virtual vector<PlotResizeEventHandlerPtr> allResizeHandlers() const;
00954     virtual void unregisterResizeHandler(PlotResizeEventHandlerPtr handler);
00955     // </group>
00956     
00957 protected:    
00958     // One-per-canvas axes stack.
00959     PlotAxesStack m_stack;
00960     
00961     // One-per-canvas operations.
00962     // <group>
00963     PlotOperationPtr m_drawOperation;
00964     PlotOperationPtr m_exportOperation;
00965     // </group>
00966     
00967     // Draw watchers.
00968     vector<PlotDrawWatcherPtr> m_drawWatchers;
00969     
00970     // One-per-canvas standard mouse tools.
00971     PlotStandardMouseToolGroupPtr m_standardTools;
00972     
00973     // Registered mouse tools.
00974     vector<PlotMouseToolPtr> m_mouseTools;
00975     
00976     // Event handlers.
00977     // <group>
00978     vector<pair<PlotSelectEventHandlerPtr, PlotCoordinate::System> >
00979         m_selectHandlers;
00980     vector<pair<PlotClickEventHandlerPtr, PlotCoordinate::System> >
00981         m_clickHandlers;
00982     vector<pair<PlotMousePressEventHandlerPtr, PlotCoordinate::System> >
00983         m_pressHandlers;
00984     vector<pair<PlotMouseReleaseEventHandlerPtr, PlotCoordinate::System> >
00985         m_releaseHandlers;
00986     vector<pair<PlotMouseDragEventHandlerPtr, PlotCoordinate::System> >
00987         m_dragHandlers;
00988     vector<pair<PlotMouseMoveEventHandlerPtr, PlotCoordinate::System> >
00989         m_moveHandlers;
00990     vector<pair<PlotWheelEventHandlerPtr, PlotCoordinate::System> >
00991         m_wheelHandlers;
00992     vector<PlotKeyEventHandlerPtr> m_keyHandlers;
00993     vector<PlotResizeEventHandlerPtr> m_resizeHandlers;
00994     // </group>
00995     
00996     
00997     // Resets mouse tools.
00998     void resetMouseTools();
00999     
01000     // Notifies any registered draw watchers that a draw is about to begin, and
01001     // returns the AND of the PlotDrawWatcher::canvasDrawBeginning() results.
01002     // See PlotDrawWatcher::canvasDrawBeginning() for parameters.
01003     bool notifyDrawWatchers(PlotOperationPtr drawOperation,
01004             bool drawingIsThreaded, int drawnLayersFlag);
01005     
01006     // Notification methods for event handlers.  Returns true if one mouse tool
01007     // or event handler was available to handle the event, false otherwise.
01008     // <group>
01009     bool notifySelectHandlers(const PlotRegion& selectedRegion);
01010     bool notifyMouseHandlers(PlotMouseEvent::Type type,
01011             PlotMouseEvent::Button button, const PlotCoordinate& coord);
01012     bool notifyClickHandlers(PlotMouseEvent::Button button,
01013             const PlotCoordinate& coord);
01014     bool notifyPressHandlers(PlotMouseEvent::Button button,
01015             const PlotCoordinate& coord);
01016     bool notifyReleaseHandlers(PlotMouseEvent::Button button,
01017             const PlotCoordinate& coord);
01018     bool notifyDragHandlers(PlotMouseEvent::Button button,
01019             const PlotCoordinate& coord);
01020     bool notifyMoveHandlers(PlotMouseEvent::Button button,
01021             const PlotCoordinate& coord);
01022     bool notifyWheelHandlers(int delta, const PlotCoordinate& coord);
01023     bool notifyKeyHandlers(char key,
01024             const vector<PlotKeyEvent::Modifier>& modifiers);
01025     bool notifyResizeHandlers(int oldWidth, int oldHeight,
01026             int newWidth, int newHeight);
01027     // </group>
01028 };
01029 typedef CountedPtr<PlotCanvas> PlotCanvasPtr;
01030 
01031 }
01032 
01033 #endif /*PLOTCANVAS_H_*/