001: /*
002: * ============================================================================
003: * GNU Lesser General Public License
004: * ============================================================================
005: *
006: * JasperReports - Free Java report-generating library.
007: * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
008: *
009: * This library is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU Lesser General Public
011: * License as published by the Free Software Foundation; either
012: * version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library 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 GNU
017: * Lesser General Public License for more details.
018: *
019: * You should have received a copy of the GNU Lesser General Public
020: * License along with this library; if not, write to the Free Software
021: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022: *
023: * JasperSoft Corporation
024: * 303 Second Street, Suite 450 North
025: * San Francisco, CA 94107
026: * http://www.jaspersoft.com
027: */
028: package net.sf.jasperreports.crosstabs;
029:
030: import net.sf.jasperreports.engine.JRElement;
031: import net.sf.jasperreports.engine.JRExpression;
032: import net.sf.jasperreports.engine.JRPrintText;
033: import net.sf.jasperreports.engine.JRVariable;
034:
035: /**
036: * Crosstab element interface.
037: *
038: * @author Lucian Chirita (lucianc@users.sourceforge.net)
039: * @version $Id: JRCrosstab.java 1741 2007-06-08 10:53:33Z lucianc $
040: */
041: public interface JRCrosstab extends JRElement {
042: /**
043: * The default offset used for column breaks.
044: * @see #getColumnBreakOffset()
045: */
046: public static final int DEFAULT_COLUMN_BREAK_OFFSET = 10;
047:
048: /**
049: * Name of the built-in row count variable.
050: */
051: public static final String VARIABLE_ROW_COUNT = "ROW_COUNT";
052:
053: /**
054: * Name of the built-in column count variable.
055: */
056: public static final String VARIABLE_COLUMN_COUNT = "COLUMN_COUNT";
057:
058: /**
059: * Crosstab left to right run direction.
060: */
061: public static final byte RUN_DIRECTION_LTR = JRPrintText.RUN_DIRECTION_LTR;
062:
063: /**
064: * Crosstab right to left run direction.
065: *
066: * <p>
067: * When a crosstab is filled from right to left, the crosstab contents will start
068: * from the right extremity of the crosstab element area and grow towards the left.
069: * </p>
070: */
071: public static final byte RUN_DIRECTION_RTL = JRPrintText.RUN_DIRECTION_RTL;
072:
073: /**
074: * Returns the ID of the crosstab.
075: * <p>
076: * The ID is generated when the report is compiled and is used internally.
077: *
078: * @return the ID of the crosstab
079: */
080: public int getId();
081:
082: /**
083: * Returns the input dataset of the crosstab.
084: *
085: * @return the input dataset of the crosstab
086: */
087: public JRCrosstabDataset getDataset();
088:
089: /**
090: * Returns the row groups of the crosstab.
091: *
092: * @return the row groups
093: */
094: public JRCrosstabRowGroup[] getRowGroups();
095:
096: /**
097: * Returns the column groups of the crosstab.
098: *
099: * @return the column groups
100: */
101: public JRCrosstabColumnGroup[] getColumnGroups();
102:
103: /**
104: * Returns the crosstab measures.
105: *
106: * @return the crosstab measures
107: */
108: public JRCrosstabMeasure[] getMeasures();
109:
110: /**
111: * Returns the column break offset.
112: * <p>
113: * When the crosstab columns do not fit the width, the crosstab
114: * breaks the columns and prints the ones that don't fit after printing
115: * the first set of columns for all rows. This method returns the offset
116: * to be used when continuing the printing after a column break.
117: *
118: * @return the column break offset
119: */
120: public int getColumnBreakOffset();
121:
122: /**
123: * Returns whether to repeat the column headers after a row break.
124: *
125: * @return whether to repeat the column headers after a row break
126: */
127: public boolean isRepeatColumnHeaders();
128:
129: /**
130: * Returns whether to repeat the row headers after a column break.
131: *
132: * @return whether to repeat the row headers after a column break
133: */
134: public boolean isRepeatRowHeaders();
135:
136: /**
137: * Returns the data cell matrix.
138: * <p>
139: * A crosstab can have multiple data cells for row/groups totals.
140: * These cells are organized in a (rowGroupCount + 1) x (columnGroupCount + 1)
141: * matrix as following:
142: * <ul>
143: * <li>the row index of a cell is
144: * <ul>
145: * <li>the row group index, if the cell corresponds to a total row</li>
146: * <li>rowGroupCount, otherwise</li>
147: * </ul>
148: * </li>
149: * <li>the column index of a cell is
150: * <ul>
151: * <li>the column group index, if the cell corresponds to a total column</li>
152: * <li>columnGroupCount, otherwise</li>
153: * </ul>
154: * </li>
155: * </ul>
156: * <p>
157: * E.g. if the crosstab has Country and City (subgroup of Country) row groups and Year and Month column
158: * groups, the cells will be organized in the following matrix
159: * <table border="1">
160: * <tr>
161: * <td></td>
162: * <td>0/Years total</td>
163: * <td>1/Months total</td>
164: * <td>2/Base</td>
165: * </tr>
166: * <tr>
167: * <td>0/Countries total</td>
168: * <td>Total for all countries and all years</td>
169: * <td>Total for all countries and a year</td>
170: * <td>Total for all countries and a month</td>
171: * </tr>
172: * <tr>
173: * <td>1/Cities total</td>
174: * <td>Total for a country and all years</td>
175: * <td>Total for a country and a year</td>
176: * <td>Total for a country and a month</td>
177: * </tr>
178: * <tr>
179: * <td>2/Base</td>
180: * <td>Total for a city and all years</td>
181: * <td>Total for a city and a year</td>
182: * <td>Total for a city and a month</td>
183: * </tr>
184: * </table>
185: * <p>
186: * If the data cell for a total row/column is not specified, the cell will be inherited
187: * from lower levels, if possible. For example, if the "Total for all countries and a year"
188: * cell is not specified, the "Total for a country and a year" or "Total for a city and a year"
189: * cell will be used (in this order).
190: * <p>
191: * The data cell sizes are calculated from the base data cell sizes, i.e.
192: * the height of all data cells for a row will be the height of the base cell
193: * of that row. The base cell sizes are also inherited, e.g. if the height of a total
194: * row is not specified the height of the base row will be used.
195: *
196: * @return the data cell matrix
197: */
198: public JRCrosstabCell[][] getCells();
199:
200: /**
201: * Returns the crosstab parameters.
202: * <p>
203: * Crosstabs have separate expression evaluators and cannot access
204: * the parameters/fields/variables of the report.
205: * In order to use a value from the report inside a crosstab, it should be
206: * passed as parameter to the crosstab.
207: * <p>
208: * A crosstab parameters has a name and a value expression.
209: *
210: * @return the crosstab parameters
211: */
212: public JRCrosstabParameter[] getParameters();
213:
214: /**
215: * Returns the parameters map expression.
216: * <p>
217: * The set of values for crosstab parameters can be set using a map.
218: * If a parameter has also a value expression, it will overwrite the value
219: * from the map.
220: *
221: * @return the parameters map expression
222: */
223: public JRExpression getParametersMapExpression();
224:
225: /**
226: * Returns a cell which will be rendered when no data was fed to the crosstab.
227: * <p>
228: * If this cell is not specified for a crosstab, nothing will be rendered for an
229: * empty crosstab.
230: * <p>
231: * The cell sizes are the same as the crosstab element sizes.
232: *
233: * @return a cell which will be rendered when no data was fed to the crosstab
234: */
235: public JRCellContents getWhenNoDataCell();
236:
237: /**
238: * Searches for an element inside all crosstab cells.
239: *
240: * @param key the element key
241: * @return the first element having the specified key
242: */
243: public JRElement getElementByKey(String key);
244:
245: /**
246: * Returns a cell which will be rendered at the upper-left corner of the crosstab.
247: * <p/>
248: * The cell size will be calculated based on the row/column header cell widths/heights.
249: *
250: * @return a cell which will be rendered at the upper-left corner of the crosstab
251: */
252: public JRCellContents getHeaderCell();
253:
254: /**
255: * Returns the variables defined for the crosstab.
256: *
257: * @return variables defined for the crosstab
258: * @see JRCrosstabGroup#getVariable()
259: * @see JRCrosstabMeasure#getVariable()
260: * @see #VARIABLE_ROW_COUNT
261: * @see #VARIABLE_COLUMN_COUNT
262: */
263: public JRVariable[] getVariables();
264:
265: /**
266: * Retrieves the run direction of this crosstab.
267: *
268: * @return the run direction of this crosstab
269: * @see #setRunDirection(byte)
270: */
271: public byte getRunDirection();
272:
273: /**
274: * Sets the run direction of the crosstab.
275: * <p>
276: * Crosstabs can either be filled from left to right (the default)
277: * or from right to left (mainly for reports in RTL languages).
278: * </p>
279: *
280: * @param direction one of {@link #RUN_DIRECTION_LTR RUN_DIRECTION_LTR}
281: * and {@link #RUN_DIRECTION_RTL RUN_DIRECTION_RTL}
282: */
283: public void setRunDirection(byte direction);
284:
285: }
|