0
# Labels, Tooltips, and Legends
1

2
Label generation, tooltip creation, and legend management for enhancing chart interactivity and readability. These components provide essential information display and user interaction capabilities that make charts more informative and user-friendly.
3

4
## Capabilities
5

6
### Label Generators
7

8
Interfaces and implementations for generating text labels for chart data items.
9

10
```java { .api }
11
/**
12
 * Interface for generating labels for category items
13
 */
14
public interface CategoryItemLabelGenerator {
15
    /**
16
     * Generates a label for a specific data item
17
     * @param dataset the dataset
18
     * @param row the row index (zero-based)
19
     * @param column the column index (zero-based)
20
     * @return the item label (possibly null)
21
     */
22
    public String generateLabel(CategoryDataset dataset, int row, int column);
23
    
24
    /**
25
     * Generates a label for a data row (series)
26
     * @param dataset the dataset
27
     * @param row the row index (zero-based)
28
     * @return the row label (possibly null)
29
     */
30
    public String generateRowLabel(CategoryDataset dataset, int row);
31
    
32
    /**
33
     * Generates a label for a data column (category)
34
     * @param dataset the dataset
35
     * @param column the column index (zero-based)
36
     * @return the column label (possibly null)
37
     */
38
    public String generateColumnLabel(CategoryDataset dataset, int column);
39
}
40

41
/**
42
 * Standard implementation of CategoryItemLabelGenerator
43
 */
44
public class StandardCategoryItemLabelGenerator implements CategoryItemLabelGenerator, Cloneable, PublicCloneable, Serializable {
45
    // Default format string showing the value
46
    public static final String DEFAULT_LABEL_FORMAT_STRING = "{2}";
47
    
48
    /**
49
     * Creates a generator with default format
50
     */
51
    public StandardCategoryItemLabelGenerator();
52
    
53
    /**
54
     * Creates a generator with custom format
55
     * @param labelFormat the label format string (uses MessageFormat)
56
     * @param formatter the number formatter
57
     */
58
    public StandardCategoryItemLabelGenerator(String labelFormat, NumberFormat formatter);
59
    
60
    /**
61
     * Creates a generator with separate number and date formatters
62
     * @param labelFormat the label format string
63
     * @param formatter the number formatter
64
     * @param percentFormatter the percentage formatter
65
     */
66
    public StandardCategoryItemLabelGenerator(String labelFormat, NumberFormat formatter, NumberFormat percentFormatter);
67
    
68
    public String getLabelFormat();
69
    public void setLabelFormat(String format);
70
    public NumberFormat getNumberFormat();
71
    public void setNumberFormat(NumberFormat formatter);
72
    public NumberFormat getPercentFormat();
73
    public void setPercentFormat(NumberFormat formatter);
74
    
75
    public String generateLabel(CategoryDataset dataset, int row, int column);
76
    public String generateRowLabel(CategoryDataset dataset, int row);
77
    public String generateColumnLabel(CategoryDataset dataset, int column);
78
}
79

80
/**
81
 * Interface for generating labels for XY items
82
 */
83
public interface XYItemLabelGenerator {
84
    /**
85
     * Generates a label for a data item
86
     * @param dataset the dataset
87
     * @param series the series index (zero-based)
88
     * @param item the item index (zero-based)
89
     * @return the item label (possibly null)
90
     */
91
    public String generateLabel(XYDataset dataset, int series, int item);
92
}
93

94
/**
95
 * Standard implementation of XYItemLabelGenerator
96
 */
97
public class StandardXYItemLabelGenerator implements XYItemLabelGenerator, Cloneable, PublicCloneable, Serializable {
98
    // Default format showing X and Y values
99
    public static final String DEFAULT_ITEM_LABEL_FORMAT = "{0}: ({1}, {2})";
100
    
101
    /**
102
     * Creates a generator with default format
103
     */
104
    public StandardXYItemLabelGenerator();
105
    
106
    /**
107
     * Creates a generator with custom format
108
     * @param formatString the format string
109
     * @param xFormat the X value formatter
110
     * @param yFormat the Y value formatter
111
     */
112
    public StandardXYItemLabelGenerator(String formatString, NumberFormat xFormat, NumberFormat yFormat);
113
    
114
    /**
115
     * Creates a generator with date formatting for X values
116
     * @param formatString the format string
117
     * @param xFormat the X value date formatter
118
     * @param yFormat the Y value number formatter
119
     */
120
    public StandardXYItemLabelGenerator(String formatString, DateFormat xFormat, NumberFormat yFormat);
121
    
122
    public String getFormatString();
123
    public void setFormatString(String format);
124
    public NumberFormat getXFormat();
125
    public void setXFormat(NumberFormat format);
126
    public NumberFormat getYFormat();
127
    public void setYFormat(NumberFormat format);
128
    public DateFormat getXDateFormat();
129
    public void setXDateFormat(DateFormat format);
130
    
131
    public String generateLabel(XYDataset dataset, int series, int item);
132
}
133

134
/**
135
 * Interface for generating labels for pie sections
136
 */
137
public interface PieSectionLabelGenerator {
138
    /**
139
     * Generates a label for a pie section
140
     * @param dataset the dataset
141
     * @param key the section key
142
     * @return the section label (possibly null)
143
     */
144
    public String generateSectionLabel(PieDataset dataset, Comparable key);
145
    
146
    /**
147
     * Generates an attributed string for a pie section (for advanced formatting)
148
     * @param dataset the dataset
149
     * @param key the section key
150
     * @return the attributed section label (possibly null)
151
     */
152
    public AttributedString generateAttributedSectionLabel(PieDataset dataset, Comparable key);
153
}
154

155
/**
156
 * Standard implementation of PieSectionLabelGenerator
157
 */
158
public class StandardPieSectionLabelGenerator implements PieSectionLabelGenerator, Cloneable, PublicCloneable, Serializable {
159
    // Default format showing key and percentage
160
    public static final String DEFAULT_SECTION_LABEL_FORMAT = "{0} = {1} ({2})";
161
    
162
    /**
163
     * Creates a generator with default format
164
     */
165
    public StandardPieSectionLabelGenerator();
166
    
167
    /**
168
     * Creates a generator with custom format
169
     * @param labelFormat the label format string
170
     * @param numberFormat the number formatter
171
     * @param percentFormat the percentage formatter
172
     */
173
    public StandardPieSectionLabelGenerator(String labelFormat, NumberFormat numberFormat, NumberFormat percentFormat);
174
    
175
    /**
176
     * Creates a generator with locale-specific formatting
177
     * @param locale the locale for default formatting
178
     */
179
    public StandardPieSectionLabelGenerator(Locale locale);
180
    
181
    public String getLabelFormat();
182
    public void setLabelFormat(String format);
183
    public NumberFormat getNumberFormat();
184
    public void setNumberFormat(NumberFormat formatter);
185
    public NumberFormat getPercentFormat();
186
    public void setPercentFormat(NumberFormat formatter);
187
    
188
    public String generateSectionLabel(PieDataset dataset, Comparable key);
189
    public AttributedString generateAttributedSectionLabel(PieDataset dataset, Comparable key);
190
}
191
```
192

193
**Usage Example:**
194

195
```java
196
import org.jfree.chart.labels.*;
197
import java.text.DecimalFormat;
198

199
// Category item label generator
200
StandardCategoryItemLabelGenerator categoryGenerator = 
201
    new StandardCategoryItemLabelGenerator(
202
        "{1}: {2}",  // Format: Category: Value
203
        new DecimalFormat("#,##0.00")  // Number format
204
    );
205

206
BarRenderer renderer = (BarRenderer) plot.getRenderer();
207
renderer.setDefaultItemLabelGenerator(categoryGenerator);
208
renderer.setDefaultItemLabelsVisible(true);
209

210
// XY item label generator  
211
StandardXYItemLabelGenerator xyGenerator = 
212
    new StandardXYItemLabelGenerator(
213
        "({1}, {2})",  // Format: (X, Y)
214
        new DecimalFormat("#.##"),   // X format
215
        new DecimalFormat("#.##")    // Y format
216
    );
217

218
XYLineAndShapeRenderer xyRenderer = (XYLineAndShapeRenderer) xyPlot.getRenderer();
219
xyRenderer.setDefaultItemLabelGenerator(xyGenerator);
220
xyRenderer.setDefaultItemLabelsVisible(true);
221

222
// Pie section label generator
223
StandardPieSectionLabelGenerator pieGenerator = 
224
    new StandardPieSectionLabelGenerator(
225
        "{0}: {2}",  // Format: Key: Percentage
226
        new DecimalFormat("#,##0"),      // Number format
227
        new DecimalFormat("#.#%")        // Percentage format
228
    );
229

230
PiePlot piePlot = (PiePlot) chart.getPlot();
231
piePlot.setLabelGenerator(pieGenerator);
232
```
233

234
### Tooltip Generators
235

236
Interfaces and implementations for generating interactive tooltips.
237

238
```java { .api }
239
/**
240
 * Interface for generating tooltips for category items
241
 */
242
public interface CategoryToolTipGenerator {
243
    /**
244
     * Generates a tooltip for a data item
245
     * @param dataset the dataset
246
     * @param row the row index (zero-based)
247
     * @param column the column index (zero-based)
248
     * @return the tooltip text (possibly null)
249
     */
250
    public String generateToolTip(CategoryDataset dataset, int row, int column);
251
}
252

253
/**
254
 * Standard implementation of CategoryToolTipGenerator
255
 */
256
public class StandardCategoryToolTipGenerator implements CategoryToolTipGenerator, Cloneable, PublicCloneable, Serializable {
257
    // Default tooltip format
258
    public static final String DEFAULT_TOOL_TIP_FORMAT_STRING = "({0}, {1}) = {2}";
259
    
260
    /**
261
     * Creates a generator with default format
262
     */
263
    public StandardCategoryToolTipGenerator();
264
    
265
    /**
266
     * Creates a generator with custom format
267
     * @param labelFormat the tooltip format string
268
     * @param formatter the number formatter
269
     */
270
    public StandardCategoryToolTipGenerator(String labelFormat, NumberFormat formatter);
271
    
272
    public String getLabelFormat();
273
    public void setLabelFormat(String format);
274
    public NumberFormat getNumberFormat();
275
    public void setNumberFormat(NumberFormat formatter);
276
    
277
    public String generateToolTip(CategoryDataset dataset, int row, int column);
278
}
279

280
/**
281
 * Interface for generating tooltips for XY items
282
 */
283
public interface XYToolTipGenerator {
284
    /**
285
     * Generates a tooltip for a data item
286
     * @param dataset the dataset
287
     * @param series the series index (zero-based)
288
     * @param item the item index (zero-based)
289
     * @return the tooltip text (possibly null)
290
     */
291
    public String generateToolTip(XYDataset dataset, int series, int item);
292
}
293

294
/**
295
 * Standard implementation of XYToolTipGenerator
296
 */
297
public class StandardXYToolTipGenerator implements XYToolTipGenerator, Cloneable, PublicCloneable, Serializable {
298
    // Default tooltip format
299
    public static final String DEFAULT_TOOL_TIP_FORMAT = "{0}: ({1}, {2})";
300
    
301
    /**
302
     * Creates a generator with default format
303
     */
304
    public StandardXYToolTipGenerator();
305
    
306
    /**
307
     * Creates a generator with custom format
308
     * @param formatString the format string
309
     * @param xFormat the X value formatter
310
     * @param yFormat the Y value formatter
311
     */
312
    public StandardXYToolTipGenerator(String formatString, NumberFormat xFormat, NumberFormat yFormat);
313
    
314
    /**
315
     * Creates a generator with date formatting for X values
316
     * @param formatString the format string
317
     * @param xFormat the X value date formatter
318
     * @param yFormat the Y value number formatter
319
     */
320
    public StandardXYToolTipGenerator(String formatString, DateFormat xFormat, NumberFormat yFormat);
321
    
322
    public String generateToolTip(XYDataset dataset, int series, int item);
323
}
324

325
/**
326
 * Interface for generating tooltips for pie sections
327
 */
328
public interface PieToolTipGenerator {
329
    /**
330
     * Generates a tooltip for a pie section
331
     * @param dataset the dataset
332
     * @param key the section key
333
     * @return the tooltip text (possibly null)
334
     */
335
    public String generateToolTip(PieDataset dataset, Comparable key);
336
}
337

338
/**
339
 * Standard implementation of PieToolTipGenerator
340
 */
341
public class StandardPieToolTipGenerator implements PieToolTipGenerator, Cloneable, PublicCloneable, Serializable {
342
    // Default tooltip format
343
    public static final String DEFAULT_TOOLTIP_FORMAT = "{0} = {1} ({2})";
344
    
345
    /**
346
     * Creates a generator with default format
347
     */
348
    public StandardPieToolTipGenerator();
349
    
350
    /**
351
     * Creates a generator with custom format
352
     * @param labelFormat the tooltip format string
353
     * @param numberFormat the number formatter
354
     * @param percentFormat the percentage formatter
355
     */
356
    public StandardPieToolTipGenerator(String labelFormat, NumberFormat numberFormat, NumberFormat percentFormat);
357
    
358
    /**
359
     * Creates a generator with locale-specific formatting
360
     * @param locale the locale for default formatting
361
     */
362
    public StandardPieToolTipGenerator(Locale locale);
363
    
364
    public String generateToolTip(PieDataset dataset, Comparable key);
365
}
366

367
/**
368
 * Specialized tooltip generators for specific chart types
369
 */
370

371
// Box and whisker tooltip generator
372
public class BoxAndWhiskerToolTipGenerator implements CategoryToolTipGenerator {
373
    public BoxAndWhiskerToolTipGenerator();
374
    public String generateToolTip(CategoryDataset dataset, int row, int column);
375
}
376

377
// XY box and whisker tooltip generator
378
public class BoxAndWhiskerXYToolTipGenerator implements XYToolTipGenerator {
379
    public BoxAndWhiskerXYToolTipGenerator();
380
    public String generateToolTip(XYDataset dataset, int series, int item);
381
}
382

383
// High-low-open-close tooltip generator
384
public class HighLowItemLabelGenerator implements XYItemLabelGenerator, XYToolTipGenerator {
385
    public static final String DEFAULT_TOOL_TIP_FORMAT = "Date: {1}; High: {2}; Low: {3}; Open: {4}; Close: {5}; Volume: {6}";
386
    public static final String DEFAULT_LABEL_FORMAT = "{5}";
387
    
388
    public HighLowItemLabelGenerator();
389
    public HighLowItemLabelGenerator(String toolTipFormat, DateFormat dateFormatter);
390
    
391
    public String generateLabel(XYDataset dataset, int series, int item);
392
    public String generateToolTip(XYDataset dataset, int series, int item);
393
}
394

395
// Bubble chart tooltip generator
396
public class BubbleXYItemLabelGenerator extends StandardXYItemLabelGenerator {
397
    public static final String DEFAULT_FORMAT_STRING = "({1}, {2}, {3})";
398
    
399
    public BubbleXYItemLabelGenerator();
400
    public BubbleXYItemLabelGenerator(String formatString, NumberFormat xFormat, NumberFormat yFormat, NumberFormat zFormat);
401
}
402

403
// 3D XYZ tooltip generator  
404
public class StandardXYZToolTipGenerator extends StandardXYToolTipGenerator {
405
    public static final String DEFAULT_TOOL_TIP_FORMAT = "{0}: ({1}, {2}, {3})";
406
    
407
    public StandardXYZToolTipGenerator();
408
    public StandardXYZToolTipGenerator(String formatString, NumberFormat xFormat, NumberFormat yFormat, NumberFormat zFormat);
409
}
410
```
411

412
**Usage Example:**
413

414
```java
415
import org.jfree.chart.labels.*;
416
import java.text.SimpleDateFormat;
417

418
// Category tooltip generator
419
StandardCategoryToolTipGenerator categoryTooltip = 
420
    new StandardCategoryToolTipGenerator(
421
        "Series: {0}, Category: {1}, Value: {2}",
422
        new DecimalFormat("#,##0.00")
423
    );
424

425
renderer.setDefaultToolTipGenerator(categoryTooltip);
426

427
// Time series tooltip generator
428
StandardXYToolTipGenerator timeTooltip = 
429
    new StandardXYToolTipGenerator(
430
        "{0}: {1} = {2}",
431
        new SimpleDateFormat("MMM dd, yyyy"),  // Date format for X
432
        new DecimalFormat("#,##0.00")          // Number format for Y
433
    );
434

435
xyRenderer.setDefaultToolTipGenerator(timeTooltip);
436

437
// Financial data tooltip generator
438
HighLowItemLabelGenerator financialTooltip = new HighLowItemLabelGenerator(
439
    "Date: {1}; Open: {4}; High: {2}; Low: {3}; Close: {5}",
440
    new SimpleDateFormat("yyyy-MM-dd")
441
);
442

443
candlestickRenderer.setDefaultToolTipGenerator(financialTooltip);
444

445
// Bubble chart tooltip generator
446
BubbleXYItemLabelGenerator bubbleTooltip = new BubbleXYItemLabelGenerator(
447
    "X: {1}, Y: {2}, Size: {3}",
448
    new DecimalFormat("#.##"),   // X format
449
    new DecimalFormat("#.##"),   // Y format  
450
    new DecimalFormat("#.##")    // Z format
451
);
452

453
bubbleRenderer.setDefaultToolTipGenerator(bubbleTooltip);
454
```
455

456
### Item Label Positioning
457

458
Classes for controlling the position and orientation of item labels.
459

460
```java { .api }
461
/**
462
 * Defines the position of an item label relative to a data item
463
 */
464
public class ItemLabelPosition implements Serializable {
465
    /**
466
     * Creates an item label position
467
     * @param itemLabelAnchor the item label anchor point
468
     * @param textAnchor the text anchor point
469
     * @param rotationAnchor the rotation anchor point
470
     * @param angle the rotation angle (in radians)
471
     */
472
    public ItemLabelPosition(ItemLabelAnchor itemLabelAnchor, TextAnchor textAnchor, TextAnchor rotationAnchor, double angle);
473
    
474
    public ItemLabelAnchor getItemLabelAnchor();
475
    public TextAnchor getTextAnchor();
476
    public TextAnchor getRotationAnchor();
477
    public double getAngle();
478
}
479

480
/**
481
 * Anchor points for item labels relative to data items
482
 */
483
public final class ItemLabelAnchor implements Serializable {
484
    // Inside positions (within the data item area)
485
    public static final ItemLabelAnchor CENTER = new ItemLabelAnchor("CENTER");
486
    public static final ItemLabelAnchor INSIDE1 = new ItemLabelAnchor("INSIDE1");
487
    public static final ItemLabelAnchor INSIDE2 = new ItemLabelAnchor("INSIDE2");
488
    public static final ItemLabelAnchor INSIDE3 = new ItemLabelAnchor("INSIDE3");
489
    public static final ItemLabelAnchor INSIDE4 = new ItemLabelAnchor("INSIDE4");
490
    public static final ItemLabelAnchor INSIDE5 = new ItemLabelAnchor("INSIDE5");
491
    public static final ItemLabelAnchor INSIDE6 = new ItemLabelAnchor("INSIDE6");
492
    public static final ItemLabelAnchor INSIDE7 = new ItemLabelAnchor("INSIDE7");
493
    public static final ItemLabelAnchor INSIDE8 = new ItemLabelAnchor("INSIDE8");
494
    public static final ItemLabelAnchor INSIDE9 = new ItemLabelAnchor("INSIDE9");
495
    public static final ItemLabelAnchor INSIDE10 = new ItemLabelAnchor("INSIDE10");
496
    public static final ItemLabelAnchor INSIDE11 = new ItemLabelAnchor("INSIDE11");
497
    public static final ItemLabelAnchor INSIDE12 = new ItemLabelAnchor("INSIDE12");
498
    
499
    // Outside positions (outside the data item area)
500
    public static final ItemLabelAnchor OUTSIDE1 = new ItemLabelAnchor("OUTSIDE1");
501
    public static final ItemLabelAnchor OUTSIDE2 = new ItemLabelAnchor("OUTSIDE2");
502
    public static final ItemLabelAnchor OUTSIDE3 = new ItemLabelAnchor("OUTSIDE3");
503
    public static final ItemLabelAnchor OUTSIDE4 = new ItemLabelAnchor("OUTSIDE4");
504
    public static final ItemLabelAnchor OUTSIDE5 = new ItemLabelAnchor("OUTSIDE5");
505
    public static final ItemLabelAnchor OUTSIDE6 = new ItemLabelAnchor("OUTSIDE6");
506
    public static final ItemLabelAnchor OUTSIDE7 = new ItemLabelAnchor("OUTSIDE7");
507
    public static final ItemLabelAnchor OUTSIDE8 = new ItemLabelAnchor("OUTSIDE8");
508
    public static final ItemLabelAnchor OUTSIDE9 = new ItemLabelAnchor("OUTSIDE9");
509
    public static final ItemLabelAnchor OUTSIDE10 = new ItemLabelAnchor("OUTSIDE10");
510
    public static final ItemLabelAnchor OUTSIDE11 = new ItemLabelAnchor("OUTSIDE11");
511
    public static final ItemLabelAnchor OUTSIDE12 = new ItemLabelAnchor("OUTSIDE12");
512
    
513
    public String toString();
514
}
515

516
/**
517
 * Text anchor points for label text positioning
518
 */
519
public final class TextAnchor implements Serializable {
520
    public static final TextAnchor TOP_LEFT = new TextAnchor("TOP_LEFT");
521
    public static final TextAnchor TOP_CENTER = new TextAnchor("TOP_CENTER");
522
    public static final TextAnchor TOP_RIGHT = new TextAnchor("TOP_RIGHT");
523
    public static final TextAnchor HALF_ASCENT_LEFT = new TextAnchor("HALF_ASCENT_LEFT");
524
    public static final TextAnchor HALF_ASCENT_CENTER = new TextAnchor("HALF_ASCENT_CENTER");
525
    public static final TextAnchor HALF_ASCENT_RIGHT = new TextAnchor("HALF_ASCENT_RIGHT");
526
    public static final TextAnchor CENTER_LEFT = new TextAnchor("CENTER_LEFT");
527
    public static final TextAnchor CENTER = new TextAnchor("CENTER");
528
    public static final TextAnchor CENTER_RIGHT = new TextAnchor("CENTER_RIGHT");
529
    public static final TextAnchor BASELINE_LEFT = new TextAnchor("BASELINE_LEFT");
530
    public static final TextAnchor BASELINE_CENTER = new TextAnchor("BASELINE_CENTER");
531
    public static final TextAnchor BASELINE_RIGHT = new TextAnchor("BASELINE_RIGHT");
532
    public static final TextAnchor BOTTOM_LEFT = new TextAnchor("BOTTOM_LEFT");
533
    public static final TextAnchor BOTTOM_CENTER = new TextAnchor("BOTTOM_CENTER");
534
    public static final TextAnchor BOTTOM_RIGHT = new TextAnchor("BOTTOM_RIGHT");
535
    
536
    public String toString();
537
}
538

539
/**
540
 * Category label positioning for category axes
541
 */
542
public class CategoryLabelPosition implements Serializable {
543
    /**
544
     * Creates a category label position
545
     * @param categoryAnchor the category anchor
546
     * @param labelAnchor the label anchor
547
     * @param rotationAnchor the rotation anchor
548
     * @param angle the rotation angle
549
     */
550
    public CategoryLabelPosition(RectangleAnchor categoryAnchor, TextAnchor labelAnchor, TextAnchor rotationAnchor, double angle);
551
    
552
    public RectangleAnchor getCategoryAnchor();
553
    public TextAnchor getLabelAnchor();  
554
    public TextAnchor getRotationAnchor();
555
    public double getAngle();
556
}
557

558
/**
559
 * A set of category label positions for different orientations
560
 */
561
public class CategoryLabelPositions implements Serializable {
562
    // Standard positions
563
    public static final CategoryLabelPositions STANDARD = new CategoryLabelPositions(
564
        new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.BOTTOM_CENTER, TextAnchor.BOTTOM_CENTER, 0.0),
565
        new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.TOP_CENTER, TextAnchor.TOP_CENTER, 0.0),
566
        new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.CENTER_RIGHT, TextAnchor.CENTER_RIGHT, 0.0),
567
        new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_LEFT, 0.0)
568
    );
569
    
570
    // Up 45 degree rotation
571
    public static final CategoryLabelPositions UP_45 = new CategoryLabelPositions(
572
        new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.BOTTOM_LEFT, TextAnchor.BOTTOM_LEFT, -Math.PI / 4.0),
573
        new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.TOP_RIGHT, TextAnchor.TOP_RIGHT, -Math.PI / 4.0),
574
        new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.BOTTOM_RIGHT, TextAnchor.BOTTOM_RIGHT, -Math.PI / 4.0),
575
        new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.TOP_LEFT, TextAnchor.TOP_LEFT, -Math.PI / 4.0)
576
    );
577
    
578
    // Down 45 degree rotation
579
    public static final CategoryLabelPositions DOWN_45 = new CategoryLabelPositions(
580
        new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.BOTTOM_RIGHT, TextAnchor.BOTTOM_RIGHT, Math.PI / 4.0),
581
        new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.TOP_LEFT, TextAnchor.TOP_LEFT, Math.PI / 4.0),
582
        new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.TOP_RIGHT, TextAnchor.TOP_RIGHT, Math.PI / 4.0),
583
        new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.BOTTOM_LEFT, TextAnchor.BOTTOM_LEFT, Math.PI / 4.0)
584
    );
585
    
586
    // Up 90 degree rotation (vertical)
587
    public static final CategoryLabelPositions UP_90 = new CategoryLabelPositions(
588
        new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_LEFT, -Math.PI / 2.0),
589
        new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.CENTER_RIGHT, TextAnchor.CENTER_RIGHT, -Math.PI / 2.0),
590
        new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.BOTTOM_CENTER, TextAnchor.BOTTOM_CENTER, -Math.PI / 2.0),
591
        new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.TOP_CENTER, TextAnchor.TOP_CENTER, -Math.PI / 2.0)
592
    );
593
    
594
    // Down 90 degree rotation
595
    public static final CategoryLabelPositions DOWN_90 = new CategoryLabelPositions(
596
        new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.CENTER_RIGHT, TextAnchor.CENTER_RIGHT, Math.PI / 2.0),
597
        new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_LEFT, Math.PI / 2.0),
598
        new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.TOP_CENTER, TextAnchor.TOP_CENTER, Math.PI / 2.0),
599
        new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.BOTTOM_CENTER, TextAnchor.BOTTOM_CENTER, Math.PI / 2.0)
600
    );
601
    
602
    /**
603
     * Creates category label positions
604
     * @param top position for top edge
605
     * @param bottom position for bottom edge
606
     * @param left position for left edge
607
     * @param right position for right edge
608
     */
609
    public CategoryLabelPositions(CategoryLabelPosition top, CategoryLabelPosition bottom, CategoryLabelPosition left, CategoryLabelPosition right);
610
    
611
    public CategoryLabelPosition getLabelPosition(RectangleEdge edge);
612
}
613
```
614

615
**Usage Example:**
616

617
```java
618
import org.jfree.chart.labels.*;
619

620
// Configure item label positioning for bar chart
621
BarRenderer renderer = (BarRenderer) plot.getRenderer();
622

623
// Position labels outside bars at the top
624
ItemLabelPosition positive = new ItemLabelPosition(
625
    ItemLabelAnchor.OUTSIDE12,  // Above the bar
626
    TextAnchor.BOTTOM_CENTER,   // Anchor text at bottom center
627
    TextAnchor.BOTTOM_CENTER,   // No rotation anchor needed
628
    0.0                         // No rotation
629
);
630

631
// Position labels inside bars for negative values
632
ItemLabelPosition negative = new ItemLabelPosition(
633
    ItemLabelAnchor.CENTER,     // Center of bar
634
    TextAnchor.CENTER,          // Center text
635
    TextAnchor.CENTER,          // No rotation anchor needed
636
    0.0                         // No rotation
637
);
638

639
renderer.setDefaultPositiveItemLabelPosition(positive);
640
renderer.setDefaultNegativeItemLabelPosition(negative);
641
renderer.setDefaultItemLabelsVisible(true);
642

643
// Configure category axis labels with rotation
644
CategoryAxis categoryAxis = plot.getDomainAxis();
645
categoryAxis.setCategoryLabelPositions(CategoryLabelPositions.UP_45);
646

647
// Custom category label positions
648
CategoryLabelPositions customPositions = new CategoryLabelPositions(
649
    new CategoryLabelPosition(RectangleAnchor.BOTTOM, TextAnchor.BOTTOM_RIGHT, TextAnchor.BOTTOM_RIGHT, Math.PI / 6.0),  // 30 degrees
650
    new CategoryLabelPosition(RectangleAnchor.TOP, TextAnchor.TOP_LEFT, TextAnchor.TOP_LEFT, -Math.PI / 6.0),
651
    new CategoryLabelPosition(RectangleAnchor.RIGHT, TextAnchor.CENTER_RIGHT, TextAnchor.CENTER_RIGHT, 0.0),
652
    new CategoryLabelPosition(RectangleAnchor.LEFT, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_LEFT, 0.0)
653
);
654
categoryAxis.setCategoryLabelPositions(customPositions);
655
```
656

657
### Legend Management
658

659
Classes for creating and customizing chart legends.
660

661
```java { .api }
662
/**
663
 * A chart title that displays a legend
664
 */
665
public class LegendTitle extends Title implements LegendItemSource {
666
    /**
667
     * Creates a legend title with a single source
668
     * @param source the legend item source
669
     */
670
    public LegendTitle(LegendItemSource source);
671
    
672
    /**
673
     * Creates a legend title with custom arrangement
674
     * @param source the legend item source
675
     * @param hLayout the horizontal arrangement
676
     * @param vLayout the vertical arrangement
677
     */
678
    public LegendTitle(LegendItemSource source, Arrangement hLayout, Arrangement vLayout);
679
    
680
    // Sources
681
    public LegendItemSource[] getSources();
682
    public void setSources(LegendItemSource[] sources);
683
    
684
    // Item arrangement
685
    public Arrangement getItemArrangement();
686
    public void setItemArrangement(Arrangement arrangement);
687
    
688
    // Item appearance
689
    public Paint getItemPaint();
690
    public void setItemPaint(Paint paint);
691
    public Font getItemFont();
692
    public void setItemFont(Font font);
693
    public double getItemLabelPadding();
694
    public void setItemLabelPadding(double padding);
695
    
696
    // Graphic properties
697
    public RectangleAnchor getLegendItemGraphicAnchor();
698
    public void setLegendItemGraphicAnchor(RectangleAnchor anchor);
699
    public RectangleEdge getLegendItemGraphicEdge();
700
    public void setLegendItemGraphicEdge(RectangleEdge edge);
701
    public RectangleAnchor getLegendItemGraphicLocation();
702
    public void setLegendItemGraphicLocation(RectangleAnchor anchor);
703
    public RectangleInsets getLegendItemGraphicPadding();
704
    public void setLegendItemGraphicPadding(RectangleInsets padding);
705
    
706
    // Sorting
707
    public SortOrder getSortOrder();
708
    public void setSortOrder(SortOrder order);
709
    
710
    // Background
711
    public Paint getBackgroundPaint();
712
    public void setBackgroundPaint(Paint paint);
713
    public RectangleInsets getItemContainer();
714
    public void setItemContainer(RectangleInsets container);
715
}
716

717
/**
718
 * Interface for objects that can provide legend items
719
 */
720
public interface LegendItemSource {
721
    /**
722
     * Returns the legend items for this source
723
     * @return the legend items
724
     */
725
    public LegendItemCollection getLegendItems();
726
}
727

728
/**
729
 * A single item in a legend
730
 */
731
public class LegendItem implements Cloneable, Serializable {
732
    /**
733
     * Creates a simple legend item
734
     * @param label the label
735
     */
736
    public LegendItem(String label);
737
    
738
    /**
739
     * Creates a legend item with color
740
     * @param label the label
741
     * @param paint the color
742
     */
743
    public LegendItem(String label, Paint paint);
744
    
745
    /**
746
     * Creates a legend item with full customization
747
     * @param label the label
748
     * @param description the description
749
     * @param toolTipText the tooltip text
750
     * @param urlText the URL text
751
     * @param shape the shape to display
752
     * @param fillPaint the fill paint
753
     */
754
    public LegendItem(String label, String description, String toolTipText, String urlText, Shape shape, Paint fillPaint);
755
    
756
    /**
757
     * Creates a legend item with shape and line
758
     * @param label the label
759
     * @param description the description
760
     * @param toolTipText the tooltip text  
761
     * @param urlText the URL text
762
     * @param shapeVisible flag to show shape
763
     * @param shape the shape
764
     * @param shapeFilled flag to fill shape
765
     * @param fillPaint the fill paint
766
     * @param shapeOutlineVisible flag to show shape outline
767
     * @param outlinePaint the outline paint
768
     * @param outlineStroke the outline stroke
769
     * @param lineVisible flag to show line
770
     * @param line the line shape
771
     * @param lineStroke the line stroke
772
     * @param linePaint the line paint
773
     */
774
    public LegendItem(String label, String description, String toolTipText, String urlText, boolean shapeVisible, Shape shape, boolean shapeFilled, Paint fillPaint, boolean shapeOutlineVisible, Paint outlinePaint, Stroke outlineStroke, boolean lineVisible, Shape line, Stroke lineStroke, Paint linePaint);
775
    
776
    // Label properties
777
    public String getLabel();
778
    public void setLabel(String label);
779
    public String getDescription();
780
    public void setDescription(String description);
781
    public String getToolTipText();
782
    public void setToolTipText(String text);
783
    public String getURLText();
784
    public void setURLText(String text);
785
    
786
    // Shape properties
787
    public boolean isShapeVisible();
788
    public void setShapeVisible(boolean visible);
789
    public Shape getShape();
790
    public void setShape(Shape shape);
791
    public boolean isShapeFilled();
792
    public void setShapeFilled(boolean filled);
793
    public Paint getFillPaint();
794
    public void setFillPaint(Paint paint);
795
    public boolean isShapeOutlineVisible();
796
    public void setShapeOutlineVisible(boolean visible);
797
    public Paint getOutlinePaint();
798
    public void setOutlinePaint(Paint paint);
799
    public Stroke getOutlineStroke();
800
    public void setOutlineStroke(Stroke stroke);
801
    
802
    // Line properties
803
    public boolean isLineVisible();
804
    public void setLineVisible(boolean visible);
805
    public Shape getLine();
806
    public void setLine(Shape line);
807
    public Stroke getLineStroke();
808
    public void setLineStroke(Stroke stroke);
809
    public Paint getLinePaint();
810
    public void setLinePaint(Paint paint);
811
    
812
    // Dataset and series information
813
    public Dataset getDataset();
814
    public void setDataset(Dataset dataset);
815
    public int getDatasetIndex();
816
    public void setDatasetIndex(int index);
817
    public Comparable getSeriesKey();
818
    public void setSeriesKey(Comparable key);
819
    public int getSeriesIndex();
820
    public void setSeriesIndex(int index);
821
}
822

823
/**
824
 * A collection of legend items
825
 */
826
public class LegendItemCollection implements Cloneable, Serializable {
827
    /**
828
     * Creates an empty legend item collection
829
     */
830
    public LegendItemCollection();
831
    
832
    public void add(LegendItem item);
833
    public void addAll(LegendItemCollection collection);
834
    public LegendItem get(int index);
835
    public int getItemCount();
836
    public Iterator iterator();
837
    public void clear();
838
}
839

840
/**
841
 * Specialized legends for paint scales
842
 */
843
public class PaintScaleLegend extends Title implements LegendItemSource {
844
    /**
845
     * Creates a paint scale legend
846
     * @param scale the paint scale
847
     * @param axis the axis for the legend
848
     */
849
    public PaintScaleLegend(PaintScale scale, ValueAxis axis);
850
    
851
    public PaintScale getScale();
852
    public void setScale(PaintScale scale);
853
    public ValueAxis getAxis();
854
    public void setAxis(ValueAxis axis);
855
    public AxisLocation getAxisLocation();
856
    public void setAxisLocation(AxisLocation location);
857
    public double getAxisOffset();
858
    public void setAxisOffset(double offset);
859
    public double getStripWidth();
860
    public void setStripWidth(double width);
861
    public boolean isStripOutlineVisible();
862
    public void setStripOutlineVisible(boolean visible);
863
    public Paint getStripOutlinePaint();
864
    public void setStripOutlinePaint(Paint paint);
865
    public Stroke getStripOutlineStroke();
866
    public void setStripOutlineStroke(Stroke stroke);
867
    public Paint getBackgroundPaint();
868
    public void setBackgroundPaint(Paint paint);
869
    public int getSubdivisionCount();
870
    public void setSubdivisionCount(int count);
871
}
872
```
873

874
**Usage Example:**
875

876
```java
877
import org.jfree.chart.title.*;
878
import org.jfree.chart.*;
879

880
// Get default legend and customize
881
LegendTitle legend = chart.getLegend();
882
if (legend != null) {
883
    // Position and appearance
884
    legend.setPosition(RectangleEdge.RIGHT);
885
    legend.setItemFont(new Font("Arial", Font.PLAIN, 12));
886
    legend.setItemPaint(Color.BLACK);
887
    legend.setBackgroundPaint(Color.WHITE);
888
    
889
    // Item arrangement
890
    legend.setItemArrangement(new ColumnArrangement(HorizontalAlignment.LEFT, VerticalAlignment.CENTER, 2.0, 2.0));
891
    
892
    // Graphic positioning
893
    legend.setLegendItemGraphicAnchor(RectangleAnchor.CENTER_LEFT);
894
    legend.setLegendItemGraphicEdge(RectangleEdge.LEFT);
895
    legend.setLegendItemGraphicLocation(RectangleAnchor.CENTER_LEFT);
896
}
897

898
// Create custom legend items
899
LegendItemCollection customItems = new LegendItemCollection();
900

901
// Add shape-based legend item
902
LegendItem shapeItem = new LegendItem(
903
    "Data Points",                                    // Label
904
    "Scatter plot data points",                       // Description
905
    "Tooltip for data points",                        // Tooltip
906
    null,                                            // URL
907
    true,                                            // Shape visible
908
    new Ellipse2D.Double(-4, -4, 8, 8),            // Shape
909
    true,                                            // Shape filled
910
    Color.BLUE,                                      // Fill paint
911
    true,                                            // Outline visible
912
    Color.BLACK,                                     // Outline paint
913
    new BasicStroke(1.0f),                          // Outline stroke
914
    false,                                           // Line visible
915
    new Line2D.Double(-5, 0, 5, 0),                // Line shape
916
    new BasicStroke(2.0f),                          // Line stroke
917
    Color.BLUE                                       // Line paint
918
);
919

920
// Add line-based legend item
921
LegendItem lineItem = new LegendItem(
922
    "Trend Line",                                    // Label
923
    "Linear regression line",                        // Description
924
    "Tooltip for trend line",                       // Tooltip
925
    null,                                           // URL
926
    false,                                          // Shape visible
927
    null,                                           // Shape
928
    false,                                          // Shape filled
929
    null,                                           // Fill paint
930
    false,                                          // Outline visible
931
    null,                                           // Outline paint
932
    null,                                           // Outline stroke
933
    true,                                           // Line visible
934
    new Line2D.Double(-7, 0, 7, 0),               // Line shape
935
    new BasicStroke(2.0f, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND), // Line stroke
936
    Color.RED                                       // Line paint
937
);
938

939
customItems.add(shapeItem);
940
customItems.add(lineItem);
941

942
// Create custom legend
943
LegendTitle customLegend = new LegendTitle(new LegendItemSource() {
944
    public LegendItemCollection getLegendItems() {
945
        return customItems;
946
    }
947
});
948

949
customLegend.setPosition(RectangleEdge.BOTTOM);
950
chart.addSubtitle(customLegend);
951
```