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.table; 034 035import java.awt.Graphics2D; 036import java.awt.geom.Dimension2D; 037import java.awt.geom.Rectangle2D; 038import java.util.List; 039import java.util.Map; 040import org.jfree.chart3d.graphics2d.RefPt2D; 041 042/** 043 * An element (typically a single cell) in a table. This interface defines 044 * methods for determining the preferred size of the element, for laying out 045 * the element (including sub-elements if there are any), and drawing the 046 * element within specified bounds. Various kinds of table elements will be 047 * used to construct interesting tables. 048 * <br><br> 049 * It is important that these methods are implemented in a stateless manner. 050 * There is some redundancy in calculation between the layout and drawing 051 * methods in order to preserve the statelessness, but it is important to 052 * ensure that table elements can be rendered to multiple targets 053 * simultaneously. 054 * 055 */ 056public interface TableElement { 057 058 /** 059 * A property key for the class of a table element. 060 * 061 * @since 1.3 062 */ 063 String CLASS = "class"; 064 065 /** 066 * Calculates the preferred size for the element, with reference to the 067 * specified bounds. The preferred size can exceed the bounds, but the 068 * bounds might influence how sub-elements are sized and/or positioned. 069 * For example, in a {@link FlowElement}, the width of the bounds will 070 * determine when the flow layout wraps. 071 * 072 * @param g2 the graphics target ({@code null} not permitted). 073 * @param bounds the bounds ({@code null} not permitted). 074 * 075 * @return The preferred size (never {@code null}). 076 */ 077 Dimension2D preferredSize(Graphics2D g2, Rectangle2D bounds); 078 079 /** 080 * Returns the preferred size of the element, subject to the supplied 081 * constraints. 082 * 083 * @param g2 the graphics target ({@code null} not permitted). 084 * @param bounds the bounds ({@code null} not permitted). 085 * @param constraints the constraints ({@code null} permitted). 086 * 087 * @return The preferred size. 088 */ 089 Dimension2D preferredSize(Graphics2D g2, Rectangle2D bounds, 090 Map<String, Object> constraints); 091 092 /** 093 * Returns the reference point used to align the element with the bounding 094 * rectangle within which it is drawn. 095 * 096 * @return The anchor point (never {@code null}). 097 */ 098 RefPt2D getRefPoint(); 099 100 /** 101 * Performs a layout of this table element, returning a list of bounding 102 * rectangles for the element and its subelements. This method is 103 * typically called by the {@link #draw(java.awt.Graphics2D, 104 * java.awt.geom.Rectangle2D)} method. 105 * 106 * @param g2 the graphics target ({@code null} not permitted). 107 * @param bounds the bounds ({@code null} not permitted). 108 * @param constraints the constraints (if any). 109 * 110 * @return A list of bounding rectangles. 111 */ 112 List<Rectangle2D> layoutElements(Graphics2D g2, Rectangle2D bounds, 113 Map<String, Object> constraints); 114 115 /** 116 * Draws the element within the specified bounds. 117 * 118 * @param g2 the graphics target ({@code null} not permitted). 119 * @param bounds the bounds ({@code null} not permitted). 120 */ 121 void draw(Graphics2D g2, Rectangle2D bounds); 122 123 /** 124 * Draws the element within the specified bounds. The 125 * {@code onDrawHandler} provides (optional) access to all elements 126 * before and after they are rendered. 127 * 128 * @param g2 the graphics target ({@code null} not permitted). 129 * @param bounds the bounds ({@code null} not permitted). 130 * @param onDrawHandler an object that will receive notification before 131 * and after the element is drawn ({@code null} permitted). 132 * 133 * @since 1.3 134 */ 135 void draw(Graphics2D g2, Rectangle2D bounds, 136 TableElementOnDraw onDrawHandler); 137 138 /** 139 * Returns the value of the property with the specified key, or 140 * {@code null}. 141 * 142 * @param key the key ({@code null} not permitted). 143 * 144 * @return The property value or {@code null}. 145 * 146 * @since 1.3 147 */ 148 Object getProperty(String key); 149 150 /** 151 * Sets the value of the property with the specified key. 152 * 153 * @param key the key ({@code null} not permitted). 154 * @param value the value ({@code null} permitted). 155 * 156 * @since 1.3 157 */ 158 void setProperty(String key, Object value); 159 160 /** 161 * Receives a {@link TableElementVisitor}. The visitor will have its 162 * {@code visit(TableElement)} method called for each child element 163 * of this table element (if it has children) and then for this element. 164 * 165 * @param visitor the visitor ({@code null} not permitted). 166 * 167 * @since 1.2 168 */ 169 void receive(TableElementVisitor visitor); 170 171}