jimm.datavision.field
Class Field

java.lang.Object
  java.util.Observable
      jimm.datavision.Element
          jimm.datavision.field.Field

All Implemented Interfaces:

java.lang.Cloneable, java.util.Observer, Draggable, Identity, Writeable

Direct Known Subclasses:

AggregateField, ColumnField, FormulaField, ImageField, ParameterField, SpecialField, SubreportField, TextField, UserColumnField

public abstract class Field
extends Element
implements Identity, Draggable, java.lang.Cloneable

The abstract superclass of visual report fields that display text labels, database columns, special values, aggregate values, formulas, and parameters. A field has a bounds Rectangle that determines its position within a section and an associated Format and Border for determining how to display the field.

To avoid repeated font size and line width calculations, a FormattedValueCache holds the formatted version of this field's value.

Author:

Jim Menard, jimm@io.com

Field Summary

protected Border	border
protected Rectangle	bounds
protected FormattedValueCache	cache
static double	DEFAULT_HEIGHT
static double	DEFAULT_WIDTH
protected Format	format
protected java.lang.Long	id
(package private) static java.lang.Long	maxIdSeen
protected java.lang.Object	value

Fields inherited from class jimm.datavision.Element

report, section, visible

Constructor Summary

protected

Field(java.lang.Long id, Report report, Section section, java.lang.Object value, boolean visible) Constructor.

Method Summary

boolean	canBeAggregated() Returns true if this field can be aggregated.
java.lang.Object	clone() Returns a clone.
static Field	create(java.lang.Long id, Report report, Section section, java.lang.String type, java.lang.Object value, boolean visible) This factory method constructs and returns a new instance of a subclass of Field based on the type string.
static Field	createFromDragString(Report report, java.lang.String str) Creates a field from a drag string.
java.lang.String	designLabel() Returns a string representing the field in the GUI during report design.
abstract java.lang.String	dragString() Returns the string used to identify a field type when dragging.
protected void	finalize()
abstract java.lang.String	formulaString() Returns a string representing the field as it appears in a formula.
Border	getBorder() Returns the border for this field.
Border	getBorderOrDefault() Returns the border for this field or, if it is null, the report's default border.
Rectangle	getBounds() Returns the bounds rectangle for this field.
Format	getFormat() Returns the format for this field.
java.lang.Object	getId() Returns the identity.
double	getOutputHeight() Returns the height needed to output the current value of this field.
java.lang.Object	getValue() Returns the value for this field.
FieldWidget	makeWidget(SectionWidget sw) Returns a new widget of the appropriate FieldWidget subclass for this field.
boolean	refersTo(Field f) Returns true if this field contains a reference to the specified field.
boolean	refersTo(Formula f) Returns true if this field contains a reference to the specified formula.
boolean	refersTo(Parameter p) Returns true if this field contains a reference to the specified parameter.
boolean	refersTo(UserColumn uc) Returns true if this field contains a reference to the specified user column.
void	setBorder(Border newBorder) Sets the border.
void	setBounds(Rectangle newBounds) Sets the bounds rectangle.
void	setFormat(Format newFormat) Sets the format.
void	setValue(java.lang.Object newValue) Sets the value.
java.lang.String	toString() Returns this fields formatted value, ready for display in the report.
abstract java.lang.String	typeString() Returns the string that specifies this field's type in the report XML.
void	update(java.util.Observable o, java.lang.Object arg)
protected void	writeFieldGuts(XMLWriter out) Writes objects contained within this field (bounds, border, and format).
void	writeXML(XMLWriter out) Writes this field as an XML tag.

Methods inherited from class jimm.datavision.Element

getReport, getSection, isVisible, setSection, setVisible

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_WIDTH

public static final double DEFAULT_WIDTH

See Also:

Constant Field Values

DEFAULT_HEIGHT

public static final double DEFAULT_HEIGHT

See Also:

Constant Field Values

maxIdSeen

static java.lang.Long maxIdSeen

id

protected java.lang.Long id

bounds

protected Rectangle bounds

format

protected Format format

border

protected Border border

value

protected java.lang.Object value

cache

protected FormattedValueCache cache

Constructor Detail

Field

protected Field(java.lang.Long id,
                Report report,
                Section section,
                java.lang.Object value,
                boolean visible)

Constructor.

Parameters:

id - the unique identifier for the new field

report - the report containing this element

section - the report section containing the field

value - the value this field represents visually

visible - show/hide flag

Method Detail

create

public static Field create(java.lang.Long id,
                           Report report,
                           Section section,
                           java.lang.String type,
                           java.lang.Object value,
                           boolean visible)

This factory method constructs and returns a new instance of a subclass of Field based on the type string.

If id is null, generates a new id number. This number is one higher than any previously-seen id number. This does not guarantee that no later field will be created manually with the same id number.

Parameters:

id - the unique identifier for the new field; if null, generate a new id

section - the report section containing the field

type - one of "special", "text", "column", "formula", "parameter", "image", or one of the aggregate function names; found in report XML

createFromDragString

public static Field createFromDragString(Report report,
                                         java.lang.String str)

Creates a field from a drag string. str should a string created by some field's dragString() method.

Parameters:

report - the report containing this element

str - a drag string

Returns:

a new field

clone

public java.lang.Object clone()

Returns a clone. Subclasses may need ot override this method to copy additional instance variables that are not set in their constructors.

Overrides:

clone in class java.lang.Object

Returns:

an almost-ready clone of this object

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

update

public void update(java.util.Observable o,
                   java.lang.Object arg)

Specified by:

update in interface java.util.Observer

Overrides:

update in class Element

getId

public java.lang.Object getId()

Description copied from interface: Identity

Returns the identity.

Specified by:

getId in interface Identity

getBounds

public Rectangle getBounds()

Returns the bounds rectangle for this field.

Returns:

the bounds rectangle

setBounds

public void setBounds(Rectangle newBounds)

Sets the bounds rectangle.

Parameters:

newBounds - the new bounds rectangle

getOutputHeight

public double getOutputHeight()

Returns the height needed to output the current value of this field. This default implementation returns the height of the field as defined in the report designer (the bounds height).

getFormat

public Format getFormat()

Returns the format for this field. May return null.

Returns:

the format, possibly null

setFormat

public void setFormat(Format newFormat)

Sets the format. If this field already has a format, you can just modify it instead of giving it a completely new one.

Parameters:

newFormat - the format

getBorder

public Border getBorder()

Returns the border for this field. May return null.

Returns:

the border, possibly null

getBorderOrDefault

public Border getBorderOrDefault()

Returns the border for this field or, if it is null, the report's default border. If we return the default border, we clone it in order to give it this field.

Returns:

this field's border or the default border

setBorder

public void setBorder(Border newBorder)

Sets the border.

Parameters:

newBorder - the new border

getValue

public java.lang.Object getValue()

Returns the value for this field. May return null.

Returns:

the value, possibly null

setValue

public void setValue(java.lang.Object newValue)

Sets the value.

Parameters:

newValue - the new value

makeWidget

public FieldWidget makeWidget(SectionWidget sw)

Returns a new widget of the appropriate FieldWidget subclass for this field. Subclasses override this method to return different types of widgets.

Parameters:

sw - a field widget

typeString

public abstract java.lang.String typeString()

Returns the string that specifies this field's type in the report XML.

Returns:

a string representing this field's type; used in XML files

dragString

public abstract java.lang.String dragString()

Returns the string used to identify a field type when dragging. Usually returns typeString() plus a value or an id.

Specified by:

dragString in interface Draggable

Returns:

the string used to identify the field when dragging

designLabel

public java.lang.String designLabel()

Returns a string representing the field in the GUI during report design.

Returns:

a string useful for display in the design GUI

formulaString

public abstract java.lang.String formulaString()

Returns a string representing the field as it appears in a formula.

Returns:

a string useful in a formula

refersTo

public boolean refersTo(Field f)

Returns true if this field contains a reference to the specified field. Most fields return false; only a AggregateField or FormulaField would return true.

Parameters:

f - a field

Returns:

true if this field contains a reference to the specified field

refersTo

public boolean refersTo(Formula f)

Returns true if this field contains a reference to the specified formula. Most fields return false; only a AggregateField or FormulaField would return true.

Parameters:

f - a formula

Returns:

true if this field contains a reference to the specified field

refersTo

public boolean refersTo(UserColumn uc)

Returns true if this field contains a reference to the specified user column. Most fields return false; only a AggregateField, UserColumnField, or FormulaField would return true.

Parameters:

uc - a user column

Returns:

true if this field contains a reference to the specified user column

refersTo

public boolean refersTo(Parameter p)

Returns true if this field contains a reference to the specified parameter. Most fields return false; only a AggregateField or FormulaField would return true.

Parameters:

p - a parameter

Returns:

true if this field contains a reference to the specified field

canBeAggregated

public boolean canBeAggregated()

Returns true if this field can be aggregated. This method returns false by default but is overridded by classes whose values may be aggregated.

Returns:

true if this field can be aggregated

toString

public java.lang.String toString()

Returns this fields formatted value, ready for display in the report. If this field is invisible, or getValue returns null then this method will return null.

Overrides:

toString in class java.lang.Object

Returns:

the report display string; may be null

writeXML

public void writeXML(XMLWriter out)

Writes this field as an XML tag. Writes bounds, border, and format.

Specified by:

writeXML in interface Writeable

Specified by:

writeXML in class Element

Parameters:

out - a writer that knows how to write XML

writeFieldGuts

protected void writeFieldGuts(XMLWriter out)

Writes objects contained within this field (bounds, border, and format).

Parameters:

out - a writer that knows how to write XML