com.sas.table
Class Cell

com.sas.table.Cell

All Implemented Interfaces:

TableElementInterface

Direct Known Subclasses:

DataCell, LabelCell

public abstract class Cell

Defines an abstract base class for TableView's data and label cells.

Cell includes methods for accessing and changing a cell's data, determining whether it's displayed or been selected or modified, finding out its location and size, and associating a style with it.

Since TableView is designed to work with different cell types (implementations), a uniform way to access cells is needed -- Cell provides this. Cell is actually a wrapper around a cell view. A cell view is an implemenation of CellViewInterface that is used to display, format, and edit a cell's data. The cell view is accessible via the getView() method. The class of cell view that gets created is determined by the effective CellStyle.viewClass property. By default, TableView uses a TextCell for all cells, but each cell is free to use any implementation of CellViewInterface. For example, if TableView's model had a column (say column 3) of boolean data, you might want to configure TableView to use check boxes to display that data like so:

 Column col = tableView.getColumn(3);
 ColumnStyle colStyle = new ColumnStyle();
 CellStyle cellStyle = new CellStyle();
 cellStyle.setViewClass (CheckBoxCell.class);
 colStyle.setDefaultCellStyle (cellStyle);
 col.setStyle (colStyle);
 

See Also:

TableView, DataCell, LabelCell, CellStyle, CellViewInterface

Field Summary

Fields inherited from class com.sas.table.TableElement

emptyModelTypesArray, emptyModelTypeStylesArray, tableView

Fields inherited from interface com.sas.table.TableElementInterface

REFRESH_ALL, REFRESH_DATA, REFRESH_DATA_STYLE, REFRESH_LABEL, REFRESH_LABEL_STYLE, REFRESH_STYLE

Constructor Summary

protected

Cell(TableView table) Constructor.

Method Summary

abstract boolean	equals(Cell other) Compares this and a given cell for equality.
boolean	equals(TableElement obj) Compares this and a given table element for equality.
int	getActiveState() Returns the cell's activeState, i.e. it's degree or level of activation.
java.awt.Rectangle	getBounds() Returns a rectangle that matches the cell's bounds, i.e. its location and size.
java.awt.Rectangle	getDisplayedBounds() Returns a rectangle that matches the cell's displayed bounds, i.e. its location and displayed size.
abstract int	getDisplayedHeight() Returns the vertical size of the area allotted to the cell in the table's current display.
abstract int	getDisplayedWidth() Returns the horizontal size of the area allotted to the cell in the table's current display.
java.awt.Font	getEffectiveFont() Returns the effective font, i.e. the font that will be used to paint the cell.
void	getEffectiveStylePropertyBag(java.lang.String propertyID, com.sas.collection.PropertyBagInterface bag, boolean clearBag) Determines the effective value of the specified style property of type StaticPropertyBagInterface.
java.lang.Object	getEffectiveStylePropertyValue(java.lang.String propertyID, java.lang.Object defaultValue) Returns the effective value of the specified style property.
java.awt.Graphics	getGraphics() Creates a graphics context for this cell.
abstract int	getHeight() Returns the vertical extent of the cell.
abstract int	getHorizontalPosition() Returns the x-coordinate of the top-left corner of the cell (relative to the top-left corner of the table).
java.awt.Insets	getInsets() Returns this cell's insets.
int	getMinimumHeight(java.awt.Graphics g) Returns the minimum amount of vertical space needed to display the cell in the given graphics context.
int	getMinimumWidth(java.awt.Graphics g) Returns the minimum amount of horizontal space needed to display the cell in the given graphics context.
java.lang.String[]	getModelTypes() Returns the types associated with this cell by the table view's model.
com.sas.collection.StaticPropertyBagInterface[]	getModelTypeStyles() Returns the styles associated with the cell's model types.
java.lang.Object	getObjectData() Returns the cell's data.
abstract java.lang.Class	getObjectDataClass() Returns the class of the cell's data.
int	getPreferredHeight(java.awt.Graphics g) Alias for "getPreferredHeight (g, -1)".
int	getPreferredHeight(java.awt.Graphics g, int width) Returns the preferred amount of vertical space needed to display the cell in the given graphics context.
int	getPreferredWidth(java.awt.Graphics g) Alias for "getPreferredWidth (g, -1)".
int	getPreferredWidth(java.awt.Graphics g, int height) Returns the preferred amount of horizontal space needed to display the cell in the given graphics context.
protected TableElement	getThis() Returns the TableElement instance to delegate all variable access to.
protected abstract Cell	getThisCell() Returns the Cell instance to delegate all variable access to.
abstract int	getVerticalPosition() Returns the y-coordinate of the top-left corner of the cell (relative to the top-left corner of the table).
CellViewInterface	getView() Returns the instance of the effective CellStyle.viewClass that is used to format, render, and edit the cell's data.
abstract int	getWidth() Returns the horizontal extent of the cell.
boolean	isActivated() Returns true if the activeState is either ACTIVE_LIGHT or ACTIVE and false otherwise.
boolean	isDataInvalid() Returns true if the cell contains invalid data and false otherwise.
boolean	isKeyHandled() Returns the value of the keyHandled property.
abstract boolean	isLabel() Returns true if the cell is a label and false otherwise.
boolean	isModified() Returns true if the cell contains modified data and false otherwise.
boolean	isMouseCaptured() Returns true if the cell has captured the mouse and false otherwise.
boolean	isSelected() Returns true if the cell is selected in table and false otherwise.
protected java.lang.String	onGetFormattedData() Cell framework method for seeding the cell's view with formatted data from the table's model.
protected abstract java.lang.Object	onGetObjectData() Cell framework method for seeding the cell's view with data from the table's model.
protected abstract java.lang.String[]	onGetTypes() Cell framework method for initializing the cell's type(s) from the table's model.
protected void	onPaintBackground(java.awt.Graphics g, int width, int height) Cell.paint framework method for painting the cell's background.
protected void	onPaintBorder(java.awt.Graphics g, int width, int height) Cell.paint framework method for painting the cell's border.
protected void	onPaintForeground(java.awt.Graphics g, int width, int height) Cell.paint framework method for painting the cell's foreground.
protected abstract void	onWriteObjectData() Cell framework method for writing the cell's data to the table's model.
void	paint(java.awt.Graphics g) Paints the cell.
void	processFocusEvent(java.awt.event.FocusEvent event) Forwards a focus event to the cell's view.
void	processKeyEvent(java.awt.event.KeyEvent event) Forwards a key event to the cell's view.
void	processMouseEvent(java.awt.event.MouseEvent event) Forwards a mouse event to the cell's view.
void	processMouseMotionEvent(java.awt.event.MouseEvent event) Forwards a mouse motion event to the cell's view.
void	refresh(int flags) Refreshes the cell to its state as maintained by the table view's model.
void	repaint() Alias for "repaint (0, 0, getWidth(), getHeight())".
void	repaint(int x, int y, int width, int height) Repaints the specified rectangle of the cell.
void	setActiveState(int newValue) Alias for "setActiveState (newValue, null)".
void	setActiveState(int newValue, java.awt.Point point) Sets the cell's activeState, i.e. it's degree or level of activation.
void	setKeyHandled(boolean newValue) Sets the value of the keyHandled property.
void	setModified(boolean newValue) Sets the value of the modified property.
void	setMouseCaptured(boolean newValue) Enables or disables mouse capture by the cell.
void	setObsolete() Indicates that the cell should be considered obsolete.
void	writeObjectData() Writes the cell's data to the table's model.

Methods inherited from class com.sas.table.TableElement

equals, getDefaultStyle, getModelDefaultStyle, getModelStyle, getStyle, getTableView, isCurrent, isTransient, onGetEffectiveStylePropertyBag, onGetEffectiveStylePropertyValue, onGetModelStyle, setStyle

Methods inherited from interface com.sas.table.TableElementInterface

isDisplayed

Constructor Detail

Cell

protected Cell(TableView table)

Constructor.

Parameters:

table - The TableView instance that contains this cell.

Method Detail

equals

public final boolean equals(TableElement obj)

Compares this and a given table element for equality.

Specified by:

equals in class TableElement

Returns:

true if obj is a Cell and equals((Cell)obj) returns true; false otherwise.

equals

public abstract boolean equals(Cell other)

Compares this and a given cell for equality.

Returns:

true if this cell is equivalent to other; false otherwise.

getActiveState

public int getActiveState()

Returns the cell's activeState, i.e. it's degree or level of activation. Possible values are any of the values defined by CellActiveStates.

Returns:

The value of the activeState property.

See Also:

CellActiveStates, setActiveState(int)

getBounds

public final java.awt.Rectangle getBounds()

Returns a rectangle that matches the cell's bounds, i.e. its location and size. Note that bounds is undefined when displayed is false.

Returns:

The copied value of the bounds property.

See Also:

getDisplayedBounds()

getDisplayedBounds

public final java.awt.Rectangle getDisplayedBounds()

Returns a rectangle that matches the cell's displayed bounds, i.e. its location and displayed size.

Returns:

The copied value of the displayedBounds property.

See Also:

getBounds()

getDisplayedHeight

public abstract int getDisplayedHeight()

Returns the vertical size of the area allotted to the cell in the table's current display. displayedHeight is always less than or equal to height.

Returns:

The value of the displayedHeight property in pixels.

See Also:

getHeight()

getDisplayedWidth

public abstract int getDisplayedWidth()

Returns the horizontal size of the area allotted to the cell in the table's current display. displayedWidth is always less than or equal to width.

Returns:

The value of the displayedWidth property in pixels.

See Also:

getWidth()

getEffectiveFont

public java.awt.Font getEffectiveFont()

Returns the effective font, i.e. the font that will be used to paint the cell.

Returns:

A Font that represents the composite set of FontStyles associated with this cell.

getEffectiveStylePropertyBag

public void getEffectiveStylePropertyBag(java.lang.String propertyID,
                                         com.sas.collection.PropertyBagInterface bag,
                                         boolean clearBag)

Determines the effective value of the specified style property of type StaticPropertyBagInterface. Overrides super to make tableView.getDefaultInvalidCellStyle() the the highest priority style if isInvalid() is true.

Overrides:

getEffectiveStylePropertyBag in class TableElement

Parameters:

propertyID - An interned String (see String.intern()) which identifies a property of type PropertyBagInterface, for example, CellStyle.FONT_STYLE.

bag - The bag to fill with the effective values of the subproperties associated with propertyID.

clearBag - If true, an initial bag.removeAll() is done.

See Also:

TableElement.getEffectiveStylePropertyBag(java.lang.String, com.sas.collection.PropertyBagInterface, boolean), getEffectiveStylePropertyValue(java.lang.String, java.lang.Object)

getEffectiveStylePropertyValue

public java.lang.Object getEffectiveStylePropertyValue(java.lang.String propertyID,
                                                       java.lang.Object defaultValue)

Returns the effective value of the specified style property. Overrides super to make tableView.getDefaultInvalidCellStyle() the the highest priority style if isInvalid() is true.

Overrides:

getEffectiveStylePropertyValue in class TableElement

Parameters:

propertyID - An interned String (see String.intern()) which identifies the property, for example, CellStyle.FOREGROUND_COLOR.

defaultValue - Value to return if no value is found for the property.

Returns:

The effective property value.

See Also:

TableElement.getEffectiveStylePropertyValue(java.lang.String, java.lang.Object), getEffectiveStylePropertyBag(java.lang.String, com.sas.collection.PropertyBagInterface, boolean)

getGraphics

public java.awt.Graphics getGraphics()

Creates a graphics context for this cell. This method will return null if this cell is not currently on the screen.

Returns:

A graphics context for this cell, or null if it has none.

getHeight

public abstract int getHeight()

Returns the vertical extent of the cell.

Returns:

The value of the height property in pixels.

See Also:

getDisplayedHeight()

getHorizontalPosition

public abstract int getHorizontalPosition()

Returns the x-coordinate of the top-left corner of the cell (relative to the top-left corner of the table). Note, it is undefined when displayed is false.

Returns:

The value of the horizontalPosition property in pixels.

getInsets

public java.awt.Insets getInsets()

Returns this cell's insets.

Returns:

The insets.

getMinimumHeight

public int getMinimumHeight(java.awt.Graphics g)

Returns the minimum amount of vertical space needed to display the cell in the given graphics context.

Parameters:

g - The graphics context to measure the cell in.

Returns:

The cell's minimum height in pixels.

getMinimumWidth

public int getMinimumWidth(java.awt.Graphics g)

Returns the minimum amount of horizontal space needed to display the cell in the given graphics context.

Parameters:

g - The graphics context to measure the cell in.

Returns:

The cell's minimum width in pixels.

getObjectData

public java.lang.Object getObjectData()
                               throws com.sas.table.TableException

Returns the cell's data. The data is returned in the preferred output format of the cell's view.

Returns:

The cell's data.

Throws:

TableException - If this is the first access of the data, the table's model will be queried for it. This query can generate a TableException. If the cell's view hasn't yet been created, it will be and any failure while doing so (e.g. InstantiationException) will be recast as a TableException.

See Also:

writeObjectData()

getObjectDataClass

public abstract java.lang.Class getObjectDataClass()
                                            throws com.sas.table.TableException

Returns the class of the cell's data.

Returns:

The class of the cell's data.

Throws:

TableException - Thrown if the query can not be satisfied (e.g. i/o-failure).

getPreferredHeight

public final int getPreferredHeight(java.awt.Graphics g)

Alias for "getPreferredHeight (g, -1)".

Parameters:

g - The graphics context to measure the cell in.

Returns:

The cell's preferred height in pixels.

getPreferredHeight

public int getPreferredHeight(java.awt.Graphics g,
                              int width)

Returns the preferred amount of vertical space needed to display the cell in the given graphics context. The width parameter allows the question "assuming this much horizontal space, how tall would the cell be" to be answered.

Parameters:

g - The graphics context to measure the cell in.

width - The width (in pixels) to constrain by. Specify -1 to not constrain.

Returns:

The cell's preferred height in pixels.

getPreferredWidth

public final int getPreferredWidth(java.awt.Graphics g)

Alias for "getPreferredWidth (g, -1)".

Parameters:

g - The graphics context to measure the cell in.

Returns:

The cell's preferred width in pixels.

getPreferredWidth

public int getPreferredWidth(java.awt.Graphics g,
                             int height)

Returns the preferred amount of horizontal space needed to display the cell in the given graphics context. The height parameter allows the question "assuming this much vertical space, how wide would the cell be" to be answered.

Parameters:

g - The graphics context to measure the cell in.

height - The height (in pixels) to constrain by. Specify -1 to not constrain.

Returns:

The cell's preferred width in pixels.

getThis

protected final TableElement getThis()

Returns the TableElement instance to delegate all variable access to. Usually the instance will be this, but if this has been obsoleted then a different, but equivalent, instance will be returned.

Specified by:

getThis in class TableElement

Returns:

The proxy for accessing our variables.

See Also:

TableElement.setObsolete()

getThisCell

protected abstract Cell getThisCell()

Returns the Cell instance to delegate all variable access to. Usually the instance will be this, but if this has been obsoleted then a different, but equivalent, instance will be returned.

Returns:

The proxy for accessing our variables.

See Also:

TableElement.setObsolete()

getModelTypes

public java.lang.String[] getModelTypes()

Returns the types associated with this cell by the table view's model. For cells that have more than one type, the types will be ordered (if applicable) in the array from most important to least important.

Specified by:

getModelTypes in class TableElement

Returns:

A string array of the cell's types; will never be null.

See Also:

StaticTableTypeInterface, getModelTypeStyles()

getModelTypeStyles

public com.sas.collection.StaticPropertyBagInterface[] getModelTypeStyles()

Returns the styles associated with the cell's model types.

Specified by:

getModelTypeStyles in class TableElement

Returns:

An array of styles ordered such that there is a one-to-one correspondence between its elements and the elements of the array returned by getModelTypes. Neither the array nor any of its elements will ever be null.

See Also:

StaticTableTypeStylesInterface, getModelTypes()

getVerticalPosition

public abstract int getVerticalPosition()

Returns the y-coordinate of the top-left corner of the cell (relative to the top-left corner of the table). Note, it is undefined when displayed is false.

Returns:

The value of the verticalPosition property in pixels.

getView

public final CellViewInterface getView()
                                throws com.sas.table.TableException

Returns the instance of the effective CellStyle.viewClass that is used to format, render, and edit the cell's data. The view is returned as type CellViewInterface, since at a minimum the view's class must implement that, but callers of getView will likely cast the returned view to the effective CellStyle.viewClass in order use that class's properties and methods.

Returns:

The value of the view property (will never be null).

Throws:

TableException - If this is the first access to the view, the view will be created and any failure while doing so (e.g. InstantiationException) will be recast as a TableException. Creating the view involves seeding it with data from the table's model. This model query can also generate a TableException.

getWidth

public abstract int getWidth()

Returns the horizontal extent of the cell.

Returns:

The value of the width property in pixels.

See Also:

getDisplayedWidth()

isActivated

public boolean isActivated()

Returns true if the activeState is either ACTIVE_LIGHT or ACTIVE and false otherwise.

Returns:

The value of the activated property.

isDataInvalid

public boolean isDataInvalid()

Returns true if the cell contains invalid data and false otherwise. Implementation note: cell does not maintain its own invalid state, but instead delegates to "tableView.getInvalidCells().contains(this)".

Returns:

The value of the dataInvalid property.

isKeyHandled

public boolean isKeyHandled()

Returns the value of the keyHandled property. See processKeyEvent for more details.

Returns:

The value of the keyHandled property.

See Also:

setKeyHandled(boolean)

isLabel

public abstract boolean isLabel()

Returns true if the cell is a label and false otherwise.

Returns:

The value of the label property.

isModified

public boolean isModified()

Returns true if the cell contains modified data and false otherwise. Implementation note: cell does not maintain its own modified state, but instead delegates to "table.getModifiedCells().contains(this)".

Returns:

The value of the modified property.

See Also:

setModified(boolean)

isMouseCaptured

public boolean isMouseCaptured()

Returns true if the cell has captured the mouse and false otherwise.

Returns:

The value of the mouseCaptured property.

See Also:

setMouseCaptured(boolean)

isSelected

public boolean isSelected()

Returns true if the cell is selected in table and false otherwise. Implementation note: cell does not maintain its own selected state, but instead delegates to "tableView.isCellSelected(this)".

Returns:

The value of the selected property.

onGetFormattedData

protected java.lang.String onGetFormattedData()
                                       throws com.sas.table.TableException

Cell framework method for seeding the cell's view with formatted data from the table's model. Default implementation simply returns onGetObjectData().toString().

Returns:

Model supplied formatted data for cell.

Throws:

TableException - Propagated from call to model.

onGetObjectData

protected abstract java.lang.Object onGetObjectData()
                                             throws com.sas.table.TableException

Cell framework method for seeding the cell's view with data from the table's model.

Returns:

Model supplied data for cell.

Throws:

TableException - Propagated from call to model.

onGetTypes

protected abstract java.lang.String[] onGetTypes()
                                          throws com.sas.table.TableException

Cell framework method for initializing the cell's type(s) from the table's model.

Returns:

Model supplied types for cell.

Throws:

TableException - Propagated from call to model.

onPaintBackground

protected void onPaintBackground(java.awt.Graphics g,
                                 int width,
                                 int height)

Cell.paint framework method for painting the cell's background.

Parameters:

g - The graphics context to use for painting. Painting should be done relative to (0, 0).

width - The paintable width of the graphics context.

height - The paintable height of the graphics context.

onPaintBorder

protected void onPaintBorder(java.awt.Graphics g,
                             int width,
                             int height)

Cell.paint framework method for painting the cell's border. Called after onPaintForeground().

Parameters:

g - The graphics context to use for painting. Painting should be done relative to (0, 0).

width - The paintable width of the graphics context.

height - The paintable height of the graphics context.

onPaintForeground

protected void onPaintForeground(java.awt.Graphics g,
                                 int width,
                                 int height)
                          throws com.sas.table.TableException

Cell.paint framework method for painting the cell's foreground.

Parameters:

g - The graphics context to use for painting. Painting should be done relative to (0, 0).

width - The paintable width of the graphics context.

height - The paintable height of the graphics context.

Throws:

TableException - Can arise from a call to getView.

onWriteObjectData

protected abstract void onWriteObjectData()
                                   throws com.sas.table.TableException

Cell framework method for writing the cell's data to the table's model.

Throws:

TableException - Propagated from call to model.

paint

public void paint(java.awt.Graphics g)

Paints the cell.

Parameters:

g - The graphics context to use for painting.

processFocusEvent

public void processFocusEvent(java.awt.event.FocusEvent event)

Forwards a focus event to the cell's view. Subclasses can override to provide behavior that is independent of the cell's view.

Parameters:

event - The focus event.

processKeyEvent

public void processKeyEvent(java.awt.event.KeyEvent event)

Forwards a key event to the cell's view. Subclasses can override to provide behavior that is independent of the cell's view.

NOTE: Sets keyHandled to true before calling CellViewInterface.processKeyEvent. keyHandled-aware implementations of CellViewInterface can choose to set keyHandled to false in order to defer handling of the event to the table. For example, TextCell will do this for a right-arrow key event when the text cursor is already at the end of its text string, thus allowing the table to move to the next cell.

Parameters:

event - The key event.

processMouseEvent

public void processMouseEvent(java.awt.event.MouseEvent event)

Forwards a mouse event to the cell's view. Subclasses can override to provide behavior that is independent of the cell's view.

Parameters:

event - The mouse event. The event's point should be relative to the table's origin, not the cell's.

processMouseMotionEvent

public void processMouseMotionEvent(java.awt.event.MouseEvent event)

Forwards a mouse motion event to the cell's view. Subclasses can override to provide behavior that is independent of the cell's view.

Parameters:

event - The mouse motion event. The event's point should be relative to the table's origin, not the cell's.

refresh

public void refresh(int flags)

Refreshes the cell to its state as maintained by the table view's model. What gets refreshed -- data and/or style information -- is controlled by flags. Includes a call to repaint().

Specified by:

refresh in interface TableElementInterface

Overrides:

refresh in class TableElement

Parameters:

flags - Bitmask of REFRESH_DATA and/or REFRESH_STYLE.

repaint

public final void repaint()

Alias for "repaint (0, 0, getWidth(), getHeight())".

repaint

public void repaint(int x,
                    int y,
                    int width,
                    int height)

Repaints the specified rectangle of the cell. Nothing happens if displayed is false.

Parameters:

x - The x coordinate of the rectangle in pixels relative to the top-left corner of the cell.

y - The y coordinate of the rectangle in pixels relative to the top-left corner of the cell.

width - The width of the rectangle in pixels.

height - The height of the rectangle in pixels.

setActiveState

public final void setActiveState(int newValue)

Alias for "setActiveState (newValue, null)".

setActiveState

public void setActiveState(int newValue,
                           java.awt.Point point)

Sets the cell's activeState, i.e. it's degree or level of activation.

Note: this is designed to be called by TableView; independent calls will result in TableView's currentElement property getting out-of-sync.

Parameters:

newValue - The new value to assign the activeState property. Valid values are any of the values defined by CellActiveStates.

point - Optional xy-coordinate (relative to the table's origin) where the activation was initiated. Could be used to position a text cursor, for example.

See Also:

getActiveState()

setKeyHandled

public void setKeyHandled(boolean newValue)

Sets the value of the keyHandled property. See processKeyEvent for more details.

Parameters:

newValue - The new value to assign the keyHandled property.

See Also:

isKeyHandled()

setModified

public void setModified(boolean newValue)

Sets the value of the modified property.

Parameters:

newValue - The new value to assign the modified property.

See Also:

isModified()

setMouseCaptured

public void setMouseCaptured(boolean newValue)

Enables or disables mouse capture by the cell.

Parameters:

newValue - The new value to assign the mouseCaptured property.

See Also:

isMouseCaptured()

setObsolete

public void setObsolete()

Indicates that the cell should be considered obsolete. See TableElement.setObsolete() for a definition of "obsolete".

Specified by:

setObsolete in class TableElement

See Also:

TableElement.isTransient(), TableElement.equals(java.lang.Object)

writeObjectData

public void writeObjectData()
                     throws com.sas.table.TableException

Writes the cell's data to the table's model.

Throws:

TableException - Propagated from call to model.

See Also:

getObjectData()