com.antelmann.util.gui
Class FormDialog<T>

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Window
              java.awt.Dialog
                  javax.swing.JDialog
                      com.antelmann.util.gui.FormDialog<T>

All Implemented Interfaces:

Form, ValueRetriever<T>, ActionListener, ImageObserver, MenuContainer, PropertyChangeListener, Serializable, EventListener, Accessible, RootPaneContainer, WindowConstants

public class FormDialog<T>
extends JDialog
implements Form, ActionListener, ValueRetriever<T>

allows easy display and handling of forms in a dialog. Initially, the dialog is instantiated modal, but this may be changed. The FormDialog contains a given form and embeds it into a dialog adding an OK-button and a CANCEL-button. Upon pressing OK, the form will be processed by a FormValidator. In addition, this class provides some generally useful static methods for forms.

Author:

Holger Antelmann

See Also:

FormValidator, FormFrame, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JDialog

JDialog.AccessibleJDialog

Nested classes/interfaces inherited from class java.awt.Dialog

Dialog.AccessibleAWTDialog, Dialog.ModalExclusionType, Dialog.ModalityType

Nested classes/interfaces inherited from class java.awt.Window

Window.AccessibleAWTWindow

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static int	APPLY indicates that the APPLY-button has been pressed
static int	CANCEL indicates that the CANCEL-button has been pressed
static int	CLOSED indicates that the dialog has been closed w/o pressing a button
static int	OK indicates that the OK-button has been pressed

Fields inherited from class javax.swing.JDialog

accessibleContext, rootPane, rootPaneCheckingEnabled

Fields inherited from class java.awt.Dialog

DEFAULT_MODALITY_TYPE

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface com.antelmann.util.gui.Form

EDIT_PROPERTY_KEY

Fields inherited from interface javax.swing.WindowConstants

DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

FormDialog(Component parent, String title, JComponent container, FormValidator<T> validator)
constructs a modal dialog using a container as a form and adding buttons for OK, CANCEL.

FormDialog(Component parent, String title, JComponent container, FormValidator<T> validator, boolean applyOption)

FormDialog(Component parent, String title, JComponent container, FormValidator<T> validator, boolean applyOption, Logger logger)
this constructor allows to further specify whether an apply button should be available on the dialog

FormDialog(Component parent, String title, JComponent container, FormValidator<T> validator, Logger logger)
this cunstructor allows to futher specify a Logger which logs when a button of this form is pressed; in addition, all window events are logged.

Method Summary

void	actionPerformed(ActionEvent ev) performs the action upon pressing the OK button.
void	addListener(FormListener l)
void	applyAction() programmatically presses the apply button action on this dialog.
void	cancelAction() programmatic cancel button action on this dialog
boolean	checkForClose() returns true only if the form has actually been disposed
boolean	disposeForm(boolean forceWithoutConfirm) allows to programmatically close the form.
void	enableEscapeForCancel()
boolean	getApplyAlwaysEnabled() if false (the default), the apply button (if available) is only turned on by calling the propertyChange() method and will be disabled after each time the button is pressed
JPanel	getButtonContainer() provides the container that contains the functional buttons of the Form, so that other additional buttons may be added here
JPanel	getButtonPanel() returns the panel that contains the buttons for the available form actions (ok, cancel, apply) so that another special button may be added.
Action	getCancelAction()
Exception	getException() if an exception was thrown during commitFormAction(), this method returns it - or null.
JComponent	getFormComponent()
Container	getFormContainer() provides access to the overall window, dialog, frame, internal frame or other that holds the form with the formComponent and all the functional buttons that belong to the form
FormListener[]	getFormListeners()
FormValidator<T>	getFormValidator()
Logger	getLogger() provides access to the logger used to capture events (and exeptions) upon pressing buttons
Action	getOKAction()
T	getRelevantValue() returns the value returned by the FormValidator on commitFormAction() if the OK button was successfully pressed or if at any time the APPLY button was successfully pressed.
boolean	getWarnOnClose() determines whether a warning is displayed upon cancel if the form is marked as changed (false by default)
boolean	hasApplyButton() indicates whether the dialog is to be displayed with an apply option
boolean	isDirty() returns true if the propertyChange() method was called after any saving action (apply or ok)
boolean	isValidateOnChange()
Object	performSaveAction() programmatically performs the action that would commonly be performed upon pressing 'save' on the form.
int	processForm() calls setVisible(true), processes the form and returns what button was pressed.
void	propertyChange(PropertyChangeEvent evt) implemented to provide feedback to the APPLY-button, if applicable.
boolean	removeListener(FormListener l)
void	setApplyAlwaysEnabled(boolean flag)
void	setValidateOnChange(boolean okOnValidationOnly)
void	setWarnOnClose(boolean flag) if set to true, a warning is displayed when the form is closed w/o saving if it is marked changed

Methods inherited from class javax.swing.JDialog

addImpl, createRootPane, dialogInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getGraphics, getJMenuBar, getLayeredPane, getRootPane, getTransferHandler, isDefaultLookAndFeelDecorated, isRootPaneCheckingEnabled, paramString, processWindowEvent, remove, repaint, setContentPane, setDefaultCloseOperation, setDefaultLookAndFeelDecorated, setGlassPane, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, setTransferHandler, update

Methods inherited from class java.awt.Dialog

addNotify, getModalityType, getTitle, hide, isModal, isResizable, isUndecorated, setModal, setModalityType, setResizable, setTitle, setUndecorated, setVisible, show, toBack

Methods inherited from class java.awt.Window

addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, paint, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, toFront

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

OK

public static final int OK

indicates that the OK-button has been pressed

See Also:

Constant Field Values

CANCEL

public static final int CANCEL

indicates that the CANCEL-button has been pressed

See Also:

Constant Field Values

CLOSED

public static final int CLOSED

indicates that the dialog has been closed w/o pressing a button

See Also:

Constant Field Values

APPLY

public static final int APPLY

indicates that the APPLY-button has been pressed

See Also:

Constant Field Values

Constructor Detail

FormDialog

public FormDialog(Component parent,
                  String title,
                  JComponent container,
                  FormValidator<T> validator)

constructs a modal dialog using a container as a form and adding buttons for OK, CANCEL. After this dialog was made visible, the application can check which - if any - button was pressed.

Parameters:

parent - the component that created this dialog

title - the title for this form dialog

container - the component that is representing the form that will be displayed in this dialog

validator - a FormValidator specifying the behavior of the form upon pressing OK

See Also:

processForm()

FormDialog

public FormDialog(Component parent,
                  String title,
                  JComponent container,
                  FormValidator<T> validator,
                  Logger logger)

this cunstructor allows to futher specify a Logger which logs when a button of this form is pressed; in addition, all window events are logged.

FormDialog

public FormDialog(Component parent,
                  String title,
                  JComponent container,
                  FormValidator<T> validator,
                  boolean applyOption)

FormDialog

public FormDialog(Component parent,
                  String title,
                  JComponent container,
                  FormValidator<T> validator,
                  boolean applyOption,
                  Logger logger)

this constructor allows to further specify whether an apply button should be available on the dialog

Method Detail

getFormValidator

public FormValidator<T> getFormValidator()

Specified by:

getFormValidator in interface Form

getFormComponent

public JComponent getFormComponent()

Specified by:

getFormComponent in interface Form

addListener

public void addListener(FormListener l)

Specified by:

addListener in interface Form

removeListener

public boolean removeListener(FormListener l)

Specified by:

removeListener in interface Form

getFormListeners

public FormListener[] getFormListeners()

Specified by:

getFormListeners in interface Form

getButtonPanel

public JPanel getButtonPanel()

returns the panel that contains the buttons for the available form actions (ok, cancel, apply) so that another special button may be added. The panel is laid out with a standard FlowLayout

getButtonContainer

public JPanel getButtonContainer()

Description copied from interface: Form

provides the container that contains the functional buttons of the Form, so that other additional buttons may be added here

Specified by:

getButtonContainer in interface Form

getLogger

public Logger getLogger()

provides access to the logger used to capture events (and exeptions) upon pressing buttons

getWarnOnClose

public boolean getWarnOnClose()

Description copied from interface: Form

determines whether a warning is displayed upon cancel if the form is marked as changed (false by default)

Specified by:

getWarnOnClose in interface Form

setWarnOnClose

public void setWarnOnClose(boolean flag)

Description copied from interface: Form

if set to true, a warning is displayed when the form is closed w/o saving if it is marked changed

Specified by:

setWarnOnClose in interface Form

cancelAction

public void cancelAction()

programmatic cancel button action on this dialog

checkForClose

public boolean checkForClose()

returns true only if the form has actually been disposed

disposeForm

public boolean disposeForm(boolean forceWithoutConfirm)

Description copied from interface: Form

allows to programmatically close the form.

Specified by:

disposeForm in interface Form

Parameters:

forceWithoutConfirm - if true, the form will be disposed no matter what; if false, a confirmation dialog may appear if the form is dirty and warnOnClose is true

Returns:

true only if the form has been closed (and the listeners were informed accordingly)

getApplyAlwaysEnabled

public boolean getApplyAlwaysEnabled()

if false (the default), the apply button (if available) is only turned on by calling the propertyChange() method and will be disabled after each time the button is pressed

setApplyAlwaysEnabled

public void setApplyAlwaysEnabled(boolean flag)

applyAction

public void applyAction()

programmatically presses the apply button action on this dialog. This method will only do something if the button is actually available; the dialog is not disposed. Also, the apply button will be disabled after this call until a call to the propertyChange() method was made again.

hasApplyButton

public boolean hasApplyButton()

indicates whether the dialog is to be displayed with an apply option

isValidateOnChange

public boolean isValidateOnChange()

setValidateOnChange

public void setValidateOnChange(boolean okOnValidationOnly)

actionPerformed

public void actionPerformed(ActionEvent ev)

performs the action upon pressing the OK button. By making this method externally available, a form component can be configured to perform this action on other events, too, like pressing 'Enter' on a field.

Specified by:

actionPerformed in interface ActionListener

performSaveAction

public Object performSaveAction()

Description copied from interface: Form

programmatically performs the action that would commonly be performed upon pressing 'save' on the form. Commonly, this method would first call FormValidator.validateForm(Component) and then call FormValidator.commitFormAction(Component); also this method resets the Form.isDirty() status if the commit was successful.

Specified by:

performSaveAction in interface Form

Returns:

the object saved or null if that didn't happen

processForm

public int processForm()

calls setVisible(true), processes the form and returns what button was pressed. The dialog stays visible until either OK was pressed and the validation and commit action went smooth, or if CANCEL was pressed. Last, the dialog may also have been closed w/o a button. Note that even though the dialog was closed through something other than OK, the commit action of the form could still have been performed through the apply button (if applicable).

Returns:

OK, CANCEL or CLOSED

See Also:

FormDialog

getOKAction

public Action getOKAction()

getCancelAction

public Action getCancelAction()

enableEscapeForCancel

public void enableEscapeForCancel()

propertyChange

public void propertyChange(PropertyChangeEvent evt)

implemented to provide feedback to the APPLY-button, if applicable. If there is no apply button, this method has no effect. if there is an apply button, calling this method will re-enable the button (as by default, the apply button will be disabled after pressing it). It is ok to call this method with null as a parameter.

Specified by:

propertyChange in interface PropertyChangeListener

isDirty

public boolean isDirty()

returns true if the propertyChange() method was called after any saving action (apply or ok)

Specified by:

isDirty in interface Form

getRelevantValue

public T getRelevantValue()

returns the value returned by the FormValidator on commitFormAction() if the OK button was successfully pressed or if at any time the APPLY button was successfully pressed. If the commit action was never successfully executed, this method returns null.

Specified by:

getRelevantValue in interface ValueRetriever<T>

See Also:

FormValidator.commitFormAction(Component)

getException

public Exception getException()

if an exception was thrown during commitFormAction(), this method returns it - or null. In case an exception was thrown, it will already have been displayed to the user.

See Also:

FormValidator.commitFormAction(Component)

getFormContainer

public Container getFormContainer()

Description copied from interface: Form

provides access to the overall window, dialog, frame, internal frame or other that holds the form with the formComponent and all the functional buttons that belong to the form

Specified by:

getFormContainer in interface Form