Holger's Java API

## 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`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads