001/* =========================================================== 002 * Orson Charts : a 3D chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C)opyright 2013-2022, by David Gilbert. All rights reserved. 006 * 007 * https://github.com/jfree/orson-charts 008 * 009 * This program is free software: you can redistribute it and/or modify 010 * it under the terms of the GNU General Public License as published by 011 * the Free Software Foundation, either version 3 of the License, or 012 * (at your option) any later version. 013 * 014 * This program is distributed in the hope that it will be useful, 015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 017 * GNU General Public License for more details. 018 * 019 * You should have received a copy of the GNU General Public License 020 * along with this program. If not, see <http://www.gnu.org/licenses/>. 021 * 022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 023 * Other names may be trademarks of their respective owners.] 024 * 025 * If you do not wish to be bound by the terms of the GPL, an alternative 026 * commercial license can be purchased. For details, please see visit the 027 * Orson Charts home page: 028 * 029 * http://www.object-refinery.com/orsoncharts/index.html 030 * 031 */ 032 033package org.jfree.chart3d.label; 034 035import java.io.Serializable; 036import java.util.Formatter; 037 038import org.jfree.chart3d.data.xyz.XYZDataset; 039import org.jfree.chart3d.data.xyz.XYZItemKey; 040import org.jfree.chart3d.interaction.XYZDataItemSelection; 041import org.jfree.chart3d.internal.Args; 042 043/** 044 * A default implementation of the {@link XYZItemLabelGenerator} interface. 045 * The implementation uses a {@link java.util.Formatter} instance to generate 046 * the item labels. Four values are passed to the formatter for possible 047 * inclusion in the resulting label: (1) the key for the series, 048 * (2) the x-value (3) the y-value and (4) the z-value. 049 * <br><br> 050 * NOTE: This class is serializable, but the serialization format is subject 051 * to change in future releases and should not be relied upon for persisting 052 * instances of this class. 053 * 054 * @since 1.3 055 */ 056@SuppressWarnings("serial") 057public class StandardXYZItemLabelGenerator implements XYZItemLabelGenerator, 058 Serializable { 059 060 /** 061 * A label template that will display the series key followed by the 062 * (x, y, z) coordinates with 3 decimal places. 063 */ 064 public static final String KEY_AND_COORDS_3DP_TEMPLATE 065 = "%s (%2$.3f, %3$.3f, %4$.3f)"; 066 067 /** 068 * A label template that will display the (x, y, z) coordinates with 3 069 * decimal places. 070 */ 071 public static final String COORDS_3DP_TEMPLATE = "(%2$.3f, %3$.3f, %4$.3f)"; 072 073 /** The default label template. */ 074 public static final String DEFAULT_TEMPLATE = KEY_AND_COORDS_3DP_TEMPLATE; 075 076 /** The label template. */ 077 private String template; 078 079 private XYZDataItemSelection itemSelection; 080 081 /** 082 * The default constructor. 083 */ 084 public StandardXYZItemLabelGenerator() { 085 this(DEFAULT_TEMPLATE); 086 } 087 088 /** 089 * Creates a new instance with the specified label template. 090 * 091 * @param template the label template ({@code null} not permitted). 092 */ 093 public StandardXYZItemLabelGenerator(String template) { 094 Args.nullNotPermitted(template, "template"); 095 this.template = template; 096 this.itemSelection = null; 097 } 098 099 /** 100 * Returns the item selection (if this is non-{@code null}, labels 101 * will only be generated for the items in the selection). 102 * 103 * @return The item selection (possibly {@code null}). 104 */ 105 public XYZDataItemSelection getItemSelection() { 106 return this.itemSelection; 107 } 108 109 /** 110 * Sets the item selection, which can be used to specify a subset of the 111 * data items that should have item labels generated. If this is set to 112 * {@code null} then item labels will be generated for all items. 113 * 114 * @param selection the selection ({@code null} permitted). 115 */ 116 public void setItemSelection(XYZDataItemSelection selection) { 117 this.itemSelection = selection; 118 } 119 120 /** 121 * Generates a label for the specified data item. 122 * 123 * @param dataset the dataset ({@code null} not permitted). 124 * @param seriesKey the series key ({@code null} not permitted). 125 * 126 * @return The series label (possibly {@code null}). 127 */ 128 @Override @SuppressWarnings("unchecked") 129 public String generateItemLabel(XYZDataset dataset, 130 Comparable<?> seriesKey, int itemIndex) { 131 Args.nullNotPermitted(dataset, "dataset"); 132 Args.nullNotPermitted(seriesKey, "seriesKey"); 133 if (this.itemSelection != null) { 134 XYZItemKey key = new XYZItemKey(seriesKey, itemIndex); 135 if (!this.itemSelection.isSelected(key)) { 136 return null; 137 } 138 } 139 int seriesIndex = dataset.getSeriesIndex(seriesKey); 140 Formatter formatter = new Formatter(new StringBuilder()); 141 double x = dataset.getX(seriesIndex, itemIndex); 142 double y = dataset.getY(seriesIndex, itemIndex); 143 double z = dataset.getZ(seriesIndex, itemIndex); 144 formatter.format(this.template, seriesKey, x, y, z); 145 String result = formatter.toString(); 146 formatter.close(); 147 return result; 148 } 149 150 /** 151 * Tests this label generator for equality with an arbitrary object. 152 * 153 * @param obj the object ({@code null} permitted). 154 * 155 * @return A boolean. 156 */ 157 @Override 158 public boolean equals(Object obj) { 159 if (obj == this) { 160 return true; 161 } 162 if (!(obj instanceof StandardXYZItemLabelGenerator)) { 163 return false; 164 } 165 StandardXYZItemLabelGenerator that = (StandardXYZItemLabelGenerator) obj; 166 if (!this.template.equals(that.template)) { 167 return false; 168 } 169 return true; 170 } 171 172 @Override 173 public int hashCode() { 174 return this.template.hashCode(); 175 } 176 177}