Source for org.jfree.chart.renderer.xy.XYItemRenderer

   1: /* ===========================================================
   2:  * JFreeChart : a free chart library for the Java(tm) platform
   3:  * ===========================================================
   4:  *
   5:  * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors.
   6:  *
   7:  * Project Info:  http://www.jfree.org/jfreechart/index.html
   8:  *
   9:  * This library is free software; you can redistribute it and/or modify it 
  10:  * under the terms of the GNU Lesser General Public License as published by 
  11:  * the Free Software Foundation; either version 2.1 of the License, or 
  12:  * (at your option) any later version.
  13:  *
  14:  * This library is distributed in the hope that it will be useful, but 
  15:  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
  16:  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
  17:  * License for more details.
  18:  *
  19:  * You should have received a copy of the GNU Lesser General Public
  20:  * License along with this library; if not, write to the Free Software
  21:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
  22:  * USA.  
  23:  *
  24:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
  25:  * in the United States and other countries.]
  26:  *
  27:  * -------------------
  28:  * XYItemRenderer.java
  29:  * -------------------
  30:  * (C) Copyright 2001-2007, by Object Refinery Limited and Contributors.
  31:  *
  32:  * Original Author:  David Gilbert (for Object Refinery Limited);
  33:  * Contributor(s):   Mark Watson (www.markwatson.com);
  34:  *                   Sylvain Vieujot;
  35:  *                   Focus Computer Services Limited;
  36:  *                   Richard Atkinson;
  37:  *
  38:  * Changes
  39:  * -------
  40:  * 19-Oct-2001 : Version 1, based on code by Mark Watson (DG);
  41:  * 22-Oct-2001 : Renamed DataSource.java --> Dataset.java etc. (DG);
  42:  * 13-Dec-2001 : Changed return type of drawItem from void --> Shape.  The area
  43:  *               returned can be used as the tooltip region.
  44:  * 23-Jan-2002 : Added DrawInfo parameter to drawItem() method (DG);
  45:  * 28-Mar-2002 : Added a property change listener mechanism.  Now renderers do 
  46:  *               not have to be immutable (DG);
  47:  * 04-Apr-2002 : Added the initialise() method (DG);
  48:  * 09-Apr-2002 : Removed the translated zero from the drawItem method, it can 
  49:  *               be calculated inside the initialise method if it is required.
  50:  *               Added a new getToolTipGenerator() method.  Changed the return 
  51:  *               type for drawItem() to void (DG);
  52:  * 24-May-2002 : Added ChartRenderingInfo the initialise method API (DG);
  53:  * 25-Jun-2002 : Removed redundant import (DG);
  54:  * 20-Aug-2002 : Added get/setURLGenerator methods to interface (DG);
  55:  * 02-Oct-2002 : Fixed errors reported by Checkstyle (DG);
  56:  * 18-Nov-2002 : Added methods for drawing grid lines (DG);
  57:  * 17-Jan-2003 : Moved plot classes into a separate package (DG);
  58:  * 27-Jan-2003 : Added shape lookup table (DG);
  59:  * 05-Jun-2003 : Added domain and range grid bands (sponsored by Focus Computer
  60:  *               Services Ltd) (DG);
  61:  * 27-Jul-2003 : Added getRangeType() to support stacked XY area charts (RA);
  62:  * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
  63:  * 25-Feb-2004 : Replaced CrosshairInfo with CrosshairState.  Renamed 
  64:  *               XYToolTipGenerator --> XYItemLabelGenerator (DG);
  65:  * 26-Feb-2004 : Added lots of new methods (DG);
  66:  * 30-Apr-2004 : Added getRangeExtent() method (DG);
  67:  * 06-May-2004 : Added methods for controlling item label visibility (DG);
  68:  * 13-May-2004 : Removed property change listener mechanism (DG);
  69:  * 18-May-2004 : Added item label font and paint methods (DG);
  70:  * 10-Sep-2004 : Removed redundant getRangeType() method (DG);
  71:  * 06-Oct-2004 : Replaced getRangeExtent() with findRangeBounds() and added 
  72:  *               findDomainBounds (DG);
  73:  * 23-Nov-2004 : Changed drawRangeGridLine() --> drawRangeLine() (DG);
  74:  * 07-Jan-2005 : Removed deprecated method (DG);
  75:  * 24-Feb-2005 : Now extends LegendItemSource (DG);
  76:  * 20-Apr-2005 : Renamed XYLabelGenerator --> XYItemLabelGenerator (DG);
  77:  * ------------- JFREECHART 1.0.x ---------------------------------------------
  78:  * 19-Apr-2007 : Deprecated seriesVisible and seriesVisibleInLegend flags (DG);
  79:  * 20-Apr-2007 : Deprecated paint, fillPaint, outlinePaint, stroke, 
  80:  *               outlineStroke, shape, itemLabelsVisible, itemLabelFont, 
  81:  *               itemLabelPaint, positiveItemLabelPosition, 
  82:  *               negativeItemLabelPosition and createEntities override 
  83:  *               fields (DG);
  84:  *
  85:  */
  86: 
  87: package org.jfree.chart.renderer.xy;
  88: 
  89: import java.awt.Font;
  90: import java.awt.Graphics2D;
  91: import java.awt.Paint;
  92: import java.awt.Shape;
  93: import java.awt.Stroke;
  94: import java.awt.geom.Rectangle2D;
  95: 
  96: import org.jfree.chart.LegendItem;
  97: import org.jfree.chart.LegendItemSource;
  98: import org.jfree.chart.annotations.XYAnnotation;
  99: import org.jfree.chart.axis.ValueAxis;
 100: import org.jfree.chart.event.RendererChangeEvent;
 101: import org.jfree.chart.event.RendererChangeListener;
 102: import org.jfree.chart.labels.ItemLabelPosition;
 103: import org.jfree.chart.labels.XYItemLabelGenerator;
 104: import org.jfree.chart.labels.XYSeriesLabelGenerator;
 105: import org.jfree.chart.labels.XYToolTipGenerator;
 106: import org.jfree.chart.plot.CrosshairState;
 107: import org.jfree.chart.plot.Marker;
 108: import org.jfree.chart.plot.PlotRenderingInfo;
 109: import org.jfree.chart.plot.XYPlot;
 110: import org.jfree.chart.urls.XYURLGenerator;
 111: import org.jfree.data.Range;
 112: import org.jfree.data.xy.XYDataset;
 113: import org.jfree.ui.Layer;
 114: 
 115: /**
 116:  * Interface for rendering the visual representation of a single (x, y) item on
 117:  * an {@link XYPlot}.
 118:  * <p>
 119:  * To support cloning charts, it is recommended that renderers implement both 
 120:  * the {@link Cloneable} and <code>PublicCloneable</code> interfaces.
 121:  */
 122: public interface XYItemRenderer extends LegendItemSource {
 123: 
 124:     /**
 125:      * Initialises the renderer then returns the number of 'passes' through the
 126:      * data that the renderer will require (usually just one).  This method 
 127:      * will be called before the first item is rendered, giving the renderer 
 128:      * an opportunity to initialise any state information it wants to maintain.
 129:      * The renderer can do nothing if it chooses.
 130:      *
 131:      * @param g2  the graphics device.
 132:      * @param dataArea  the area inside the axes.
 133:      * @param plot  the plot.
 134:      * @param dataset  the dataset.
 135:      * @param info  an optional info collection object to return data back to 
 136:      *              the caller.
 137:      *
 138:      * @return The number of passes the renderer requires.
 139:      */
 140:     public XYItemRendererState initialise(Graphics2D g2,
 141:                                           Rectangle2D dataArea,
 142:                                           XYPlot plot,
 143:                                           XYDataset dataset,
 144:                                           PlotRenderingInfo info);
 145: 
 146:     /**
 147:      * Returns the number of passes through the data required by the renderer.
 148:      * 
 149:      * @return The pass count.
 150:      */
 151:     public int getPassCount();
 152: 
 153:     /**
 154:      * Returns a boolean that indicates whether or not the specified item 
 155:      * should be drawn (this is typically used to hide an entire series).
 156:      * 
 157:      * @param series  the series index.
 158:      * @param item  the item index.
 159:      * 
 160:      * @return A boolean.
 161:      */
 162:     public boolean getItemVisible(int series, int item);
 163:     
 164:     /**
 165:      * Returns a boolean that indicates whether or not the specified series 
 166:      * should be drawn (this is typically used to hide an entire series).
 167:      * 
 168:      * @param series  the series index.
 169:      * 
 170:      * @return A boolean.
 171:      */
 172:     public boolean isSeriesVisible(int series);
 173:     
 174:     /**
 175:      * Returns the flag that controls the visibility of ALL series.  This flag 
 176:      * overrides the per series and default settings - you must set it to 
 177:      * <code>null</code> if you want the other settings to apply.
 178:      * 
 179:      * @return The flag (possibly <code>null</code>).
 180:      * 
 181:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 182:      *     It is sufficient to rely on {@link #getSeriesVisible(int)} and
 183:      *     {@link #getBaseSeriesVisible()}.
 184:      */
 185:     public Boolean getSeriesVisible();
 186:     
 187:     /**
 188:      * Sets the flag that controls the visibility of ALL series and sends a 
 189:      * {@link RendererChangeEvent} to all registered listeners.  This flag 
 190:      * overrides the per series and default settings - you must set it to 
 191:      * <code>null</code> if you want the other settings to apply.
 192:      * 
 193:      * @param visible  the flag (<code>null</code> permitted).
 194:      *
 195:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 196:      *     It is sufficient to rely on {@link #setSeriesVisible(int, Boolean)} 
 197:      *     and {@link #setBaseSeriesVisible(boolean)}.
 198:      */
 199:     public void setSeriesVisible(Boolean visible);
 200:     
 201:     /**
 202:      * Sets the flag that controls the visibility of ALL series and sends a 
 203:      * {@link RendererChangeEvent} to all registered listeners.  This flag 
 204:      * overrides the per series and default settings - you must set it to 
 205:      * <code>null</code> if you want the other settings to apply.
 206:      * 
 207:      * @param visible  the flag (<code>null</code> permitted).
 208:      * @param notify  notify listeners?
 209:      *
 210:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 211:      *     It is sufficient to rely on {@link #setSeriesVisible(int, Boolean, 
 212:      *     boolean)} and {@link #setBaseSeriesVisible(boolean, boolean)}.
 213:      */
 214:     public void setSeriesVisible(Boolean visible, boolean notify);
 215:     
 216:     /**
 217:      * Returns the flag that controls whether a series is visible.
 218:      *
 219:      * @param series  the series index (zero-based).
 220:      *
 221:      * @return The flag (possibly <code>null</code>).
 222:      */
 223:     public Boolean getSeriesVisible(int series);
 224:     
 225:     /**
 226:      * Sets the flag that controls whether a series is visible and sends a 
 227:      * {@link RendererChangeEvent} to all registered listeners.
 228:      *
 229:      * @param series  the series index (zero-based).
 230:      * @param visible  the flag (<code>null</code> permitted).
 231:      */
 232:     public void setSeriesVisible(int series, Boolean visible);
 233:     
 234:     /**
 235:      * Sets the flag that controls whether a series is visible and, if 
 236:      * requested, sends a {@link RendererChangeEvent} to all registered 
 237:      * listeners.
 238:      * 
 239:      * @param series  the series index.
 240:      * @param visible  the flag (<code>null</code> permitted).
 241:      * @param notify  notify listeners?
 242:      */
 243:     public void setSeriesVisible(int series, Boolean visible, boolean notify);
 244: 
 245:     /**
 246:      * Returns the base visibility for all series.
 247:      *
 248:      * @return The base visibility.
 249:      */
 250:     public boolean getBaseSeriesVisible();
 251: 
 252:     /**
 253:      * Sets the base visibility and sends a {@link RendererChangeEvent} to all
 254:      * registered listeners.
 255:      *
 256:      * @param visible  the flag.
 257:      */
 258:     public void setBaseSeriesVisible(boolean visible);
 259:     
 260:     /**
 261:      * Sets the base visibility and, if requested, sends 
 262:      * a {@link RendererChangeEvent} to all registered listeners.
 263:      * 
 264:      * @param visible  the visibility.
 265:      * @param notify  notify listeners?
 266:      */
 267:     public void setBaseSeriesVisible(boolean visible, boolean notify);
 268: 
 269:     // SERIES VISIBLE IN LEGEND (not yet respected by all renderers)
 270:     
 271:     /**
 272:      * Returns <code>true</code> if the series should be shown in the legend,
 273:      * and <code>false</code> otherwise.
 274:      * 
 275:      * @param series  the series index.
 276:      * 
 277:      * @return A boolean.
 278:      */
 279:     public boolean isSeriesVisibleInLegend(int series);
 280:     
 281:     /**
 282:      * Returns the flag that controls the visibility of ALL series in the 
 283:      * legend.  This flag overrides the per series and default settings - you 
 284:      * must set it to <code>null</code> if you want the other settings to 
 285:      * apply.
 286:      * 
 287:      * @return The flag (possibly <code>null</code>).
 288:      * 
 289:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 290:      *     It is sufficient to rely on {@link #getSeriesVisibleInLegend(int)} 
 291:      *     and {@link #getBaseSeriesVisibleInLegend()}.
 292:      */
 293:     public Boolean getSeriesVisibleInLegend();
 294:     
 295:     /**
 296:      * Sets the flag that controls the visibility of ALL series in the legend 
 297:      * and sends a {@link RendererChangeEvent} to all registered listeners.  
 298:      * This flag overrides the per series and default settings - you must set 
 299:      * it to <code>null</code> if you want the other settings to apply.
 300:      * 
 301:      * @param visible  the flag (<code>null</code> permitted).
 302:      * 
 303:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 304:      *     It is sufficient to rely on {@link #setSeriesVisibleInLegend(int, 
 305:      *     Boolean)} and {@link #setBaseSeriesVisibleInLegend(boolean)}.
 306:      */
 307:     public void setSeriesVisibleInLegend(Boolean visible);
 308:     
 309:     /**
 310:      * Sets the flag that controls the visibility of ALL series in the legend 
 311:      * and sends a {@link RendererChangeEvent} to all registered listeners.  
 312:      * This flag overrides the per series and default settings - you must set 
 313:      * it to <code>null</code> if you want the other settings to apply.
 314:      * 
 315:      * @param visible  the flag (<code>null</code> permitted).
 316:      * @param notify  notify listeners?
 317:      * 
 318:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 319:      *     It is sufficient to rely on {@link #setSeriesVisibleInLegend(int, 
 320:      *     Boolean, boolean)} and {@link #setBaseSeriesVisibleInLegend(boolean,
 321:      *     boolean)}.
 322:      */
 323:     public void setSeriesVisibleInLegend(Boolean visible, boolean notify);
 324:     
 325:     /**
 326:      * Returns the flag that controls whether a series is visible in the 
 327:      * legend.  This method returns only the "per series" settings - to 
 328:      * incorporate the override and base settings as well, you need to use the 
 329:      * {@link #isSeriesVisibleInLegend(int)} method.
 330:      *
 331:      * @param series  the series index (zero-based).
 332:      *
 333:      * @return The flag (possibly <code>null</code>).
 334:      */
 335:     public Boolean getSeriesVisibleInLegend(int series);
 336:     
 337:     /**
 338:      * Sets the flag that controls whether a series is visible in the legend 
 339:      * and sends a {@link RendererChangeEvent} to all registered listeners.
 340:      *
 341:      * @param series  the series index (zero-based).
 342:      * @param visible  the flag (<code>null</code> permitted).
 343:      */
 344:     public void setSeriesVisibleInLegend(int series, Boolean visible);
 345:     
 346:     /**
 347:      * Sets the flag that controls whether a series is visible in the legend
 348:      * and, if requested, sends a {@link RendererChangeEvent} to all registered 
 349:      * listeners.
 350:      * 
 351:      * @param series  the series index.
 352:      * @param visible  the flag (<code>null</code> permitted).
 353:      * @param notify  notify listeners?
 354:      */
 355:     public void setSeriesVisibleInLegend(int series, Boolean visible, 
 356:                                          boolean notify);
 357: 
 358:     /**
 359:      * Returns the base visibility in the legend for all series.
 360:      *
 361:      * @return The base visibility.
 362:      */
 363:     public boolean getBaseSeriesVisibleInLegend();
 364: 
 365:     /**
 366:      * Sets the base visibility in the legend and sends a 
 367:      * {@link RendererChangeEvent} to all registered listeners.
 368:      *
 369:      * @param visible  the flag.
 370:      */
 371:     public void setBaseSeriesVisibleInLegend(boolean visible);
 372:     
 373:     /**
 374:      * Sets the base visibility in the legend and, if requested, sends 
 375:      * a {@link RendererChangeEvent} to all registered listeners.
 376:      * 
 377:      * @param visible  the visibility.
 378:      * @param notify  notify listeners?
 379:      */
 380:     public void setBaseSeriesVisibleInLegend(boolean visible, boolean notify);
 381: 
 382:     // PAINT
 383:     
 384:     /**
 385:      * Returns the paint used to fill data items as they are drawn.
 386:      *
 387:      * @param row  the row (or series) index (zero-based).
 388:      * @param column  the column (or category) index (zero-based).
 389:      *
 390:      * @return The paint (never <code>null</code>).
 391:      */
 392:     public Paint getItemPaint(int row, int column);
 393: 
 394:     /**
 395:      * Returns the paint used to fill an item drawn by the renderer.
 396:      *
 397:      * @param series  the series index (zero-based).
 398:      *
 399:      * @return The paint (possibly <code>null</code>).
 400:      */
 401:     public Paint getSeriesPaint(int series);
 402: 
 403:     /**
 404:      * Sets the paint to be used for ALL series, and sends a 
 405:      * {@link RendererChangeEvent} to all registered listeners.  If this is 
 406:      * <code>null</code>, the renderer will use the paint for the series.
 407:      * 
 408:      * @param paint  the paint (<code>null</code> permitted).
 409:      * 
 410:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 411:      *     It is sufficient to rely on {@link #setSeriesPaint(int, Paint)} and 
 412:      *     {@link #setBasePaint(Paint)}.
 413:      */
 414:     public void setPaint(Paint paint);
 415:     
 416:     /**
 417:      * Sets the paint used for a series and sends a {@link RendererChangeEvent}
 418:      * to all registered listeners.
 419:      *
 420:      * @param series  the series index (zero-based).
 421:      * @param paint  the paint (<code>null</code> permitted).
 422:      */
 423:     public void setSeriesPaint(int series, Paint paint);
 424:     
 425:     // FIXME: add setSeriesPaint(int, Paint, boolean)?
 426:     
 427:     /**
 428:      * Returns the base paint.
 429:      *
 430:      * @return The base paint (never <code>null</code>).
 431:      */
 432:     public Paint getBasePaint();
 433: 
 434:     /**
 435:      * Sets the base paint and sends a {@link RendererChangeEvent} to all 
 436:      * registered listeners.
 437:      *
 438:      * @param paint  the paint (<code>null</code> not permitted).
 439:      */
 440:     public void setBasePaint(Paint paint);
 441:     
 442:     // FIXME: add setBasePaint(int, Paint, boolean)?
 443:     
 444: //    // FILL PAINT
 445: //    
 446: //    /**
 447: //     * Returns the paint used to fill data items as they are drawn.
 448: //     *
 449: //     * @param row  the row (or series) index (zero-based).
 450: //     * @param column  the column (or category) index (zero-based).
 451: //     *
 452: //     * @return The paint (never <code>null</code>).
 453: //     */
 454: //    public Paint getItemFillPaint(int row, int column);
 455: //
 456: //    /**
 457: //     * Returns the paint used to fill an item drawn by the renderer.
 458: //     *
 459: //     * @param series  the series index (zero-based).
 460: //     *
 461: //     * @return The paint (possibly <code>null</code>).
 462: //     */
 463: //    public Paint getSeriesFillPaint(int series);
 464: //    
 465: //    /**
 466: //     * Sets the paint used for a series and sends a 
 467: //     * {@link RendererChangeEvent} to all registered listeners.
 468: //     *
 469: //     * @param series  the series index (zero-based).
 470: //     * @param paint  the paint (<code>null</code> permitted).
 471: //     */
 472: //    public void setSeriesFillPaint(int series, Paint paint);
 473: //    
 474: //    // FIXME: add setSeriesFillPaint(int, Paint, boolean)?
 475: //    
 476: //    /**
 477: //     * Returns the base paint.
 478: //     *
 479: //     * @return The base paint (never <code>null</code>).
 480: //     */
 481: //    public Paint getBaseFillPaint();
 482: //
 483: //    /**
 484: //     * Sets the base paint and sends a {@link RendererChangeEvent} to all 
 485: //     * registered listeners.
 486: //     *
 487: //     * @param paint  the paint (<code>null</code> not permitted).
 488: //     */
 489: //    public void setBaseFillPaint(Paint paint);
 490: //    
 491: //    // FIXME: add setBaseFillPaint(int, Paint, boolean)?
 492:     
 493:     // OUTLINE PAINT
 494:     
 495:     /**
 496:      * Returns the paint used to outline data items as they are drawn.
 497:      *
 498:      * @param row  the row (or series) index (zero-based).
 499:      * @param column  the column (or category) index (zero-based).
 500:      *
 501:      * @return The paint (never <code>null</code>).
 502:      */
 503:     public Paint getItemOutlinePaint(int row, int column);
 504: 
 505:     /**
 506:      * Returns the paint used to outline an item drawn by the renderer.
 507:      *
 508:      * @param series  the series (zero-based index).
 509:      *
 510:      * @return The paint (possibly <code>null</code>).
 511:      */
 512:     public Paint getSeriesOutlinePaint(int series);
 513: 
 514:     /**
 515:      * Sets the paint used for a series outline and sends a 
 516:      * {@link RendererChangeEvent} to all registered listeners.
 517:      *
 518:      * @param series  the series index (zero-based).
 519:      * @param paint  the paint (<code>null</code> permitted).
 520:      */
 521:     public void setSeriesOutlinePaint(int series, Paint paint);
 522: 
 523:     // FIXME: add setSeriesOutlinePaint(int, Paint, boolean)?
 524: 
 525:     /**
 526:      * Sets the outline paint for ALL series (optional).
 527:      * 
 528:      * @param paint  the paint (<code>null</code> permitted).
 529:      * 
 530:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 531:      *     It is sufficient to rely on {@link #setSeriesOutlinePaint(int, 
 532:      *     Paint)} and {@link #setBaseOutlinePaint(Paint)}.
 533:      */
 534:     public void setOutlinePaint(Paint paint);
 535:     
 536:     /**
 537:      * Returns the base outline paint.
 538:      *
 539:      * @return The paint (never <code>null</code>).
 540:      */
 541:     public Paint getBaseOutlinePaint();
 542: 
 543:     /**
 544:      * Sets the base outline paint and sends a {@link RendererChangeEvent} to
 545:      * all registered listeners.
 546:      *
 547:      * @param paint  the paint (<code>null</code> not permitted).
 548:      */
 549:     public void setBaseOutlinePaint(Paint paint);
 550:     
 551:     // FIXME: add setBaseOutlinePaint(Paint, boolean)?
 552: 
 553:     // STROKE
 554:     
 555:     /**
 556:      * Returns the stroke used to draw data items.
 557:      *
 558:      * @param row  the row (or series) index (zero-based).
 559:      * @param column  the column (or category) index (zero-based).
 560:      *
 561:      * @return The stroke (never <code>null</code>).
 562:      */
 563:     public Stroke getItemStroke(int row, int column);
 564: 
 565:     /**
 566:      * Returns the stroke used to draw the items in a series.
 567:      *
 568:      * @param series  the series (zero-based index).
 569:      *
 570:      * @return The stroke (possibly <code>null</code>).
 571:      */
 572:     public Stroke getSeriesStroke(int series);
 573:     
 574:     /**
 575:      * Sets the stroke for ALL series and sends a {@link RendererChangeEvent} 
 576:      * to all registered listeners.
 577:      * 
 578:      * @param stroke  the stroke (<code>null</code> permitted).
 579:      * 
 580:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 581:      *     It is sufficient to rely on {@link #setSeriesStroke(int, Stroke)} 
 582:      *     and {@link #setBaseStroke(Stroke)}.
 583:      */
 584:     public void setStroke(Stroke stroke);
 585: 
 586:     /**
 587:      * Sets the stroke used for a series and sends a 
 588:      * {@link RendererChangeEvent} to all registered listeners.
 589:      *
 590:      * @param series  the series index (zero-based).
 591:      * @param stroke  the stroke (<code>null</code> permitted).
 592:      */
 593:     public void setSeriesStroke(int series, Stroke stroke);
 594: 
 595:     // FIXME: add setSeriesStroke(int, Stroke, boolean) ?
 596: 
 597:     /**
 598:      * Returns the base stroke.
 599:      *
 600:      * @return The base stroke (never <code>null</code>).
 601:      */
 602:     public Stroke getBaseStroke();
 603: 
 604:     /**
 605:      * Sets the base stroke.
 606:      *
 607:      * @param stroke  the stroke (<code>null</code> not permitted).
 608:      */
 609:     public void setBaseStroke(Stroke stroke);
 610:     
 611:     // FIXME: add setBaseStroke(Stroke, boolean) ?
 612: 
 613:     // OUTLINE STROKE 
 614:     
 615:     /**
 616:      * Returns the stroke used to outline data items.  The default 
 617:      * implementation passes control to the lookupSeriesOutlineStroke method.
 618:      * You can override this method if you require different behaviour.
 619:      *
 620:      * @param row  the row (or series) index (zero-based).
 621:      * @param column  the column (or category) index (zero-based).
 622:      *
 623:      * @return The stroke (never <code>null</code>).
 624:      */
 625:     public Stroke getItemOutlineStroke(int row, int column);
 626: 
 627:     /**
 628:      * Returns the stroke used to outline the items in a series.
 629:      *
 630:      * @param series  the series (zero-based index).
 631:      *
 632:      * @return The stroke (possibly <code>null</code>).
 633:      */
 634:     public Stroke getSeriesOutlineStroke(int series);
 635: 
 636:     /**
 637:      * Sets the outline stroke for ALL series and sends a 
 638:      * {@link RendererChangeEvent} to all registered listeners.
 639:      *
 640:      * @param stroke  the stroke (<code>null</code> permitted).
 641:      * 
 642:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 643:      *     It is sufficient to rely on {@link #setSeriesOutlineStroke(int, 
 644:      *     Stroke)} and {@link #setBaseOutlineStroke(Stroke)}.
 645:      */
 646:     public void setOutlineStroke(Stroke stroke);
 647:     
 648:     /**
 649:      * Sets the outline stroke used for a series and sends a 
 650:      * {@link RendererChangeEvent} to all registered listeners.
 651:      *
 652:      * @param series  the series index (zero-based).
 653:      * @param stroke  the stroke (<code>null</code> permitted).
 654:      */
 655:     public void setSeriesOutlineStroke(int series, Stroke stroke);
 656:     
 657:     // FIXME: add setSeriesOutlineStroke(int, Stroke, boolean) ?
 658: 
 659:     /**
 660:      * Returns the base outline stroke.
 661:      *
 662:      * @return The stroke (never <code>null</code>).
 663:      */
 664:     public Stroke getBaseOutlineStroke();
 665: 
 666:     /**
 667:      * Sets the base outline stroke and sends a {@link RendererChangeEvent} to
 668:      * all registered listeners.
 669:      *
 670:      * @param stroke  the stroke (<code>null</code> not permitted).
 671:      */
 672:     public void setBaseOutlineStroke(Stroke stroke);
 673:     
 674:     // FIXME: add setBaseOutlineStroke(Stroke, boolean) ?
 675:     
 676:     // SHAPE
 677:     
 678:     /**
 679:      * Returns a shape used to represent a data item.
 680:      *
 681:      * @param row  the row (or series) index (zero-based).
 682:      * @param column  the column (or category) index (zero-based).
 683:      *
 684:      * @return The shape (never <code>null</code>).
 685:      */
 686:     public Shape getItemShape(int row, int column);
 687: 
 688:     /**
 689:      * Returns a shape used to represent the items in a series.
 690:      *
 691:      * @param series  the series (zero-based index).
 692:      *
 693:      * @return The shape (possibly <code>null</code>).
 694:      */
 695:     public Shape getSeriesShape(int series);
 696:     /**
 697:      * Sets the shape for ALL series (optional) and sends a 
 698:      * {@link RendererChangeEvent} to all registered listeners.
 699:      * 
 700:      * @param shape  the shape (<code>null</code> permitted).
 701:      * 
 702:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 703:      *     It is sufficient to rely on {@link #setSeriesShape(int, Shape)} and 
 704:      *     {@link #setBaseShape(Shape)}.
 705:      */
 706:     public void setShape(Shape shape);
 707:     
 708:     /**
 709:      * Sets the shape used for a series and sends a {@link RendererChangeEvent}
 710:      * to all registered listeners.
 711:      *
 712:      * @param series  the series index (zero-based).
 713:      * @param shape  the shape (<code>null</code> permitted).
 714:      */
 715:     public void setSeriesShape(int series, Shape shape);
 716:     
 717:     // FIXME: add setSeriesShape(int, Shape, boolean) ?
 718:     
 719:     /**
 720:      * Returns the base shape.
 721:      *
 722:      * @return The shape (never <code>null</code>).
 723:      */
 724:     public Shape getBaseShape();
 725: 
 726:     /**
 727:      * Sets the base shape and sends a {@link RendererChangeEvent} to all 
 728:      * registered listeners.
 729:      *
 730:      * @param shape  the shape (<code>null</code> not permitted).
 731:      */
 732:     public void setBaseShape(Shape shape);
 733:     
 734:     // FIXME: add setBaseShape(Shape, boolean) ?
 735: 
 736:     // ITEM LABELS VISIBLE 
 737:     
 738:     /**
 739:      * Returns <code>true</code> if an item label is visible, and 
 740:      * <code>false</code> otherwise.
 741:      * 
 742:      * @param row  the row index (zero-based).
 743:      * @param column  the column index (zero-based).
 744:      * 
 745:      * @return A boolean.
 746:      */
 747:     public boolean isItemLabelVisible(int row, int column);
 748:     
 749:     /**
 750:      * Returns <code>true</code> if the item labels for a series are visible,
 751:      * and <code>false</code> otherwise.
 752:      * 
 753:      * @param series  the series index (zero-based).
 754:      * 
 755:      * @return A boolean.
 756:      */    
 757:     public boolean isSeriesItemLabelsVisible(int series);
 758:     
 759:     /**
 760:      * Sets a flag that controls whether or not the item labels for ALL series
 761:      * are visible.
 762:      * 
 763:      * @param visible  the flag.
 764:      * 
 765:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 766:      *     It is sufficient to rely on {@link #setSeriesItemLabelsVisible(int, 
 767:      *     Boolean)} and {@link #setBaseItemLabelsVisible(boolean)}.
 768:      */
 769:     public void setItemLabelsVisible(boolean visible);
 770: 
 771:     /**
 772:      * Sets a flag that controls whether or not the item labels for ALL series
 773:      * are visible.
 774:      * 
 775:      * @param visible  the flag (<code>null</code> permitted).
 776:      * 
 777:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 778:      *     It is sufficient to rely on {@link #setSeriesItemLabelsVisible(int, 
 779:      *     Boolean)} and {@link #setBaseItemLabelsVisible(boolean)}.
 780:      */
 781:     public void setItemLabelsVisible(Boolean visible);
 782: 
 783:     /**
 784:      * Sets the visibility of item labels for ALL series and, if requested, 
 785:      * sends a {@link RendererChangeEvent} to all registered listeners.
 786:      * 
 787:      * @param visible  a flag that controls whether or not the item labels are
 788:      *                 visible (<code>null</code> permitted).
 789:      * @param notify  a flag that controls whether or not listeners are 
 790:      *                notified.
 791:      *                
 792:      * @deprecated This method should no longer be used (as of version 1.0.6). 
 793:      *     It is sufficient to rely on {@link #setSeriesItemLabelsVisible(int, 
 794:      *     Boolean, boolean)} and {@link #setBaseItemLabelsVisible(Boolean, 
 795:      *     boolean)}.
 796:      */
 797:     public void setItemLabelsVisible(Boolean visible, boolean notify);
 798: 
 799:     /**
 800:      * Sets a flag that controls the visibility of the item labels for a series.
 801:      * 
 802:      * @param series  the series index (zero-based).
 803:      * @param visible  the flag.
 804:      */
 805:     public void setSeriesItemLabelsVisible(int series, boolean visible);
 806:     
 807:     /**
 808:      * Sets a flag that controls the visibility of the item labels for a series.
 809:      * 
 810:      * @param series  the series index (zero-based).
 811:      * @param visible  the flag (<code>null</code> permitted).
 812:      */
 813:     public void setSeriesItemLabelsVisible(int series, Boolean visible);
 814:     
 815:     /**
 816:      * Sets the visibility of item labels for a series and, if requested, 
 817:      * sends a {@link RendererChangeEvent} to all registered listeners.
 818:      * 
 819:      * @param series  the series index (zero-based).
 820:      * @param visible  the visible flag.
 821:      * @param notify  a flag that controls whether or not listeners are 
 822:      *                notified.
 823:      */
 824:     public void setSeriesItemLabelsVisible(int series, Boolean visible, 
 825:                                            boolean notify);
 826:     
 827:     /**
 828:      * Returns the base setting for item label visibility.
 829:      * 
 830:      * @return A flag (possibly <code>null</code>).
 831:      */
 832:     public Boolean getBaseItemLabelsVisible();
 833:     
 834:     /**
 835:      * Sets the base flag that controls whether or not item labels are visible.
 836:      * 
 837:      * @param visible  the flag.
 838:      */
 839:     public void setBaseItemLabelsVisible(boolean visible);
 840:     
 841:     /**
 842:      * Sets the base setting for item label visibility.
 843:      * 
 844:      * @param visible  the flag (<code>null</code> permitted).
 845:      */
 846:     public void setBaseItemLabelsVisible(Boolean visible);
 847:     
 848:     /**
 849:      * Sets the base visibility for item labels and, if requested, sends a 
 850:      * {@link RendererChangeEvent} to all registered listeners.
 851:      * 
 852:      * @param visible  the visibility flag.
 853:      * @param notify  a flag that controls whether or not listeners are
 854:      *                notified.
 855:      */
 856:     public void setBaseItemLabelsVisible(Boolean visible, boolean notify);
 857: 
 858:     // ITEM LABEL GENERATOR
 859: 
 860:     /**
 861:      * Returns the item label generator for a data item.
 862:      *
 863:      * @param row  the row index (zero based).
 864:      * @param column  the column index (zero based).
 865:      *
 866:      * @return The generator (possibly <code>null</code>).
 867:      */
 868:     public XYItemLabelGenerator getItemLabelGenerator(int row, int column);
 869:     
 870:     /**
 871:      * Returns the item label generator for a series.
 872:      *
 873:      * @param series  the series index (zero based).
 874:      *
 875:      * @return The generator (possibly <code>null</code>).
 876:      */
 877:     public XYItemLabelGenerator getSeriesItemLabelGenerator(int series);
 878: 
 879:     /**
 880:      * Sets the item label generator for ALL series and sends a 
 881:      * {@link RendererChangeEvent} to all registered listeners.
 882:      *
 883:      * @param generator  the generator (<code>null</code> permitted).
 884:      * 
 885:      * @deprecated As of version 1.0.6, this override setting should not be
 886:      *     used.  You can use the base setting instead 
 887:      *     ({@link #setBaseItemLabelGenerator(XYItemLabelGenerator)}).
 888:      */
 889:     public void setItemLabelGenerator(XYItemLabelGenerator generator);
 890: 
 891:     /**
 892:      * Sets the item label generator for a series and sends a 
 893:      * {@link RendererChangeEvent} to all registered listeners.
 894:      *
 895:      * @param series  the series index (zero based).
 896:      * @param generator  the generator (<code>null</code> permitted).
 897:      */
 898:     public void setSeriesItemLabelGenerator(int series, 
 899:                                             XYItemLabelGenerator generator);
 900: 
 901:     /**
 902:      * Returns the base item label generator.
 903:      *
 904:      * @return The generator (possibly <code>null</code>).
 905:      */
 906:     public XYItemLabelGenerator getBaseItemLabelGenerator();
 907: 
 908:     /**
 909:      * Sets the base item label generator and sends a 
 910:      * {@link RendererChangeEvent} to all registered listeners.
 911:      *
 912:      * @param generator  the generator (<code>null</code> permitted).
 913:      */
 914:     public void setBaseItemLabelGenerator(XYItemLabelGenerator generator);
 915: 
 916:     // TOOL TIP GENERATOR
 917: 
 918:     /**
 919:      * Returns the tool tip generator for a data item.
 920:      *
 921:      * @param row  the row index (zero based).
 922:      * @param column  the column index (zero based).
 923:      *
 924:      * @return The generator (possibly <code>null</code>).
 925:      */
 926:     public XYToolTipGenerator getToolTipGenerator(int row, int column);
 927:     
 928:     /**
 929:      * Returns the tool tip generator for a series.
 930:      *
 931:      * @param series  the series index (zero based).
 932:      *
 933:      * @return The generator (possibly <code>null</code>).
 934:      */
 935:     public XYToolTipGenerator getSeriesToolTipGenerator(int series);
 936: 
 937:     /**
 938:      * Sets the tool tip generator for ALL series and sends a 
 939:      * {@link RendererChangeEvent} to all registered listeners.
 940:      *
 941:      * @param generator  the generator (<code>null</code> permitted).
 942:      * 
 943:      * @deprecated As of version 1.0.6, this override setting should not be
 944:      *     used.  You can use the base setting instead 
 945:      *     ({@link #setBaseToolTipGenerator(XYToolTipGenerator)}).
 946:      */
 947:     public void setToolTipGenerator(XYToolTipGenerator generator);
 948: 
 949:     /**
 950:      * Sets the tool tip generator for a series and sends a 
 951:      * {@link RendererChangeEvent} to all registered listeners.
 952:      *
 953:      * @param series  the series index (zero based).
 954:      * @param generator  the generator (<code>null</code> permitted).
 955:      */
 956:     public void setSeriesToolTipGenerator(int series,               
 957:                                           XYToolTipGenerator generator);
 958: 
 959:     /**
 960:      * Returns the base tool tip generator.
 961:      *
 962:      * @return The generator (possibly <code>null</code>).
 963:      */
 964:     public XYToolTipGenerator getBaseToolTipGenerator();
 965: 
 966:     /**
 967:      * Sets the base tool tip generator and sends a {@link RendererChangeEvent}
 968:      * to all registered listeners.
 969:      *
 970:      * @param generator  the generator (<code>null</code> permitted).
 971:      */
 972:     public void setBaseToolTipGenerator(XYToolTipGenerator generator);
 973: 
 974:     // URL GENERATOR
 975:     
 976:     /**
 977:      * Returns the URL generator for HTML image maps.
 978:      *
 979:      * @return The URL generator (possibly null).
 980:      */
 981:     public XYURLGenerator getURLGenerator();
 982: 
 983:     /**
 984:      * Sets the URL generator for HTML image maps.
 985:      *
 986:      * @param urlGenerator the URL generator (null permitted).
 987:      */
 988:     public void setURLGenerator(XYURLGenerator urlGenerator);
 989: 
 990:     //// ITEM LABEL FONT ///////////////////////////////////////////////////////
 991: 
 992:     /**
 993:      * Returns the font for an item label.
 994:      * 
 995:      * @param row  the row index (zero-based).
 996:      * @param column  the column index (zero-based).
 997:      * 
 998:      * @return The font (never <code>null</code>).
 999:      */
1000:     public Font getItemLabelFont(int row, int column);
1001: 
1002:     /**
1003:      * Returns the font used for all item labels.  This may be 
1004:      * <code>null</code>, in which case the per series font settings will apply.
1005:      * 
1006:      * @return The font (possibly <code>null</code>).
1007:      * 
1008:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1009:      *     It is sufficient to rely on {@link #getSeriesItemLabelFont(int)} and
1010:      *     {@link #getBaseItemLabelFont()}.
1011:      */
1012:     public Font getItemLabelFont();
1013:     
1014:     /**
1015:      * Sets the item label font for ALL series and sends a 
1016:      * {@link RendererChangeEvent} to all registered listeners.  You can set 
1017:      * this to <code>null</code> if you prefer to set the font on a per series 
1018:      * basis.
1019:      * 
1020:      * @param font  the font (<code>null</code> permitted).
1021:      * 
1022:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1023:      *     It is sufficient to rely on {@link #setSeriesItemLabelFont(int, 
1024:      *     Font)} and {@link #setBaseItemLabelFont(Font)}.
1025:      */
1026:     public void setItemLabelFont(Font font);
1027:     
1028:     /**
1029:      * Returns the font for all the item labels in a series.
1030:      * 
1031:      * @param series  the series index (zero-based).
1032:      * 
1033:      * @return The font (possibly <code>null</code>).
1034:      */
1035:     public Font getSeriesItemLabelFont(int series);
1036: 
1037:     /**
1038:      * Sets the item label font for a series and sends a 
1039:      * {@link RendererChangeEvent} to all registered listeners.  
1040:      * 
1041:      * @param series  the series index (zero-based).
1042:      * @param font  the font (<code>null</code> permitted).
1043:      */
1044:     public void setSeriesItemLabelFont(int series, Font font);
1045: 
1046:     /**
1047:      * Returns the base item label font (this is used when no other font 
1048:      * setting is available).
1049:      * 
1050:      * @return The font (<code>never</code> null).
1051:      */
1052:     public Font getBaseItemLabelFont();
1053: 
1054:     /**
1055:      * Sets the base item label font and sends a {@link RendererChangeEvent} 
1056:      * to all registered listeners.  
1057:      * 
1058:      * @param font  the font (<code>null</code> not permitted).
1059:      */
1060:     public void setBaseItemLabelFont(Font font);
1061: 
1062:     //// ITEM LABEL PAINT  /////////////////////////////////////////////////////
1063: 
1064:     /**
1065:      * Returns the paint used to draw an item label.
1066:      * 
1067:      * @param row  the row index (zero based).
1068:      * @param column  the column index (zero based).
1069:      * 
1070:      * @return The paint (never <code>null</code>).
1071:      */
1072:     public Paint getItemLabelPaint(int row, int column);
1073:     
1074:     /**
1075:      * Returns the paint used for all item labels.  This may be 
1076:      * <code>null</code>, in which case the per series paint settings will 
1077:      * apply.
1078:      * 
1079:      * @return The paint (possibly <code>null</code>).
1080:      * 
1081:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1082:      *     It is sufficient to rely on {@link #getSeriesItemLabelPaint(int)} 
1083:      *     and {@link #getBaseItemLabelPaint()}.
1084:      */
1085:     public Paint getItemLabelPaint();
1086: 
1087:     /**
1088:      * Sets the item label paint for ALL series and sends a 
1089:      * {@link RendererChangeEvent} to all registered listeners.
1090:      * 
1091:      * @param paint  the paint (<code>null</code> permitted).
1092:      * 
1093:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1094:      *     It is sufficient to rely on {@link #setSeriesItemLabelPaint(int, 
1095:      *     Paint)} and {@link #setBaseItemLabelPaint(Paint)}.
1096:      */
1097:     public void setItemLabelPaint(Paint paint);
1098:     
1099:     /**
1100:      * Returns the paint used to draw the item labels for a series.
1101:      * 
1102:      * @param series  the series index (zero based).
1103:      * 
1104:      * @return The paint (possibly <code>null<code>).
1105:      */
1106:     public Paint getSeriesItemLabelPaint(int series);
1107: 
1108:     /**
1109:      * Sets the item label paint for a series and sends a 
1110:      * {@link RendererChangeEvent} to all registered listeners.
1111:      * 
1112:      * @param series  the series (zero based index).
1113:      * @param paint  the paint (<code>null</code> permitted).
1114:      */
1115:     public void setSeriesItemLabelPaint(int series, Paint paint);
1116:         
1117:     /**
1118:      * Returns the base item label paint.
1119:      * 
1120:      * @return The paint (never <code>null<code>).
1121:      */
1122:     public Paint getBaseItemLabelPaint();
1123: 
1124:     /**
1125:      * Sets the base item label paint and sends a {@link RendererChangeEvent} 
1126:      * to all registered listeners.
1127:      * 
1128:      * @param paint  the paint (<code>null</code> not permitted).
1129:      */
1130:     public void setBaseItemLabelPaint(Paint paint);
1131:     
1132:     // POSITIVE ITEM LABEL POSITION...
1133: 
1134:     /**
1135:      * Returns the item label position for positive values.
1136:      * 
1137:      * @param row  the row index (zero-based).
1138:      * @param column  the column index (zero-based).
1139:      * 
1140:      * @return The item label position (never <code>null</code>).
1141:      */
1142:     public ItemLabelPosition getPositiveItemLabelPosition(int row, int column);
1143: 
1144:     /**
1145:      * Returns the item label position for positive values in ALL series.
1146:      * 
1147:      * @return The item label position (possibly <code>null</code>).
1148:      * 
1149:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1150:      *     It is sufficient to rely on 
1151:      *     {@link #getSeriesPositiveItemLabelPosition(int)} 
1152:      *     and {@link #getBasePositiveItemLabelPosition()}.
1153:      */
1154:     public ItemLabelPosition getPositiveItemLabelPosition();
1155: 
1156:     /**
1157:      * Sets the item label position for positive values in ALL series, and 
1158:      * sends a {@link RendererChangeEvent} to all registered listeners.  You 
1159:      * need to set this to <code>null</code> to expose the settings for 
1160:      * individual series.
1161:      * 
1162:      * @param position  the position (<code>null</code> permitted).
1163:      * 
1164:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1165:      *     It is sufficient to rely on 
1166:      *     {@link #setSeriesPositiveItemLabelPosition(int, ItemLabelPosition)} 
1167:      *     and {@link #setBasePositiveItemLabelPosition(ItemLabelPosition)}.
1168:      */
1169:     public void setPositiveItemLabelPosition(ItemLabelPosition position);
1170:     
1171:     /**
1172:      * Sets the positive item label position for ALL series and (if requested)
1173:      * sends a {@link RendererChangeEvent} to all registered listeners.
1174:      * 
1175:      * @param position  the position (<code>null</code> permitted).
1176:      * @param notify  notify registered listeners?
1177:      * 
1178:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1179:      *     It is sufficient to rely on 
1180:      *     {@link #setSeriesPositiveItemLabelPosition(int, ItemLabelPosition, 
1181:      *     boolean)} and {@link #setBasePositiveItemLabelPosition(
1182:      *     ItemLabelPosition, boolean)}.
1183:      */
1184:     public void setPositiveItemLabelPosition(ItemLabelPosition position, 
1185:                                              boolean notify);
1186: 
1187:     /**
1188:      * Returns the item label position for all positive values in a series.
1189:      * 
1190:      * @param series  the series index (zero-based).
1191:      * 
1192:      * @return The item label position (never <code>null</code>).
1193:      */
1194:     public ItemLabelPosition getSeriesPositiveItemLabelPosition(int series);
1195:     
1196:     /**
1197:      * Sets the item label position for all positive values in a series and 
1198:      * sends a {@link RendererChangeEvent} to all registered listeners.
1199:      * 
1200:      * @param series  the series index (zero-based).
1201:      * @param position  the position (<code>null</code> permitted).
1202:      */
1203:     public void setSeriesPositiveItemLabelPosition(int series, 
1204:                                                    ItemLabelPosition position);
1205: 
1206:     /**
1207:      * Sets the item label position for all positive values in a series and (if
1208:      * requested) sends a {@link RendererChangeEvent} to all registered 
1209:      * listeners.
1210:      * 
1211:      * @param series  the series index (zero-based).
1212:      * @param position  the position (<code>null</code> permitted).
1213:      * @param notify  notify registered listeners?
1214:      */
1215:     public void setSeriesPositiveItemLabelPosition(int series, 
1216:                                                    ItemLabelPosition position, 
1217:                                                    boolean notify);
1218: 
1219:     /**
1220:      * Returns the base positive item label position.
1221:      * 
1222:      * @return The position (never <code>null</code>).
1223:      */
1224:     public ItemLabelPosition getBasePositiveItemLabelPosition();
1225: 
1226:     /**
1227:      * Sets the base positive item label position.
1228:      * 
1229:      * @param position  the position (<code>null</code> not permitted).
1230:      */
1231:     public void setBasePositiveItemLabelPosition(ItemLabelPosition position);
1232:     
1233:     /**
1234:      * Sets the base positive item label position and, if requested, sends a 
1235:      * {@link RendererChangeEvent} to all registered listeners.
1236:      * 
1237:      * @param position  the position (<code>null</code> not permitted).
1238:      * @param notify  notify registered listeners?
1239:      */
1240:     public void setBasePositiveItemLabelPosition(ItemLabelPosition position, 
1241:                                                  boolean notify);
1242: 
1243:     // NEGATIVE ITEM LABEL POSITION...
1244: 
1245:     /**
1246:      * Returns the item label position for negative values.  This method can be
1247:      * overridden to provide customisation of the item label position for 
1248:      * individual data items.
1249:      * 
1250:      * @param row  the row index (zero-based).
1251:      * @param column  the column (zero-based).
1252:      * 
1253:      * @return The item label position (never <code>null</code>).
1254:      */
1255:     public ItemLabelPosition getNegativeItemLabelPosition(int row, int column);
1256: 
1257:     /**
1258:      * Returns the item label position for negative values in ALL series.
1259:      * 
1260:      * @return The item label position (possibly <code>null</code>).
1261:      * 
1262:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1263:      *     It is sufficient to rely on 
1264:      *     {@link #getSeriesNegativeItemLabelPosition(int)} 
1265:      *     and {@link #getBaseNegativeItemLabelPosition()}.
1266:      */
1267:     public ItemLabelPosition getNegativeItemLabelPosition();
1268: 
1269:     /**
1270:      * Sets the item label position for negative values in ALL series, and 
1271:      * sends a {@link RendererChangeEvent} to all registered listeners.  You 
1272:      * need to set this to <code>null</code> to expose the settings for 
1273:      * individual series.
1274:      * 
1275:      * @param position  the position (<code>null</code> permitted).
1276:      * 
1277:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1278:      *     It is sufficient to rely on 
1279:      *     {@link #setSeriesNegativeItemLabelPosition(int, ItemLabelPosition)} 
1280:      *     and {@link #setBaseNegativeItemLabelPosition(ItemLabelPosition)}.
1281:      */
1282:     public void setNegativeItemLabelPosition(ItemLabelPosition position);
1283:     
1284:     /**
1285:      * Sets the item label position for negative values in ALL series and (if
1286:      * requested) sends a {@link RendererChangeEvent} to all registered 
1287:      * listeners.  
1288:      * 
1289:      * @param position  the position (<code>null</code> permitted).
1290:      * @param notify  notify registered listeners?
1291:      * 
1292:      * @deprecated This method should no longer be used (as of version 1.0.6). 
1293:      *     It is sufficient to rely on 
1294:      *     {@link #setSeriesNegativeItemLabelPosition(int, ItemLabelPosition, 
1295:      *     boolean)} and {@link #setBaseNegativeItemLabelPosition(
1296:      *     ItemLabelPosition, boolean)}.
1297:      */
1298:     public void setNegativeItemLabelPosition(ItemLabelPosition position, 
1299:                                              boolean notify);
1300: 
1301:     /**
1302:      * Returns the item label position for all negative values in a series.
1303:      * 
1304:      * @param series  the series index (zero-based).
1305:      * 
1306:      * @return The item label position (never <code>null</code>).
1307:      */
1308:     public ItemLabelPosition getSeriesNegativeItemLabelPosition(int series);
1309: 
1310:     /**
1311:      * Sets the item label position for negative values in a series and sends a 
1312:      * {@link RendererChangeEvent} to all registered listeners.
1313:      * 
1314:      * @param series  the series index (zero-based).
1315:      * @param position  the position (<code>null</code> permitted).
1316:      */
1317:     public void setSeriesNegativeItemLabelPosition(int series, 
1318:                                                    ItemLabelPosition position);
1319:     
1320:     /**
1321:      * Sets the item label position for negative values in a series and (if 
1322:      * requested) sends a {@link RendererChangeEvent} to all registered 
1323:      * listeners.
1324:      * 
1325:      * @param series  the series index (zero-based).
1326:      * @param position  the position (<code>null</code> permitted).
1327:      * @param notify  notify registered listeners?
1328:      */
1329:     public void setSeriesNegativeItemLabelPosition(int series, 
1330:                                                    ItemLabelPosition position, 
1331:                                                    boolean notify);
1332: 
1333:     /**
1334:      * Returns the base item label position for negative values.
1335:      * 
1336:      * @return The position (never <code>null</code>).
1337:      */
1338:     public ItemLabelPosition getBaseNegativeItemLabelPosition();
1339: 
1340:     /**
1341:      * Sets the base item label position for negative values and sends a 
1342:      * {@link RendererChangeEvent} to all registered listeners.
1343:      * 
1344:      * @param position  the position (<code>null</code> not permitted).
1345:      */
1346:     public void setBaseNegativeItemLabelPosition(ItemLabelPosition position);
1347:     
1348:     /**
1349:      * Sets the base negative item label position and, if requested, sends a 
1350:      * {@link RendererChangeEvent} to all registered listeners.
1351:      * 
1352:      * @param position  the position (<code>null</code> not permitted).
1353:      * @param notify  notify registered listeners?
1354:      */
1355:     public void setBaseNegativeItemLabelPosition(ItemLabelPosition position, 
1356:                                                  boolean notify);
1357: 
1358:     // CREATE ENTITIES
1359:     // FIXME:  these methods should be defined
1360:     
1361: //    public boolean getItemCreateEntity(int series, int item);
1362: //    
1363: //    public Boolean getSeriesCreateEntities(int series);
1364: //    
1365: //    public void setSeriesCreateEntities(int series, Boolean create);
1366: //    
1367: //    public void setSeriesCreateEntities(int series, Boolean create, 
1368: //            boolean notify);
1369: //    
1370: //    public boolean getBaseCreateEntities();
1371: //    
1372: //    public void setBaseCreateEntities(boolean create);
1373: //    
1374: //    public void setBaseCreateEntities(boolean create, boolean notify);
1375:     
1376:     /**
1377:      * Adds an annotation and sends a {@link RendererChangeEvent} to all 
1378:      * registered listeners.  The annotation is added to the foreground
1379:      * layer.
1380:      * 
1381:      * @param annotation  the annotation (<code>null</code> not permitted).
1382:      */
1383:     public void addAnnotation(XYAnnotation annotation);
1384: 
1385:     /**
1386:      * Adds an annotation to the specified layer.
1387:      * 
1388:      * @param annotation  the annotation (<code>null</code> not permitted).
1389:      * @param layer  the layer (<code>null</code> not permitted).
1390:      */
1391:     public void addAnnotation(XYAnnotation annotation, Layer layer);
1392: 
1393:     /**
1394:      * Removes the specified annotation and sends a {@link RendererChangeEvent}
1395:      * to all registered listeners.
1396:      * 
1397:      * @param annotation  the annotation to remove (<code>null</code> not 
1398:      *                    permitted).
1399:      * 
1400:      * @return A boolean to indicate whether or not the annotation was 
1401:      *         successfully removed.
1402:      */
1403:     public boolean removeAnnotation(XYAnnotation annotation);
1404:     
1405:     /**
1406:      * Removes all annotations and sends a {@link RendererChangeEvent}
1407:      * to all registered listeners.
1408:      */
1409:     public void removeAnnotations();
1410:     
1411:     /**
1412:      * Draws all the annotations for the specified layer.
1413:      * 
1414:      * @param g2  the graphics device.
1415:      * @param dataArea  the data area.
1416:      * @param domainAxis  the domain axis.
1417:      * @param rangeAxis  the range axis.
1418:      * @param layer  the layer.
1419:      * @param info  the plot rendering info.
1420:      */
1421:     public void drawAnnotations(Graphics2D g2, 
1422:                                 Rectangle2D dataArea, 
1423:                                 ValueAxis domainAxis, 
1424:                                 ValueAxis rangeAxis, 
1425:                                 Layer layer, 
1426:                                 PlotRenderingInfo info);
1427:     
1428:     /**
1429:      * Called for each item to be plotted.
1430:      * <p>
1431:      * The {@link XYPlot} can make multiple passes through the dataset, 
1432:      * depending on the value returned by the renderer's initialise() method.
1433:      *
1434:      * @param g2  the graphics device.
1435:      * @param state  the renderer state.
1436:      * @param dataArea  the area within which the data is being rendered.
1437:      * @param info  collects drawing info.
1438:      * @param plot  the plot (can be used to obtain standard color 
1439:      *              information etc).
1440:      * @param domainAxis  the domain axis.
1441:      * @param rangeAxis  the range axis.
1442:      * @param dataset  the dataset.
1443:      * @param series  the series index (zero-based).
1444:      * @param item  the item index (zero-based).
1445:      * @param crosshairState  crosshair information for the plot 
1446:      *                        (<code>null</code> permitted).
1447:      * @param pass  the pass index.
1448:      */
1449:     public void drawItem(Graphics2D g2,
1450:                          XYItemRendererState state,
1451:                          Rectangle2D dataArea,
1452:                          PlotRenderingInfo info,
1453:                          XYPlot plot,
1454:                          ValueAxis domainAxis,
1455:                          ValueAxis rangeAxis,
1456:                          XYDataset dataset,
1457:                          int series,
1458:                          int item,
1459:                          CrosshairState crosshairState,
1460:                          int pass);
1461: 
1462:     /**
1463:      * Returns a legend item for a series from a dataset.
1464:      *
1465:      * @param datasetIndex  the dataset index.
1466:      * @param series  the series (zero-based index).
1467:      *
1468:      * @return The legend item (possibly <code>null</code>).
1469:      */
1470:     public LegendItem getLegendItem(int datasetIndex, int series);
1471: 
1472:     /**
1473:      * Returns the legend item label generator.
1474:      * 
1475:      * @return The legend item label generator (never <code>null</code>).
1476:      */
1477:     public XYSeriesLabelGenerator getLegendItemLabelGenerator();
1478:     
1479:     /**
1480:      * Sets the legend item label generator.
1481:      * 
1482:      * @param generator  the generator (<code>null</code> not permitted).
1483:      */
1484:     public void setLegendItemLabelGenerator(XYSeriesLabelGenerator generator);
1485: 
1486:         /**
1487:      * Fills a band between two values on the axis.  This can be used to color 
1488:      * bands between the grid lines.
1489:      *
1490:      * @param g2  the graphics device.
1491:      * @param plot  the plot.
1492:      * @param axis  the domain axis.
1493:      * @param dataArea  the data area.
1494:      * @param start  the start value.
1495:      * @param end  the end value.
1496:      */
1497:     public void fillDomainGridBand(Graphics2D g2,
1498:                                    XYPlot plot,
1499:                                    ValueAxis axis,
1500:                                    Rectangle2D dataArea,
1501:                                    double start, double end);
1502: 
1503:     /**
1504:      * Fills a band between two values on the range axis.  This can be used to 
1505:      * color bands between the grid lines.
1506:      *
1507:      * @param g2  the graphics device.
1508:      * @param plot  the plot.
1509:      * @param axis  the range axis.
1510:      * @param dataArea  the data area.
1511:      * @param start  the start value.
1512:      * @param end  the end value.
1513:      */
1514:     public void fillRangeGridBand(Graphics2D g2,
1515:                                   XYPlot plot,
1516:                                   ValueAxis axis,
1517:                                   Rectangle2D dataArea,
1518:                                   double start, double end);
1519: 
1520:     /**
1521:      * Draws a grid line against the domain axis.
1522:      *
1523:      * @param g2  the graphics device.
1524:      * @param plot  the plot.
1525:      * @param axis  the value axis.
1526:      * @param dataArea  the area for plotting data (not yet adjusted for any 
1527:      *                  3D effect).
1528:      * @param value  the value.
1529:      */
1530:     public void drawDomainGridLine(Graphics2D g2,
1531:                                    XYPlot plot,
1532:                                    ValueAxis axis,
1533:                                    Rectangle2D dataArea,
1534:                                    double value);
1535: 
1536:     /**
1537:      * Draws a grid line against the range axis.
1538:      *
1539:      * @param g2  the graphics device.
1540:      * @param plot  the plot.
1541:      * @param axis  the value axis.
1542:      * @param dataArea  the area for plotting data (not yet adjusted for any 
1543:      *                  3D effect).
1544:      * @param value  the value.
1545:      * @param paint  the paint (<code>null</code> not permitted).
1546:      * @param stroke  the stroke (<code>null</code> not permitted).
1547:      */
1548:     public void drawRangeLine(Graphics2D g2,
1549:                               XYPlot plot,
1550:                               ValueAxis axis,
1551:                               Rectangle2D dataArea,
1552:                               double value,
1553:                               Paint paint,
1554:                               Stroke stroke);
1555: 
1556:     /**
1557:      * Draws the specified <code>marker</code> against the domain axis.
1558:      *
1559:      * @param g2  the graphics device.
1560:      * @param plot  the plot.
1561:      * @param axis  the value axis.
1562:      * @param marker  the marker.
1563:      * @param dataArea  the axis data area.
1564:      */
1565:     public void drawDomainMarker(Graphics2D g2,
1566:                                  XYPlot plot,
1567:                                  ValueAxis axis,
1568:                                  Marker marker,
1569:                                  Rectangle2D dataArea);
1570: 
1571:     /**
1572:      * Draws a horizontal line across the chart to represent a 'range marker'.
1573:      *
1574:      * @param g2  the graphics device.
1575:      * @param plot  the plot.
1576:      * @param axis  the value axis.
1577:      * @param marker  the marker line.
1578:      * @param dataArea  the axis data area.
1579:      */
1580:     public void drawRangeMarker(Graphics2D g2,
1581:                                 XYPlot plot,
1582:                                 ValueAxis axis,
1583:                                 Marker marker,
1584:                                 Rectangle2D dataArea);
1585: 
1586:     /**
1587:      * Returns the plot that this renderer has been assigned to.
1588:      *
1589:      * @return The plot.
1590:      */
1591:     public XYPlot getPlot();
1592: 
1593:     /**
1594:      * Sets the plot that this renderer is assigned to.  This method will be 
1595:      * called by the plot class...you do not need to call it yourself.
1596:      *
1597:      * @param plot  the plot.
1598:      */
1599:     public void setPlot(XYPlot plot);
1600:     
1601:     /**
1602:      * Returns the lower and upper bounds (range) of the x-values in the 
1603:      * specified dataset.
1604:      * 
1605:      * @param dataset  the dataset (<code>null</code> permitted).
1606:      * 
1607:      * @return The range.
1608:      */
1609:     public Range findDomainBounds(XYDataset dataset);
1610:     
1611:     /**
1612:      * Returns the lower and upper bounds (range) of the y-values in the
1613:      * specified dataset.  The implementation of this method will take 
1614:      * into account the presentation used by the renderers (for example,
1615:      * a renderer that "stacks" values will return a bigger range than
1616:      * a renderer that doesn't.
1617:      * 
1618:      * @param dataset  the dataset (<code>null</code> permitted).
1619:      * 
1620:      * @return The range (or <code>null</code> if the dataset is 
1621:      *         <code>null</code> or empty).
1622:      */
1623:     public Range findRangeBounds(XYDataset dataset);
1624:     
1625:     /**
1626:      * Add a renderer change listener.
1627:      * 
1628:      * @param listener  the listener.
1629:      */
1630:     public void addChangeListener(RendererChangeListener listener);
1631: 
1632:     /**
1633:      * Removes a change listener.
1634:      * 
1635:      * @param listener  the listener.
1636:      */
1637:     public void removeChangeListener(RendererChangeListener listener);
1638:     
1639: }