com.sssw.rt.event
Interface AgiPropertyValidationListener

All Superinterfaces:

EventListener

public interface AgiPropertyValidationListener

extends EventListener

The AgiPropertyValidationListener interface is implemented by objects that participate in the validation process for controls on a form or page. AgfForm and AgpPage both implement this interface automatically. This interface can be implemented with another object if it is necessary to perform more validation than the form or page can support, namely for dynamically created controls that are unknown to the form or page at design time.

Like any "listener" interface, AgiPropertyValidationListener works in conjunction with objects that have a corresponding method addAgiPropertyValidationListener(). The only object in the SilverStream environment that has this method is the binding manager, which is present as agDataMgr in any form or page.

If an object is added as an AgiPropertyValidationListener to the binding manager, it will be notified with validation events for all controls on the form or page. Validation events occur when control values are changed by the user.

Method Summary

void	validationFailed(AgoPropertyChangeEvent evt) Called when an attempted new value for a control has been determined to be invalid.
void	validationTest(AgoPropertyChangeEvent evt) Called when a control's value changes, either directly from user action or because of executed code.
void	valueChanged(AgoPropertyChangeEvent evt) Called when a control's value has changed, and the value has been accepted by all applicable validation tests.

Method Detail

validationTest

public void validationTest(AgoPropertyChangeEvent evt)
                    throws AgoValidationException

Called when a control's value changes, either directly from user action or because of executed code. Provides an opportunity to accept or reject the new value.

Parameters:

evt - an instance of an AgoPropertyChangeEvent, containing information about the old and new control values

Usage:

• evt.getSource() returns an object which is the control whose value is being tested.
• evt.getOldValue() returns the previous value of the control.
• evt.getNewValue() returns the putative new value of the control.

To reject the new value of the control, construct and throw an AgoValidationException with its disposition set to AgoValidationException.FAIL.

Note that the control will keep its rejected value, but the value will not be propagated to data sources or other controls that may be bound to the control.

See Also:

AgoValidationException, AgoPropertyChangeEvent, AgiPropertyValidationListener.validationFailed(AgoPropertyChangeEvent)

validationFailed

public void validationFailed(AgoPropertyChangeEvent evt)
                      throws AgoValidationException

Called when an attempted new value for a control has been determined to be invalid.

Parameters:

evt - an instance of an AgoPropertyChangeEvent

Usage:

The validationFailed() method supplies an AgoPropertyChangeEvent event object which may be used to obtain the source of then change, a validation failed message, or other information.

Note that the control will keep its rejected value, but the value will not be propagated to data sources or other controls that may be bound to the control.

See Also:

AgoPropertyChangeEvent, AgoValidationException, AgiPropertyValidationListener.validationTest(AgoPropertyChangeEvent)

valueChanged

public void valueChanged(AgoPropertyChangeEvent evt)

Called when a control's value has changed, and the value has been accepted by all applicable validation tests.

Parameters:

evt - an instance of an AgoPropertyChangeEvent

Usage:

The valueChanged() method is called after the value has been validated. If the value is not valid, the valueChanged() method is not called.

The source can be determined using the evt.getChangeSource() method. One of these constants is returned:

• SOURCE_USER - Indicates that the value was changed by an end-user action. This has an integer value of 1.
• SOURCE_PROG - Indicates that the value was changed by a SilverStream application program. This has an integer value of 2.

See Also:

AgoPropertyChangeEvent