jimm.datavision.field
Class Field

java.lang.Object
  extended by java.util.Observable
      extended by jimm.datavision.Element
          extended by 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