/*********************************************************************
*
* Copyright (C) 2002 Andrew Khan
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
***************************************************************************/
package jxl.write;
import jxl.CellView;
import jxl.Range;
import jxl.Sheet;
import jxl.format.CellFormat;
import jxl.format.PageOrientation;
import jxl.format.PaperSize;
import jxl.write.biff.RowsExceededException;
/**
* Interface for a worksheet that may be modified. The most
* important modification for a sheet is to have cells added to it
*/
public interface WritableSheet extends Sheet
{
/**
* Adds a cell to this sheet
* The RowsExceededException may be caught if client code wishes to
* explicitly trap the case where too many rows have been written
* to the current sheet. If this behaviour is not desired, it is
* sufficient simply to handle the WriteException, since this is a base
* class of RowsExceededException
*
* @param cell the cell to add
* @exception jxl.write..WriteException
* @exception jxl.write.biff.RowsExceededException
*/
public void addCell(WritableCell cell)
throws WriteException, RowsExceededException;
/**
* Sets the name of this sheet
*
* @param name the name of the sheet
*/
public void setName(String name);
/**
* Indicates whether or not this sheet is hidden
*
* @param hidden hidden flag
* @deprecated use the SheetSettings bean instead
*/
public void setHidden(boolean hidden);
/**
* Indicates whether or not this sheet is protected
*
* @param prot Protected flag
* @deprecated use the SheetSettings bean instead
*/
public void setProtected(boolean prot);
/**
* Sets the width of the column on this sheet, in characters. This causes
* Excel to resize the entire column.
* If the columns specified already has view information associated
* with it, then it is replaced by the new data
*
* @param col the column to be formatted
* @param width the width of the column
*/
public void setColumnView(int col, int width);
/**
* Sets the width and style of every cell in the specified column.
* If the columns specified already has view information associated
* with it, then it is replaced by the new data
*
* @param col the column to be formatted
* @param format the format of every cell in the column
* @param width the width of the column, in characters
* @deprecated Use the CellView bean instead
*/
public void setColumnView(int col, int width, CellFormat format);
/**
* Sets the view for this column
*
* @param col the column on which to set the view
* @param view the view to set
*/
public void setColumnView(int col, CellView view);
/**
* Sets the height of the specified row, as well as its collapse status
*
* @param row the row to be formatted
* @param height the row height in characters
* @exception jxl.write.biff.RowsExceededException
*/
public void setRowView(int row, int height)
throws RowsExceededException;
/**
* Sets the properties of the specified row
*
* @param row the row to be formatted
* @param collapsed indicates whether the row is collapsed
* @exception jxl.write.biff.RowsExceededException
*/
public void setRowView(int row, boolean collapsed)
throws RowsExceededException;
/**
* Sets the height of the specified row, as well as its collapse status
*
* @param row the row to be formatted
* @param height the row height in 1/20th of a point
* @param collapsed indicates whether the row is collapsed
* @exception jxl.write.biff.RowsExceededException
*/
public void setRowView(int row, int height,
boolean collapsed)
throws RowsExceededException;
/**
* Sets the view for this column
*
* @param row the column on which to set the view
* @param view the view to set
* @exception RowsExceededException
*/
public void setRowView(int row, CellView view) throws RowsExceededException;
/**
* Gets the writable cell from this sheet. Use of this method allows
* the returned cell to be modified by the users application
*
* @param column the column
* @param row the row
* @return the cell at the specified position
*/
public WritableCell getWritableCell(int column, int row);
/**
* Returns the cell for the specified location eg. "A4". Note that this
* method is identical to calling getCell(CellReferenceHelper.getColumn(loc),
* CellReferenceHelper.getRow(loc)) and its implicit performance
* overhead for string parsing. As such,this method should therefore
* be used sparingly
*
* @param loc the cell reference
* @return the cell at the specified co-ordinates
*/
public WritableCell getWritableCell(String loc);
/**
* Gets the writable hyperlinks from this sheet. The hyperlinks
* that are returned may be modified by user applications
*
* @return the writable hyperlinks
*/
public WritableHyperlink[] getWritableHyperlinks();
/**
* Inserts a blank row into this spreadsheet. If the row is out of range
* of the rows in the sheet, then no action is taken
*
* @param row the row to insert
*/
public void insertRow(int row);
/**
* Inserts a blank column into this spreadsheet. If the column is out of
* range of the columns in the sheet, then no action is taken
*
* @param col the column to insert
*/
public void insertColumn(int col);
/**
* Removes a column from this spreadsheet. If the column is out of range
* of the columns in the sheet, then no action is taken
*
* @param col the column to remove
*/
public void removeColumn(int col);
/**
* Removes a row from this spreadsheet. If the row is out of
* range of the columns in the sheet, then no action is taken
*
* @param row the row to remove
*/
public void removeRow(int row);
/**
* Merges the specified cells. Any clashes or intersections between
* merged cells are resolved when the spreadsheet is written out
*
* @param col1 the column number of the top left cell
* @param row1 the row number of the top left cell
* @param col2 the column number of the bottom right cell
* @param row2 the row number of the bottom right cell
* @return the Range object representing the merged cells
* @exception jxl.write..WriteException
* @exception jxl.write.biff.RowsExceededException
*/
public Range mergeCells(int col1, int row1, int col2, int row2)
throws WriteException, RowsExceededException;
/**
* Sets a row grouping
*
* @param row1 the first row of the group
* @param row2 the last row of the group
* @param collapsed should the group be collapsed?
* @exception WriteException
* @exception RowsExceededException
*/
public void setRowGroup(int row1, int row2, boolean collapsed)
throws WriteException, RowsExceededException;
/**
* Unsets a row grouping
*
* @param row1 the first row to unset
* @param row2 the last row to unset
* @exception WriteException
* @exception RowsExceededException
*/
public void unsetRowGroup(int row1, int row2)
throws WriteException, RowsExceededException;
/**
* Sets a column grouping
*
* @param col1 the first column of the group
* @param col2 the last column of the group
* @param collapsed should the group be collapsed?
* @exception WriteException
* @exception RowsExceededException
*/
public void setColumnGroup(int col1, int col2, boolean collapsed)
throws WriteException, RowsExceededException;
/**
* Unsets a column grouping
*
* @param col1 the first column to unset
* @param col2 the last column to unset
* @exception WriteException
* @exception RowsExceededException
*/
public void unsetColumnGroup(int col1, int col2)
throws WriteException, RowsExceededException;
/**
* Unmerges the specified cells. The Range passed in should be one that
* has been previously returned as a result of the getMergedCells method
*
* @param r the range of cells to unmerge
*/
public void unmergeCells(Range r);
/**
* Adds the specified hyperlink. Adding a hyperlink causes any populated
* cells in the range of the hyperlink to be set to empty
* If the cells which activate this hyperlink clash with any other cells,
* they are still added to the worksheet and it is left to Excel to
* handle this.
*
* @param h the hyperlink
* @exception jxl.write..WriteException
* @exception jxl.write.biff.RowsExceededException
*/
public void addHyperlink(WritableHyperlink h)
throws WriteException, RowsExceededException;;
/**
* Removes the specified hyperlink. Note that if you merely set the
* cell contents to be an Empty cell, then the cells containing the
* hyperlink will still be active. The contents of the cell which
* activate the hyperlink are removed.
* The hyperlink passed in must be a hyperlink retrieved using the
* getHyperlinks method
*
* @param h the hyperlink to remove.
*/
public void removeHyperlink(WritableHyperlink h);
/**
* Removes the specified hyperlink. Note that if you merely set the
* cell contents to be an Empty cell, then the cells containing the
* hyperlink will still be active.
* If the preserveLabel field is set, the cell contents of the
* hyperlink are preserved, although the hyperlink is deactivated. If
* this value is FALSE, the cell contents are removed
* The hyperlink passed in must be a hyperlink retrieved using the
* getHyperlinks method
*
* @param h the hyperlink to remove.
* @param preserveLabel if TRUE preserves the label contents, if FALSE
* removes them
*/
public void removeHyperlink(WritableHyperlink h, boolean preserveLabel);
/**
* Sets the header for this page
*
* @param l the print header to print on the left side
* @param c the print header to print in the centre
* @param r the print header to print on the right hand side
* @deprecated use the SheetSettings bean
*/
public void setHeader(String l, String c, String r);
/**
* Sets the footer for this page
*
* @param l the print header to print on the left side
* @param c the print header to print in the centre
* @param r the print header to print on the right hand side
* @deprecated use the SheetSettings bean
*/
public void setFooter(String l, String c, String r);
/**
* Sets the page setup details
*
* @param p the page orientation
*/
public void setPageSetup(PageOrientation p);
/**
* Sets the page setup details
*
* @param p the page orientation
* @param hm the header margin, in inches
* @param fm the footer margin, in inches
*/
public void setPageSetup(PageOrientation p, double hm, double fm);
/**
* Sets the page setup details
*
* @param p the page orientation
* @param ps the paper size
* @param hm the header margin, in inches
* @param fm the footer margin, in inches
*/
public void setPageSetup(PageOrientation p, PaperSize ps,
double hm, double fm);
/**
* Forces a page break at the specified row
*
* @param row the row to break at
*/
public void addRowPageBreak(int row);
/**
* Forces a page break at the specified column
*
* @param col the column to break at
*/
public void addColumnPageBreak(int col);
/**
* Adds an image to the sheet
*
* @param image the image to add
*/
public void addImage(WritableImage image);
/**
* Accessor for the number of images on the sheet
*
* @return the number of images on this sheet
*/
public int getNumberOfImages();
/**
* Accessor for the image
*
* @param i the 0 based image number
* @return the image at the specified position
*/
public WritableImage getImage(int i);
/**
* Removes the specified image from the sheet. The image passed in
* must be the same instance as that previously retrieved using the
* getImage() method
*
* @param wi the image to remove
*/
public void removeImage(WritableImage wi);
/**
* Extend the data validation contained in the specified cell across and
* downwards.
* NOTE: The source cell (top left) must have been added to the sheet prior
* to this method being called
*
* @param col the number of cells accross to apply this data validation
* @param row the number of cells downwards to apply this data validation
*/
public void applySharedDataValidation(WritableCell cell, int col, int row)
throws WriteException;
/**
* Remove the shared data validation from multiple cells. The cell passed
* in is the top left cell. The data validation is removed from this
* cell and all cells which share the same validation.
*
* @param cell the top left cell containing the shared data validation
*/
public void removeSharedDataValidation(WritableCell cell)
throws WriteException;
}
|