001/*
002 * Copyright (c) 2005 Einar Pehrson <einar@pehrson.nu>.
003 *
004 * This file is part of
005 * CleanSheets - a spreadsheet application for the Java platform.
006 *
007 * CleanSheets is free software; you can redistribute it and/or modify
008 * it under the terms of the GNU General Public License as published by
009 * the Free Software Foundation; either version 2 of the License, or
010 * (at your option) any later version.
011 *
012 * CleanSheets is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU General Public License
018 * along with CleanSheets; if not, write to the Free Software
019 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
020 */
021package csheets.core;
022
023import java.io.Serializable;
024import java.util.SortedSet;
025
026import csheets.core.formula.Formula;
027import csheets.core.formula.compiler.FormulaCompilationException;
028import csheets.ext.Extensible;
029
030/**
031 * A cell in a spreadsheet.
032 * <p>The cell has content, which can be interpreted in
033 * different ways: <ul>
034 * <li>As a formula - The content should consitute a syntactically correct
035 * expression, and begin with an assignment.
036 * <li>As a value - If the cell contains a formula, the formula is evaluated to
037 * produce a value, provided that the cell does not contain calculation errors
038 * (e.g. division by 0). Otherwise, the content is interpreted as the value.
039 * </ul>
040 * @author Einar Pehrson
041 */
042public interface Cell extends Comparable<Cell>, Extensible<Cell>, Serializable {
043
044/*
045 * LOCATION
046 */
047
048        /**
049         * Returns the spreadsheet to which the cell belongs.
050         * @return the spreadsheet to which the cell belongs
051         */
052        public Spreadsheet getSpreadsheet();
053
054        /**
055         * Returns the address of the cell.
056         * @return the address of the cell
057         */
058        public Address getAddress();
059
060/*
061 * VALUE
062 */
063
064        /**
065         * Returns the value of the cell.
066         * @return the value of the cell
067         */
068        public Value getValue();
069
070/*
071 * CONTENT
072 */
073
074        /**
075         * Returns the content of the cell, as entered by the user.
076         * @return the content of the cell
077         */
078        public String getContent();
079
080        /**
081         * Returns an expression representing the cell's formula.
082         * @return the cell's formula, or null if the cell does not contain one
083         */
084        public Formula getFormula();
085
086        /**
087         * Sets the content of the cell and if it starts with the assignment operator
088         * attempts to parse a formula from it.
089         * @throws FormulaCompilationException if an incorrectly formatted formula was entered
090         */
091        public void setContent(String content) throws FormulaCompilationException;
092
093        /**
094         * Clears the content of the cell.
095         */
096        public void clear();
097
098/*
099 * DEPENDENCIES
100 */
101
102        /**
103         * Returns the precedents of the cell, i.e. the cells that the
104         * formula in the cell references.
105         * @return a set of the cell's precedents
106         */
107        public SortedSet<Cell> getPrecedents();
108
109        /**
110         * Returns the dependents of the cell, i.e. the cells that contain a reference
111         * to the cell in their formula.
112         * @return a set of the cells which depend on the cell
113         */
114        public SortedSet<Cell> getDependents() ;
115
116/*
117 * CLIPBOARD
118 */
119
120        /**
121         * Copies all data from the source cell to this one.
122         * @param source the cell from which data should be copied
123         */
124        public void copyFrom(Cell source);
125
126        /**
127         * Moves all data from the source cell to this one.
128         * @param source the cell from which data should be moved
129         */
130        public void moveFrom(Cell source);
131
132/*
133 * EVENT HANDLING
134 */
135
136        /**
137         * Registers the given listener on the cell.
138         * @param listener the listener to be added
139         */
140        public void addCellListener(CellListener listener);
141
142        /**
143         * Removes the given listener from the cell.
144         * @param listener the listener to be removed
145         */
146        public void removeCellListener(CellListener listener);
147        
148        /**
149         * Returns the listeners that have been registered on the cell.
150         * @return the listeners that have been registered on the cell
151         */
152        public CellListener[] getCellListeners();
153}