refs bug 302220 - updated javadocs
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AnnotatedTimeLine.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AnnotatedTimeLine.java
index 1a6bf76..0bf93a5 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AnnotatedTimeLine.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AnnotatedTimeLine.java
@@ -15,7 +15,7 @@
import org.eclipse.swt.widgets.Composite;
/**
- * <p>Renders a Google Visualization Annotated Timeline.</p>
+ * Renders a Google Visualization Annotated Timeline.
* <p>
* This visualization is configured using the widget data and options
* set by <code>setWidgetData()</code> and <code>setWidgetOptions()</code>.
@@ -36,8 +36,6 @@
* AnnotatedTimeLine timeLine = new AnnotatedTimeLine( composite, SWT.NONE );
* timeLine.setWidgetOptions("{width: 500, height: 300, displayAnnotations: true}");
* timeLine.setWidgetData(widgetData);
- * gridData = new GridData(500, 300);
- * timeLine.setLayoutData(gridData);
* timeLine.addListener(SWT.Selection, this);
* </pre>
* </p>
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AreaChart.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AreaChart.java
index 0451a51..bc6886f 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AreaChart.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/AreaChart.java
@@ -36,8 +36,6 @@
* AreaChart barChart = new AreaChart( composite, SWT.NONE );
* barChart.setWidgetOptions("{width: 300, height: 300}");
* barChart.setWidgetData(widgetData);
- * gridData = new GridData(300, 300);
- * barChart.setLayoutData(gridData);
* barChart.addListener(SWT.Selection, this);
* </pre>
* </p>
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/BarChart.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/BarChart.java
index 35261a3..a8f5117 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/BarChart.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/BarChart.java
@@ -16,40 +16,41 @@
/**
* Renders a Google Visualization Bar Chart.
- * @See http://code.google.com/apis/visualization/documentation/gallery/barchart.html
- *
- * Note that this widget is rendered upon calling the setWidgetData method.
- * So if you wish to set options like width, height, colors, etc., you must do this
- * using method setWidgetOptions, before calling setWidgetData.
- *
- * Usage:<code>
+ * <p>
+ * This visualization is configured using the widget data and options
+ * set by <code>setWidgetData()</code> and <code>setWidgetOptions()</code>.
+ * Note that if the widget data or options are changed after initial rendering,
+ * the <code>redraw()</code> method should be called to render the changes.
+ * </p>
+ * <p>
+ * <b>Usage:</b>
+ * <pre>
* JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
- dataTable.addColumn("theyear", "Date", "string", null);
- dataTable.addColumn("CO2", "CO2", "number", null);
- dataTable.addColumn("Temperature", "Temperature", "number", null);
- dataTable.addRow(new Object[] {"1970", 325, 14.1});
- dataTable.addRow(new Object[] {"2009", 389, 14.7});
- widgetData = dataTable.toString();
+ * dataTable.addColumn("theyear", "Date", "string", null);
+ * dataTable.addColumn("CO2", "CO2", "number", null);
+ * dataTable.addColumn("Temperature", "Temperature", "number", null);
+ * dataTable.addRow(new Object[] {"1970", 325, 14.1});
+ * dataTable.addRow(new Object[] {"2009", 389, 14.7});
+ * widgetData = dataTable.toString();
- BarChart barChart = new BarChart( composite, SWT.NONE );
- barChart.setWidgetOptions("{width: 300, height: 300}");
- barChart.setWidgetData(widgetData);
- gridData = new GridData(300, 300);
- barChart.setLayoutData(gridData);
- barChart.addListener(SWT.Selection, this);
- * </code>
-
- <code>
- public void handleEvent(Event event) {
- log.info("Event: " + event);
- VisualizationWidget widget = (VisualizationWidget)event.widget;
- log.info( "Selected item=" + widget.getSelectedItem() +
- "; row=" + widget.getSelectedRow() +
- "; column=" + widget.getSelectedColumn() +
- "; value=" + widget.getSelectedValue());
- </code>
-
- *
+ * BarChart barChart = new BarChart( composite, SWT.NONE );
+ * barChart.setWidgetOptions("{width: 300, height: 300}");
+ * barChart.setWidgetData(widgetData);
+ * barChart.addListener(SWT.Selection, this);
+ * </pre>
+ * </p>
+ * <pre>
+ * public void handleEvent(Event event) {
+ * System.out.println("Event: " + event);
+ * VisualizationWidget widget = (VisualizationWidget)event.widget;
+ * System.out.println("Selected item=" + widget.getSelectedItem() +
+ * "; row=" + widget.getSelectedRow() +
+ * "; column=" + widget.getSelectedColumn() +
+ * "; value=" + widget.getSelectedValue());
+ * }
+ * </pre>
+ * </p>
+ * @see <a href="http://code.google.com/apis/visualization/documentation/gallery/barchart.html">Bar Chart Example</a>
*/
public class BarChart extends VisualizationWidget {
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/ColumnChart.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/ColumnChart.java
index 2a21556..84e9af5 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/ColumnChart.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/ColumnChart.java
@@ -16,40 +16,40 @@
/**
* Renders a Google Visualization Column Chart.
- * @See http://code.google.com/apis/visualization/documentation/gallery/columnchart.html
- *
- * Note that this widget is rendered upon calling the setWidgetData method.
- * So if you wish to set options like width, height, colors, etc., you must do this
- * using method setWidgetOptions, before calling setWidgetData.
- *
- * Usage:
- * <code>
+ * <p>
+ * This visualization is configured using the widget data and options
+ * set by <code>setWidgetData()</code> and <code>setWidgetOptions()</code>.
+ * Note that if the widget data or options are changed after initial rendering,
+ * the <code>redraw()</code> method should be called to render the changes.
+ * </p>
+ * <p>
+ * <b>Usage:</b>
+ * <pre>
* JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
- dataTable.addColumn("theyear", "Date", "string", null);
- dataTable.addColumn("CO2", "CO2", "number", null);
- dataTable.addColumn("Temperature", "Temperature", "number", null);
- dataTable.addRow(new Object[] {"1970", 325, 14.1});
- dataTable.addRow(new Object[] {"2009", 389, 14.7});
- widgetData = dataTable.toString();
-
- ColumnChart chart = new ColumnChart( composite, SWT.NONE );
- chart.setWidgetOptions("{width: 300, height: 300}");
- chart.setWidgetData(serializedData);
- gridData = new GridData(300, 300);
- chart.setLayoutData(gridData);
- </code>
-
- <code>
- public void handleEvent(Event event) {
- log.info("Event: " + event);
- VisualizationWidget widget = (VisualizationWidget)event.widget;
- log.info( "Selected item=" + widget.getSelectedItem() +
- "; row=" + widget.getSelectedRow() +
- "; column=" + widget.getSelectedColumn() +
- "; value=" + widget.getSelectedValue());
- }
- </code>
- *
+ * dataTable.addColumn("theyear", "Date", "string", null);
+ * dataTable.addColumn("CO2", "CO2", "number", null);
+ * dataTable.addColumn("Temperature", "Temperature", "number", null);
+ * dataTable.addRow(new Object[] {"1970", 325, 14.1});
+ * dataTable.addRow(new Object[] {"2009", 389, 14.7});
+ * widgetData = dataTable.toString();
+ *
+ * ColumnChart chart = new ColumnChart( composite, SWT.NONE );
+ * chart.setWidgetOptions("{width: 300, height: 300}");
+ * chart.setWidgetData(serializedData);
+ * </pre>
+ * </p>
+ * <pre>
+ * public void handleEvent(Event event) {
+ * System.out.println("Event: " + event);
+ * VisualizationWidget widget = (VisualizationWidget)event.widget;
+ * System.out.println("Selected item=" + widget.getSelectedItem() +
+ * "; row=" + widget.getSelectedRow() +
+ * "; column=" + widget.getSelectedColumn() +
+ * "; value=" + widget.getSelectedValue());
+ * }
+ * </pre>
+ * </p>
+ * @see <a href="http://code.google.com/apis/visualization/documentation/gallery/columnchart.html">Column Chart Example</a>
*/
public class ColumnChart extends VisualizationWidget {
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Gauge.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Gauge.java
index 9ff84e5..4273c6a 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Gauge.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Gauge.java
@@ -16,37 +16,39 @@
/**
* Renders a Google Visualization Gauge.
- * @See http://code.google.com/apis/visualization/documentation/gallery/gauge.html
- *
- * Note that this widget is rendered upon calling the setWidgetData method.
- * So if you wish to set options like width, height, colors, etc., you must do this
- * using method setWidgetOptions, before calling setWidgetData.
- *
- * Usage:<code>
- JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
- dataTable.addColumn("CO2", "CO2", "number", null);
- dataTable.addColumn("CH4", "CH4", "number", null);
- dataTable.addColumn("Temperature", "Temperature", "number", null);
- dataTable.addRow(new Object[] {389, 1800, 14});
- widgetData = dataTable.toString();
-
- Gauge gauge = new Gauge( composite, SWT.NONE );
- gauge.setWidgetOptions("{width: 300, height: 300}");
- gauge.setWidgetData(widgetData);
- gridData = new GridData(300, 300);
- gauge.setLayoutData(gridData);
- </code>
-
- <code>
- public void handleEvent(Event event) {
- log.info("Event: " + event);
- VisualizationWidget widget = (VisualizationWidget)event.widget;
- log.info( "Selected item=" + widget.getSelectedItem() +
- "; row=" + widget.getSelectedRow() +
- "; column=" + widget.getSelectedColumn() +
- "; value=" + widget.getSelectedValue());
- </code>
- *
+* <p>
+ * This visualization is configured using the widget data and options
+ * set by <code>setWidgetData()</code> and <code>setWidgetOptions()</code>.
+ * Note that if the widget data or options are changed after initial rendering,
+ * the <code>redraw()</code> method should be called to render the changes.
+ * </p>
+ * <p>
+ * <b>Usage:</b>
+ * <pre>
+ * JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
+ * dataTable.addColumn("CO2", "CO2", "number", null);
+ * dataTable.addColumn("CH4", "CH4", "number", null);
+ * dataTable.addColumn("Temperature", "Temperature", "number", null);
+ * dataTable.addRow(new Object[] {389, 1800, 14});
+ * widgetData = dataTable.toString();
+ *
+ * Gauge gauge = new Gauge( composite, SWT.NONE );
+ * gauge.setWidgetOptions("{width: 300, height: 300}");
+ * gauge.setWidgetData(widgetData);
+ * </pre>
+ * </p>
+ * <pre>
+ * public void handleEvent(Event event) {
+ * System.out.println("Event: " + event);
+ * VisualizationWidget widget = (VisualizationWidget)event.widget;
+ * System.out.println("Selected item=" + widget.getSelectedItem() +
+ * "; row=" + widget.getSelectedRow() +
+ * "; column=" + widget.getSelectedColumn() +
+ * "; value=" + widget.getSelectedValue());
+ * }
+ * </pre>
+ * </p>
+ * @see <a href="http://code.google.com/apis/visualization/documentation/gallery/gauge.html">Gauge Example</a>
*/
public class Gauge extends VisualizationWidget {
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Geomap.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Geomap.java
index 4449f66..6450184 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Geomap.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/Geomap.java
@@ -15,43 +15,42 @@
import org.eclipse.swt.widgets.Composite;
/**
- * <p>Renders a Google Visualization Geomap.</p>
+ * Renders a Google Visualization Geomap.
+ * <p>
+ * This visualization is configured using the widget data and options
+ * set by <code>setWidgetData()</code> and <code>setWidgetOptions()</code>.
+ * Note that if the widget data or options are changed after initial rendering,
+ * the <code>redraw()</code> method should be called to render the changes.
+ * </p>
* <p>
* Note that this is a partial implementation of the Google GeoMap widget.
- * I have omitted the Markers capability of this widget, as this
- * require a Google API developer key. Support for markers could certainly
- * be added.
+ * The Markers capability has been omitted since this would require a Google API developer key. Support for markers could certainly
* </p>
* <p>
- * Note that this widget is rendered upon calling the setWidgetData method.
- * So if you wish to set options like width, height, colors, etc., you must do this
- * using method setWidgetOptions, before calling setWidgetData.
- * </p>
- * <p>
- * Usage:<pre>
+ * <b>Usage:</b>
+ * <pre>
* JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
- dataTable.addColumn("Country", "Country", "string", null);
- dataTable.addColumn("Happiness", "Happiness", "number", null);
- dataTable.addRow(new Object[] {"Tanzania", 25});
- dataTable.addRow(new Object[] {"US", 40});
- widgetData = dataTable.toString();
-
- Geomap geomap = new Geomap( composite, SWT.NONE );
- geomap.setWidgetOptions("{width: 500, height: 500}");
- geomap.setWidgetData(widgetData);
- gridData = new GridData(500, 500);
- geomap.setLayoutData(gridData);
- geomap.addListener(SWT.Selection, this);
- </pre>
- </p>
- <p>
- <pre>
- public void handleEvent(Event event) {
- log.info("Event: " + event);
- VisualizationWidget widget = (VisualizationWidget)event.widget;
- log.info( "Selected item=" + widget.getSelectedItem());
- </pre>
- </p>
+ * dataTable.addColumn("Country", "Country", "string", null);
+ * dataTable.addColumn("Happiness", "Happiness", "number", null);
+ * dataTable.addRow(new Object[] {"Tanzania", 25});
+ * dataTable.addRow(new Object[] {"US", 40});
+ * widgetData = dataTable.toString();
+ *
+ * Geomap geomap = new Geomap( composite, SWT.NONE );
+ * geomap.setWidgetOptions("{width: 500, height: 500}");
+ * geomap.setWidgetData(widgetData);
+ * geomap.addListener(SWT.Selection, this);
+ * </pre>
+ * </p>
+ * <p>
+ * <pre>
+ * public void handleEvent(Event event) {
+ * System.out.println("Event: " + event);
+ * VisualizationWidget widget = (VisualizationWidget)event.widget;
+ * System.out.println("Selected item=" + widget.getSelectedItem());
+ * }
+ * </pre>
+ * </p>
* @see <a href="http://code.google.com/apis/visualization/documentation/gallery/geomap.html">Geomap Example</a>
*
*/
diff --git a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/VisualizationWidget.java b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/VisualizationWidget.java
index 2298197..7fbfef8 100644
--- a/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/VisualizationWidget.java
+++ b/bundles/org.eclipse.rap.rwt.visualization.google/src/org/eclipse/rap/rwt/visualization/google/VisualizationWidget.java
@@ -19,7 +19,7 @@
import org.eclipse.swt.widgets.Layout;
/**
- * Abstract class for rendering any of the Google Visualization API UI elements.
+ * Base type for all of the Google Visualization implementations.
*
* @See http://code.google.com/apis/visualization/
*
@@ -35,7 +35,13 @@
private String selectedValue = "";
private boolean dirty;
- public VisualizationWidget( final Composite parent, final int style ) {
+ /**
+ * Constructs a visualization widget in the specified parent and style. A visualization widget by
+ * default will resize to fill its parent.
+ * @param parent the parent composite
+ * @param style the style of this widget
+ */
+ protected VisualizationWidget( final Composite parent, final int style ) {
super( parent, style );
this.addControlListener(new ControlAdapter() {
public void controlResized(ControlEvent e)
@@ -56,17 +62,25 @@
});
}
+ /**
+ * Returns the data that composes/defines the actual visualization.
+ * @return a string representating the data, or <code>null</code> if no data has been set.
+ */
public String getWidgetData() {
return widgetData;
}
- /*
- * Intentionally commented out as a Motion Chart cannot have a layout
+ /**
+ * Sets the layout of the widget. Calling this method has no effect.
*/
public void setLayout( final Layout layout ) {
+ //noop
}
-
+ /**
+ * Sets the data that composes/defines the actual visualization.
+ * @param widgetData a JSON string that represents the data for this visualization.
+ */
public void setWidgetData( String widgetData ) {
if (widgetData==null) {
this.widgetData = "";
@@ -75,6 +89,13 @@
}
}
+ /**
+ * Sets the configurable options for this visualization widget.
+ * The actual value depends on the type of Google visualization represented by this widget.
+ * @param widgetOptions the configurable options of this widget. Specifying <code>null</code>
+ * will clear the options. If a width and height are specified in the options they will override
+ * the default behavior, which is to auto-resize with the parent composite.
+ */
public void setWidgetOptions( String widgetOptions ) {
if (widgetOptions==null) {
widgetOptions = "";
@@ -83,51 +104,104 @@
}
}
+ /**
+ * Returns the configurable options for this visualization widget.
+ * The actual value depends on the type of Google visualization represented by this widget.
+ * @return a string representing the widget options
+ */
public String getWidgetOptions() {
return widgetOptions+widgetSize;
}
+ /**
+ * Asks this widget to perform a redraw which will update the visualization according to the
+ * current widget data and options.
+ */
public void redraw() {
super.redraw();
dirty = true;
}
+ /**
+ * Marks this widget as 'dirty' which will update the visualization according to the
+ * current widget data and options.
+ */
public void setDirty (boolean dirty) {
this.dirty = dirty;
}
+ /**
+ * Returns the 'dirty' state of this widget.
+ * @return <code>true</code> if the widget has been marked dirty, else <code>false</code>
+ */
public boolean isDirty () {
return dirty;
}
+ /**
+ * Sets the selected item in the visualization. The actual effects of this depend on the visualization.
+ * @param selectedItem a string representing the item to select in the visualization.
+ */
public void setSelectedItem( String selectedItem ) {
this.selectedItem = selectedItem;
}
+ /**
+ * Returns the selected item in the visualization. The actual selected item returned depends on the
+ * visualization.
+ * @return a string representing the selected item.
+ */
public String getSelectedItem() {
return selectedItem;
}
+ /**
+ * Sets the selected row in the visualization. The actual effects of this depend on the visualization.
+ * @param selectedRow a string representing the row to select in the visualization.
+ */
public void setSelectedRow( String selectedRow ) {
this.selectedRow = selectedRow;
}
+ /**
+ * Returns the selected row in the visualization. The actual selected item returned depends on the
+ * visualization.
+ * @return a string representing the selected row.
+ */
public String getSelectedRow() {
return selectedRow;
}
+ /**
+ * Sets the selected column in the visualization. The actual effects of this depend on the visualization.
+ * @param selectedColumn a string representing the column to select in the visualization.
+ */
public void setSelectedColumn( String selectedColumn ) {
this.selectedColumn = selectedColumn;
}
+ /**
+ * Returns the selected column in the visualization. The actual selected column returned depends on the
+ * visualization.
+ * @return a string representing the selected column.
+ */
public String getSelectedColumn() {
return selectedColumn;
}
+ /**
+ * Sets the selected value in the visualization. The actual effects of this depend on the visualization.
+ * @param selectedValue a string representing the value to select in the visualization.
+ */
public void setSelectedValue( String selectedValue ) {
this.selectedValue = selectedValue;
}
+ /**
+ * Returns the selected value in the visualization. The actual selected value returned depends on the
+ * visualization.
+ * @return a string representing the selected item.
+ */
public String getSelectedValue() {
return selectedValue;
}
