com.googlecode.gwt.charts.client.ChartWrapperObject Maven / Gradle / Ivy
/*
* Copyright 2012 Rui Afonso
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
* an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*/
package com.googlecode.gwt.charts.client;
import com.google.gwt.core.client.JavaScriptObject;
import com.google.gwt.core.client.JsArray;
import com.google.gwt.core.client.JsArrayMixed;
import com.google.gwt.core.client.JsArrayString;
import com.google.gwt.core.client.JsDate;
import com.googlecode.gwt.charts.client.event.ErrorEvent;
import com.googlecode.gwt.charts.client.event.ErrorHandler;
import com.googlecode.gwt.charts.client.event.EventHandler;
import com.googlecode.gwt.charts.client.event.HandlerRef;
import com.googlecode.gwt.charts.client.event.ReadyEvent;
import com.googlecode.gwt.charts.client.event.ReadyHandler;
import com.googlecode.gwt.charts.client.event.SelectEvent;
import com.googlecode.gwt.charts.client.event.SelectHandler;
import com.googlecode.gwt.charts.client.options.Options;
import com.googlecode.gwt.charts.client.util.ChartHelper;
import com.googlecode.gwt.charts.client.util.DateHelper;
import java.util.Date;
/**
* A ChartWrapperObject class is used to wrap your chart and handle all loading, drawing, and Datasource querying for
* your
* chart. The class exposes convenience methods for setting values on the chart and drawing it. This class simplifies
* reading from a data source, because you do not have to create a query callback handler. You can also use it to save a
* chart easily for reuse.
*
* Another bonus of using ChartWrapperObject is that you can reduce the number of library loads by using dynamic
* loading.
* Additionally, you don't need to load the JSAPI library explicitly, and ChartWrapperObject will handle looking up the
* chart
* libraries for you, so you do not need to specify any chart libraries in your loading statement. See the examples
* below for details.
*
* However, ChartWrapperObject currently only propagates a subset of events thrown by charts: select, ready, and error.
* Other
* events are not transmitted through the ChartWrapperObject instance; to get other events, you must call getChart() and
* subscribe to events directly on the chart handle.
*
* @param the options this chart implements
*/
public class ChartWrapperObject extends HasListeners {
/**
* Creates a empty ChartWrapperObject instance.
* You must set all the appropriate properties using the set... methods exposed by this object.
*
* @param the chart options type
*
* @return a new ChartWrapperObject instance
*/
public static native ChartWrapperObject create() /*-{
return new $wnd.google.visualization.ChartWrapper();
}-*/;
/**
* Creates a ChartWrapperObject instance with the provided properties.
*
* @param the chart options type
*
* @param chartWrapperSpec chart properties specification
* @return a new ChartWrapperObject instance
*/
public static native ChartWrapperObject create(ChartWrapperSpec chartWrapperSpec) /*-{
return new $wnd.google.visualization.ChartWrapper(chartWrapperSpec);
}-*/;
protected ChartWrapperObject() {
// Default constructor
}
/**
* Fired when an error occurs when attempting to render the chart.
*
* @param handler the error handler
* @return a reference for removing this handler
*/
public final HandlerRef addErrorHandler(ErrorHandler handler) {
return addListener(ErrorEvent.NAME, handler);
}
/**
* Adds an event directly to the chart
*
* @param handler the chart handler
* @return a reference for removing this handler
*/
public final HandlerRef addHandler(final EventHandler handler) {
return addListener(ReadyEvent.NAME, new ReadyHandler() {
@Override
public void onReady(ReadyEvent event) {
addListener(getChart(), handler.getEventName(), handler);
}
});
}
/**
* The chart is ready for external method calls. If you want to interact with the chart, and call methods after you
* draw it, you should set up a listener for this event before you call the draw method, and call them only after
* the event was fired
*
* @param handler the ready handler
* @return a reference for removing this handler
*/
public final HandlerRef addReadyHandler(ReadyHandler handler) {
return addListener(ReadyEvent.NAME, handler);
}
/**
* Fired when the user clicks a bar or legend. When a chart element is selected, the corresponding cell in the data
* table is selected; when a legend is selected, the corresponding column in the data table is selected. To learn
* what has been selected, call ChartWrapperObject.getChart().getSelection(). Note that this will only be thrown
* when the
* underlying chart type throws a selection event.
*
* @param handler the select handler
* @return a reference for removing this handler
*/
public final HandlerRef addSelectHandler(SelectHandler handler) {
return addListener(SelectEvent.NAME, handler);
}
/**
* Returns a deep copy of the chart wrapper.
*
* @return a deep copy of the ChartWrapperObject
*/
public final native ChartWrapperObject cloneObject() /*-{
this.clone();
}-*/;
/**
* Draws the chart. You must call this method after any changes that you make to the chart or data to show the
* changes.
*/
public final native void draw() /*-{
this.draw();
}-*/;
/**
* Returns a reference to the chart created by this ChartWrapperObject, for example a google.visualization.BarChart
* or a
* google.visualization.ColumnChart. This will return null until after you have called draw() on the
* ChartWrapperObject
* object, and it throws a ready event. Methods called on the returned object will be reflected on the page.
*
* @return a reference to the chart object
*/
public final native ChartObject getChart() /*-{
return this.getChart();
}-*/;
/**
* Returns the chart name assigned by {@link #setChartName(String)}.
*
* @return chart name
*/
public final native String getChartName() /*-{
return this.getChartName();
}-*/;
/**
* The class name of the wrapped chart. If this is a Google chart, the name will not be qualified with
* google.visualization. So, for example, if this were a Treemap chart, it would return "Treemap" rather than
* "google.visualization.treemap".
*
* @return class name of the wrapped chart
*/
public final native String getChartType() /*-{
return this.getChartType();
}-*/;
/**
* The ID of the chart's DOM container element.
*
* @return DOM container ID
*/
public final native String getContainerId() /*-{
return this.getContainerId();
}-*/;
/**
* If this chart gets its data from a data source, returns the URL for this data source. Otherwise, returns null.
*
* @return URL for this data source
*/
public final native String getDataSourceUrl() /*-{
return this.getDataSourceUrl();
}-*/;
/**
* If this chart gets its data from a locally-defined DataTable, will return a reference to the chart's DataTable.
* If this chart gets its data from a data source, it will return null.
* Any changes that you make to the returned object will be reflected by the chart the next time you call
* {@link #draw()}.
*
* @return a reference to the chart's DataTable
*/
public final native DataTable getDataTable() /*-{
return this.getDataTable();
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @return the value specified by key
*/
public final native boolean getOptionBoolean(String key) /*-{
return this.getOption(key);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @param defaultValue If the specified value is undefined or null, this value will be returned.
* @return the value specified by key
*/
public final native boolean getOptionBoolean(String key, boolean defaultValue) /*-{
return this.getOption(key, defaultValue);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @return the value specified by key
*/
public final Date getOptionDate(String key) {
JsDate jsDate = this.getOptionObject(key).cast();
return DateHelper.getDate(jsDate);
}
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @param defaultValue If the specified value is undefined or null, this value will be returned.
* @return the value specified by key
*/
public final Date getOptionDate(String key, Date defaultValue) {
JsDate jsDate = this.getOptionObject(key, DateHelper.getJsDate(defaultValue)).cast();
return DateHelper.getDate(jsDate);
}
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @return the value specified by key
*/
public final native double getOptionNumber(String key) /*-{
return this.getOption(key);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @param defaultValue If the specified value is undefined or null, this value will be returned.
* @return the value specified by key
*/
public final native double getOptionNumber(String key, double defaultValue) /*-{
return this.getOption(key, defaultValue);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @return the value specified by key
*/
public final native JavaScriptObject getOptionObject(String key) /*-{
return this.getOption(key);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @param defaultValue If the specified value is undefined or null, this value will be returned.
* @return the value specified by key
*/
public final native JavaScriptObject getOptionObject(String key, JavaScriptObject defaultValue) /*-{
return this.getOption(key, defaultValue);
}-*/;
/**
* Returns the options object for this chart.
*
* @return the options object for this chart
*/
public final native T getOptions() /*-{
return this.getOptions();
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @return the value specified by key
*/
public final native String getOptionString(String key) /*-{
return this.getOption(key);
}-*/;
/**
* Returns the specified chart option value.
*
* @param key The name of the option to retrieve. May be a qualified name, such as 'vAxis.title'
* @param defaultValue If the specified value is undefined or null, this value will be returned.
* @return the value specified by key
*/
public final native String getOptionString(String key, String defaultValue) /*-{
return this.getOption(key, defaultValue);
}-*/;
/**
* The query string for this chart, if it has one and queries, a data source.
*
* @return query string for this chart
*/
public final native String getQuery() /*-{
return this.getQuery();
}-*/;
/**
* Any refresh interval for this chart, if it queries a data source. Zero indicates no refresh.
*
* @return refresh interval in seconds
*/
public final native int getRefreshInterval() /*-{
return this.getRefreshInterval();
}-*/;
/**
* Returns an array of selected objects, each one describing a data element in the underlying table used to create
* the
* visualization (a DataView or a DataTable). Each object has properties row and/or column, with the index of the
* row and/or column of the selected item in the underlying DataTable. If the row property is null, then the
* selection is a column; if the column property is null, then the selection is a row; if both are non-null, then it
* is a specific data item. You can call the DataTable.getValue() method to get the value of the selected item. The
* retrieved array can be passed into setSelection().
*
* @return an array of selected objects
*/
public final JsArray getSelection() {
return getChart().getSelection();
}
/**
* Returns the DataView initializer object.
*
* @return the DataView initializer object
*/
public final native DataView getView() /*-{
return this.getView();
}-*/;
/**
* Returns an array of DataView initializer objects.
*
* @return an array of DataView initializer objects
*/
public final native JsArray getViewArray() /*-{
return this.getViewArray();
}-*/;
/**
* Sets an arbitrary name for the chart. This is not shown anywhere on the chart, unless a custom chart is
* explicitly designed to use it.
*
* @param chartName an arbitrary name for the chart
*/
public final native void setChartName(String chartName) /*-{
this.setChartName(chartName);
}-*/;
/**
* Sets the chart type.
*
* @param chartType the chart type to display
*/
public final void setChartType(ChartType chartType) {
setChartType(chartType.getName());
}
/**
* Sets the ID of the containing DOM element for the chart.
*
* @param containerId the DOM element ID
*/
public final native void setContainerId(String containerId) /*-{
this.setContainerId(containerId);
}-*/;
/**
* Sets the URL of a data source to use for this chart. If you also set a data table for this object, the data
* source URL will be ignored.
*
* @param url the URL of a data source to use for this chart
*/
public final native void setDataSourceUrl(String url) /*-{
this.setDataSourceUrl(url);
}-*/;
/**
* Sets the DataTable for the chart.
*
* @param dataTable the DataTable object for the chart
*/
public final native void setDataTable(DataTable dataTable) /*-{
this.setDataTable(dataTable);
}-*/;
/**
* Sets the DataTable for the chart.
*
* @param dataTable an array following the syntax of {@link ChartHelper#arrayToDataTable(JsArrayMixed)}
*/
public final native void setDataTable(JsArrayMixed dataTable) /*-{
this.setDataTable(dataTable);
}-*/;
/**
* Sets the DataTable for the chart.
*
* @param json a JSON representation of a DataTable
*/
public final native void setDataTable(String json) /*-{
this.setDataTable(json);
}-*/;
/**
* Sets a single chart option value, where key is the option name and value is the value.
* To unset an option, call {@link #setOptionNull(String)}.
*
* @param key may be a qualified name, such as 'vAxis.title'.
* @param value the value to set
*/
public final native void setOption(String key, boolean value) /*-{
this.setOption(key, value);
}-*/;
/**
* Sets a single chart option value, where key is the option name and value is the value.
* To unset an option, call {@link #setOptionNull(String)}.
*
* @param key may be a qualified name, such as 'vAxis.title'.
* @param value the value to set
*/
public final void setOption(String key, Date value) {
this.setOption(key, DateHelper.getJsDate(value));
}
/**
* Sets a single chart option value, where key is the option name and value is the value.
* To unset an option, call {@link #setOptionNull(String)}.
*
* @param key may be a qualified name, such as 'vAxis.title'.
* @param value the value to set
*/
public final native void setOption(String key, double value) /*-{
this.setOption(key, value);
}-*/;
/**
* Sets a single chart option value, where key is the option name and value is the value.
* To unset an option, call {@link #setOptionNull(String)}.
*
* @param key may be a qualified name, such as 'vAxis.title'.
* @param value the value to set
*/
public final native void setOption(String key, JavaScriptObject value) /*-{
this.setOption(key, value);
}-*/;
/**
* Sets a single chart option value, where key is the option name and value is the value.
* To unset an option, call {@link #setOptionNull(String)}.
*
* @param key may be a qualified name, such as 'vAxis.title'.
* @param value the value to set
*/
public final native void setOption(String key, String value) /*-{
this.setOption(key, value);
}-*/;
/**
* Unsets an option
*
* @param key the option key
*/
public final native void setOptionNull(String key) /*-{
this.setOption(key);
}-*/;
/**
* Sets a complete options object for a chart.
*
* @param options a complete options object
*/
public final native void setOptions(T options) /*-{
this.setOptions(options);
}-*/;
/**
* Sets a query string, if this chart queries a data source. You must also set the data source URL if specifying
* this value.
*
* @param query a data source query string
*/
public final native void setQuery(String query) /*-{
this.setQuery(query);
}-*/;
/**
* Sets the refresh interval for this chart, if it queries a data source. You must also set a data source URL if
* specifying this value. Zero indicates no refresh.
*
* @param refreshInterval refresh interval for this chart in seconds
*/
public final native void setRefreshInterval(int refreshInterval) /*-{
this.setRefreshInterval(refreshInterval);
}-*/;
/**
* Selects a data entry in the visualization—for example, a point in an area chart, or a bar in a bar chart. When
* this method is called, the visualization should visually indicate what the new selection is. The implementation
* of setSelection() should not fire a "select" event. Visualizations may ignore part of the selection. For example,
* a table that can show only selected rows may ignore cell or column elements in its setSelection() implementation,
* or it can select the entire row.
*
* Every time this method is called, all selected items are deselected, and the new selection list passed in should
* be applied. There is no explicit way to deselect individual items; to deselect individual items, call
* setSelection() with the items to remain selected; to deselect all elements, call setSelection(),
* setSelection(null), or setSelection([]).
*
* @param selection
*/
public final void setSelection(JsArray selection) {
getChart().setSelection(selection);
}
/**
* Sets a DataView initializer object, which acts as a filter over the underlying data. The chart wrapper must have
* underlying data from a DataTable or a data source to apply this view to. The first DataView in the array is
* applied to the underlying data to create a
* new data table, and the second DataView is applied to the data table resulting from application of the first
* DataView, and so on.
*
* @param view an array of DataView initializer objects, like that returned by dataview.toJSON()
*/
public final native void setView(JsArrayString view) /*-{
this.setView(view);
}-*/;
/**
* Sets a DataView initializer object, which acts as a filter over the underlying data. The chart wrapper must have
* underlying data from a DataTable or a data source to apply this view to.
*
* @param view a DataView initializer object, like that returned by dataview.toJSON()
*/
public final native void setView(String view) /*-{
this.setView(view);
}-*/;
/**
* Returns a string version of the JSON representation of the chart.
*
* @return a JSON representation of the chart
*/
public final native String toJSON() /*-{
this.toJSON();
}-*/;
private final native void setChartType(String chartType) /*-{
this.setChartType(chartType);
}-*/;
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy