001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * ------------------
028 * LevelRenderer.java
029 * ------------------
030 * (C) Copyright 2004-2016, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   Peter Kolb (patch 2511330);
034 *
035 * Changes
036 * -------
037 * 09-Jan-2004 : Version 1 (DG);
038 * 05-Nov-2004 : Modified drawItem() signature (DG);
039 * 20-Apr-2005 : Renamed CategoryLabelGenerator
040 *               --> CategoryItemLabelGenerator (DG);
041 * ------------- JFREECHART 1.0.x ---------------------------------------------
042 * 23-Jan-2006 : Renamed getMaxItemWidth() --> getMaximumItemWidth() (DG);
043 * 13-May-2008 : Code clean-up (DG);
044 * 26-Jun-2008 : Added crosshair support (DG);
045 * 23-Jan-2009 : Set more appropriate default shape in legend (DG);
046 * 23-Jan-2009 : Added support for seriesVisible flags - see patch
047 *               2511330 (PK)
048 * 24-Aug-2014 : Add element hinting for JFreeSVG (DG);
049 *
050 */
051
052package org.jfree.chart.renderer.category;
053
054import java.awt.Color;
055import java.awt.Graphics2D;
056import java.awt.Paint;
057import java.awt.Stroke;
058import java.awt.geom.Line2D;
059import java.awt.geom.Rectangle2D;
060import java.io.Serializable;
061
062import org.jfree.chart.HashUtils;
063import org.jfree.chart.axis.CategoryAxis;
064import org.jfree.chart.axis.ValueAxis;
065import org.jfree.chart.entity.EntityCollection;
066import org.jfree.chart.event.RendererChangeEvent;
067import org.jfree.chart.labels.CategoryItemLabelGenerator;
068import org.jfree.chart.plot.CategoryPlot;
069import org.jfree.chart.plot.PlotOrientation;
070import org.jfree.chart.plot.PlotRenderingInfo;
071import org.jfree.chart.ui.RectangleEdge;
072import org.jfree.chart.util.PublicCloneable;
073import org.jfree.data.category.CategoryDataset;
074
075/**
076 * A {@link CategoryItemRenderer} that draws individual data items as
077 * horizontal lines, spaced in the same way as bars in a bar chart.  The
078 * example shown here is generated by the
079 * {@code OverlaidBarChartDemo2.java} program included in the JFreeChart
080 * Demo Collection:
081 * <br><br>
082 * <img src="../../../../../images/LevelRendererSample.png"
083 * alt="LevelRendererSample.png">
084 */
085public class LevelRenderer extends AbstractCategoryItemRenderer
086        implements Cloneable, PublicCloneable, Serializable {
087
088    /** For serialization. */
089    private static final long serialVersionUID = -8204856624355025117L;
090
091    /** The default item margin percentage. */
092    public static final double DEFAULT_ITEM_MARGIN = 0.20;
093
094    /** The margin between items within a category. */
095    private double itemMargin;
096
097    /** The maximum item width as a percentage of the available space. */
098    private double maxItemWidth;
099
100    /**
101     * Creates a new renderer with default settings.
102     */
103    public LevelRenderer() {
104        super();
105        this.itemMargin = DEFAULT_ITEM_MARGIN;
106        this.maxItemWidth = 1.0;  // 100 percent, so it will not apply unless
107                                  // changed
108        setDefaultLegendShape(new Rectangle2D.Float(-5.0f, -1.0f, 10.0f, 2.0f));
109        // set the outline paint to fully transparent, then the legend shape
110        // will just have the same colour as the lines drawn by the renderer
111        setDefaultOutlinePaint(new Color(0, 0, 0, 0));
112    }
113
114    /**
115     * Returns the item margin.
116     *
117     * @return The margin.
118     *
119     * @see #setItemMargin(double)
120     */
121    public double getItemMargin() {
122        return this.itemMargin;
123    }
124
125    /**
126     * Sets the item margin and sends a {@link RendererChangeEvent} to all
127     * registered listeners.  The value is expressed as a percentage of the
128     * available width for plotting all the bars, with the resulting amount to
129     * be distributed between all the bars evenly.
130     *
131     * @param percent  the new margin.
132     *
133     * @see #getItemMargin()
134     */
135    public void setItemMargin(double percent) {
136        this.itemMargin = percent;
137        fireChangeEvent();
138    }
139
140    /**
141     * Returns the maximum width, as a percentage of the available drawing
142     * space.
143     *
144     * @return The maximum width.
145     *
146     * @see #setMaximumItemWidth(double)
147     */
148    public double getMaximumItemWidth() {
149        return this.maxItemWidth;
150    }
151
152    /**
153     * Sets the maximum item width, which is specified as a percentage of the
154     * available space for all items, and sends a {@link RendererChangeEvent}
155     * to all registered listeners.
156     *
157     * @param percent  the percent.
158     *
159     * @see #getMaximumItemWidth()
160     */
161    public void setMaximumItemWidth(double percent) {
162        this.maxItemWidth = percent;
163        fireChangeEvent();
164    }
165
166    /**
167     * Initialises the renderer and returns a state object that will be passed
168     * to subsequent calls to the drawItem method.
169     * <p>
170     * This method gets called once at the start of the process of drawing a
171     * chart.
172     *
173     * @param g2  the graphics device.
174     * @param dataArea  the area in which the data is to be plotted.
175     * @param plot  the plot.
176     * @param rendererIndex  the renderer index.
177     * @param info  collects chart rendering information for return to caller.
178     *
179     * @return The renderer state.
180     */
181    @Override
182    public CategoryItemRendererState initialise(Graphics2D g2,
183            Rectangle2D dataArea, CategoryPlot plot, int rendererIndex,
184            PlotRenderingInfo info) {
185        CategoryItemRendererState state = super.initialise(g2, dataArea, plot,
186                rendererIndex, info);
187        calculateItemWidth(plot, dataArea, rendererIndex, state);
188        return state;
189    }
190
191    /**
192     * Calculates the bar width and stores it in the renderer state.
193     *
194     * @param plot  the plot.
195     * @param dataArea  the data area.
196     * @param rendererIndex  the renderer index.
197     * @param state  the renderer state.
198     */
199    protected void calculateItemWidth(CategoryPlot plot,
200            Rectangle2D dataArea, int rendererIndex,
201            CategoryItemRendererState state) {
202
203        CategoryAxis domainAxis = getDomainAxis(plot, rendererIndex);
204        CategoryDataset dataset = plot.getDataset(rendererIndex);
205        if (dataset != null) {
206            int columns = dataset.getColumnCount();
207            int rows = state.getVisibleSeriesCount() >= 0
208                    ? state.getVisibleSeriesCount() : dataset.getRowCount();
209            double space = 0.0;
210            PlotOrientation orientation = plot.getOrientation();
211            if (orientation == PlotOrientation.HORIZONTAL) {
212                space = dataArea.getHeight();
213            } else if (orientation == PlotOrientation.VERTICAL) {
214                space = dataArea.getWidth();
215            }
216            double maxWidth = space * getMaximumItemWidth();
217            double categoryMargin = 0.0;
218            double currentItemMargin = 0.0;
219            if (columns > 1) {
220                categoryMargin = domainAxis.getCategoryMargin();
221            }
222            if (rows > 1) {
223                currentItemMargin = getItemMargin();
224            }
225            double used = space * (1 - domainAxis.getLowerMargin()
226                                     - domainAxis.getUpperMargin()
227                                     - categoryMargin - currentItemMargin);
228            if ((rows * columns) > 0) {
229                state.setBarWidth(Math.min(used / (rows * columns), maxWidth));
230            } else {
231                state.setBarWidth(Math.min(used, maxWidth));
232            }
233        }
234    }
235
236    /**
237     * Calculates the coordinate of the first "side" of a bar.  This will be
238     * the minimum x-coordinate for a vertical bar, and the minimum
239     * y-coordinate for a horizontal bar.
240     *
241     * @param plot  the plot.
242     * @param orientation  the plot orientation.
243     * @param dataArea  the data area.
244     * @param domainAxis  the domain axis.
245     * @param state  the renderer state (has the bar width precalculated).
246     * @param row  the row index.
247     * @param column  the column index.
248     *
249     * @return The coordinate.
250     */
251    protected double calculateBarW0(CategoryPlot plot, 
252            PlotOrientation orientation, Rectangle2D dataArea,
253            CategoryAxis domainAxis, CategoryItemRendererState state, int row,
254            int column) {
255        // calculate bar width...
256        double space;
257        if (orientation.isHorizontal()) {
258            space = dataArea.getHeight();
259        } else {
260            space = dataArea.getWidth();
261        }
262        double barW0 = domainAxis.getCategoryStart(column, getColumnCount(),
263                dataArea, plot.getDomainAxisEdge());
264        int seriesCount = state.getVisibleSeriesCount();
265        if (seriesCount < 0) {
266            seriesCount = getRowCount();
267        }
268        int categoryCount = getColumnCount();
269        if (seriesCount > 1) {
270            double seriesGap = space * getItemMargin()
271                    / (categoryCount * (seriesCount - 1));
272            double seriesW = calculateSeriesWidth(space, domainAxis,
273                    categoryCount, seriesCount);
274            barW0 = barW0 + row * (seriesW + seriesGap)
275                          + (seriesW / 2.0) - (state.getBarWidth() / 2.0);
276        } else {
277            barW0 = domainAxis.getCategoryMiddle(column, getColumnCount(),
278                    dataArea, plot.getDomainAxisEdge()) - state.getBarWidth()
279                    / 2.0;
280        }
281        return barW0;
282    }
283
284    /**
285     * Draws the bar for a single (series, category) data item.
286     *
287     * @param g2  the graphics device.
288     * @param state  the renderer state.
289     * @param dataArea  the data area.
290     * @param plot  the plot.
291     * @param domainAxis  the domain axis.
292     * @param rangeAxis  the range axis.
293     * @param dataset  the dataset.
294     * @param row  the row index (zero-based).
295     * @param column  the column index (zero-based).
296     * @param pass  the pass index.
297     */
298    @Override
299    public void drawItem(Graphics2D g2, CategoryItemRendererState state,
300            Rectangle2D dataArea, CategoryPlot plot, CategoryAxis domainAxis,
301            ValueAxis rangeAxis, CategoryDataset dataset, int row, int column,
302            int pass) {
303
304        // nothing is drawn if the row index is not included in the list with
305        // the indices of the visible rows...
306        int visibleRow = state.getVisibleSeriesIndex(row);
307        if (visibleRow < 0) {
308            return;
309        }
310
311        // nothing is drawn for null values...
312        Number dataValue = dataset.getValue(row, column);
313        if (dataValue == null) {
314            return;
315        }
316
317        double value = dataValue.doubleValue();
318
319        PlotOrientation orientation = plot.getOrientation();
320        double barW0 = calculateBarW0(plot, orientation, dataArea, domainAxis,
321                state, visibleRow, column);
322        RectangleEdge edge = plot.getRangeAxisEdge();
323        double barL = rangeAxis.valueToJava2D(value, dataArea, edge);
324
325        // draw the bar...
326        Line2D line;
327        double x, y;
328        if (orientation.isHorizontal()) {
329            x = barL;
330            y = barW0 + state.getBarWidth() / 2.0;
331            line = new Line2D.Double(barL, barW0, barL,
332                    barW0 + state.getBarWidth());
333        } else {
334            x = barW0 + state.getBarWidth() / 2.0;
335            y = barL;
336            line = new Line2D.Double(barW0, barL, barW0 + state.getBarWidth(),
337                    barL);
338        }
339        
340        if (state.getElementHinting()) {
341            beginElementGroup(g2, dataset.getRowKey(row), 
342                    dataset.getColumnKey(column));
343        }
344        
345        Stroke itemStroke = getItemStroke(row, column);
346        Paint itemPaint = getItemPaint(row, column);
347        g2.setStroke(itemStroke);
348        g2.setPaint(itemPaint);
349        g2.draw(line);
350        if (state.getElementHinting()) {
351            endElementGroup(g2);
352        }
353
354        CategoryItemLabelGenerator generator = getItemLabelGenerator(row,
355                column);
356        if (generator != null && isItemLabelVisible(row, column)) {
357            drawItemLabel(g2, orientation, dataset, row, column, x, y,
358                    (value < 0.0));
359        }
360
361        // submit the current data point as a crosshair candidate
362        int datasetIndex = plot.indexOf(dataset);
363        updateCrosshairValues(state.getCrosshairState(),
364                dataset.getRowKey(row), dataset.getColumnKey(column), value,
365                datasetIndex, barW0, barL, orientation);
366
367        // collect entity and tool tip information...
368        EntityCollection entities = state.getEntityCollection();
369        if (entities != null) {
370            addItemEntity(entities, dataset, row, column, line.getBounds());
371        }
372
373    }
374
375    /**
376     * Calculates the available space for each series.
377     *
378     * @param space  the space along the entire axis (in Java2D units).
379     * @param axis  the category axis.
380     * @param categories  the number of categories.
381     * @param series  the number of series.
382     *
383     * @return The width of one series.
384     */
385    protected double calculateSeriesWidth(double space, CategoryAxis axis,
386                                          int categories, int series) {
387        double factor = 1.0 - getItemMargin() - axis.getLowerMargin()
388                        - axis.getUpperMargin();
389        if (categories > 1) {
390            factor = factor - axis.getCategoryMargin();
391        }
392        return (space * factor) / (categories * series);
393    }
394
395    /**
396     * Returns the Java2D coordinate for the middle of the specified data item.
397     *
398     * @param rowKey  the row key.
399     * @param columnKey  the column key.
400     * @param dataset  the dataset.
401     * @param axis  the axis.
402     * @param area  the drawing area.
403     * @param edge  the edge along which the axis lies.
404     *
405     * @return The Java2D coordinate.
406     *
407     * @since 1.0.11
408     */
409    @Override
410    public double getItemMiddle(Comparable rowKey, Comparable columnKey,
411            CategoryDataset dataset, CategoryAxis axis, Rectangle2D area,
412            RectangleEdge edge) {
413        return axis.getCategorySeriesMiddle(columnKey, rowKey, dataset,
414                this.itemMargin, area, edge);
415    }
416
417    /**
418     * Tests an object for equality with this instance.
419     *
420     * @param obj  the object ({@code null} permitted).
421     *
422     * @return A boolean.
423     */
424    @Override
425    public boolean equals(Object obj) {
426        if (obj == this) {
427            return true;
428        }
429        if (!(obj instanceof LevelRenderer)) {
430            return false;
431        }
432        LevelRenderer that = (LevelRenderer) obj;
433        if (this.itemMargin != that.itemMargin) {
434            return false;
435        }
436        if (this.maxItemWidth != that.maxItemWidth) {
437            return false;
438        }
439        return super.equals(obj);
440    }
441
442    /**
443     * Returns a hash code for this instance.
444     *
445     * @return A hash code.
446     */
447    @Override
448    public int hashCode() {
449        int hash = super.hashCode();
450        hash = HashUtils.hashCode(hash, this.itemMargin);
451        hash = HashUtils.hashCode(hash, this.maxItemWidth);
452        return hash;
453    }
454
455}