001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2005, 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     * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
025     * in the United States and other countries.]
026     *
027     * -------------------------------
028     * CombinedDomainCategoryPlot.java
029     * -------------------------------
030     * (C) Copyright 2003-2005, by Object Refinery Limited.
031     *
032     * Original Author:  David Gilbert (for Object Refinery Limited);
033     * Contributor(s):   Nicolas Brodu;
034     *
035     * $Id: CombinedDomainCategoryPlot.java,v 1.9.2.1 2005/10/25 20:52:07 mungady Exp $
036     *
037     * Changes:
038     * --------
039     * 16-May-2003 : Version 1 (DG);
040     * 08-Aug-2003 : Adjusted totalWeight in remove() method (DG);
041     * 19-Aug-2003 : Added equals() method, implemented Cloneable and 
042     *               Serializable (DG);
043     * 11-Sep-2003 : Fix cloning support (subplots) (NB);
044     * 15-Sep-2003 : Implemented PublicCloneable (DG);
045     * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
046     * 17-Sep-2003 : Updated handling of 'clicks' (DG);
047     * 04-May-2004 : Added getter/setter methods for 'gap' attribute (DG);
048     * 12-Nov-2004 : Implemented the Zoomable interface (DG);
049     * 25-Nov-2004 : Small update to clone() implementation (DG);
050     * 21-Feb-2005 : The getLegendItems() method now returns the fixed legend
051     *               items if set (DG);
052     * 05-May-2005 : Updated draw() method parameters (DG);
053     *
054     */
055    
056    package org.jfree.chart.plot;
057    
058    import java.awt.Graphics2D;
059    import java.awt.geom.Point2D;
060    import java.awt.geom.Rectangle2D;
061    import java.io.Serializable;
062    import java.util.Collections;
063    import java.util.Iterator;
064    import java.util.List;
065    
066    import org.jfree.chart.LegendItemCollection;
067    import org.jfree.chart.axis.AxisSpace;
068    import org.jfree.chart.axis.AxisState;
069    import org.jfree.chart.axis.CategoryAxis;
070    import org.jfree.chart.event.PlotChangeEvent;
071    import org.jfree.chart.event.PlotChangeListener;
072    import org.jfree.ui.RectangleEdge;
073    import org.jfree.ui.RectangleInsets;
074    import org.jfree.util.ObjectUtilities;
075    import org.jfree.util.PublicCloneable;
076    
077    /**
078     * A combined category plot where the domain axis is shared.
079     */
080    public class CombinedDomainCategoryPlot extends CategoryPlot
081                                            implements Zoomable,
082                                                       Cloneable, PublicCloneable, 
083                                                       Serializable,
084                                                       PlotChangeListener {
085    
086        /** For serialization. */
087        private static final long serialVersionUID = 8207194522653701572L;
088        
089        /** Storage for the subplot references. */
090        private List subplots;
091    
092        /** Total weight of all charts. */
093        private int totalWeight;
094    
095        /** The gap between subplots. */
096        private double gap;
097    
098        /** Temporary storage for the subplot areas. */
099        private transient Rectangle2D[] subplotAreas;
100        // TODO:  move the above to the plot state
101        
102        /**
103         * Default constructor.
104         */
105        public CombinedDomainCategoryPlot() {
106            this(new CategoryAxis());
107        }
108        
109        /**
110         * Creates a new plot.
111         *
112         * @param domainAxis  the shared domain axis (<code>null</code> not 
113         *                    permitted).
114         */
115        public CombinedDomainCategoryPlot(CategoryAxis domainAxis) {
116            super(null, domainAxis, null, null);
117            this.subplots = new java.util.ArrayList();
118            this.totalWeight = 0;
119            this.gap = 5.0;
120        }
121    
122        /**
123         * Returns the space between subplots.
124         *
125         * @return The gap (in Java2D units).
126         */
127        public double getGap() {
128            return this.gap;
129        }
130    
131        /**
132         * Sets the amount of space between subplots and sends a 
133         * {@link PlotChangeEvent} to all registered listeners.
134         *
135         * @param gap  the gap between subplots (in Java2D units).
136         */
137        public void setGap(double gap) {
138            this.gap = gap;
139            notifyListeners(new PlotChangeEvent(this));
140        }
141    
142        /**
143         * Adds a subplot to the combined chart and sends a {@link PlotChangeEvent}
144         * to all registered listeners.
145         * 
146         * @param subplot  the subplot (<code>null</code> not permitted).
147         */
148        public void add(CategoryPlot subplot) {
149            add(subplot, 1);    
150        }
151        
152        /**
153         * Adds a subplot to the combined chart and sends a {@link PlotChangeEvent}
154         * to all registered listeners.
155         *
156         * @param subplot  the subplot (<code>null</code> not permitted).
157         * @param weight  the weight (must be >= 1).
158         */
159        public void add(CategoryPlot subplot, int weight) {
160            if (subplot == null) {
161                throw new IllegalArgumentException("Null 'subplot' argument.");
162            }
163            if (weight < 1) {
164                throw new IllegalArgumentException("Require weight >= 1.");
165            }
166            subplot.setParent(this);
167            subplot.setWeight(weight);
168            subplot.setInsets(new RectangleInsets(0.0, 0.0, 0.0, 0.0));
169            subplot.setDomainAxis(null);
170            subplot.setOrientation(getOrientation());
171            subplot.addChangeListener(this);
172            this.subplots.add(subplot);
173            this.totalWeight += weight;
174            CategoryAxis axis = getDomainAxis();
175            if (axis != null) {
176                axis.configure();
177            }
178            notifyListeners(new PlotChangeEvent(this));
179        }
180    
181        /**
182         * Removes a subplot from the combined chart.  Potentially, this removes 
183         * some unique categories from the overall union of the datasets...so the 
184         * domain axis is reconfigured, then a {@link PlotChangeEvent} is sent to 
185         * all registered listeners.
186         *
187         * @param subplot  the subplot (<code>null</code> not permitted).
188         */
189        public void remove(CategoryPlot subplot) {
190            if (subplot == null) {
191                throw new IllegalArgumentException("Null 'subplot' argument.");
192            }
193            int position = -1;
194            int size = this.subplots.size();
195            int i = 0;
196            while (position == -1 && i < size) {
197                if (this.subplots.get(i) == subplot) {
198                    position = i;
199                }
200                i++;
201            }
202            if (position != -1) {
203                this.subplots.remove(position);
204                subplot.setParent(null);
205                subplot.removeChangeListener(this);
206                this.totalWeight -= subplot.getWeight();
207    
208                CategoryAxis domain = getDomainAxis();
209                if (domain != null) {
210                    domain.configure();
211                }
212                notifyListeners(new PlotChangeEvent(this));
213            }
214        }
215    
216        /**
217         * Returns the list of subplots.
218         *
219         * @return An unmodifiable list of subplots .
220         */
221        public List getSubplots() {
222            return Collections.unmodifiableList(this.subplots);
223        }
224    
225        /**
226         * Returns the subplot (if any) that contains the (x, y) point (specified 
227         * in Java2D space).
228         * 
229         * @param info  the chart rendering info.
230         * @param source  the source point.
231         * 
232         * @return A subplot (possibly <code>null</code>).
233         */
234        public CategoryPlot findSubplot(PlotRenderingInfo info, Point2D source) {
235            CategoryPlot result = null;
236            int subplotIndex = info.getSubplotIndex(source);
237            if (subplotIndex >= 0) {
238                result =  (CategoryPlot) this.subplots.get(subplotIndex);
239            }
240            return result;
241        }
242        
243        /**
244         * Multiplies the range on the range axis/axes by the specified factor.
245         *
246         * @param factor  the zoom factor.
247         * @param info  the plot rendering info.
248         * @param source  the source point.
249         */
250        public void zoomRangeAxes(double factor, PlotRenderingInfo info, 
251                                  Point2D source) {
252            CategoryPlot subplot = findSubplot(info, source);
253            if (subplot != null) {
254                subplot.zoomRangeAxes(factor, info, source);
255            }
256        }
257    
258        /**
259         * Zooms in on the range axes.
260         *
261         * @param lowerPercent  the lower bound.
262         * @param upperPercent  the upper bound.
263         * @param info  the plot rendering info.
264         * @param source  the source point.
265         */
266        public void zoomRangeAxes(double lowerPercent, double upperPercent, 
267                                  PlotRenderingInfo info, Point2D source) {
268            CategoryPlot subplot = findSubplot(info, source);
269            if (subplot != null) {
270                subplot.zoomRangeAxes(lowerPercent, upperPercent, info, source);
271            }
272        }
273    
274        /**
275         * Calculates the space required for the axes.
276         * 
277         * @param g2  the graphics device.
278         * @param plotArea  the plot area.
279         * 
280         * @return The space required for the axes.
281         */
282        protected AxisSpace calculateAxisSpace(Graphics2D g2, 
283                                               Rectangle2D plotArea) {
284            
285            AxisSpace space = new AxisSpace();
286            PlotOrientation orientation = getOrientation();
287            
288            // work out the space required by the domain axis...
289            AxisSpace fixed = getFixedDomainAxisSpace();
290            if (fixed != null) {
291                if (orientation == PlotOrientation.HORIZONTAL) {
292                    space.setLeft(fixed.getLeft());
293                    space.setRight(fixed.getRight());
294                }
295                else if (orientation == PlotOrientation.VERTICAL) {
296                    space.setTop(fixed.getTop());
297                    space.setBottom(fixed.getBottom());                
298                }
299            }
300            else {
301                CategoryAxis categoryAxis = getDomainAxis();
302                RectangleEdge categoryEdge = Plot.resolveDomainAxisLocation(
303                    getDomainAxisLocation(), orientation
304                );
305                if (categoryAxis != null) {
306                    space = categoryAxis.reserveSpace(
307                        g2, this, plotArea, categoryEdge, space
308                    );
309                }
310                else {
311                    if (getDrawSharedDomainAxis()) {
312                        space = getDomainAxis().reserveSpace(
313                            g2, this, plotArea, categoryEdge, space
314                        );
315                    }
316                }
317            }
318            
319            Rectangle2D adjustedPlotArea = space.shrink(plotArea, null);
320            
321            // work out the maximum height or width of the non-shared axes...
322            int n = this.subplots.size();
323            this.subplotAreas = new Rectangle2D[n];
324            double x = adjustedPlotArea.getX();
325            double y = adjustedPlotArea.getY();
326            double usableSize = 0.0;
327            if (orientation == PlotOrientation.HORIZONTAL) {
328                usableSize = adjustedPlotArea.getWidth() - this.gap * (n - 1);
329            }
330            else if (orientation == PlotOrientation.VERTICAL) {
331                usableSize = adjustedPlotArea.getHeight() - this.gap * (n - 1);
332            }
333    
334            for (int i = 0; i < n; i++) {
335                CategoryPlot plot = (CategoryPlot) this.subplots.get(i);
336    
337                // calculate sub-plot area
338                if (orientation == PlotOrientation.HORIZONTAL) {
339                    double w = usableSize * plot.getWeight() / this.totalWeight;
340                    this.subplotAreas[i] = new Rectangle2D.Double(
341                        x, y, w, adjustedPlotArea.getHeight()
342                    );
343                    x = x + w + this.gap;
344                }
345                else if (orientation == PlotOrientation.VERTICAL) {
346                    double h = usableSize * plot.getWeight() / this.totalWeight;
347                    this.subplotAreas[i] = new Rectangle2D.Double(
348                        x, y, adjustedPlotArea.getWidth(), h
349                    );
350                    y = y + h + this.gap;
351                }
352    
353                AxisSpace subSpace = plot.calculateRangeAxisSpace(
354                    g2, this.subplotAreas[i], null
355                );
356                space.ensureAtLeast(subSpace);
357    
358            }
359    
360            return space;
361        }
362    
363        /**
364         * Draws the plot on a Java 2D graphics device (such as the screen or a 
365         * printer).  Will perform all the placement calculations for each of the
366         * sub-plots and then tell these to draw themselves.
367         *
368         * @param g2  the graphics device.
369         * @param area  the area within which the plot (including axis labels) 
370         *              should be drawn.
371         * @param anchor  the anchor point (<code>null</code> permitted).
372         * @param parentState  the state from the parent plot, if there is one.
373         * @param info  collects information about the drawing (<code>null</code> 
374         *              permitted).
375         */
376        public void draw(Graphics2D g2, 
377                         Rectangle2D area, 
378                         Point2D anchor,
379                         PlotState parentState,
380                         PlotRenderingInfo info) {
381            
382            // set up info collection...
383            if (info != null) {
384                info.setPlotArea(area);
385            }
386    
387            // adjust the drawing area for plot insets (if any)...
388            RectangleInsets insets = getInsets();
389            area.setRect(
390                area.getX() + insets.getLeft(),
391                area.getY() + insets.getTop(),
392                area.getWidth() - insets.getLeft() - insets.getRight(),
393                area.getHeight() - insets.getTop() - insets.getBottom()
394            );
395    
396    
397            // calculate the data area...
398            setFixedRangeAxisSpaceForSubplots(null);
399            AxisSpace space = calculateAxisSpace(g2, area);
400            Rectangle2D dataArea = space.shrink(area, null);
401    
402            // set the width and height of non-shared axis of all sub-plots
403            setFixedRangeAxisSpaceForSubplots(space);
404    
405            // draw the shared axis
406            CategoryAxis axis = getDomainAxis();
407            RectangleEdge domainEdge = getDomainAxisEdge();
408            double cursor = RectangleEdge.coordinate(dataArea, domainEdge);
409            AxisState axisState = axis.draw(
410                g2, cursor, area, dataArea, domainEdge, info
411            );
412            if (parentState == null) {
413                parentState = new PlotState();
414            }
415            parentState.getSharedAxisStates().put(axis, axisState);
416            
417            // draw all the subplots
418            for (int i = 0; i < this.subplots.size(); i++) {
419                CategoryPlot plot = (CategoryPlot) this.subplots.get(i);
420                PlotRenderingInfo subplotInfo = null;
421                if (info != null) {
422                    subplotInfo = new PlotRenderingInfo(info.getOwner());
423                    info.addSubplotInfo(subplotInfo);
424                }
425                plot.draw(g2, this.subplotAreas[i], null, parentState, subplotInfo);
426            }
427    
428            if (info != null) {
429                info.setDataArea(dataArea);
430            }
431    
432        }
433    
434        /**
435         * Sets the size (width or height, depending on the orientation of the 
436         * plot) for the range axis of each subplot.
437         *
438         * @param space  the space (<code>null</code> permitted).
439         */
440        protected void setFixedRangeAxisSpaceForSubplots(AxisSpace space) {
441    
442            Iterator iterator = this.subplots.iterator();
443            while (iterator.hasNext()) {
444                CategoryPlot plot = (CategoryPlot) iterator.next();
445                plot.setFixedRangeAxisSpace(space);
446            }
447    
448        }
449    
450        /**
451         * Sets the orientation of the plot (and all subplots).
452         * 
453         * @param orientation  the orientation (<code>null</code> not permitted).
454         */
455        public void setOrientation(PlotOrientation orientation) {
456    
457            super.setOrientation(orientation);
458    
459            Iterator iterator = this.subplots.iterator();
460            while (iterator.hasNext()) {
461                CategoryPlot plot = (CategoryPlot) iterator.next();
462                plot.setOrientation(orientation);
463            }
464    
465        }
466        
467        /**
468         * Returns a collection of legend items for the plot.
469         *
470         * @return The legend items.
471         */
472        public LegendItemCollection getLegendItems() {
473            LegendItemCollection result = getFixedLegendItems();
474            if (result == null) {
475                result = new LegendItemCollection();
476                if (this.subplots != null) {
477                    Iterator iterator = this.subplots.iterator();
478                    while (iterator.hasNext()) {
479                        CategoryPlot plot = (CategoryPlot) iterator.next();
480                        LegendItemCollection more = plot.getLegendItems();
481                        result.addAll(more);
482                    }
483                }
484            }
485            return result;
486        }
487        
488        /**
489         * Returns an unmodifiable list of the categories contained in all the 
490         * subplots.
491         * 
492         * @return The list.
493         */
494        public List getCategories() {
495            
496            List result = new java.util.ArrayList();
497    
498            if (this.subplots != null) {
499                Iterator iterator = this.subplots.iterator();
500                while (iterator.hasNext()) {
501                    CategoryPlot plot = (CategoryPlot) iterator.next();
502                    List more = plot.getCategories();
503                    Iterator moreIterator = more.iterator();
504                    while (moreIterator.hasNext()) {
505                        Comparable category = (Comparable) moreIterator.next();
506                        if (!result.contains(category)) {
507                            result.add(category);
508                        }
509                    }
510                }
511            }
512    
513            return Collections.unmodifiableList(result);
514        }
515        
516        /**
517         * Handles a 'click' on the plot.
518         *
519         * @param x  x-coordinate of the click.
520         * @param y  y-coordinate of the click.
521         * @param info  information about the plot's dimensions.
522         *
523         */
524        public void handleClick(int x, int y, PlotRenderingInfo info) {
525    
526            Rectangle2D dataArea = info.getDataArea();
527            if (dataArea.contains(x, y)) {
528                for (int i = 0; i < this.subplots.size(); i++) {
529                    CategoryPlot subplot = (CategoryPlot) this.subplots.get(i);
530                    PlotRenderingInfo subplotInfo = info.getSubplotInfo(i);
531                    subplot.handleClick(x, y, subplotInfo);
532                }
533            }
534    
535        }
536        
537        /**
538         * Receives a {@link PlotChangeEvent} and responds by notifying all 
539         * listeners.
540         * 
541         * @param event  the event.
542         */
543        public void plotChanged(PlotChangeEvent event) {
544            notifyListeners(event);
545        }
546    
547        /** 
548         * Tests the plot for equality with an arbitrary object.
549         * 
550         * @param obj  the object (<code>null</code> permitted).
551         * 
552         * @return A boolean.
553         */
554        public boolean equals(Object obj) {
555            if (obj == this) {
556                return true;
557            }
558            if (!(obj instanceof CombinedDomainCategoryPlot)) {
559                return false;
560            }
561            if (!super.equals(obj)) {
562                return false;
563            }
564            CombinedDomainCategoryPlot plot = (CombinedDomainCategoryPlot) obj;
565            if (!ObjectUtilities.equal(this.subplots, plot.subplots)) {
566                return false;
567            }
568            if (this.totalWeight != plot.totalWeight) {
569                return false;
570            }
571            if (this.gap != plot.gap) { 
572                return false;
573            }
574            return true;
575        }
576    
577        /**
578         * Returns a clone of the plot.
579         * 
580         * @return A clone.
581         * 
582         * @throws CloneNotSupportedException  this class will not throw this 
583         *         exception, but subclasses (if any) might.
584         */
585        public Object clone() throws CloneNotSupportedException {
586            
587            CombinedDomainCategoryPlot result 
588                = (CombinedDomainCategoryPlot) super.clone(); 
589            result.subplots = (List) ObjectUtilities.deepClone(this.subplots);
590            for (Iterator it = result.subplots.iterator(); it.hasNext();) {
591                Plot child = (Plot) it.next();
592                child.setParent(result);
593            }
594            return result;
595            
596        }
597        
598    }