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}