com.sage.accpac.sm
Class ViewField

java.lang.Object
  com.sage.accpac.sm.view.AbstractGettable
      com.sage.accpac.sm.view.AbstractSettable
          com.sage.accpac.sm.ViewField

All Implemented Interfaces:

Gettable, HasFieldAttributes, HasFieldIdentity, HasFieldLimits, HasPresentation, HasPresentationAttributes, IViewField, Settable

@ThreadSafe
public class ViewField
extends AbstractSettable
implements IViewField

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.

Constructor Summary

protected

ViewField(View view, int index, int id, java.lang.String name) The only constructor.

Method Summary

protected void	confirmValid() confirms that the instance is still valid, throwing some sort of RuntimeException otherwise.
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 field index.
IView	getIView() Gets the IView object to which this field belongs
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() Deprecated. Use getDecimalPlaces().
ViewFieldPresentationList	getPresentationList() Gets a ViewFieldPresentationList that represents 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() gets the value of the given field.
View	getView() Gets the View object to which this field belongs
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) sets the value of the given 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 com.sage.accpac.sm.view.AbstractSettable

setBigDecimal, setBigDecimal, setBoolean, setBoolean, setBytes, setBytes, setDate, setDate, setDouble, setDouble, setInt, setInt, setShort, setShort, setString, setString, setTime, setTime, setValue

Methods inherited from class com.sage.accpac.sm.view.AbstractGettable

getBigDecimal, getBoolean, getBytes, getDate, getDouble, getInt, getShort, getString, getTime

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.sage.accpac.sm.view.Settable

setBigDecimal, setBigDecimal, setBoolean, setBoolean, setBytes, setBytes, setDate, setDate, setDouble, setDouble, setInt, setInt, setShort, setShort, setString, setString, setTime, setTime, setValue

Methods inherited from interface com.sage.accpac.sm.view.Gettable

getBigDecimal, getBoolean, getBytes, getDate, getDouble, getInt, getShort, getString, getTime

Constructor Detail

ViewField

protected ViewField(View view,
                    int index,
                    int id,
                    java.lang.String name)

The only constructor. The A4wapi must already be locked.

Parameters:

view - the view that this is a field under

index - the zero-based index of the field in the view

id - the id; the unique identifier for the field

name - the name of the field

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.

Specified by:

getAttributes in interface HasFieldAttributes

Returns:

an integer containing a bitmap of the view-specific boolean attributes of the field

See Also:

HasPresentationAttributes.hasDynamicPresentation(), HasFieldAttributes.hasDynamicType(), HasFieldAttributes.mightChange(), HasFieldAttributes.wasChanged(), HasFieldAttributes.isEditable(), HasFieldAttributes.isEnabled(), HasFieldAttributes.isRequired(), HasFieldAttributes.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.

Specified by:

getDecimalPlaces in interface HasFieldAttributes

Returns:

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

getDescription

public java.lang.String getDescription()

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

Specified by:

getDescription in interface HasFieldIdentity

Returns:

a non-null String containing the description of the field

getID

public int getID()

Gets the field index. The field indexes are unique within the view.

Specified by:

getID in interface HasFieldIdentity

Returns:

the field index

getIView

public IView getIView()

Gets the IView object to which this field belongs

Specified by:

getIView in interface IViewField

Returns:

the IView to which this field belongs

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.

Specified by:

getLengthEstimate in interface HasFieldAttributes

Returns:

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

See Also:

HasFieldAttributes.hasDynamicType(), HasFieldAttributes.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 HasFieldAttributes.getLengthEstimate() for a discussion of the influence of character encoding.

Specified by:

getMaxLength in interface HasFieldAttributes

Returns:

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

See Also:

HasFieldAttributes.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.

Specified by:

getMaxDigits in interface HasFieldAttributes

Returns:

the number of digits permitted.

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.

Specified by:

getMaxValue in interface HasFieldLimits

Returns:

the maximum value possible for this kind of field

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.

Specified by:

getMinValue in interface HasFieldLimits

Returns:

the minimum value possible for this kind of field

getName

public java.lang.String getName()

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

Specified by:

getName in interface HasFieldIdentity

Returns:

the name of the field

See Also:

HasFieldIdentity.getID()

getPrecision

@Deprecated
public int getPrecision()

Deprecated. Use getDecimalPlaces().

Gets the precision of the field.

Returns:

the precision of the field

getPresentationList

public ViewFieldPresentationList getPresentationList()

Gets a ViewFieldPresentationList that represents the presentation list defined for the field. If HasPresentationAttributes.hasDynamicPresentation() is true, indicating the presentation list is dynamic, the presentation list will first be refreshed (by calling ViewFieldPresentationList.refresh()) from the view before being returned. Returns null if the field does not have a presentation list.

If overriding this method, ensure that the HasPresentationAttributes.hasDynamicPresentation() and HasPresentation.getPresentationType() methods are compatible, overriding them if you need to.

Specified by:

getPresentationList in interface HasPresentation

Returns:

a ViewFieldPresentationList for the field, or a null reference

See Also:

HasPresentationAttributes.hasDynamicPresentation(), HasPresentation.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.

Specified by:

getPresentationMask in interface HasPresentation

Returns:

the presentation mask of the field, or an empty string

See Also:

HasPresentationAttributes.hasDynamicPresentation(), HasPresentation.getPresentationType()

getPresentationType

public ViewField.ViewFieldPresentationType getPresentationType()

Gets the presentation type of the field.

Specified by:

getPresentationType in interface HasPresentation

Returns:

the presentation type of the field

See Also:

HasPresentationAttributes.hasDynamicPresentation(), HasPresentation.getPresentationMask(), HasPresentation.getPresentationList()

getType

public ViewField.ViewFieldType getType()

Gets the data type of the field

Specified by:

getType in interface HasFieldAttributes

Returns:

a ViewField.ViewFieldType representing the type of the field

getValue

public java.lang.Object getValue()

gets the value of the given field. The exact type returned depends upon the field.

Specified by:

getValue in interface Gettable

Specified by:

getValue in class AbstractGettable

Returns:

an Object containing the value, or a null reference if the value of the field is null

See Also:

Gettable

getView

public View getView()

Gets the View object to which this field belongs

Returns:

the View to which this field belongs

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.

Specified by:

hasDynamicPresentation in interface HasPresentationAttributes

Returns:

true if, and only if, the presentation of the field can change during the life of the field object

See Also:

HasPresentation.getPresentationType(), HasPresentation.getPresentationMask(), HasPresentation.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.

Specified by:

hasDynamicType in interface HasFieldAttributes

Returns:

true if, and only if, the type information of the field can change

See Also:

HasFieldAttributes.getDecimalPlaces(), HasFieldAttributes.getLengthEstimate()

isEditable

public boolean isEditable()

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

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

Specified by:

isEditable in interface HasFieldAttributes

Returns:

true if, and only if, the value can be changed by the caller

See Also:

HasFieldAttributes.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.

Specified by:

isEnabled in interface HasFieldAttributes

Returns:

true if, and only if, the field can currently be meaningfully used

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.

Specified by:

isRequired in interface HasFieldAttributes

Returns:

true if, and only if, the value must be set 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 HasFieldAttributes.isEditable() is false.

Specified by:

mightChange in interface HasFieldAttributes

Returns:

true if, and only if, the field might change automatically

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 HasFieldAttributes.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 HasFieldAttributes.isEditable() will not change during the time the view is open and so the isEditable result can be cached.

Specified by:

mustCheckEditable in interface HasFieldAttributes

Returns:

true if the caller must check the editable setting regularly

See Also:

HasFieldAttributes.isEditable()

setToMax

public int setToMax()

Sets the field value to the maximum value

Specified by:

setToMax in interface HasFieldLimits

Returns:

the status of the call.

• 0 on total success
• 10 (OLD_ERRNUM_WARNING) if the view returned it
• <0 (a warning) if the view returned it
• ViewException.FieldInvalid if the view stated the field id is not valid
• ViewException.FieldDisabled if the view stated that the field was disabled
• ViewException.FieldReadonly if the view stated that the field was Read-only

setToMin

public int setToMin()

Sets the field value to the minimum value

Specified by:

setToMin in interface HasFieldLimits

Returns:

the status of the call.

• 0 on total success
• 10 (OLD_ERRNUM_WARNING) if the view returned it
• <0 (a warning) if the view returned it
• ViewException.FieldInvalid if the view stated the field id is not valid
• ViewException.FieldDisabled if the view stated that the field was disabled
• ViewException.FieldReadonly if the view stated that the field was Read-only

setValue

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

sets the value of the given field. The exact type of the value depends upon the type of field.

Specified by:

setValue in interface Settable

Parameters:

newValue - the value to which the field is to be set

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

Returns:

the view return code from the operation, as documented above

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:

the status of the call.

• 0 on total success
• 10 (OLD_ERRNUM_WARNING) if the view returned it
• <0 (a warning) if the view returned it
• ViewException.FieldInvalid if the view stated the field id is not valid
• ViewException.FieldDisabled if the view stated that the field was disabled
• ViewException.FieldReadonly if the view stated that the field was Read-only

Throws:

ViewException - if an error occurred other than those permitted errors listed in the return values. Call ViewException.getReason() to get the error code.

StringTooLongException - if the value is or is converted to a string and the string does not fit in the bytes provided by the field. Query the exception to find out how much would fit.

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 or damaged string).

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

Specified by:

wasChanged in interface HasFieldAttributes

Returns:

true if, and only if, the field value has changed

confirmValid

protected void confirmValid()

confirms that the instance is still valid, throwing some sort of RuntimeException otherwise.

Throws:

java.lang.RuntimeException

See Also:

ViewKey.confirmValid()