ewe.data
Class FieldData

java.lang.Object
  ewe.data.FieldData

public class FieldData

extends Object

A FieldData class is used to specify information about a particular item of data stored in an Object and to transfer that data to and from the Object. Usually a FieldData refers directly to a member variable in a Class and so transferred by direct reads/writes to that variable. However a FieldData can also refer to an abstract field and a special _getSetField() method is used to read and write the data.

Apart from the specifics of the data itself a FieldData Object also holds information on a Header for the data (a more descriptive name), how the data is to be displayed or edited and even how big it should be by default on screen.

The fieldName must be of the form:

<fieldName>[$[<type>]]

fieldName must be a symbolic fieldName that should be of a form acceptable as a Java variable name. This means it must start with a letter or '_' and can then contain only numbers, letters and the '_' character.

The $ symbol at the end of the fieldName is used to specify the type of the field if the type cannot be determined through reflection discovery. For example if the data object does not have a variable with the specified field name (say it uses _getSetField() for data transfer instead) but does not provide the _getFieldType(String fieldName) method then there will be no way to determine the type of the field. The '$' character at the end of the field name either specifies that the field is a String (in which case NO characters follow the '$') or it is followed by a Java Type specifier.

A Java Type specifier is either one of the primitive types: 'Z'(boolean),'B'(byte),'C'(char),'S'(short),'I'(int),'D'(double),'J'(long),'F'(float) or an Object type: 'L<fully_qualified_class_name>;'(Object) or '[<Java Type>'(Array).

When using the 'L<fully_qualified_class_name>;' syntax you must use '/' instead of '.' as the package separator.

Examples:
fieldName - A field named "fieldName".
fieldName$ - A field that is of type String.
fieldName$I - A field that is of type int.
fieldName$Lewe/io/File; - A field that is of type ewe.io.File

Field Summary

int	alignment The alignment of the text of the data when displayed - by default it is UIConstants.LEFT.
int	anchor The anchor of the text of the data when displayed - by default it is UIConstants.WEST.
int	controlAnchor The anchor of any Control used to edit/display the data - by default it is UIConstants.WEST|UIConstants.EAST which stretches it horizontally to fill its conatainer.
Class	dataClass This is the Class of the Object that holds the data.
Control	display This is a Control that is used to display the data - it can be null in which case a default Control will be used.
boolean	editable This states whether the data is editable - by default it is true.
Control	editor This is a Control that is used to edit the data - it can be null in which case a default Control will be used.
Object	exampleObject This is possibly an actual instance of the Object that holds the data.
FieldTransfer	ft This does the work of transferring data to and from the Object.
String	header This is an optional descriptive name for the data which may be used as a prompt when the data is input, or as a column name when the data is stored or displayed in a Table.
int	height The approximate height of the data in characters when displayed/edited on screen.
int	hotKey An optional hot key for the data.
int	length The approximate length (width) of the data in characters when displayed/edited on screen.
int	maxWidth The maximum width in characters for the control - by default this is -1 which indicates no effective maximum.
int	minWidth The minimum width in characters for the control - by default this is 5.

Constructor Summary

FieldData()
Create an empty FieldData.

FieldData(FieldTransfer ft, String header)
Create a Field data using the specified FieldTransfer and header.

Method Summary

FieldData	decode(Object objectOrReflect, String properties) Given the properties (encoded as a String: e.g.
FieldData	decode(PropertyList pl) Decode the FieldData from a PropertyList containing properties that specify this FieldData.
boolean	equals(Object other) equals will check the equality of the field names.
Control	makeControl() Create and return a default Control for the FieldData.
static Vector	makeFieldsFromEncodedString(Object objectOrReflect, String headersAndFields, Vector destination) This method can be used to add fields to the destination Vector OR to modify fields already in the destination Vector.
static Vector	makeFieldsFromEncodedString(Object objectOrReflect, String headersAndFields, Vector destination, boolean decodeFormatOnly) This method can be used to add fields to the destination Vector OR to modify fields already in the destination Vector.
static Vector	makeFieldsFromProperties(Object objectOrReflect, String[] properties, Vector destination) Create a set of FieldData objects from a set of String encoded properties.
Control	newControl(String className) Try to create a Control given the specified class name.
Object	newInstance(String className) Try to create a new instance of a class, using the dataClass as the source to locate a possible separate ClassLoader.
void	setHeader(String newHeader) Set the header for the FieldData.
static MultiListSelect.SingleListSelect	toListSelect(Vector allFields, int[] initial)
String	toString() Return a String representation of this object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode

Field Detail

ft

public FieldTransfer ft

This does the work of transferring data to and from the Object. You never create this directly - it is created in the construction of the FieldData.

header

public String header

This is an optional descriptive name for the data which may be used as a prompt when the data is input, or as a column name when the data is stored or displayed in a Table.

length

public int length

The approximate length (width) of the data in characters when displayed/edited on screen. By default it is 15.

height

public int height

The approximate height of the data in characters when displayed/edited on screen. By default it is 1.

alignment

public int alignment

The alignment of the text of the data when displayed - by default it is UIConstants.LEFT.

anchor

public int anchor

The anchor of the text of the data when displayed - by default it is UIConstants.WEST.

controlAnchor

public int controlAnchor

The anchor of any Control used to edit/display the data - by default it is UIConstants.WEST|UIConstants.EAST which stretches it horizontally to fill its conatainer.

editable

public boolean editable

This states whether the data is editable - by default it is true.

editor

public Control editor

This is a Control that is used to edit the data - it can be null in which case a default Control will be used.

display

public Control display

This is a Control that is used to display the data - it can be null in which case a default Control will be used.

maxWidth

public int maxWidth

The maximum width in characters for the control - by default this is -1 which indicates no effective maximum.

minWidth

public int minWidth

The minimum width in characters for the control - by default this is 5.

dataClass

public Class dataClass

This is the Class of the Object that holds the data. You do not set this directly.

exampleObject

public Object exampleObject

This is possibly an actual instance of the Object that holds the data.

hotKey

public int hotKey

An optional hot key for the data.

Constructor Detail

FieldData

public FieldData()

Create an empty FieldData.

FieldData

public FieldData(FieldTransfer ft,
                 String header)

Create a Field data using the specified FieldTransfer and header.

Parameters:

ft - The FieldTransfer for the data.

header - The header for the data.

Method Detail

setHeader

public void setHeader(String newHeader)

Set the header for the FieldData. The specified header can be null in which case the fieldName for the FieldData is used to create a header.

Parameters:

newHeader - A header for the FieldData (can be null).

decode

public FieldData decode(Object objectOrReflect,
                        String properties)

Given the properties (encoded as a String: e.g. "field|lastName|header|Last Name|editable|false") for a FieldData and an example of the object to hold the data, decode the FieldData from a PropertyList object constructed from the two parameters. The source code is:

        PropertyList pl = new PropertyList();
        pl.setStrings(properties);
        pl.set("object",objectOrReflect);
        return decode(pl);

Parameters:

objectOrReflect - The data object or the Class/Reflect object representing the data object.

properties - the String encoded properties for the field.

Returns:

newInstance

public Object newInstance(String className)

Try to create a new instance of a class, using the dataClass as the source to locate a possible separate ClassLoader.

Parameters:

className - The name of the class to instantiate.

Returns:

The new object or null on failure.

newControl

public Control newControl(String className)

Try to create a Control given the specified class name.

Parameters:

className - The name of the class for the Control.

Returns:

The new Control or null on failure.

makeControl

public Control makeControl()

Create and return a default Control for the FieldData. Will return null on failure.

decode

public FieldData decode(PropertyList pl)

Decode the FieldData from a PropertyList containing properties that specify this FieldData.

The required properties are:

• "object" = Either an instance of the object that will hold the data, OR the java.lang.Class object for the object that will hold the data, OR the ewe.reflect.Reflect object for the object that will hold the data.
• "field" = The symbolic name of the field. See the Class documentation above on the format to use for a field name.

The optional properties are:

• "header" = The header for the data. This may end with "$K" where 'K' is a single character specifying the HotKey for the FieldData.
• "length" = The length(width) of the field in characters.
• "height" = The height of the field in characters.
• "alignment" = The alignment of text for the field. This should be "L" or "R".
• "anchor" = The anchor of the field. This should be a combination of: "W","E","N","S" (for west, east, north, south) and "H"(expand horizontally),"h"(shrink horizontally),"V"(expand vertically),"v"(shrink vertically),"F"(expand/shrink in all directions).
• "controlAnchor" = The anchor of the Control for displaying/editing the field. It should be of the same format as "anchor".
• "editor" = The class name of the control for editing the data.
• "display" = The class name of the control for displaying the data.
• "editable" = true or false specifying whether the data is editable on screen.

Parameters:

pl -

Returns:

this FieldData.

makeFieldsFromProperties

public static Vector makeFieldsFromProperties(Object objectOrReflect,
                                              String[] properties,
                                              Vector destination)

Create a set of FieldData objects from a set of String encoded properties. Each element of the properties array must be of the form: "field|lastName|header|Last Name|editable|false"

Parameters:

objectOrReflect - The data object or the Class/Reflect object representing the data object.

properties - a set of String encoded properties for each field.

destination - An optional destination Vector.

Returns:

The Vector containg the field data.

equals

public boolean equals(Object other)

equals will check the equality of the field names.

Overrides:

equals in class Object

Parameters:

other - Another object to compare to.

Returns:

true if this object is considered equal to the other object.

toString

public String toString()

Description copied from class: Object

Return a String representation of this object.

Overrides:

toString in class Object

Returns:

a String representing this object.

makeFieldsFromEncodedString

public static Vector makeFieldsFromEncodedString(Object objectOrReflect,
                                                 String headersAndFields,
                                                 Vector destination)

This method can be used to add fields to the destination Vector OR to modify fields already in the destination Vector. The format for each entry in headersAndFields is either:

[fieldName];[length[:height]];[flags];[alignment|anchor];[control anchor];[editor class]

separated by commas OR

[headerName]|[fieldName];[length[:height]];[flags];[alignment|anchor];[control anchor]

separated by '|' symbols.

[flags] should be a combination of: 'r' for Read-Only

[alignment] should be one of: L(left), R(right)

[anchor] should be one of: N(north), S(south), E(east), W(west), H(horizontal expand), h(horizontal shrink), V(vertical expand), v(vertical shrink), F(full fill)

Parameters:

objectOrReflect - The object being edited or the class of the object.

headersAndFields - The list of headers and fields with optional formatting info.

destination - A destination vector or null to start a new one.

Returns:

The vector containing a set of FieldData objects for each field.

makeFieldsFromEncodedString

public static Vector makeFieldsFromEncodedString(Object objectOrReflect,
                                                 String headersAndFields,
                                                 Vector destination,
                                                 boolean decodeFormatOnly)

This method can be used to add fields to the destination Vector OR to modify fields already in the destination Vector. The format for each entry in headersAndFields is either:

[fieldName];[length[:height]];[flags];[alignment|anchor];[control anchor]

separated by commas OR

[headerName]|[fieldName];[length[:height]];[flags];[alignment|anchor];[control anchor]

separated by '|' symbols.

[flags] should be a combination of: 'r' for Read-Only

[alignment] should be one of: L(left), R(right)

[anchor] should be one of: N(north), S(south), E(east), W(west), H(horizontal expand), h(horizontal shrink), V(vertical expand), v(vertical shrink), F(full fill)

Parameters:

objectOrReflect - The object being edited or the class of the object.

headersAndFields - The list of headers and fields with optional formatting info.

destination - A destination vector or null to start a new one.

decodeFormatOnly - if this is true then no FieldTransfer information will be created.

Returns:

The vector containing a set of FieldData objects for each field.

toListSelect

public static MultiListSelect.SingleListSelect toListSelect(Vector allFields,
                                                            int[] initial)