com.jgoodies.uif
Class AbstractDialog

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 com.jgoodies.uif.AbstractDialog
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants

public abstract class AbstractDialog
extends JDialog

An abstract superclass that minimizes the effort required to build consistent Swing dialogs quickly. It forms a template process to build a standardized dialog and provides convenience behavior to create frequently used dialog buttons, button bars and actions. Also, this class can assist you in buffering dialog input values; therefore it use the the BufferedValueModel from the JGoodies Binding library. See below for more information on buffering.

The dialog build process begins with the #build method that builds the content pane, applies a resize hook, sets the content pane, packs the dialog, sets the resizable state and locates it on the screen. Subclasses will rarely override the #build method. Instead, subclasses must implement #buildContent to build the dialog's main content. This content shall include the button bar or button stack but not the header and not the dialog border. The optional dialog header is built in #buildHeader which answers null by default to indicate that the dialog has no header. The border returned by #getDialogBorder is wrapped around the content, not the header. Most dialogs will use a default border for a plain dialog and a different border dialog with tabs. The #resizeHook allows to resize the dialog to achieve an esthetic aspect ratio. See Resizer for an example how to resize a dialog consistently. #locateOnScreen enables you to change the dialog's location on the screen. By default a dialog is located relative to its parent frame or dialog. Other useful locations are the screen center or a screen corner; class ScreenUtils can assist you in setting such a location.

To open a dialog invoke #open, to close it you can call #close. Once it has been closed you can call #hasBeenCanceled to understand whether this dialog has been canceled or not.

AbstractDialog provides methods to create the following frequently used buttons: OK, Cancel, Accept, Apply, Reset, Close. The button texts are internationalized and can be localized under the keys mentioned in the associated #createXXXButton method. If you click on such a button, the associated #doXXX method will be invoked. For example, if you click on the Apply button, #doApply is invoked. If you override a #doXXX method, be sure to call the super behavior. There are three methods that build button bars from the standardized buttons mentioned before, where #createButtonBarWithOKCancel is the most frequently used.

Find below a sample subclass that has a header, a button bar with OK and Cancel and is resized to an esthetic aspect ratio:

 public final class MyDialog extends AbstractDialog {

     protected JComponent buildHeader() {
         return new HeaderPanel(
             "My Dialog",
             "You can do click on the tabs below to ...",
             ResourceUtils.getIcon(MyResourceIDs.MY_DIALOG_ICON)
         );
     }

     public JComponent buildContent() {
         JPanel content = new JPanel(new BorderLayout());
         content.add(buildMainPanel(),             BorderLayout.CENTER);
         content.add(buildButtonBarWithOKCancel(), BorderLayout.SOUTH);
         return content;
     }

     private JComponent buildMainPanel() {
         // Your custom code to build the main panel...
     }

     protected void resizeHook(JComponent component) {
         Resizer.DEFAULT.resize(component);
     }

 }
 

Buffering Input Values
This class provides optional behavior to delay the commit of dialog input values. You can create buffered models that hold back value changes until you either commit or flush the buffered values. You can find more information about binding and buffering values in the documentation for the JGoodies Binding library. This library is used to implement buffering in this class.

AbstractDialog holds a triggerChannel that can be shared by instances of BufferedValueModel to commit and flush buffered values. This way changes of dialog values can be delayed until the trigger channel triggers a commit or flush of the buffered values.

By default the trigger channel changes to true in #doApply and #doAccept and changes to false in #doReset and #doCancel. And so, clicking on Apply or OK will commit buffered dialog values; while clicking on Reset or Cancel will reset the buffered values to the original values. See the documentation f the JGoodies Data Binding framework for details.

The trigger channel is provided as the bound Java bean property triggerChannel that must be a non-null ValueModel with values of type Boolean. Attempts to read or write other value types may be rejected with runtime exceptions. The trigger channel is initialized as an instance of Trigger.

Find below a sample subclass, a customer editor, that buffers the values of two input fields for the customer's last name and first name:

 public final class CustomerDialog extends AbstractDialog {

     private Component lastNameField;
     private Component firstNameField;
     private Component titleField;
     ...

     public CustomerDialog(Frame owner, Customer customer) {
         super(owner, "Edit Customer");
         initComponents(customer);
     }

     private void initComponents(Customer customer) {

         // Bound field using a DocumentAdapter
         lastNameField = new JTextField(40);
         lastNameField.setDocument(
             new DocumentAdapter(
                 buffer(new PropertyAdapter(customer, "lastName"))
             )
         );

         // Bound field using a DocumentToValueConnector
         firstNameField = new JTextField(40);
         new DocumentToValueConnector(
             firstNameField,
             buffer(new PropertyAdapter(customer, "firstName"))
         );

         // Bound field created by a factory
         titleField = BasicComponentFactory.createTextField(
             buffer(new PropertyAdapter(customer, "title"))
         );
         titleField.setColumns(20);
     }

     public JComponent buildContent() {
         JPanel content = new JPanel(new BorderLayout());
         content.add(buildMainPanel(),             BorderLayout.CENTER);
         content.add(buildButtonBarWithOKCancel(), BorderLayout.SOUTH);
         return content;
     }

     private JComponent buildMainPanel() {
         FormLayout layout = new FormLayout(
             "pref, 4dlu, default",  // columns
             ""                      // add rows dynamically
         );
         DefaultFormBuilder builder = new DefaultFormBuilder(layout);
         builder.setDefaultDialogBorder();
         builder.append("Last name",  lastNameField);
         builder.append("First name", firstNameField);
         builder.append("Title",      titleField);
         ...
         return builder.getPanel();
     }

 }
 

Version:
$Revision: 1.10 $
Author:
Karsten Lentzsch
See Also:
ButtonBarFactory, Resizer, ValueModel, BufferedValueModel, Trigger, 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
protected static Border CARD_DIALOG_BORDER
          TODO: Move this constant to the Forms Borders class.
protected static Border DIALOG_BORDER
          TODO: Move this constant to the Forms Borders class.
static String PROPERTYNAME_TRIGGER_CHANNEL
          The name of the bound read-write property triggerChannel.
 
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
AbstractDialog()
           
AbstractDialog(Dialog owner)
          Constructs a modal AbstractDialog with the given Dialog as its owner using the application's default window title.
AbstractDialog(Dialog owner, String title)
          Constructs a modal AbstractDialog with the given Dialog as its owner using the given window title.
AbstractDialog(Dialog owner, String title, boolean modal)
          Constructs an AbstractDialog with the given Dialog as its owner using the given window title and the specified modal state.
AbstractDialog(Frame owner)
          Constructs a modal AbstractDialog with the given Frame as its owner, using the application's default window title.
AbstractDialog(Frame owner, String title)
          Constructs a modal AbstractDialog with the given Frame as its owner using the given window title.
AbstractDialog(Frame owner, String title, boolean modal)
          Constructs an AbstractDialog with the given Frame as its owner using the given window title and the specified modal state.
 
Method Summary
 com.jgoodies.binding.value.BufferedValueModel buffer(com.jgoodies.binding.value.ValueModel valueModel)
          Creates and returns a BufferedValueModel on the given ValueModel using the dialog's trigger channel to trigger commit and flush events.
protected  void build()
          Builds the dialog's content pane, packs it, sets the resizable property, and locates it on the screen.
protected  JComponent buildButtonBarWithClose()
          Builds and returns a button bar with a Close button.
protected  JComponent buildButtonBarWithOKCancel()
          Builds and returns a button bar with an OK and a Cancel button.
protected  JComponent buildButtonBarWithOKCancelApply()
          Builds and returns a button bar with three buttons: OK, Cancel and Apply.
protected abstract  JComponent buildContent()
          Builds and answers the dialog's main content without header and border.
protected  JComponent buildContentPane()
          Builds and returns the content pane, sets the border and puts an optional header component in the dialog's north.
protected  JComponent buildHeader()
          Builds and returns the optional header component, which will be put in the dialog's north by the default #buildContentPane implementation.
 void close()
          Closes the dialog: makes it invisible and disposes it, which in turn releases all required OS resources.
protected  void configureWindowClosing()
          Configures the closing behavior: invokes #doCloseWindow instead of just closing the dialog.
protected  UIFButton createAcceptButton(String text, boolean isDefault)
          Creates and returns an Accept button with the given label text and default state.
protected  UIFButton createApplyButton()
          Creates and returns an Apply button.
protected  UIFButton createCancelButton()
          Creates and returns a Cancel button.
protected  UIFButton createCloseButton(boolean isDefault)
          Creates and returns a Close button.
protected  UIFButton createOKButton(boolean isDefault)
          Creates and returns an OK button.
protected  UIFButton createResetButton()
          Creates and returns a Reset button.
 void doAccept()
          Invokes #doApply, marks the dialog as uncanceled and finally closes it.
 void doApply()
          Applies changes in the dialog and leaves the dialog open.
 void doCancel()
          Resets changed dialog values, marks the dialog as canceled and closes it.
 void doClose()
          Marks the dialog as uncanceled and closes it.
protected  void doCloseWindow()
          Performs the close window action that is invoked if the dialog is closing, for example by clicking the dialog's close button (often in the upper right corner).
 void doReset()
          Resets changed dialog values and leaves the dialog open.
 Action getApplyAction()
          Lazily creates and returns the Apply Action that invokes #doApply.
 Action getCancelAction()
          Lazily creates and returns the Cancel Action that invokes #doCancel.
 Action getCloseAction()
          Lazily creates and returns the Close Action that invokes #doClose.
protected  Border getDialogBorder()
          Returns the border that will be put around the content, which has been created by #buildContent.
static Mode getEscapeCancelsDefaultMode()
          Returns the default value for the escapeCancelsMode property.
 Mode getEscapeCancelsMode()
          Answers whether Escape cancels this dialog.
 Action getOKAction()
          Lazily creates and returns the OK Action that invokes #doAccept.
 Action getResetAction()
          Lazily creates and returns the Reset Action that invokes #doReset.
 ResourceMap getResourceMap()
          Returns the ResourceMap used to lookup localized button texts and other resources.
protected  String getString(String key)
          Retrieves and returns a String for the given key from this dialog's resource map.
 com.jgoodies.binding.value.ValueModel getTriggerChannel()
          Returns a ValueModel that can be used to trigger commit and flush events in BufferedValueModels.
 boolean hasBeenCanceled()
          Checks and answers whether the dialog has been canceled.
protected  void locateOnScreen()
          Locates the dialog on the screen.
 void open()
          Builds the dialog content, marks it as not canceled and makes it visible.
protected  void resizeHook(JComponent component)
          Resizes the specified component.
protected  void setDefaultButton(JButton button)
          Sets a button as default button in the dialog's root pane.
static void setEscapeCancelsDefaultMode(Mode defaultValue)
          Sets the application-wide default for the escapeCancelsMode property.
 void setEscapeCancelsMode(Mode escapeCancelsMode)
          Specifies whether this dialog will be canceled if Escape is pressed.
 void setInitialComponent(Component initialComponent)
          Sets a Component that should receive the focus when this dialog is made visible for the first time.
protected  void setResizable()
          Sets the dialog's resizable state.
 void setTriggerChannel(com.jgoodies.binding.value.ValueModel newTriggerChannel)
          Sets the given ValueModel as the dialog's new trigger channel.
protected  void triggerCommit()
          Ensures that the trigger channel changes to true which in turn triggers commit events in all BufferedValueModel instances that share this trigger.
protected  void triggerFlush()
          Ensures that the trigger channel changes to false which in turn triggers flush events in all BufferedValueModel instances that share this trigger.
 
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, 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
 

Field Detail

PROPERTYNAME_TRIGGER_CHANNEL

public static final String PROPERTYNAME_TRIGGER_CHANNEL
The name of the bound read-write property triggerChannel.

See Also:
getTriggerChannel(), setTriggerChannel(ValueModel), Constant Field Values

DIALOG_BORDER

protected static final Border DIALOG_BORDER
TODO: Move this constant to the Forms Borders class.


CARD_DIALOG_BORDER

protected static final Border CARD_DIALOG_BORDER
TODO: Move this constant to the Forms Borders class.

Constructor Detail

AbstractDialog

public AbstractDialog()

AbstractDialog

public AbstractDialog(Frame owner)
Constructs a modal AbstractDialog with the given Frame as its owner, using the application's default window title.

Parameters:
owner - the dialog's parent frame

AbstractDialog

public AbstractDialog(Frame owner,
                      String title)
Constructs a modal AbstractDialog with the given Frame as its owner using the given window title.

Parameters:
owner - the dialog's parent frame
title - the window title

AbstractDialog

public AbstractDialog(Frame owner,
                      String title,
                      boolean modal)
Constructs an AbstractDialog with the given Frame as its owner using the given window title and the specified modal state.

Parameters:
owner - the dialog's parent frame
title - the window title
modal - true for a model dialog, false for non-modal

AbstractDialog

public AbstractDialog(Dialog owner)
Constructs a modal AbstractDialog with the given Dialog as its owner using the application's default window title.

Parameters:
owner - the dialog's parent dialog

AbstractDialog

public AbstractDialog(Dialog owner,
                      String title)
Constructs a modal AbstractDialog with the given Dialog as its owner using the given window title.

Parameters:
owner - the dialog's parent dialog
title - the window title

AbstractDialog

public AbstractDialog(Dialog owner,
                      String title,
                      boolean modal)
Constructs an AbstractDialog with the given Dialog as its owner using the given window title and the specified modal state.

Parameters:
owner - the dialog's parent dialog
title - the window title
modal - true for a model dialog, false for non-modal
Method Detail

getResourceMap

public ResourceMap getResourceMap()
Returns the ResourceMap used to lookup localized button texts and other resources.

Returns:
the ResourceMap used to lookup localized button texts and other resources

getString

protected String getString(String key)
Retrieves and returns a String for the given key from this dialog's resource map. If the resource is absent, the key is returned instead.

Parameters:
key - the key used to lookup the localized string
Returns:
the localized text or default text
See Also:
getResourceMap()

getEscapeCancelsDefaultMode

public static Mode getEscapeCancelsDefaultMode()
Returns the default value for the escapeCancelsMode property. The value will be used to initialize this property. The default can be overridden per dialog using setEscapeCancelsMode.

Returns:
the default value for the escapeCancelsMode property.
Since:
1.4
See Also:
setEscapeCancelsDefaultMode(Mode), getEscapeCancelsMode(), setEscapeCancelsMode(Mode)

setEscapeCancelsDefaultMode

public static void setEscapeCancelsDefaultMode(Mode defaultValue)
Sets the application-wide default for the escapeCancelsMode property. The default value can be overridden per dialog using setEscapeCancelsMode.

Parameters:
defaultValue - the value to be set as default
Since:
1.4
See Also:
getEscapeCancelsDefaultMode(), getEscapeCancelsMode(), setEscapeCancelsMode(Mode)

getEscapeCancelsMode

public Mode getEscapeCancelsMode()
Answers whether Escape cancels this dialog. If so, this dialog's cancel Action will be performed if the Escape key is pressed while any component in this dialog has the focus.

The default value for this property can be specified using #setEscapeCancelsDefaultMode.

Returns:
the default value for the escapeCancelsMode property.
Since:
1.4
See Also:
setEscapeCancelsMode(Mode), getEscapeCancelsDefaultMode(), setEscapeCancelsDefaultMode(Mode)

setEscapeCancelsMode

public void setEscapeCancelsMode(Mode escapeCancelsMode)
Specifies whether this dialog will be canceled if Escape is pressed. If the given Mode is enabled in the current environment, this key binding will be added, otherwise it'll be removed. If enabled, the Escape key is mapped to this dialog's root pane using this dialog's cancel Action.

The default value for this property can be specified using #setEscapeCancelsDefaultMode.

Parameters:
escapeCancelsMode - true to bind the Escape key to the cancel action
Since:
1.4
See Also:
getEscapeCancelsMode(), getEscapeCancelsDefaultMode(), setEscapeCancelsDefaultMode(Mode)

setInitialComponent

public void setInitialComponent(Component initialComponent)
Sets a Component that should receive the focus when this dialog is made visible for the first time. Therefore it sets an instance of UIFFocusTraversalPolicy as this dialog's focus traversal policy, that will return the given component as initial component.

Useful if Swing default choice for the initial component as returned by this dialog's FocusTraversalPolicy is not appropriate. For example, if you want to set the initial focus to the first component of the first tab of a dialog's tabbed pane, you can use this method.

Note: As a side-effect this method changes this dialog's FocusTraversalPolicy to an instance of UIFFocusTraversalPolicy. If you want to set a different FocusTraversalPolicy, do not invoke this method.

Parameters:
initialComponent - the Component to get the focus if this dialog becomes visible the first time
Since:
1.4
See Also:
FocusTraversalPolicy.getInitialComponent(Window), UIFFocusTraversalPolicy.getInitialComponent(Window)

build

protected void build()
Builds the dialog's content pane, packs it, sets the resizable property, and locates it on the screen. The dialog is then ready to be opened.

Subclasses should rarely override this method.


buildContentPane

protected JComponent buildContentPane()
Builds and returns the content pane, sets the border and puts an optional header component in the dialog's north.

Subclasses will rarely override this method.

Returns:
the dialog's content pane with a border set and optional header in the north

buildHeader

protected JComponent buildHeader()
Builds and returns the optional header component, which will be put in the dialog's north by the default #buildContentPane implementation. By default this method answers null and so, no header will be used.

A typical implementation answers an instance of HeaderPane or a similar component, see the following code example:

 protected JComponent buildHeader() {
     return new HeaderPanel(
         "My Dialog",
           "You can do click on the tabs below to ...",
                   ResourceUtils.getIcon(MyResourceIDs.MY_DIALOG_ICON)
                );
 }
 

Returns:
the built header component

buildContent

protected abstract JComponent buildContent()
Builds and answers the dialog's main content without header and border. Subclass must override this method. See the class comment for a detailed description how this method is part of the build process.

Returns:
the dialog's main content without header and border

open

public void open()
Builds the dialog content, marks it as not canceled and makes it visible.


close

public void close()
Closes the dialog: makes it invisible and disposes it, which in turn releases all required OS resources.


hasBeenCanceled

public boolean hasBeenCanceled()
Checks and answers whether the dialog has been canceled. This indicator is set in #doAccept and #doCancel.

Returns:
true indicates that the dialog has been canceled

configureWindowClosing

protected void configureWindowClosing()
Configures the closing behavior: invokes #doCloseWindow instead of just closing the dialog. This allows subclasses to hook into the close process and perform a custom code sequence.


resizeHook

protected void resizeHook(JComponent component)
Resizes the specified component. This method is called during the build process and enables subclasses to achieve a better aspect ratio, by applying a resizer, e.g. the Resizer.

Parameters:
component - the component to be resized

getDialogBorder

protected Border getDialogBorder()
Returns the border that will be put around the content, which has been created by #buildContent.

Subclasses will typically use DIALOG_BORDER or CARD_DIALOG_BORDER, which is more narrow than the default.

Returns:
the dialog's border

setResizable

protected void setResizable()
Sets the dialog's resizable state. By default dialogs are non-resizable; subclasses may override.


locateOnScreen

protected void locateOnScreen()
Locates the dialog on the screen. The default implementation sets the location relative to the parent.

Subclasses may choose to center the dialog or put it in a screen corner.


buffer

public final com.jgoodies.binding.value.BufferedValueModel buffer(com.jgoodies.binding.value.ValueModel valueModel)
Creates and returns a BufferedValueModel on the given ValueModel using the dialog's trigger channel to trigger commit and flush events. This is just a convenience method to minimize the code necessary to buffer underlying models.

Parameters:
valueModel - the value model to be buffered
Returns:
a BufferedValueModel triggered by the dialog's trigger channel
See Also:
BufferedValueModel, ValueModel, Trigger

getTriggerChannel

public final com.jgoodies.binding.value.ValueModel getTriggerChannel()
Returns a ValueModel that can be used to trigger commit and flush events in BufferedValueModels. The trigger channel's value changes to true in #doApply which is invoked by #doAccept, and it changes to false in #doReset and #doCancel.

Returns:
the dialog's trigger channel
See Also:
BufferedValueModel, ValueModel, setTriggerChannel(ValueModel)

setTriggerChannel

public final void setTriggerChannel(com.jgoodies.binding.value.ValueModel newTriggerChannel)
Sets the given ValueModel as the dialog's new trigger channel. Subsequent invocations of #doApply, #doAccept, #doReset and #doCancel will trigger commit and flush events using the new trigger channel.

Parameters:
newTriggerChannel - the ValueModel to be set as the dialog's trigger channel
Throws:
NullPointerException - if the new trigger channel is null
See Also:
BufferedValueModel, ValueModel, getTriggerChannel()

triggerCommit

protected final void triggerCommit()
Ensures that the trigger channel changes to true which in turn triggers commit events in all BufferedValueModel instances that share this trigger. By default this method is invoked in doApply().

See Also:
triggerFlush(), doApply()

triggerFlush

protected final void triggerFlush()
Ensures that the trigger channel changes to false which in turn triggers flush events in all BufferedValueModel instances that share this trigger. By default this method is invoked in doReset().

See Also:
triggerCommit(), doReset()

createAcceptButton

protected UIFButton createAcceptButton(String text,
                                       boolean isDefault)
Creates and returns an Accept button with the given label text and default state. Clicking this button invokes #doAccept, which by default closes this dialog.

While this method allows to use a custom label, method #createOKButton uses a standardized internationalized OK text.

Subclasses that use this method to create the dialog OK or Accept button shall ensure that #doAccept performs the appropriate actions.

Parameters:
text - the button's label text
isDefault - true to make the button the default button
Returns:
an accept button with the given label text and default state
See Also:
doAccept(), createOKButton(boolean)

createApplyButton

protected UIFButton createApplyButton()
Creates and returns an Apply button. Clicking this button invokes #doApply which by default lets the dialog remain open. The button's label text can be localized under key ResourceID.BUTTON_APPLY_TEXT.

Returns:
an Apply button
See Also:
doApply(), getApplyAction()

createCancelButton

protected UIFButton createCancelButton()
Creates and returns a Cancel button. Clicking this button invokes #doCancel which by default closes the dialog. The button's label text can be localized under key ResourceID.BUTTON_CANCEL_TEXT.

The button created by this method has the property verifyInputWhenFocusTarget set to false.

Returns:
a Cancel button
See Also:
doCancel()

createCloseButton

protected UIFButton createCloseButton(boolean isDefault)
Creates and returns a Close button. Clicking this button invokes #doClose which by default just closes the dialog. The button's label text can be localized under key ResourceID.BUTTON_CLOSE_TEXT.

Parameters:
isDefault - true to make this the default button
Returns:
a Close button
See Also:
doClose()

createOKButton

protected UIFButton createOKButton(boolean isDefault)
Creates and returns an OK button. Clicking this button invokes #doAccept which by default performs a #doAccept, sets the canceled marker to false and finally closes the dialog.

This method uses #createAcceptButton to create the button, and uses a standardized internationalized OK label text that you can be localize under key ResourceID.BUTTON_OK_TEXT.

Parameters:
isDefault - true to make this the default button
Returns:
an OK button
See Also:
doAccept(), doApply()

createResetButton

protected UIFButton createResetButton()
Creates and returns a Reset button. Clicking this button invokes #doReset which by default lets the dialog remain open. The button's label text can be localized under key ResourceID.BUTTON_RESET_TEXT.

Returns:
a Reset button
See Also:
doReset()

setDefaultButton

protected void setDefaultButton(JButton button)
Sets a button as default button in the dialog's root pane.

Parameters:
button - the button to be set as default

buildButtonBarWithClose

protected JComponent buildButtonBarWithClose()
Builds and returns a button bar with a Close button. Uses #createCloseButton to create a standardized button.

Returns:
a button bar that contains a Close button
See Also:
createCloseButton(boolean)

buildButtonBarWithOKCancel

protected JComponent buildButtonBarWithOKCancel()
Builds and returns a button bar with an OK and a Cancel button. Uses #createOKButton and #createCancelButton to create standardized buttons.

Returns:
a button bar that contains an OK and a Cancel button
See Also:
createOKButton(boolean), createCancelButton()

buildButtonBarWithOKCancelApply

protected JComponent buildButtonBarWithOKCancelApply()
Builds and returns a button bar with three buttons: OK, Cancel and Apply. Uses #createOKButton, #createCancelButton and #createApplyButton to create standardized buttons.

Returns:
a button bar that contains: an OK, a Cancel and an Apply button
See Also:
createOKButton(boolean), createCancelButton(), createApplyButton()

doAccept

public void doAccept()
Invokes #doApply, marks the dialog as uncanceled and finally closes it. This method is intended to apply value changes and then quit the dialog. Typically the core of this action is performed in #doApply. This method is invoked if an Accept or OK button created by #createAcceptButton or createOKButton has been clicked. Such buttons use a DispatchingActionListener that in turn delegates the action perform to this method.


doApply

public void doApply()
Applies changes in the dialog and leaves the dialog open. Changes the trigger channel to true, which will commit values buffered by BufferedValueModels that share this dialog's trigger channel.

This method is invoked if an Apply button created by #createApplyButton has been clicked. Such buttons use a DispatchingActionListener that in turn delegates the action perform to this method. By default this method is called by #doAccept which is performed when an Accept or OK button has been clicked.

Subclasses that override this method shall typically invoke this super method or shall ensure that the trigger is committed.

See Also:
doAccept(), doReset(), triggerCommit()

doCancel

public void doCancel()
Resets changed dialog values, marks the dialog as canceled and closes it. This method is invoked if a Cancel button created by #createCancelButton has been clicked. Such buttons use a DispatchingActionListener that in turn delegates the action perform to this method.


doClose

public void doClose()
Marks the dialog as uncanceled and closes it. This method is invoked if a Close button created by #createCloseButton has been clicked. Such buttons use a DispatchingActionListener that in turn delegates the action perform to this method.


doCloseWindow

protected void doCloseWindow()
Performs the close window action that is invoked if the dialog is closing, for example by clicking the dialog's close button (often in the upper right corner). By default this methods performs a cancel via #doCancel.


doReset

public void doReset()
Resets changed dialog values and leaves the dialog open. Changes the trigger channel to false, which will flush values buffered by BufferedValueModels that share this dialog's trigger channel.

This method is invoked if a Reset button created by #createResetButton has been clicked. Such buttons use a DispatchingActionListener that in turn delegates the action perform to this method. By default this method is called by #doCancel which is performed when a Cancel button has been clicked.

Subclasses that override this method shall typically invoke this super method or shall ensure that the trigger is flushed.

See Also:
doAccept(), doReset(), triggerFlush()

getApplyAction

public Action getApplyAction()
Lazily creates and returns the Apply Action that invokes #doApply.

Returns:
the lazily created Apply Action
See Also:
createApplyButton(), buildButtonBarWithOKCancelApply()

getCancelAction

public Action getCancelAction()
Lazily creates and returns the Cancel Action that invokes #doCancel.

Returns:
the lazily created Cancel Action
See Also:
createCancelButton(), buildButtonBarWithOKCancel(), buildButtonBarWithOKCancelApply()

getCloseAction

public Action getCloseAction()
Lazily creates and returns the Close Action that invokes #doClose.

Returns:
the lazily created Close Action
See Also:
createCloseButton(boolean), buildButtonBarWithOKCancelApply()

getOKAction

public Action getOKAction()
Lazily creates and returns the OK Action that invokes #doAccept.

Returns:
the lazily created OK Action
See Also:
createOKButton(boolean), buildButtonBarWithOKCancel(), buildButtonBarWithOKCancelApply()

getResetAction

public Action getResetAction()
Lazily creates and returns the Reset Action that invokes #doReset.

Returns:
the lazily created Reset Action
See Also:
createResetButton()


Copyright © 2000-2008 JGoodies Karsten Lentzsch. All Rights Reserved.