dsto.dfc.swing.forms
Class FormDialog

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by java.awt.Window
              extended by java.awt.Dialog
                  extended by javax.swing.JDialog
                      extended by dsto.dfc.swing.controls.DfcDialog
                          extended by dsto.dfc.swing.controls.DfcOkCancelDialog
                              extended by dsto.dfc.swing.forms.FormDialog
All Implemented Interfaces:
Form, FormEditor, Disposable, ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants

public class FormDialog
extends DfcOkCancelDialog
implements Form, Disposable

A Form-compatible extension of DfcOkCancelDialog designed to contain FormEditor's. Clients should use this class by adding a FormEditor-compatible component as the main dialog panel (via setFormPanel ()) and NOT by using setDialogPanel () in the usual way for DfcOkCancelDialog's. The main dialog panel will be committed when the user selects either OK or Apply.

NOTE: There are two modes this dialog can be used in: bound and non-bound. In bound mode, the editor inside the dialog is bound to a property of the dialog's editor value. In this mode, changes to the form dialog's value can be updated automatically when the OK button is pressed (to enable cancelling, FormDialog is set to be in deferred commit mode so that edits are not committed into the form value until the OK or Apply button is pressed even if child editors fire an editCommitted event). Bound mode is enabled when setFormPanel(FormEditor,String) is used. In non bound mode (the default), the editor value for the dialog and the panel is the same, and is cloned when it is passed into the dialog's setEditorValue () method. In this mode it is up to the client to store the edited value when OK or Apply is pressed.

Eg for non bound mode:

   FormDialog dialog = new FormDialog ("Test");
   Person person = new Person ("Foo");
   // PersonCustomizer is a form editor for Person objects
   PersonCustomizer personEditor = new PersonCustomizer ();

   dialog.setFormPanel (personEditor);
   dialog.setEditorValue (person);  // clones person before setting
   dialog.show ();                  // show and edit person

   if (!dialog.isCancelled ())
   {
     Person newPerson = (Person)dialog.getEditorValue ();

     // do something with edited newPerson
   }
 

TIP: If no natural class makes sense as the editor value for this dialog in bound mode, clients can implement a special property for loading/saving the editor value. For example: a command that pops up a FormDialog could provide a "dialogValue" property and bind itself as the form value.

Version:
$Revision$
Author:
Matthew
See Also:
Form, DfcOkCancelDialog, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class dsto.dfc.swing.controls.DfcDialog
DfcDialog.CmdCancel
 
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
 
Fields inherited from class dsto.dfc.swing.controls.DfcOkCancelDialog
listeners, OK_ACCELERATOR, okListener
 
Fields inherited from class dsto.dfc.swing.controls.DfcDialog
ALIGN_CENTER_CLIENT, ALIGN_CENTER_SCREEN, ALIGN_NONE, CANCEL_ACCELERATOR
 
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 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()
           
FormDialog(Component client, String title, boolean modal)
           
 
Method Summary
 void addEditor(String property, FormEditor editor)
           
 void addEditor(String property, FormEditor editor, ValueConverter converter)
          Add an editor for a given property of the form value.
 void addFormEditorListener(FormEditorListener l)
           
 void commitEdits()
          Commit any changes not already committed into the value of this editor (eg a text editor will attempt to perform any uncommitted text conversions at this point).
 void dispose()
          Dispose of the object (unregister listeners, close open resources etc).
 Component getEditorComponent()
          Get the component, if any, that acts as a UI for this editor.
 String getEditorDescription()
          Get a short description of the value being edited for this editor (eg 'host name').
 Object getEditorValue()
          Get the current value from the form editor.
 FormEditor getFormPanel()
           
 Class getPreferredValueType()
          Default implementation: returns java.lang.Object to indicate no preferred type.
 boolean isBoundMode()
           
 boolean isDeferredCommit()
          True if editor commit requests from child editors are deferred until commitEdits () is explicitly called on this form.
 boolean isDirectEdit()
          True if the editor directly edits the value passed in with setValue ().
 boolean removeEditor(FormEditor editor)
          Remove a bound form editor.
 void removeFormEditorListener(FormEditorListener l)
           
 boolean saveResult()
          Do not override.
 void setDeferredCommit(boolean newValue)
           
 void setEditorValue(Object newValue)
          Sets the value to be displayed/edited by the form editor.
 void setFormPanel(FormEditor panel)
          Set the main panel for the dialog.
 void setFormPanel(FormEditor panel, String property)
          Set the main panel for the dialog.
 
Methods inherited from class dsto.dfc.swing.controls.DfcOkCancelDialog
addActionListener, apply, button_actionPerformed, cancel, enableOkAccelerator, fireActionEvent, getApplyButton, getCancelButton, getOkButton, isCancelled, ok, removeActionListener, setCancelled
 
Methods inherited from class dsto.dfc.swing.controls.DfcDialog
cancelButton_actionPerformed, getAlignMode, getButtonPanel, getCancelCommand, getContentPanel, getDialogPanel, placeWindow, setAlignMode, setContentPanel, setDialogPanel, setVisible, this_windowClosing
 
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, show, toBack
 
Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, 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, 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, paint, 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
 

Constructor Detail

FormDialog

public FormDialog(Component client,
                  String title,
                  boolean modal)

FormDialog

public FormDialog()
Method Detail

dispose

public void dispose()
Description copied from interface: Disposable
Dispose of the object (unregister listeners, close open resources etc). It should be safe to call this method more than once. Note for beans that support client event listeners: if there are listeners registered when this is called, this method should do nothing.

Specified by:
dispose in interface Disposable
Overrides:
dispose in class DfcDialog

getPreferredValueType

public Class getPreferredValueType()
Default implementation: returns java.lang.Object to indicate no preferred type.

Specified by:
getPreferredValueType in interface FormEditor

isBoundMode

public boolean isBoundMode()

setFormPanel

public void setFormPanel(FormEditor panel)
Set the main panel for the dialog.

Parameters:
panel - The main panel (must both extend Component and implement the FormEditor interface).

setFormPanel

public void setFormPanel(FormEditor panel,
                         String property)
Set the main panel for the dialog.

Parameters:
panel - The main panel (must both extend Component and implement the FormEditor interface). May be null to unset form panel.
property - The property of the dialog editor value value to bind to the panel. May be null for no binding.

getFormPanel

public FormEditor getFormPanel()

saveResult

public boolean saveResult()
Do not override.

Overrides:
saveResult in class DfcOkCancelDialog
Returns:
True if result was saved.

addEditor

public void addEditor(String property,
                      FormEditor editor)
Specified by:
addEditor in interface Form

addEditor

public void addEditor(String property,
                      FormEditor editor,
                      ValueConverter converter)
Description copied from interface: Form
Add an editor for a given property of the form value.

Specified by:
addEditor in interface Form
Parameters:
property - The property name.
editor - The editor for the property.
converter - The value converter that will be used to convert values into the editor's format (determined by FormEditor.getPreferredValueType() and from the editor back to the property value. May be null for no conversion.
See Also:
Form.removeEditor(dsto.dfc.swing.forms.FormEditor)

removeEditor

public boolean removeEditor(FormEditor editor)
Description copied from interface: Form
Remove a bound form editor.

Specified by:
removeEditor in interface Form
Returns:
True if the editor was removed.
See Also:
Form.addEditor(java.lang.String, dsto.dfc.swing.forms.FormEditor)

isDeferredCommit

public boolean isDeferredCommit()
Description copied from interface: Form
True if editor commit requests from child editors are deferred until commitEdits () is explicitly called on this form. This can be used to implement forms where the user can apply changes via commitEdits () or cancel edits by simply not calling commitEdits () without having to copy the value being edited by the form. When in deferred commit mode, the form will copy values before passing them to setValue () on "direct edit" child FormEditor's and handle editCommitRequested events from sub-editors by calling commit () but not storing the subeditor's value.

Specified by:
isDeferredCommit in interface Form

setDeferredCommit

public void setDeferredCommit(boolean newValue)
Specified by:
setDeferredCommit in interface Form

getEditorDescription

public String getEditorDescription()
Description copied from interface: FormEditor
Get a short description of the value being edited for this editor (eg 'host name'). May be null.

Specified by:
getEditorDescription in interface FormEditor

isDirectEdit

public boolean isDirectEdit()
Description copied from interface: FormEditor
True if the editor directly edits the value passed in with setValue (). If false, the parent editor will be reponsible for retrieving the value from the editor and storing it.

Specified by:
isDirectEdit in interface FormEditor

commitEdits

public void commitEdits()
                 throws IllegalFormatException
Description copied from interface: FormEditor
Commit any changes not already committed into the value of this editor (eg a text editor will attempt to perform any uncommitted text conversions at this point). Only editors that need support editing in non-atomic sessions (such as text fields) will generally do anything when this method is called. If commit is made that has not been signalled with a previous editCommitted event, the editor should fire an editCommitted event at this point. Composite editors, such as forms, will generally forward this request to their child editors.

Specified by:
commitEdits in interface FormEditor
Throws:
IllegalFormatException - if the commit failed because of an illegal input or other error. The source specified by the exception should be the FormEditor instance that caused the error (ie either this editor or a child).

setEditorValue

public void setEditorValue(Object newValue)
                    throws IllegalFormatException
Description copied from interface: FormEditor
Sets the value to be displayed/edited by the form editor.

Specified by:
setEditorValue in interface FormEditor
Parameters:
newValue - The value to display.
Throws:
IllegalFormatException - if the value was not in the correct format for display by this editor. The source specified by the exception should be this FormEditor instance or a child.

getEditorValue

public Object getEditorValue()
Description copied from interface: FormEditor
Get the current value from the form editor. At least one call to setValue () must be made beforehand.

Specified by:
getEditorValue in interface FormEditor

getEditorComponent

public Component getEditorComponent()
Description copied from interface: FormEditor
Get the component, if any, that acts as a UI for this editor. May return null if not associated with a component.

Specified by:
getEditorComponent in interface FormEditor

addFormEditorListener

public void addFormEditorListener(FormEditorListener l)
Specified by:
addFormEditorListener in interface FormEditor

removeFormEditorListener

public void removeFormEditorListener(FormEditorListener l)
Specified by:
removeFormEditorListener in interface FormEditor


Copyright © 2008 Commonwealth of Australia