com.sage.accpac.sm
Class ViewField

java.lang.Object
  com.sage.accpac.sm.ViewField

@ThreadSafe
public final class ViewField
extends java.lang.Object

Represents a field in an Accpac view FIXME documentation

Thread safety

Thread-safe

Nested Class Summary

static class	ViewField.ViewFieldPresentationType Indicates the type of presentation information defined for a field.
static class	ViewField.ViewFieldType Defines the possible data types of a view field.

Method Summary

int	getAttributes() Gets the view-specific boolean attributes of the field.
int	getDecimalPlaces() Gets the number of decimal places to which the number field will be stored.
java.lang.String	getDescription() Gets the description of the field.
int	getID() Gets the identifier of the field.
int	getLengthEstimate() Return a realistic length limit for this field.
int	getMaxDigits() Gets the maximum number of digits that will be stored.
int	getMaxLength() returns the maximum number of characters that might (but only might) fit in this field.
java.lang.Object	getMaxValue() Gets the maximum value allowed for this field The maximum value is based solely on the field type, without regard to business logic dictating whether the value is acceptable according to its context.
java.lang.Object	getMinValue() Gets the minimum value allowed for this field The minimum value is based solely on the field type, without regard to business logic dictating whether the value is acceptable according to its context.
java.lang.String	getName() Gets the name of the field.
int	getPrecision() Gets the precision of the field.
ViewFieldPresentationList	getPresentationList() Gets a ViewFieldPresentationList object that stores the presentation list defined for the field.
java.lang.String	getPresentationMask() Gets the presentation mask of the field that controls its display format.
ViewField.ViewFieldPresentationType	getPresentationType() Gets the presentation type of the field.
ViewField.ViewFieldType	getType() Gets the data type of the field
java.lang.Object	getValue() Get the current value of the field
View	getView() Gets the View object this field belongs to
boolean	hasDynamicPresentation() returns true if and only if the presentation of the field can change.
boolean	hasDynamicType() returns true if and only if the 'type' information of the field can change.
boolean	isEditable() returns true if and only if the value can be changed by the caller.
boolean	isEnabled() returns true if and only if the field can be meaningfully used.
boolean	isRequired() returns true if and only if the value must be changed interactively before the record can be inserted.
boolean	mightChange() returns true if and only if the value of the field might change non-interactively.
boolean	mustCheckEditable() returns true if and only if the caller must check regularly that the field is editable.
int	setToMax() Sets the field value to the maximum value
int	setToMin() Sets the field value to the minimum value
int	setValue(java.lang.Object newValue, boolean verify) Assign a new value to the field.
int	setValueOptionalField(java.lang.Object newValue, boolean verify, int length) Assign a new value to the field in an optional field.
boolean	wasChanged() returns true if and only if the value of the field has been changed since the last operation that retrieved or initialized the current record of the view

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getAttributes

public int getAttributes()

Gets the view-specific boolean attributes of the field.

This gets a bitmap of the up to 16 view-specific attributes that view implementers can assign a meaning to.

For the Accpac-specific attributes that relate to the viewAttribs function use the appropriate specific function below.

See Also:

hasDynamicPresentation(), hasDynamicType(), mightChange(), wasChanged(), isEditable(), isEnabled(), #isInKey(), isRequired(), mustCheckEditable()

getDecimalPlaces

public int getDecimalPlaces()

Gets the number of decimal places to which the number field will be stored.
This only applies to ViewFieldType.Decimal fields.

Returns:

the number of digits after the decimal point that will be stored.

Throws:

java.lang.UnsupportedOperationException - if the field is not a Decimal field.

getDescription

public java.lang.String getDescription()

Gets the description of the field. The description is localized according to the user's language preference/

getID

public int getID()

Gets the identifier of the field. The field identifiers are unique within the view.

This is frequently referred to in view documentation as the "field index".

getLengthEstimate

public int getLengthEstimate()

Return a realistic length limit for this field.
This is intended as an aid for user interface elements. It only provides an estimated length limit; strings longer than this limit may fit and strings shorter may fail to fit.
The complication is that for most character representation schemes these days the amount of space required to hold a given number of "characters" is dependent upon what the characters actually are. For example if the underlying A4wapi core is using one of the Chinese DBCS code pages (e.g. CP936 or CP950) and the field is a description field (e.g. an IC Item description) with space for 60 bytes that can hold 60 ASCII characters or 30 Chinese characters in the double-byte range or perhaps 30 ASCII plus 15 Chinese etc.
This function will ensure that the same value is returned every time it is called for this field during a given process. However it may return different answers when run in different processes.
The returned value is the number of Unicode characters that might reasonably fit in the given space. This is defined to be in terms of true Unicode characters (as if encoded in UCS-4 currently). Since Java uses a (modified) UTF-16 encoding this will be smaller than the number of "char" type elements needed to store it if the character is not in the Basic Multilingual Plane.

Returns:

an estimate of the number of Unicode characters that will fit in the field

Throws:

java.lang.UnsupportedOperationException - if this field is not a character field

See Also:

hasDynamicType(), getMaxLength()

getMaxLength

public int getMaxLength()

returns the maximum number of characters that might (but only might) fit in this field.

This is the largest number of characters (Unicode Code Points) that could possibly fit in the field. It is always possible that a string of this length will not fit.

See the description of getLengthEstimate() for a discussion of the influence of character encoding.

Returns:

the maximum number of characters that might (but only might) fit.

Throws:

java.lang.UnsupportedOperationException - if this field is not a character field

See Also:

getLengthEstimate()

getMaxDigits

public int getMaxDigits()

Gets the maximum number of digits that will be stored.
This only applies to ViewFieldType.Decimal fields.
This is the total number of digits, including those before and after the decimal point. See getDecimalPlaces for how many of them are after the decimal point.

Returns:

the number of digits permitted.

Throws:

java.lang.UnsupportedOperationException - if the field is not a Decimal field.

getMaxValue

public java.lang.Object getMaxValue()

Gets the maximum value allowed for this field The maximum value is based solely on the field type, without regard to business logic dictating whether the value is acceptable according to its context. If the field uses a presentation list and is enabled the maximum value is the value of the last presentation item in the list.

getMinValue

public java.lang.Object getMinValue()

Gets the minimum value allowed for this field The minimum value is based solely on the field type, without regard to business logic dictating whether the value is acceptable according to its context. If the field uses a presentation list and is enabled the minimum value is the value of the first presentation item in the list.

getName

public java.lang.String getName()

Gets the name of the field. Field names are unique within the view.

getPrecision

public int getPrecision()

Gets the precision of the field.
Obsolete. Use getDecimalPlaces().

getPresentationList

public ViewFieldPresentationList getPresentationList()

Gets a ViewFieldPresentationList object that stores the presentation list defined for the field. Returns null if the field does not have a presentation list.

See Also:

hasDynamicPresentation(), getPresentationType()

getPresentationMask

public java.lang.String getPresentationMask()

Gets the presentation mask of the field that controls its display format. This is an empty string if the field does not use a presentation mask.

See Also:

hasDynamicPresentation(), getPresentationType()

getPresentationType

public ViewField.ViewFieldPresentationType getPresentationType()

Gets the presentation type of the field.

See Also:

hasDynamicPresentation(), getPresentationMask(), getPresentationList()

getType

public ViewField.ViewFieldType getType()

Gets the data type of the field

getValue

public java.lang.Object getValue()

Get the current value of the field

getView

public View getView()

Gets the View object this field belongs to

hasDynamicPresentation

public boolean hasDynamicPresentation()

returns true if and only if the presentation of the field can change.

This is true if the field has a mask and the mask may change, or if the field has a presentation list and that list may change.

It would be very unusual for the presentation type itself to change.

See Also:

getPresentationType(), getPresentationMask(), getPresentationList()

hasDynamicType

public boolean hasDynamicType()

returns true if and only if the 'type' information of the field can change.

Typically this means that the precision of a decimal type may change.

See Also:

getDecimalPlaces(), getLengthEstimate()

isEditable

public boolean isEditable()

returns true if and only if the value can be changed by the caller.

If mustCheckEditable() is true then this property can change but if it returns false then the property will remain the same.

See Also:

mustCheckEditable(), FieldChangeEvent.isEditable()

isEnabled

public boolean isEnabled()

returns true if and only if the field can be meaningfully used.

If this returns false most field operations are not permitted and will result in an exception being thrown.

See Also:

FieldChangeEvent.isEnabled()

isRequired

public boolean isRequired()

returns true if and only if the value must be changed interactively before the record can be inserted.

See Also:

FieldChangeEvent.isRequired()

mightChange

public boolean mightChange()

returns true if and only if the value of the field might change non-interactively.

Clearly if this is true then isEditable() is false.

mustCheckEditable

public boolean mustCheckEditable()

returns true if and only if the caller must check regularly that the field is editable.

If this returns true then the caller must use isEditable() regularly to check that the field is still editable as that can change at any time. If this returns false then the result of isEditable() will not change during the time the view is open and so the isEditable result can be cached.

See Also:

isEditable()

setToMax

public int setToMax()

Sets the field value to the maximum value

setToMin

public int setToMin()

Sets the field value to the minimum value

setValue

public int setValue(java.lang.Object newValue,
                    boolean verify)

Assign a new value to the field. The caller must also specify whether the new value should be validated by the view. If the value is not acceptable then the method will return ViewException.FieldInvalid.
This method will return the status code for a large number of errors but will throw an exception for the more technical ones.

setValueOptionalField

public int setValueOptionalField(java.lang.Object newValue,
                                 boolean verify,
                                 int length)

Assign a new value to the field in an optional field. The caller must also specify whether the new value should be validated by the view. If the value is not acceptable then the method will return ViewException.FieldInvalid.
This method will return the status code for a large number of errors but will throw an exception for the more technical ones.
For an optional field the field width may actually be shorter than the advertised length

Parameters:

newValue - the value to which the field will be set

verify - whether the value should be verified. (NB some verification may also occur even if this is false)

length - the length to assume

Returns:

true if successful, false if unsuccessful in normal ways

Throws:

StringTooLongException - if the value is or is converted to a string and the string does not fit in the bytes provided

UncheckedCharacterCodingException - if the value is or is converted to a string and there is a coding problem with the string (such as wrong character set)

wasChanged

public boolean wasChanged()

returns true if and only if the value of the field has been changed since the last operation that retrieved or initialized the current record of the view