public class FormController extends Object implements WindowListener, FormFocusListener, FormActionListener
A base class for form controllers.
The form builder library follows the MVC paradigm when dealing with forms:
BindingStrategy
.This class provides a fully functional controller implementation, which handles all phases of the form's life-cycle. It can be used out of the box. In most cases adaptation to a specific application's needs is possible by configuring some of the helper objects used by this class. This way for instance the validation handling can be changed or the way fields containing invalid data are displayed. Refer to the documentation of the corresponding set methods for further details.
One of the main tasks of this class is to ensure that input validation is
performed when necessary. When clicking the OK button, a
validation has to be performed in any case. But it is also possible to
perform validation earlier, e.g. when the user left an input field. This can
be achieved by configuring a corresponding FormValidationTrigger
.
A FieldMarker
is used for defining the appearance of input
fields depending on their validation status.
Implementation note: This class is not thread-safe. It is intended to be associated with a single form instance and not to be used concurrently with multiple forms or threads.
Constructor and Description |
---|
FormController()
Creates a new instance of
FormController . |
Modifier and Type | Method and Description |
---|---|
void |
actionPerformed(FormActionEvent e)
Processes action events.
|
void |
addFieldStatusListener(FormControllerFieldStatusListener l)
Adds a
FormControllerFieldStatusListener to this controller. |
void |
addFormListener(FormControllerFormListener l)
Adds a
FormControllerFormListener to this controller. |
void |
addValidationListener(FormControllerValidationListener l)
Adds a
FormControllerValidationListener to this controller. |
protected void |
cancelButtonClicked(FormActionEvent event)
The cancel button was clicked.
|
protected void |
closeForm()
Closes the associated form.
|
protected MessageOutput |
fetchMessageOutput()
Returns the current
MessageOutput object. |
protected String |
fetchValidationMessageBoxCaption()
Returns the caption for a message box for displaying validation error
messages.
|
protected FormValidationMessageFormat |
fetchValidationMessageFormat()
Obtains the
FormValidationMessageFormat object to be used. |
protected void |
fireFieldStatusEvent(String fieldName)
Notifies all registered field status listeners about a change in the
status of a field.
|
protected void |
fireFormEvent()
Notifies all registered form listeners that the form has been closed.
|
protected void |
fireValidationEvent(FormValidatorResults results)
Notifies all registered validation listeners about a validation
operation.
|
void |
focusGained(FormFocusEvent e)
A component of the associated window was given the focus.
|
void |
focusLost(FormFocusEvent e)
A component of the associated window lost the focus.
|
String |
getBtnCancelName()
Returns the name of the component representing the cancel button.
|
String |
getBtnOkName()
Returns the name of the component representing the OK button.
|
protected BuilderData |
getBuilderData()
Returns the current
BuilderData object. |
Command |
getCancelCommand()
Returns the command to be executed when the form is canceled.
|
ComponentBuilderData |
getComponentBuilderData()
Returns the
ComponentBuilderData object. |
FormControllerFieldStatusListener[] |
getFieldStatusListeners()
Returns an array with all
FormControllerFieldStatusListener
objects registered at this FormController . |
Form |
getForm()
Returns the current form.
|
Object |
getFormBean()
Returns the current form bean.
|
FormControllerFormListener[] |
getFormListeners()
Returns an array with all
FormControllerFormListener objects
registered at this FormController . |
FormValidator |
getFormValidator()
Returns a
FormValidator for validating the associated form. |
FormValidatorResults |
getLastValidationResults()
Returns the results of the last validation operation.
|
MessageOutput |
getMessageOutput()
Returns the
MessageOutput object to be used by this
controller. |
Command |
getOkCommand()
Returns the command to be executed when the form is closed in reaction of
the OK button.
|
FormControllerValidationListener[] |
getValidationListeners()
Returns an array with all
FormControllerValidationListener
objects registered at this FormController . |
String |
getValidationMessageBoxCaption()
Returns the caption of the message box for displaying validation error
messages.
|
FormValidationMessageFormat |
getValidationMessageFormat()
Returns the
FormValidationMessageFormat object to be used
by this controller. |
FormValidationTrigger |
getValidationTrigger()
Returns the
FormValidationTrigger . |
Window |
getWindow()
Returns the associated window.
|
WindowBuilderData |
getWindowBuilderData()
Returns the
WindowBuilderData object. |
protected boolean |
isCommitted()
Returns a flag whether the form was committed.
|
boolean |
isFieldVisited(String name)
Tests whether the field with the given name has already been visited by
the user.
|
protected void |
okButtonClicked(FormActionEvent event)
The OK button was clicked.
|
void |
removeFieldStatusListener(FormControllerFieldStatusListener l)
Removes the specified
FormControllerFieldStatusListener from this
controller. |
void |
removeFormListener(FormControllerFormListener l)
Removes the specified
FormControllerFormListener from this
controller. |
void |
removeValidationListener(FormControllerValidationListener l)
Removes the specified
FormControllerValidationListener from this
controller. |
void |
setBtnCancelName(String btnCancelName)
Sets the name of the component representing the cancel button.
|
void |
setBtnOkName(String btnOkName)
Sets the name of the component representing the OK button.
|
void |
setCancelCommand(Command cancelCommand)
Sets the command to be executed when the form is canceled.
|
void |
setComponentBuilderData(ComponentBuilderData componentBuilderData)
Sets the
ComponentBuilderData object. |
void |
setFormValidator(FormValidator formValidator)
Sets a
FormValidator for the the associated form. |
void |
setMessageOutput(MessageOutput messageOutput)
Sets the
MessageOutput object to be used by this controller. |
void |
setOkCommand(Command okCommand)
Sets the command to be executed when the form is closed in reaction of
the OK button.
|
void |
setValidationMessageBoxCaption(String validationMessageBoxCaption)
Sets the caption of the message box for displaying validation error
messages.
|
void |
setValidationMessageFormat(FormValidationMessageFormat validationMessageFormat)
Sets the
FormValidationMessageFormat object to be used by
this controller. |
void |
setValidationTrigger(FormValidationTrigger validationTrigger)
Sets the
FormValidationTrigger . |
void |
setWindowBuilderData(WindowBuilderData windowBuilderData)
Sets the
WindowBuilderData object. |
FormValidatorResults |
validate()
Performs a validation of the associated form.
|
FormValidatorResults |
validateAndDisplayMessages()
Performs a validation of the associated form and displays validation
messages if this is not successful.
|
void |
windowActivated(WindowEvent event)
Dummy implementation of this window event.
|
void |
windowClosed(WindowEvent event)
The associated window was closed.
|
void |
windowClosing(WindowEvent event)
Dummy implementation of this window event.
|
void |
windowDeactivated(WindowEvent event)
Dummy implementation of this window event.
|
void |
windowDeiconified(WindowEvent event)
Dummy implementation of this window event.
|
void |
windowIconified(WindowEvent event)
Dummy implementation of this window event.
|
void |
windowOpened(WindowEvent event)
The window containing the associated form was opened.
|
public ComponentBuilderData getComponentBuilderData()
ComponentBuilderData
object.public void setComponentBuilderData(ComponentBuilderData componentBuilderData)
ComponentBuilderData
object. This object must
have been set before an instance of this class can be used. It allows
access to all components involved and the current form as well.componentBuilderData
- the component builder data objectpublic WindowBuilderData getWindowBuilderData()
WindowBuilderData
object.public void setWindowBuilderData(WindowBuilderData windowBuilderData)
WindowBuilderData
object. This object must have
been set before an instance of this class can be used. It allows access
to important information about the current window including its form
bean.windowBuilderData
- the window builder data objectpublic FormValidator getFormValidator()
FormValidator
for validating the associated form.
Result can be null if no specific FormValidator
was set.
Note that the result of this method need not always be in sync with the
object returned by Form.getFormValidator()
: this method always
returns the object that was set on a previous
setFormValidator(FormValidator)
call.FormValidator
setFormValidator(FormValidator)
public void setFormValidator(FormValidator formValidator)
FormValidator
for the the associated form. This method is
intended to be called during a builder script. When the associated form
is opened, the FormValidator
is automatically installed. If this
method is called later (if the window is already open and the form
exists), the specified in FormValidator
is directly passed to the
Form
object.formValidator
- the FormValidator
for the associated Form
public Object getFormBean()
WindowBuilderData
object.public Form getForm()
ComponentBuilderData
object.public Window getWindow()
WindowBuilderData
object.public MessageOutput getMessageOutput()
MessageOutput
object to be used by this
controller. This can be null if no specific object has been set.MessageOutput
objectsetMessageOutput(MessageOutput)
public void setMessageOutput(MessageOutput messageOutput)
MessageOutput
object to be used by this controller.
The MessageOutput
object is used for displaying validation
error messages to the user. Per default the MessageOutput
object defined in the BuilderData
object will be used (which is
typically the application-global output object). With this method it is
possible to set a specific output object for this controller.messageOutput
- the MessageOutput
object to usefetchMessageOutput()
public FormValidationMessageFormat getValidationMessageFormat()
FormValidationMessageFormat
object to be used
by this controller. This can be null if no specific object has
been set.FormValidationMessageFormat
objectsetValidationMessageFormat(FormValidationMessageFormat)
public void setValidationMessageFormat(FormValidationMessageFormat validationMessageFormat)
FormValidationMessageFormat
object to be used by
this controller. This object is used for generating error messages for a
failed validation that are to be displayed to the user. With this method
it is possible to set a specific format object for this purpose. If no
specific object is set, the application-global default format object is
used (which is obtained from the current BeanContext
).validationMessageFormat
- the
FormValidationMessageFormat
object to usefetchValidationMessageFormat()
public String getBtnOkName()
public void setBtnOkName(String btnOkName)
btnOkName
- the name of the OK button componentpublic String getBtnCancelName()
public void setBtnCancelName(String btnCancelName)
btnCancelName
- the name of the cancel button componentpublic String getValidationMessageBoxCaption()
public void setValidationMessageBoxCaption(String validationMessageBoxCaption)
validationMessageBoxCaption
- the caption of the validation error
message boxpublic FormValidationTrigger getValidationTrigger()
FormValidationTrigger
.public void setValidationTrigger(FormValidationTrigger validationTrigger)
FormValidationTrigger
. This object is called
once in the initialization phase to give it opportunity to register
itself as event listener.validationTrigger
- the new validation trigger (can be null)public void addValidationListener(FormControllerValidationListener l)
FormControllerValidationListener
to this controller. The
listener will be notified whenever a validation is performed.l
- the listener to be added (must not be null)IllegalArgumentException
- if the event listener is nullpublic void removeValidationListener(FormControllerValidationListener l)
FormControllerValidationListener
from this
controller. If the listener is not registered, this method has no effect.l
- the listener to be removedpublic FormControllerValidationListener[] getValidationListeners()
FormControllerValidationListener
objects registered at this FormController
.FormControllerValidationListener
objectspublic void addFieldStatusListener(FormControllerFieldStatusListener l)
FormControllerFieldStatusListener
to this controller. The
listener will be notified whenever the visited status of a field in the
controller's form changes.l
- the listener to be added (must not be null)IllegalArgumentException
- if the event listener is nullpublic void removeFieldStatusListener(FormControllerFieldStatusListener l)
FormControllerFieldStatusListener
from this
controller. If the listener is not registered, this method has no effect.l
- the listener to be removedpublic FormControllerFieldStatusListener[] getFieldStatusListeners()
FormControllerFieldStatusListener
objects registered at this FormController
.FormControllerFieldStatusListener
objectspublic void addFormListener(FormControllerFormListener l)
FormControllerFormListener
to this controller. The
listener will be notified when the form associated with this controller
is closed.l
- the listener to be added (must not be null)IllegalArgumentException
- if the listener is nullpublic void removeFormListener(FormControllerFormListener l)
FormControllerFormListener
from this
controller. If the listener is not registered, this method has no effect.l
- the listener to be removedpublic FormControllerFormListener[] getFormListeners()
FormControllerFormListener
objects
registered at this FormController
.FormControllerFormListener
objectspublic Command getOkCommand()
public void setOkCommand(Command okCommand)
Command
object and associated with this
controller. In its action handler for the OK event the controller will
check (after a successful validation) whether a command was set. If this
is the case, it will be passed to the current command queue.okCommand
- the command to be executed when the form is committedpublic Command getCancelCommand()
public void setCancelCommand(Command cancelCommand)
setOkCommand(Command)
, but it allows
to associate a Command
object with the cancel
button (or any other close action that does not mean a commit). This way
it is possible to execute some action when the user decides to throw away
its input.cancelCommand
- the command to be executed when the form is canceledpublic FormValidatorResults validate()
FormControllerValidationListener
objects registered at this
controller will be notified.public FormValidatorResults validateAndDisplayMessages()
validate()
. If validation results indicate errors, a message
window is displayed containing corresponding validation error messages.
This method is intended to do a validation in reaction on a user action,
e.g. when the user clicks an apply button.public FormValidatorResults getLastValidationResults()
validate()
call. This is useful for instance to determine which
input fields are currently invalid. If no validation has been performed
so far, a valid result object is returned.FormValidatorResults
object with the last validation
resultspublic void windowActivated(WindowEvent event)
windowActivated
in interface WindowListener
event
- the received eventpublic void windowClosed(WindowEvent event)
FormControllerFormListener
objects are notified.windowClosed
in interface WindowListener
event
- the received eventpublic void windowDeactivated(WindowEvent event)
windowDeactivated
in interface WindowListener
event
- the received eventpublic void windowDeiconified(WindowEvent event)
windowDeiconified
in interface WindowListener
event
- the received eventpublic void windowIconified(WindowEvent event)
windowIconified
in interface WindowListener
event
- the received eventpublic void windowClosing(WindowEvent event)
windowClosing
in interface WindowListener
event
- the received eventpublic void windowOpened(WindowEvent event)
windowOpened
in interface WindowListener
event
- the eventIllegalStateException
- if a required field is missingpublic void focusGained(FormFocusEvent e)
focusGained
in interface FormFocusListener
e
- the focus eventpublic void focusLost(FormFocusEvent e)
FieldMarker
also
needs to be notified.focusLost
in interface FormFocusListener
e
- the focus eventpublic void actionPerformed(FormActionEvent e)
actionPerformed
in interface FormActionListener
e
- the eventokButtonClicked(FormActionEvent)
,
cancelButtonClicked(FormActionEvent)
public boolean isFieldVisited(String name)
name
- the name of the fieldprotected BuilderData getBuilderData()
BuilderData
object. This object can be
used for gaining access to some application global objects and the
complete configuration of the builder.BuilderData
objectprotected MessageOutput fetchMessageOutput()
MessageOutput
object. If an output
object was set explicitly using the setMessageOutput()
method, this object will be returned. Otherwise this method obtains the
MessageOutput
object from the current
BuilderData
object.MessageOutput
object to be usedprotected FormValidationMessageFormat fetchValidationMessageFormat()
FormValidationMessageFormat
object to be used.
If a format object was set explicitly using the
setValidationMessageFormat()
method, this object will be
returned. Otherwise this method queries the current
BeanContext
for the default format object.FormValidationMessageFormat
object to be usedprotected String fetchValidationMessageBoxCaption()
setValidationMessageBoxCaption()
). If this is
the case, it is returned. Otherwise the resource key for the default
caption is resolved.protected void okButtonClicked(FormActionEvent event)
FormValidationMessageFormat
object and
displayed to the user via the current MessageOutput
object. When the user clicks OK, he or she indicates that all fields have
been properly filled in; so they are marked as visited.event
- the event object that triggered this method callprotected void cancelButtonClicked(FormActionEvent event)
event
- the event object that triggered this method callprotected void closeForm()
close()
method on the associated window
object.protected boolean isCommitted()
protected void fireValidationEvent(FormValidatorResults results)
results
- the validation resultsprotected void fireFieldStatusEvent(String fieldName)
fieldName
- the name of the affected fieldprotected void fireFormEvent()
Copyright © 2016 The JGUIraffe Team. All rights reserved.