//
// Copyright (c) 2011, Peter Lane
// Licensed under the Academic Free License version 3.0
//
// History:
//   7 March 11  Peter Lane  Tidied up peer classes, made some constructors private.
//   6 March 11  Peter Lane  Added AxisTick and ErrorBars.
//   5 March 11  Peter Lane  Peer classes working.  First examples.
//                           Grid, Legend and Title classes completed.
//                           Series subclasses completed.
//                           Most classes implemented and 10 examples working.
//   3 March 11  Peter Lane  Creation
//

using fwt
using gfx

**
** Chart displays an instance of a chart, containing series of lines, bars or 
** scattered points.
**
class Chart : Canvas
{
  **
  ** The chart's title.  This field is readonly.
  **
  native Title title

  **
  ** Retrieve the x-axis for the chart.  This field is readonly.
  **
  native Axis xAxis

  **
  ** Retrieve the y-axis for the chart.  This field is readonly.
  **
  native Axis yAxis

  **
  ** Colour of chart's background.
  **
  native Color background

  **
  ** Colour of background for plotted area of chart.
  **
  native Color plotBackground

  **
  ** List of series subclassing `swtChartWrapper::Series` to be plotted on the chart.
  **
  native Series[] data

  **
  ** Orientation of graph: horizontal plots the x-axis as usual, and vertical 
  ** plots the x-axis vertically.
  ** Defaults to horizontal.
  **
  native Orientation orientation

  **
  ** The chart's legend.  This field is readonly.
  **
  native Legend legend

  **
  ** Alter ranges of axes so all data are visible.
  **
  native Void adjustRange ()

  **
  ** Zoom in all axes.
  **
  native Void zoomIn ()

  **
  ** Zoom out all axes.
  **
  native Void zoomOut ()

  **
  ** Save chart to given filename.
  **
  native Void save (Str filename, ImageType format)

// unimplemented:
// void   dispose()
// void   enableCompress(boolean enabled)
// IAxisSet   getAxisSet()
// org.eclipse.swt.widgets.Composite  getPlotArea()
// void   handleEvent(org.eclipse.swt.widgets.Event event)
// boolean  isCompressEnabled()
// void   redraw()
// void   update()
// void   updateLayout() 
}

**
** Image types, for saving charts to files.  Some types may not be available on 
** all operating systems. 
**
enum class ImageType { bmp_rle, bmp, jpeg, ico, gif, tiff, png }

**
** Title holds properties for the title of a chart or axis.
**
class Title
{
  **
  ** Constructor is private, as instance created within chart or axis. 
  **
  private new make () {}

  **
  ** The text for the title.
  **
  native Str text

  **
  ** The font for the title.
  **
  native Font font

  **
  ** The foreground colour for the title.
  ** Defaults to Color.blue.
  **
  native Color foreground

  **
  ** Indicates if the title is visible.
  **
  native Bool visible
}

**
** Legend holds properties for the legend of a chart.
** 
class Legend
{
  **
  ** The constructor is private, as legend instance is created by its chart.
  **
  private new make () {}

  **
  ** The background colour for the chart's legend.
  ** Defaults to Color.white.
  **
  native Color background

  **
  ** The foreground colour for the chart's legend.
  ** Defaults to Color.blue.
  **
  native Color foreground

  **
  ** The font for the chart's legend.
  **
  native Font font

  **
  ** The position of the chart's legend.
  ** Defaults to Position.right.
  **
  native Position position

  **
  ** Indicates if the legend is visible.
  ** Defaults to true.
  **
  native Bool visible

// unimplemented 'getBounds'
}

**
** For describing position of items in chart.
**
enum class Position { left, right, top, bottom }

**
** A Grid is associated with an individual axis, for drawing marker lines within the plot area.
**
class Grid
{
  **
  ** Constructor is private, as grid instance is created within axis.
  **
  private new make () {}

  **
  ** The foreground colour of the grid lines.
  **
  native Color foreground

  **
  ** The style for drawing the grid lines.
  **
  native LineStyle lineStyle
}

**
** Different choice of line styles.
**
enum class LineStyle { dash, dash_dot, dash_dot_dot, dot, none, solid }

**
** Type of symbol to use when plotting points.
**
enum class PlotSymbolType { circle, square, diamond, triangle, inverted_triangle, cross, plus, none }

**
** Parent class for the different types of data which can be plotted on a chart.
**
class Series 
{
  **
  ** The label for the data series.
  **
  native Str label

  **
  ** To manipulate the display of labels on the data series.
  **
  native SeriesLabel pointFormat

  **
  ** Enable stacking of this data series.  All values must be positive.
  ** Stacking can only be used if the x-axis has categorical labels.
  **
  native Bool enableStack

  **
  ** Handle error bars in x-direction.  Typically only used for scatter plots.
  **
  native ErrorBar xErrorBar

  **
  ** Handle error bars in y-direction.
  **
  native ErrorBar yErrorBar

// unimplemented:
// void   addDisposeListener(IDisposeListener listener)
// java.lang.String   getId()
// org.eclipse.swt.graphics.Point   getPixelCoordinates(int index)
// int  getXAxisId()
// java.util.Date[]   getXDateSeries()
// int  getYAxisId()
// boolean  isVisible()
// void   setVisible(boolean visible)
// void   setXAxisId(int id)
// void   setXDateSeries(java.util.Date[] series)
// void   setYAxisId(int id)
}

**
** A line series is drawn as a sequence of points, connected by a line.
**
class LineSeries : Series
{
  **
  ** The y-coordinates of the points to display.
  **
  native Float[] points

  **
  ** Determine if region between line and axis is shaded.
  ** Defaults to false.
  **
  native Bool enableArea

  **
  ** Determine if the graph should be drawn as a step graph.
  ** Defaults to false.
  **
  native Bool enableStep

  **
  ** The colour to draw the line (and any area).
  ** Defaults to blue.
  **
  native Color lineColor

  **
  ** The style to draw the line.
  ** Defaults to `swtChartWrapper::LineStyle.solid`.
  **
  native LineStyle lineStyle

  **
  ** The number of pixels wide to draw the line.
  ** Defaults to 1.
  **
  native Int lineWidth

  **
  ** Colour to draw the symbol.  Defaults to gray.
  **
  native Color symbolColor

  **
  ** Size of symbol in pixels.  Defaults to 4.
  **
  native Int symbolSize

  **
  ** The symbol to use for plotting.  Defaults to `swtChartWrapper::PlotSymbolType.circle`.
  **
  native PlotSymbolType symbolType

// unimplemented:
// antialias     - to improve drawing, should be on when required
// symbolColors  - separate colours for each symbol
}

**
** A bar series is drawn as a sequence of disjoint rectangles.
**
class BarSeries : Series
{
  **
  ** The y-coordinates of the points to display.
  **
  native Float[] points

  **
  ** Colour for the bars.  Defaults to blue.
  **
  native Color color

  **
  ** Padding around the bars, as a percentage of the gap between bar centers.
  ** Defaults to 20.
  **
  native Int padding

// unimplemented
// getBounds
}

**
** A scatter series defines both the x and y coordinates of the points to display.
** Points are plotted separately.  The number of x and y coordinates should be equal.
**
class ScatterSeries : Series
{
  **
  ** The x-coordinates of the points to display.
  **
  native Float[] xPoints

  **
  ** The y-coordinates of the points to display.
  **
  native Float[] yPoints

  **
  ** Colour to draw the symbol.  Defaults to gray.
  **
  native Color symbolColor

  **
  ** Size of symbol in pixels.  Defaults to 4.
  **
  native Int symbolSize

  **
  ** The symbol to use for plotting.  Defaults to `swtChartWrapper::PlotSymbolType.circle`.
  **
  native PlotSymbolType symbolType
}

**
** Stores the formatting for labels of data points on the chart.
** 
class SeriesLabel
{
  **
  ** Constructor is private, as instance created with data series.
  **
  private new make () {}

  **
  ** The font for displaying the data labels.
  **
  native Font font

  **
  ** The colour of the displayed data labels.  Defaults to `gfx::Color.black`.
  **
  native Color foreground

  **
  ** A (Java-based) formatting string for displaying the data labels.
  **
  native Str format

  **
  ** Make the data labels visible or not.  Defaults to false.
  **
  native Bool visible

// unimplemented
// formats: a separate format for each label
}

**
** Axis defines information for an x or y axis.
**
class Axis
{
  **
  ** Constructor is private, as instances are created by a chart.
  **
  private new make () {}

  ** 
  ** The label or title for the axis.
  ** This field is read only.
  **
  native Title title

  **
  ** The grid manages the internal lines within the plotted area.
  ** This field is read only.
  **
  native Grid grid

  **
  ** List of category labels for the axis.  Setting the category labels 
  ** automatically enables the category view.
  ** The number of categories must equal the number of x-points in the 
  ** displayed series.
  **
  native Str[] categories

  **
  ** Determines if the axis is displayed using a log scale.
  ** Note, cannot be used with category labels.
  ** Throws an error if minimum value for this axis is less than 0.
  ** Defaults to false.
  **
  native Bool enableLogScale

  **
  ** Scroll the axis up.
  **
  native Void scrollUp ()

  **
  ** Scroll the axis down.
  **
  native Void scrollDown ()

  **
  ** Zoom in on this axis.
  **
  native Void zoomIn ()

  **
  ** Zoom out on this axis.
  **
  native Void zoomOut ()

  **
  ** Zoom in on this axis at given coordinate.
  ** The point of the chart at the given coordinate is kept 'fixed', and 
  ** the axis is expanded around it.
  **
  native Void zoomInAt (Float coord)

  **
  ** Zoom out on this axis at given coordinate.
  ** The point of the chart at the given coordinate is kept 'fixed', and 
  ** the axis is shrunk around it.
  **
  native Void zoomOutAt (Float coord)

  **
  ** The displayed range of points on the axis.  There should be two 
  ** Float numbers in the list, the min and max.
  **
  native Float[] range

  **
  ** Retrieve object managing properties for the tick marks on the axis.
  ** This field is read only.
  **
  native AxisTick tick

  **
  ** For given pixel position on this axis, return its data coordinate.
  **
  native Float dataCoordinate (Int coord) 

  **
  ** For given coordinate position, return its pixel value on this axis.
  **
  native Int pixelCoordinate (Float coord) 

// Unimplemented
//  void  addDisposeListener(IDisposeListener listener) 
}

**
** Manage the representation and style of tick marks on an axis.
**
class AxisTick
{
  **
  ** Constructor is private as instance created within its axis.
  **
  private new make () {}

  **
  ** The font to display the tick label.
  **
  native Font font

  **
  ** The colour for the tick label.
  ** Defaults to `gfx::Color.black`.
  **
  native Color foreground

  **
  ** Indicates if the tick marks are shown.  Defaults to true.
  **
  native Bool visible

  **
  ** The angle to display the label.  Defaults to 0.
  **
  native Int labelAngle

  **
  ** A hint to control the spacing of the tick marks.
  **
  native Int stepHint

// unimplemented
// getBounds
//  native Str format
}

**
** Error bars are associated with a series.
**
class ErrorBar
{
  **
  ** Constructor is private, as instance created with data series.
  **
  private new make () {}

  **
  ** The colour of the error bars.
  ** Defaults to `gfx::Color.black`.
  **
  native Color color

  **
  ** The width of the line used to draw the error bars.
  **
  native Int lineWidth

  **
  ** Indicates if the error bars should be shown.
  ** Defaults to false.
  **
  native Bool visible

  **
  ** An array of the errors to show in the minus (down) direction.
  **
  native Float[] minusErrors

  **
  ** An array of the errors to show in the plus (up) direction.
  **
  native Float[] plusErrors

  **
  ** Indicate which side to draw the error bars.
  ** Defaults to `swtChartWrapper::ErrorBarType.both`.
  **
  native ErrorBarType type
}

**
** Indicates which side the error bars should be shown.
**
enum class ErrorBarType { both, minus, plus }