5.7.1 Interactive plug-ins

This Section describes interactive plug-ins. These plug-ins add interactive capabilities to chart. Interactive plug-ins can be subdivided into several groups by purpose:

Zooming - these plug-ins add zooming capability to charts, for example BoxZoomer, 3D Zoom plugins

Size - these plug-ins adjust charts size in accordance to some property, for example ChartResizer

Selection - these plug-ins add selection capability to charts, for example DrillDown, CursorChanger plug-ins

Rotation - these plug-ins add rotation capability to charts (3D Series and PieSeries only), for example PieChartRotator plug-ins

Other - these plugins provide other capabilities, such as tooltips, themes and so on

Zoom box is an alternative approach to zooming. BoxZoomer is registered as a plug-in for a 2D chart object. It handles mouse input and draws a rubber band zooming rectangle. When the mouse drag operation is over, it queries current ranges of both: horizontal and vertical ScrollableAxisMappers' and updates it. This results in a chart update.

Setting BoxZoomer for both axes for Chart object:

//add BoxZoomer plug-in for Chart object chart
chart.addPlugin(new BoxZoomer(xMapper,yMapper));

ChartProjectorZoomer is registered as a plug-in for a 2D chart object. ChartProjectorZoomer can be used on Radar series, Pie series (where is no rectangular coordinate). It handles mouse input and draws a rubber band zooming rectangle. When the mouse drag operation is over, it queries current ranges of both: horizontal and vertical. This results in a chart update.

Setting ChartProjectorZoomer for Chart object:

1
2
3
4
5
6
7
8
9
10
11
12
13

ChartProjectorZoomer zoomer = new ChartProjectorZoomer();
 
// Sets maximum zoom scale in percents. Value of 1 represents 100% (no zooming).
// Value of 0.01 - 1% (zoom works till it's scale reaches 1% of whole axis range).
// If value is 0.0, then there is no zooming limit.
zoomer.setZoomMaxScale(0.01);
 
// Sets if zooming box bounds should be kept proportional to chart plotting area.
//  Default value is false.
zoomer.setBoxProportionable(true);
 
// add ChartProjectorZoomer plug-in for Chart object chart
chart.addPlugin(zoomer);

3D charts can be zoomed. Charts can be zoomed interactively by a ChartZoomer plug-in object. It handles mouse drags and updates chart size.

Setting 3D Zoom for Chart3D object:

//adds ChartZoomer plug-in for Chart3D object chart
chart.addPlugin (new ChartZoomer ());

MCharts provides full scrolling and zooming functionality. It’s based on the AxisMapper interface. Normally AxisMapper maps the entire axis range to the [0, 1] range of double values. For a scrollable mapper, only the visible axis range is mapped to the [0, 1] range. Axis values, which fall outside the visible range, also fall outside the [0, 1] range. An AxisMapperRange object is used to select the visible range from the total axis mapper range. Chart series (such as BarSeries, StockSeries, etc.) perform clipping to eliminate data values, which fall outside the visible range. Scrolling is done by changing AxisMapperRange minimum and maximum range values. This feature can be set using setScrollable() method. It handles mouse events and updates the AxisMapperRange accordingly.

In addition, an adapter for Swing BoundedRangeModel is supplied. The BoundedRangeModelAdapter allows scrolling the graph with a simple Swing scroll bar.

Setting scrollable axis:

1
2
3
4
5
6
7
8

//Sets AxisMapper
LogAxisMapper yMapper = new LogAxisMapper(0.01,10);
//Sets Axis
Axis2DY axisY = new Axis2DY(yMapper);
//Sets Axis title
axisY.setTitle("Y Axis");
//Sets Axis to be scrollable
axisY.setScrollable(true);

This plugin allows to zoom and scroll the selected axis range.

Plug-in shows always axis ranges.

• Plug-in performs axis ranges changes move minimum range, move maximum range and shift range on the specified axis, when activated.
• Axis should be scrollable for the adjuster to work correctly.
• Related axis is axis for which must be set range same as axis range.

Setting axis range adjuster :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// create axis range adjuster for Y axis
AxisRangeAdjuster axisRangeAdjusterY = new AxisRangeAdjuster(axisY, new Axis2DY[] { axisY1 });
 
// set axis range adjuster style
axisRangeAdjusterY.setHeight(6);
axisRangeAdjusterY.setWidth(12);
axisRangeAdjusterY.setMinRangeBackground(Color.RED);
axisRangeAdjusterY.setMinRangeForeground(Color.BLACK);
axisRangeAdjusterY.setShiftRangeBackground(Color.GREEN);
axisRangeAdjusterY.setShiftRangeForeground(Color.BLACK);
axisRangeAdjusterY.setMaxRangeBackground(Color.MAGENTA);
axisRangeAdjusterY.setMaxRangeForeground(Color.BLACK);
axisRangeAdjusterY.setRangeComposite(
  AlphaComposite.getInstance(AlphaComposite.SRC_OVER, 0.2f));
 
// add plugin to chart
chart.addPlugin(axisRangeAdjusterY);

This plugin allows to zoom Pie Chart using SHIFT + LEFT Mouse Button combination. Chart's container (JChartPanel) must have HotSpotMap set.

Adding PieChartZoomer plugin for Chart object, which contains PieSeries object:

//adding Pie Chart Zoomer plugin
chart.addPlugin(new PieChartZoomer());

This plugin allows to select chart entities. Chart's container (JChartPanel) must have HotSpotMap set.

Setting DrillDown for Chart object:

1
2
3
4
5
6
7
8

//adds DrillDown plug-in for Chart object chart
chart.addPlugin(new DrillDown());
//creates LabeledChart object
LabeledChart topChart = new LabeledChart(chart); 
//creates JChartPanel object
JChartPanel m_chartPanel = new JChartPanel(topChart); 
//sets SimpleHotSpotMap object DrillDown to work properly
m_chartPanel.setHotSpotMap(new SimpleHotSpotMap());

Legend entry selector. When legend entry is selected the corresponding series is also selected. This works only for Legend. When the same entry is clicked again it is deselected with its corresponding series. In order to work for this plug-in correctly, Chart container (JChartPanel) must have SimpleHotSpotMap set.

Setting LegendSelector plug-in:

1
2
3
4
5
6
7
8
9
10
11
12

//sets a new legend from Chart object, named chart
Legend legend = new Legend(chart);
//adds LegendSelector plug-in to Chart object, named chart
chart.addPlugin(new LegendSelector(legend));
//creates LabeledChart object
LabeledChart topChart = new LabeledChart(chart); 
//adds legend to bottom of chart
topChart.setBottomView(legend);
//creates JChartPanel object
JChartPanel m_chartPanel = new JChartPanel(topChart); 
//sets SimpleHotSpotMap object LegendEntrySelector to work properly
m_chartPanel.setHotSpotMap(new SimpleHotSpotMap());

This plug-in allows to explode Pie Chart using CTRL + LEFT Mouse Button combination. Chart's container (JChartPanel) must have HotSpotMap set.

Adding PieChartExploder plugin for Chart object, which contains PieSeries object:

//adding Pie Chart Exploder plug-in
chart.addPlugin(new PieChartExploder());

This plug-in allows to change cursor when chart area is selected.

//adding Cursor Changer plug-in
chart.addPlugin(new CursorChangerPlugin());

This plugin displays exact value of the selected chart part.

1
2
3
4

// creating CHart2D object
Chart2D chart = new Chart2D ();
// adding plug-in to chart - xAxis and yAxis are instances of Axis
chart.addPlugin (new AxisMarker (xAxis, yAxis));

This plugin is used to resize the font of chart objects and thickness of lines in accordance to size of frame.

Setting ChartResizer plug-in:

//adds ChartResizer plug-in to Chart object, named chart
chart.addPlugin(new ChartResizer());

This plug-in enables you to resize the x, y, z axes according to the data in the data models. The marker lines, stacked bars and lines, as well as baseline is also taken into account.

You must supply the mappers to the constructor of the adjuster in order the axes would be adjusted. The mappers must be associated with the series, that you're about to adjust.

Setting AutoAxisAdjuster plug-in:

//adds AutoAxisAdjuster plug-in to Chart object, named chart
// with AxisMapper objects - xMapper and yMapper
chart.addPlugin(new AutoAxisAdjuster(xMapper,yMapper));

3D chart can be rotated by modifying rotation and elevation angle properties of the 3D projector.

Setting rotation angle:

//sets rotation angle to 270 degrees for Chart3D object chart
 ((SimpleProjector3D)chart.projector()).setRotationAngle(270);

Chart can be also rotated interactively by a ChartRotator plug-in object.

ChartRotator handles mouse drags and updates projector rotation and elevation properties accordingly.

Setting ChartRotator plug-in:

//adds ChartRotator plug-in for Chart3D object chart
chart.addPlugin(new ChartRotator());

This plugin allows to rotate Pie Chart using SHIRT + RIGHT Mouse Button combination. Chart's container (JChartPanel) must have HotSpotMap set.

Adding PieChartRotator plugin for Chart object, which contains PieSeries object:

//adding Pie Chart Rotator plugin
chart.addPlugin(new PieChartRotator());

ColorThemesPlugin plug-in allows to select preferred colors palette for the created chart. There are 61 ColorThemes to choose from, including PrinterFriendlyTheme which uses hatch paint for series filling and is suitable for white-black printing. Each ColorTheme sets colors for chart series, grid, axis, labels and legends. Colors match altogether and create a whole ColorTheme. There are three types of themes created:

• First type is Indeterminate Themes: the colors for these themes are generated by the algorithm accordingly to the amount of colors count (or different series that require different colors). Of course, the more colors you need, the more similar they will be. Possible themes: BlueOrangeTheme, BlueGreenTheme, OrangeBlueTheme, OrangeGreenTheme, GreenOrangeTheme, GreenBlueTheme – where first color and its' hues are for series fill, second color – for grid fill.
• Second type is Simple Determinate Themes: the colors for these themes are determinate and there is a fixed number of these colors (fixed color palette size). They always remain the same and do not depend on series count. Simple Determinate Themes consists of the following color groups: Fire themes (red hues), Ocean themes (blue hues), Nature themes (green hues), Dark Magic themes (dark red, magenta, brown hues), Silent Night themes (dark blue, dark green, gray, black hues), Camouflage themes (green, brown, yellow, black hues), Deep Pastel themes (dark pastel hues), Bright Pastel themes (light pastel hues), Vivid themes (vivid hues). Each group provides several different themes. All Simple Determinate Themes begin with one of the group name (for instance SilentNightInAshesTheme).
• Third type is Gradient Determinate Themes: these themes uses the same fixed color palette and uses the same themes' groups as Simple Determinate Themes. Only for grid fill these themes use Gradient fill, what makes them more attractive. All Gradient Determinate Themes begin with word ”Gradient” (for instance GradientOceanBlurTheme).

To set up a color theme for a chart is simple. You have to use one of two available constructors:

1
2
3
4

//creates Chart object
Chart2D chart = new Chart2D(); 
//adds ColorThemesPlugin to Chart object chart with selected theme
chart.addPlugin(new ColorThemesPlugin(ColorThemesPlugin.FIRE_IN_CHOCOLATE_THEME));

1
2
3
4
5
6

//creates Chart object
Chart2D chart = new Chart2D(); 
//creates legend
Legend legend = new Legend(chart);
//adds ColorThemesPlugin to Chart object chart and legend with selected theme
chart.addPlugin(new ColorThemesPlugin(ColorThemesPlugin.FIRE_IN_CHOCOLATE_THEME, legend));

Also other chart types can be used.

The first example sets color theme only for the chart, second also applies color theme to the legend and chart.

All themes' names are stored in the ColorThemesPlugin class.

Note:

• PrinterFriendlyTheme is only available for 2D Bar series, 2D Line series.

MCharts provides tooltip support for chart objects.

In order to display tooltips when user points a mouse over a certain chart object, chart needs to have a HotSpotMap and series must have MetaDataModel with MetaDataType.HINT set.

Settting ToolTipManager:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

//setting MetaDataModel
MetaDataModel meta = new MetaDataModel();
//setting MetaDataModel, named meta, data
meta.setData(MetaDataType.HINT, "Number: $index$ \nValue: $round(x1*100)/100$");
//setting BarSeries object
// dataModel is an instance of ChartDataModel
// meta is an instance of MetaDataModel
// xMapper and yMapper are instances of AxisMapper
BarSeries bar1 = new BarSeries(dataModel,meta, xMapper, yMapper);
//setting chart
chart.setObjects(bar1);
chart.setYAxis(new Axis2DY(yMapper));
chart.setXAxis(new Axis2DX(xMapper));
//adding ToolManager plug-in
chart.addPlugin(new ToolTipManager());
//creating LabeledChart object
LabeledChart topChart = new LabeledChart(chart); 
//creating JChartPanel object
JChartPanel m_chartPanel = new JChartPanel(topChart); 
//seting SimpleHotSpotMap object ToolTipManager to work properly
m_chartPanel.setHotSpotMap(new SimpleHotSpotMap());

HotSpotMap objects create mappings between chart entity objects and positions, they occupy in the rendered chart. Each chart entity may be mapped to several polygons.

HTML client side image mapper is a special instance of the HotSpotMapper, which uses the collected mapping information to produce a HTML source code for the HTML client side image map. Using the entity mechanism, it is possible to map only specific regions of the chart, while leaving the other ones unavailable for access. For example it is possible to map an individual bar in the bar chart series, and do not include the rest of the bars in the map. Or it is possible to map all bar to one HTML link and explicitly map another bar from the same series to a different HTML link.

Setting HotSpotMap:

1
2
3
4

//sets SimpleHotSpotMap object, named map, which is an instance of HotSpotMap
SimpleHotSpotMap map = new SimpleHotSpotMap();
//adds HotSpotMap plug-in to JChartPanel object
m_chartPanel.setHotSpotMap(map);