== Overview
   * a PLOTTER is the highest-level GUI, conceptually a window, that contains
     zero or more CANVASes in a CANVAS LAYOUT
   * a CANVAS is a single plotting area that can contain zero or more PLOT ITEMs.
   * a PLOT ITEM is anything that can be attached to (drawn on) a canvas, and
     currently includes: PLOTs, SHAPEs, POINTs, and ANNOTATIONs.
   * objects are customized using standard interfaces such as COLORs, FONTs,
     LINEs, and AREA FILLs.
   * a FACTORY is a class that generates implementation-specific objects
   * a SIMPLE PLOTTER is a concrete class that provides simplified access to
     common tasks.  It uses a FACTORY to generate needed objects.


== Plotter actions
   * show/hide GUI
   * set width and height
   * set canvases in different layouts
     => single layout (one canvas), grid layout (n x m canvases)
   * set window title
   * show hide "default GUI panels": commonly-used tools already set up on the
     plotter to make the user's life easier.
     => hand tools: zoomer, panner, selecter.  optionally: show/hide tracker and
        the legend.  How the tools are managed for multiple canvases is left up
        to the implementation.
     => export tools: export to a file in one of the supported formats
   * show a file chooser dialog and return the chosen filename


== Canvas actions
   => has four axes: bottom, left, top, and right
   * set axes ranges
   * turn on/off axes auto-rescaling (which automatically rescales the axes to show
     all items on the canvas when a new one is added)
   * rescale the axes to show all items
   * set axes scale: normal, date, or log_10
   * show/hide axes
   * show/hide Cartesian axes, which are axes inside the graph at x = 0 and y = 0
   * lock/unlock the axes ratio (such that resizing one axis resizes the others
     proportionally)
   * canvas title and title font
   * axes labels and label fonts
   * show/hide a colorbar on an axis
   * canvas background
   * turn on/off autoincrementing colors, which will assign each new scatter plot
     a different color
   * export canvas to a file
     => type: JPG, PNG, PDF, PS
     => file location
     => choice between "screen dump" or high resolution
     => dots-per-inch
     => width and height for images
   * add or remove a plot, shape, or annotation
   * zoom, keeping track of past activity using a stack
   * pan, keeping track of past activity using a stack
   * locate data indices in a given region
   * show/hide and customize grid lines for major and minor ticks on axes
   * show/hide legend and customize its font, outline, and background
     => locations: inside graph area:  upper/lower left, upper/lower right;
                   outside graph area: left, top, right, bottom
   * register event handlers (see below) 
   * show a file chooser dialog and return the chosen filename  
   * keeps track of user-selected regions and provides access to the list


== Canvas events
   * events are generated by the canvas, usually as the result of user activity
   * any object wishing to act on these events must register itself as an
     event handler with the canvas
   => current event types: click (left click, right click, double click),
                           wheel (delta: negative for scrolling back, positive
                                  for scrolling forward),
                           key (modifier + alphanumeric),
                           selection (click-drag region on the canvas)


== Customization objects
   * Color
     => hexadecimal form, i.e. "000000" for black
   * Font
     => font family, i.e. "Arial"
     => point size
     => color
     => bold, italics, underline on/off
   * Line
     => color
     => width
     => style: NOLINE, SOLID, DASHED, or DOTTED
        => NOLINE can be used to hide lines
   * Area fill
     => color
     => pattern: NOFILL, FILL, MESH1, MESH2, or MESH3
        => NOFILL can be used to have no area fill
   * Symbol
     => style: NOSYMBOL, CIRCLE, SQUARE, DIAMOND, or CHARACTER
        => for CHARACTER style, a given character is drawn for the symbol
     => size
     => line for the outline of CIRCLE, SQUARE, or DIAMOND symbols
     => area fill for the inside of CIRCLE, SQUARE, or DIAMOND symbols


== Plot types
   * Scatter plot: x and y data in point form
     => can customize: line, symbol
     => can append new points to the end of the data
   * Error plot: scatter plot + error data shown as error bars
     => can customize: line, symbol, error bar line, error bar "cap" size (i.e.
                       the line on top of the T)
   * Histogram: x data in point form that divided into "bins" showing the number
                of points falling in each bin.  This information is displayed
                as a bar plot.
     => can customize: bar line, bar fill, number of bins
     => can append new values to the end of the data
   * Bar: x and y data in point form
     => can customize: bar line, bar fill
     => can append new points to the end of the data
   * Raster/Contour: raster data used to display image-like values.  Optional
                     contour lines to show separation between value levels.
     => can customize: contour line, contour levels, x/y data range
   * Spectrogram/Contour: spectrogram shown for data.  Optional contour lines
                          to show separation between value levels.
     => can customize: contour lines, contour levels, x/y data range
     
     
== Plot Point
   => a single (x, y) point drawn using a symbol
  
 
== Shape types
   * Rectangle: upper left point and lower right point
     => can customize: coordinates, line, area fill
   * Ellipse: center point, x radius, and y radius
     => can customize: coordinates, radii, line, area fill
   * Line: continuous line at a single place, i.e. at x = 5
     => can customize: coordinate, line
   * Arrow/Line Segment: "from" point and "to" point, plus an optional arrow at
                         the "to" point
     => can customize: coordinates, line, arrow type, arrow size, area fill for
                       triangle arrow
     => arrow types: NOARROW, TRIANGLE, V_ARROW
   * Polygon: series of points that are connected and the area between is filled
              in for convex polygons
     => can customize: coordinates, line, area fill
 

== Annotation customization
   * text
   * font
   * position: the text is drawn with this coordinate as its upper left point
   * outline
   * background
   * orientation: in degrees

  
== Coordinate systems
   * WORLD: in the units of the displayed axes on the graph
   * NORMALIZED_WORLD: a number from [0 ... 1] that represents a "percentage" of
                       the displayed WORLD units
   * PIXEL: number of pixels to the right and below of the upper left corner of
            the canvas
   => A canvas is expected to be able to convert between the different systems


== Plot factory
   * main interface between user and implementation
   * convenience methods for creating data
   * contains methods to create implementation-specific objects:
     => Plotter
     => PlotCanvas
     => ScatterPlot
     => ErrorPlot
     => HistogramPlot
     => BarPlot
     => RasterPlot
     => Annotation
     => PlotShapeRectangle
     => PlotShapeEllipse
     => PlotShapeLine
     => PlotShapeArrow
     => PlotShapePolygon
     => PlotPoint
     => PlotColor
     => PlotFont
     => PlotAreaFill
     => PlotLine
     => PlotSymbol
     
== Simple plotter
   => class for common, simple use cases that consist of calls to other
      interface classes
   * set window, canvas, and axes titles
   * show/hide cartesian axes
   * set axes ranges
   * turn on/off axes autorescaling
   * rescale axes
   * set lines, symbols, and area fills for future plotting calls
   * plotxy with two vectors/arrays of numbers
   * ploty with one vector/array of numbers
   * histogram plot with one vector/array of numbers
   * bar plot with two vectors/arrays of numbers
   * raster plot with a matrix of numbers
   * contour plot with a matrix of numbers and a vector of numbers
   * plot a single point
   * draw an annotation
   * draw a rectangle, ellipse, line, or arrow
   * clear everything currently on the canvas
   * clear all points that have been plotted
   * show a file chooser dialog and return the chosen filename
   * export to PDF, PS, JPG, or PNG
