Add JavaDoc, make fields final in items
Change-Id: I0b5c48ae18ca0d75d674955de7f03bee5ce4da06
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/Chart.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/Chart.java
index 1e697bf..bdab119 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/Chart.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/Chart.java
@@ -35,6 +35,18 @@
import org.eclipse.swt.widgets.Listener;
+/**
+ * An extensible Chart widget based on <a href="http://d3js.org/">d3.js</a>.
+ * <p>
+ * Be default, the d3 library (<code>d3.v3.min.js</code>) is loaded from a CDN. To change the URL,
+ * you can set the system property <em>org.eclipse.rap.addons.chart.d3JsUrl</em> to a custom URL.
+ * </p>
+ * <p>
+ * Subclasses must provide a client implementation and refer to it using a renderer id in the
+ * constructor. Have a look at the existing implementations of this class.
+ * </p>
+ * @see "http://d3js.org/"
+ */
@SuppressWarnings( "deprecation" ) // RAP 3.0 compatibility
public abstract class Chart extends Canvas {
@@ -47,7 +59,10 @@
protected final RemoteObject remoteObject;
- public Chart( Composite parent, int style, String renderer ) {
+ /**
+ * Create a chart instance that is implemented by the given <code>renderer</code>.
+ */
+ protected Chart( Composite parent, int style, String renderer ) {
super( parent, style );
remoteObject = RWT.getUISession().getConnection().createRemoteObject( REMOTE_TYPE );
remoteObject.set( "parent", getId( this ) );
@@ -72,39 +87,121 @@
requireJs( registerResource( "chart/chart.js" ) );
}
- protected void setItems( JsonArray data ) {
+ /**
+ * Set the data items. This will usually be a {@link JsonArray}.
+ *
+ * @param data the data
+ */
+ protected void setItems( JsonValue data ) {
checkWidget();
remoteObject.set( "items", data );
}
+ /**
+ * Sets an option of the client-side chart. If a function of the given name exists on the
+ * client-side chart object, it will be called with the given value as parameter. By using a
+ * dot-separated name, a function on a sub-object can be called.
+ * <p>
+ * Subclasses should call this method when the value of this option actually changes.
+ * </p>
+ *
+ * @param name the name of the option, may be separated by dots to refer to a sub-object
+ * @param value the value of the option
+ */
protected void setOption( String name, int value ) {
setOption( name, valueOf( value ) );
}
+ /**
+ * Sets an option of the client-side chart. If a function of the given name exists on the
+ * client-side chart object, it will be called with the given value as parameter. By using a
+ * dot-separated name, a function on a sub-object can be called.
+ * <p>
+ * Subclasses should call this method when the value of this option actually changes.
+ * </p>
+ *
+ * @param name the name of the option, may be separated by dots to refer to a sub-object
+ * @param value the value of the option
+ */
protected void setOption( String name, double value ) {
setOption( name, valueOf( value ) );
}
+ /**
+ * Sets an option of the client-side chart. If a function of the given name exists on the
+ * client-side chart object, it will be called with the given value as parameter. By using a
+ * dot-separated name, a function on a sub-object can be called.
+ * <p>
+ * Subclasses should call this method when the value of this option actually changes.
+ * </p>
+ *
+ * @param name the name of the option, may be separated by dots to refer to a sub-object
+ * @param value the value of the option
+ */
protected void setOption( String name, boolean value ) {
setOption( name, valueOf( value ) );
}
+ /**
+ * Sets an option of the client-side chart. If a function of the given name exists on the
+ * client-side chart object, it will be called with the given value as parameter. By using a
+ * dot-separated name, a function on a sub-object can be called.
+ * <p>
+ * Subclasses should call this method when the value of this option actually changes.
+ * </p>
+ *
+ * @param name the name of the option, may be separated by dots to refer to a sub-object
+ * @param value the value of the option
+ */
protected void setOption( String name, String value ) {
setOption( name, valueOf( value ) );
}
+ /**
+ * Sets an option of the client-side chart. If a function of the given name exists on the
+ * client-side chart object, it will be called with the given value as parameter. By using a
+ * dot-separated name, a function on a sub-object can be called.
+ * <p>
+ * Subclasses should call this method when the value of this option actually changes.
+ * </p>
+ *
+ * @param name the name of the option, may be separated by dots to refer to a sub-object
+ * @param value the value of the option
+ */
protected void setOption( String name, JsonValue value ) {
remoteObject.call( "setOptions", new JsonObject().add( name, value ) );
}
+ /**
+ * Instruct the client to immediately load and evaluate a JavaScript file from the given URL. If
+ * the file has already been loaded by the client, it won't be loaded again. You can use
+ * {@link #registerResource(String)} to register the resource with the resource manager.
+ *
+ * @param url the URL from which to load the JavaScript file
+ */
protected void requireJs( String url ) {
getClient().getService( JavaScriptLoader.class ).require( url );
}
+ /**
+ * Instruct the client to immediately load and include CSS file from the given URL. If the file
+ * has already been loaded by the client, it won't be loaded again. You can use
+ * {@link #registerResource(String)} to register the resource with the resource manager.
+ *
+ * @param url the URL from which to load the CSS file
+ */
protected void requireCss( String url ) {
cssLoader.requireCss( url );
}
+ /**
+ * Loads a resource with the given name from the class loader of this class and registers it with
+ * the resource manager if it was not registered already. If the resource has already been
+ * registered, it won't be loaded again.
+ *
+ * @param url the resource name in the format supported by the class loader
+ * @see ClassLoader#getResource(String)
+ */
protected String registerResource( String resourceName ) {
return resources.register( resourceName, resourceName, getResourceLoader() );
}
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/NvChart.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/NvChart.java
index fae98eb..5bf5f67 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/NvChart.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/NvChart.java
@@ -13,6 +13,21 @@
import org.eclipse.swt.widgets.Composite;
+/**
+ * A chart widget based on <a href="http://nvd3.org/">nvd3.js</a>.
+ * <p>
+ * Be default, the nvd3 JS library and CSS (<code>nv.d3.min.js</code> and
+ * <code>nv.d3.min.css</code>) is loaded from a CDN. To change the URLs, you can set the system
+ * properties <em>org.eclipse.rap.addons.chart.nvd3JsUrl</em> and
+ * <em>org.eclipse.rap.addons.chart.nvd3CssUrl</em> to custom URLs.
+ * </p>
+ * <p>
+ * Subclasses must provide a client implementation and refer to it using a renderer id in the
+ * constructor. Have a look at the existing implementations of this class.
+ * </p>
+ *
+ * @see "http://nvd3.org/"
+ */
public abstract class NvChart extends Chart {
private static final String PROP_NVD3_JS_URL = "org.eclipse.rap.addons.chart.nvd3JsUrl";
@@ -22,7 +37,9 @@
private static final String DEF_NVD3_CSS_URL
= "https://cdnjs.cloudflare.com/ajax/libs/nvd3/1.8.1/nv.d3.min.css";
-
+ /**
+ * Create a chart instance that is implemented by the given <code>renderer</code>.
+ */
protected NvChart( Composite parent, int style, String renderer ) {
super( parent, style, renderer );
requireJs( System.getProperty( PROP_NVD3_JS_URL, DEF_NVD3_JS_URL ) );
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarChart.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarChart.java
index 625ef38..85a6bde 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarChart.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarChart.java
@@ -16,15 +16,33 @@
import org.eclipse.swt.widgets.Composite;
+/**
+ * A basic bar chart widget.
+ *
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>none</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>Selection</dd>
+ * </dl>
+ */
public class BarChart extends NvChart {
private boolean showValues = true;
+ /**
+ * Creates a new empty BarChart.
+ */
public BarChart( Composite parent, int style ) {
super( parent, style, "nv-bar" );
requireJs( registerResource( "chart/nv/nv-bar.js" ) );
}
+ /**
+ * Whether the y values should be displayed in the chart. The default is <code>true</code>.
+ *
+ * @param show <code>true</code> to display y values
+ */
public void setShowValues( boolean show ) {
checkWidget();
if( show != showValues ) {
@@ -33,11 +51,22 @@
}
}
+ /**
+ * Returns whether y values are being displayed in the chart.
+ *
+ * @return <code>true</code> if y values are displayed
+ */
public boolean getShowValues() {
checkWidget();
return showValues;
}
+ /**
+ * Sets the data items to display. Later changes to this list won't be reflected. To change the
+ * chart data, call this method with a new list of items.
+ *
+ * @param items the data items to display
+ */
public void setItems( BarItem... items ) {
JsonArray values = new JsonArray();
for( BarItem item : items ) {
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarItem.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarItem.java
index c61ebb6..b709f7e 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarItem.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/BarItem.java
@@ -16,17 +16,34 @@
import org.eclipse.swt.graphics.RGB;
+/**
+ * Represents a bar in a bar chart.
+ *
+ * @see BarChart
+ */
public class BarItem {
- protected double value;
- protected String text;
- protected RGB color;
+ protected final double value;
+ protected final String text;
+ protected final RGB color;
+ /**
+ * Create a new bar item with the given value and text.
+ *
+ * @param value the value of the item, affects the size of the bar
+ * @param text the label text for the item, or <code>null</code> to omit the label
+ */
public BarItem( double value, String text ) {
- this.value = value;
- this.text = text;
+ this( value, text, null );
}
+ /**
+ * Create a new bar item with the given value, text, and color.
+ *
+ * @param value the value of the item, affects the size of the bar
+ * @param text the label text for the item, or <code>null</code> to omit the label
+ * @param color the color of this item, or <code>null</code> to use the default color
+ */
public BarItem( double value, String text, RGB color ) {
this.value = value;
this.text = text;
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/DataPoint.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/DataPoint.java
index fc20ad5..9b16af4 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/DataPoint.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/DataPoint.java
@@ -12,12 +12,29 @@
import org.eclipse.rap.json.JsonObject;
+
+/**
+ * Represents a data point in a Cartesian plane.
+ */
public class DataPoint {
- public double x;
- public double y;
+ /**
+ * the x coordinate of the point
+ */
+ public final double x;
- public DataPoint(double x, double y) {
+ /**
+ * the y coordinate of the point
+ */
+ public final double y;
+
+ /**
+ * Creates a new data point with the given coordinates.
+ *
+ * @param x the x coordinate of this point
+ * @param y the y coordinate of this point
+ */
+ public DataPoint( double x, double y ) {
this.x = x;
this.y = y;
}
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineChart.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineChart.java
index b3b7619..5b4067d 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineChart.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineChart.java
@@ -15,6 +15,16 @@
import org.eclipse.swt.widgets.Composite;
+/**
+ * A basic line chart widget that supports multiple lines.
+ *
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>none</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>Selection</dd>
+ * </dl>
+ */
public class LineChart extends NvChart {
private String xAxisLabel;
@@ -22,11 +32,19 @@
private String xAxisFormat;
private String yAxisFormat;
+ /**
+ * Creates a new empty LineChart.
+ */
public LineChart( Composite parent, int style ) {
- super( parent, style, "nv-line" );
+ super( parent, style, "nv-line" );
requireJs( registerResource( "chart/nv/nv-line.js" ) );
}
+ /**
+ * Sets the label to display on the x-axis.
+ *
+ * @param label the label for the x-axis
+ */
public void setXAxisLabel( String label ) {
checkWidget();
if( this.xAxisLabel != label ) {
@@ -35,11 +53,21 @@
}
}
+ /**
+ * Returns the label for the x-axis.
+ *
+ * @return the label for the x-axis
+ */
public String getXAxisLabel() {
checkWidget();
return xAxisLabel != null ? xAxisLabel : "";
}
+ /**
+ * Sets the label to display on the y-axis.
+ *
+ * @param label the label for the y-axis
+ */
public void setYAxisLabel( String label ) {
checkWidget();
if( this.yAxisLabel != label ) {
@@ -48,6 +76,23 @@
}
}
+ /**
+ * Returns the label for the y-axis.
+ *
+ * @return the label for the y-axis
+ */
+ public String getYAxisLabel() {
+ checkWidget();
+ return xAxisLabel != null ? xAxisLabel : "";
+ }
+
+ /**
+ * Sets the format for the labels on the x-axis. The format string must be recognizable by the
+ * <a href="https://github.com/mbostock/d3/wiki/Formatting#d3_format">d3.format()</a> function.
+ *
+ * @see "https://github.com/mbostock/d3/wiki/Formatting#d3_format"
+ * @param format a d3 format string for the labels of the x-axis
+ */
public void setXAxisFormat( String format ) {
checkWidget();
if( this.xAxisFormat != format ) {
@@ -56,11 +101,23 @@
}
}
+ /**
+ * Returns the format used for labels on the x-axis.
+ *
+ * @return the format for the labels on the x-axis
+ */
public String getXAxisFormat() {
checkWidget();
return xAxisFormat;
}
+ /**
+ * Sets the format for the labels on the y-axis. The format string must be recognizable by the
+ * <a href="https://github.com/mbostock/d3/wiki/Formatting#d3_format">d3.format()</a> function.
+ *
+ * @see "https://github.com/mbostock/d3/wiki/Formatting#d3_format"
+ * @param format a d3 format string for the labels of the y-axis
+ */
public void setYAxisFormat( String format ) {
checkWidget();
if( this.yAxisFormat != format ) {
@@ -69,11 +126,22 @@
}
}
+ /**
+ * Returns the format used for labels on the y-axis.
+ *
+ * @return the format for the labels on the y-axis
+ */
public String getYAxisFormat() {
checkWidget();
return yAxisFormat;
}
+ /**
+ * Sets the data items to display. Every item represents a separate line. Later changes to this
+ * list won't be reflected. To change the chart data, call this method with a new list of items.
+ *
+ * @param items the data items to display
+ */
public void setItems( LineItem... items ) {
JsonArray values = new JsonArray();
for( LineItem item : items ) {
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineItem.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineItem.java
index 831c4d2..50a02a9 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineItem.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/LineItem.java
@@ -16,16 +16,37 @@
import org.eclipse.rap.json.JsonObject;
import org.eclipse.swt.graphics.RGB;
+
+/**
+ * Represents a line in a line chart.
+ *
+ * @see LineChart
+ */
public class LineItem {
- private DataPoint[] points;
- private String text;
- private RGB color;
+ protected final DataPoint[] points;
+ protected final String text;
+ protected final RGB color;
+ /**
+ * Creates a line with the given data points and text. Later changes to the data points won't be
+ * reflected in the chart.
+ *
+ * @param points the data point that form the line
+ * @param text the label text for the line, or <code>null</code> to omit the label
+ */
public LineItem( DataPoint[] points, String text ) {
this( points, text, null );
}
+ /**
+ * Creates a line with the given data points, text, and color. Later changes to the data points
+ * won't be reflected in the chart.
+ *
+ * @param points the data point that form the line
+ * @param text the label text for the line, or <code>null</code> to omit the label
+ * @param color the color of this line, or <code>null</code> to use the default color
+ */
public LineItem( DataPoint[] points, String text, RGB color ) {
this.points = points;
this.text = text;
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieChart.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieChart.java
index 138140f..36ccac3 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieChart.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieChart.java
@@ -15,16 +15,34 @@
import org.eclipse.swt.widgets.Composite;
+/**
+ * A basic pie or donut chart widget.
+ *
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>none</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>Selection</dd>
+ * </dl>
+ */
public class PieChart extends NvChart {
private boolean showLabels = true;
private boolean donut;
+ /**
+ * Creates a new empty Pie chart.
+ */
public PieChart( Composite parent, int style ) {
super( parent, style, "nv-pie" );
requireJs( registerResource( "chart/nv/nv-pie.js" ) );
}
+ /**
+ * Set whether labels should be displayed for each segment. The default is <code>true</code>.
+ *
+ * @param show <code>true</code> to display labels for each segment
+ */
public void setShowLabels( boolean show ) {
checkWidget();
if( show != showLabels ) {
@@ -33,11 +51,22 @@
}
}
+ /**
+ * Returns whether labels are displayed for each segment.
+ *
+ * @return <code>true</code> if labels are displayed for each segment.
+ */
public boolean getShowLabels() {
checkWidget();
return showLabels;
}
+ /**
+ * Sets whether this chart should be displayed as a donut chart. The default is
+ * <code>false</code>.
+ *
+ * @param donut <code>true</code> to display as a donut chart
+ */
public void setDonut( boolean donut ) {
if( this.donut != donut ) {
this.donut = donut;
@@ -45,10 +74,21 @@
}
}
+ /**
+ * Returns whether this chart is displayed as a donut chart.
+ *
+ * @return <code>true</code> if displayed as a donut chart
+ */
public boolean getDonut() {
return donut;
}
+ /**
+ * Sets the data items to display. Later changes to this list won't be reflected. To change the
+ * chart data, call this method with a new list of items.
+ *
+ * @param items the data items to display
+ */
public void setItems( PieItem... items ) {
JsonArray values = new JsonArray();
for( PieItem item : items ) {
diff --git a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieItem.java b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieItem.java
index aa65a12..295f746 100644
--- a/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieItem.java
+++ b/bundles/org.eclipse.rap.addons.chart/src/org/eclipse/rap/addons/chart/basic/PieItem.java
@@ -16,17 +16,34 @@
import org.eclipse.swt.graphics.RGB;
+/**
+ * Represents a segment of a pie/donut chart.
+ *
+ * @see PieChart
+ */
public class PieItem {
- protected double value;
- protected String text;
- protected RGB color;
+ protected final double value;
+ protected final String text;
+ protected final RGB color;
+ /**
+ * Create a new pie item with the given value and text.
+ *
+ * @param value the value of the item, affects the size of the section, should not be negative
+ * @param text the label text for the item, or <code>null</code> to omit the label
+ */
public PieItem( double value, String text ) {
- this.value = value;
- this.text = text;
+ this( value, text, null );
}
+ /**
+ * Create a new pie item with the given value, text, and color.
+ *
+ * @param value the value of the item, affects the size of the section, should not be negative
+ * @param text the label text for the item, or <code>null</code> to omit the label
+ * @param color the color of this section, or <code>null</code> to use the default color
+ */
public PieItem( double value, String text, RGB color ) {
this.value = value;
this.text = text;
