casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Plotter.h
Go to the documentation of this file.
00001 //# Plotter.h: Highest level plotting object that holds one or more canvases.
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 PLOTTER_H_
00028 #define PLOTTER_H_
00029 
00030 #include <graphics/GenericPlotter/PlotCanvasLayout.h>
00031 #include <graphics/GenericPlotter/PlotLogger.h>
00032 #include <graphics/GenericPlotter/PlotPanel.h>
00033 
00034 namespace casa {
00035 
00036 //# Forward Declarations
00037 class PlotFactory;
00038 
00039 
00040 // A Plotter can be thought of as a frame that holds one or more PlotCanvases
00041 // in a configuration determined by a given PlotCanvasLayout.  It also has
00042 // some top-level and main-window functionality.
00043 class Plotter {
00044 public:
00045     // Static //
00046     
00047     // This enum should contain all known implementations.
00048     enum Implementation {
00049         QWT,
00050         
00051         // Default plotter implementation is set here.
00052         DEFAULT = QWT
00053     };
00054     
00055     // Default implementation-specific GUI panels that can be turned on or off.
00056     enum DefaultPanel {
00057         HAND_TOOLS,  // buttons/tools to: select regions, zoom, and pan;
00058                      // (optionally) turn on/off tracker;
00059                      // (optionally) show/hide and position legend
00060         EXPORT_TOOLS // buttons/tools to export the canvases to a file
00061     };
00062     
00063     // The default date format to use for the plotter.  See dateFormat().
00064     static const String DEFAULT_DATE_FORMAT;
00065     
00066     // The default relative date format to use for the plotter.  See
00067     // relativeDateFormat().
00068     static const String DEFAULT_RELATIVE_DATE_FORMAT;
00069     
00070     // Returns a String for the given date value using the given format (see
00071     // dateFormat()) and scale.  If isRelative is true, the value is treated as
00072     // a relative value (i.e., +X seconds past a reference date); otherwise it
00073     // is treated as an absolute value.  For relative values years, months, and
00074     // days are ignored.
00075     static String formattedDateString(const String& format, double value,
00076             PlotAxisScale scale, bool isRelative = false);
00077     
00078     
00079     // Non-Static //
00080     
00081     // Constructor.
00082     Plotter();
00083     
00084     // Destructor.
00085     virtual ~Plotter();
00086     
00087     
00088     // ABSTRACT METHODS //
00089     
00090     // Top-Level GUI methods //
00091     
00092     // Shows/hides the plotter GUI.
00093     virtual void showGUI(bool showGUI = true) = 0;
00094     
00095     // Returns the current size of the plotter GUI in pixels (width x height).
00096     virtual pair<int, int> size() const = 0;
00097     
00098     // Sets the plotter GUI size in pixels
00099     virtual void setSize(int width, int height) = 0;
00100     
00101     // Returns the plotter window's title.
00102     virtual String windowTitle() const = 0;
00103     
00104     // Sets the plotter window's title to the given.
00105     virtual void setWindowTitle(const String& newTitle) = 0;
00106     
00107     // Returns the size of the canvas area (i.e., minus bordering panels) in
00108     // pixels (width x height).
00109     virtual pair<int, int> canvasAreaSize() const = 0;
00110     
00111     // If the plotter has a single canvas, sets the size of the canvas to the
00112     // given.  If resizeWindow is true, the plotter is resized to fit the new
00113     // canvas size.
00114     virtual void setCanvasSize(int width, int height,
00115                                bool resizeWindow = true) = 0;
00116     
00117     // Returns the DPI used in the GUI display.
00118     virtual int displayDPI() const = 0;
00119     
00120     // Returns true if the plotter window can be casted to a QWidget, false
00121     // otherwise.
00122     virtual bool isQWidget() const = 0;
00123     
00124     // Gets/sets cursor for the whole plotter.  Can be overridden by individual
00125     // canvases.
00126     // <group>
00127     virtual PlotCursor cursor() const = 0;
00128     virtual void setCursor(PlotCursor cursor) = 0;
00129     // </group>
00130     
00131     // Refreshes the plotter GUI.
00132     virtual void refresh() = 0;
00133     
00134     // Closes the plotter window.
00135     virtual void close() = 0;
00136    
00137     
00138     // Canvas Layout methods //
00139     
00140     // Returns the current layout, or a null pointer if none has been set.
00141     virtual PlotCanvasLayoutPtr canvasLayout() = 0;
00142     
00143     // Sets the canvas layout to the given.  Clears out old canvases as needed.
00144     virtual void setCanvasLayout(PlotCanvasLayoutPtr layout) = 0;
00145     
00146     // Method for when the layout has changed (i.e. changed canvases, etc.).
00147     // This should only be used by the layout currently being used by the
00148     // plotter.
00149     virtual void canvasLayoutChanged(PlotCanvasLayout& layout) = 0;
00150     
00151     // Gets/Sets the date format for the plotter and all current and future
00152     // canvases.  This format should be used anywhere date values are displayed
00153     // to the user, such as for axis ticks and tracker tools.  A format can
00154     // consist of the following tags:
00155     // * %y : year
00156     // * %m : month
00157     // * %d : day of month
00158     // * %h : hours
00159     // * %n : minutes
00160     // * %s : seconds
00161     // The format can optionally have the following tags:
00162     // * %pX : precision to display for seconds, with X being an integer; if X
00163     //         is less than zero, the default is used.  Applies to any seconds
00164     //         tags that are AFTER the precision tag.
00165     // <group>
00166     virtual const String& dateFormat() const = 0;
00167     virtual void setDateFormat(const String& dateFormat) = 0;
00168     // </group>
00169     
00170     // Gets/Sets the date format for relative values (i.e., for reference
00171     // values on axes) for the plotter and all current and future canvases.
00172     // This format should be used anywhere relative date values are displayed
00173     // to the user, such as for axis ticks when a reference value is set.  See
00174     // dateFormat() for information on the format.
00175     // <group>
00176     virtual const String& relativeDateFormat() const = 0;
00177     virtual void setRelativeDateFormat(const String& dateFormat) = 0;
00178     // </group>
00179     
00180     
00181     // Panel methods //
00182     
00183     // Returns whether or not the given default panel is shown.
00184     virtual bool defaultPanelShown(DefaultPanel panel) = 0;
00185     
00186     // Shows/hides the given default panel.  Note: the default panels are for
00187     // convenience's sake and are left completely up to the implementation.
00188     virtual void showDefaultPanel(DefaultPanel panel, bool show = true) = 0;
00189     
00190     // Adds the given plot panel and returns its index.
00191     virtual int addPanel(PlotPanelPtr panel) = 0;
00192     
00193     // Returns all plot panels currently shown.
00194     virtual vector<PlotPanelPtr> allPanels() = 0;
00195     
00196     // Returns the number of plot panels currently on the plotter.
00197     virtual unsigned int numPanels() = 0;
00198     
00199     // Returns the plot panel at the given index, or a null pointer for an
00200     // invalid index.
00201     virtual PlotPanelPtr getPanel(int index) = 0;
00202     
00203     // Returns the index of the given plot panel, or -1 if not on canvas or
00204     // null.
00205     virtual int panelIndex(PlotPanelPtr panel) = 0;
00206     
00207     // Clears all plot panels from the plotter.
00208     virtual void clearPanels() = 0;
00209     
00210     // Removes the given plot panel from the plotter.
00211     virtual void removePanel(PlotPanelPtr panel) = 0;
00212     
00213     // Removes the plot panel with the given index from the plotter.
00214     virtual void removePanel(int id) = 0;
00215     
00216     // Removes the last-added plot panel from the plotter.
00217     virtual void removeLastPanel() = 0;
00218     
00219     
00220     // Plotting Functionality methods //
00221     
00222     // Returns the implementation of this plotter.
00223     virtual Implementation implementation() const = 0;
00224     
00225     // Returns a new instance of a PlotFactory that can create plot items for
00226     // this implementation.  It is the caller's responsibility to delete the
00227     // PlotFactory when finished.
00228     virtual PlotFactory* implementationFactory() const = 0;
00229     
00230     // Exports the plotter (all canvases) using the given format.
00231     virtual bool exportToFile(const PlotExportFormat& format) = 0;
00232     
00233     // Shows a file chooser dialog and returns the absolute filename that the
00234     // user chooses.  If a directory is given, start the dialog there.  If the
00235     // user cancels, an empty String is returned.
00236     virtual String fileChooserDialog(const String& title = "File Chooser",
00237                                      const String& directory = "") = 0;
00238 
00239     
00240     // Event Handling methods //
00241     
00242     // Registers the given resize event handler with this plotter.
00243     virtual void registerResizeHandler(PlotResizeEventHandlerPtr handler) = 0;
00244     
00245     // Returns a list of all registered resize event handlers for this plotter.
00246     virtual vector<PlotResizeEventHandlerPtr> allResizeHandlers() const = 0;
00247     
00248     // Unregisters the given resize event handler with this plotter.
00249     virtual void unregisterResizeHandler(PlotResizeEventHandlerPtr handler) =0;
00250     
00251     
00252     // IMPLEMENTED METHODS //
00253     
00254     // See PlotCanvasLayout::canvasAt().
00255     virtual PlotCanvasPtr canvasAt(const PlotLayoutCoordinate& coord);
00256     
00257     // See PlotCanvasLayout::canvas().
00258     virtual PlotCanvasPtr canvas();
00259     
00260     // Sets the layout to a single layout with the given canvas.
00261     virtual void setCanvas(PlotCanvasPtr canvas);
00262     
00263     // See PlotLogger::filterMinPriority().
00264     LogMessage::Priority logFilterMinPriority() const;
00265     
00266     // See PlotLogger::setFilterMinPriority().
00267     void setLogFilterMinPriority(PlotLogMessage::Priority minPriority);
00268     
00269     // See PlotLogger::eventFlag().
00270     virtual bool logFilterEventFlag(int flag) const;
00271     
00272     // See PlotLogger::setEventFlag().
00273     virtual void setLogFilterEventFlag(int flag, bool on);
00274     
00275     // See PlotLogger::eventFlags().
00276     virtual int logFilterEventFlags() const;
00277     
00278     // See PlotLogger::setEventFlags().
00279     virtual void setLogFilterEventFlags(int flags);
00280     
00281     // Gets the PlotLogger associated with this Plotter.  There should be
00282     // exactly one PlotLogger per Plotter.
00283     virtual PlotLoggerPtr logger() const;
00284     
00285 protected:
00286     // Logger.
00287     PlotLoggerPtr m_logger;
00288 };
00289 typedef CountedPtr<Plotter> PlotterPtr;
00290 
00291 }
00292 
00293 #endif /*PLOTTER_H_*/