|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.awt.Component
java.awt.Container
java.awt.Window
java.awt.Dialog
javax.swing.JDialog
com.jgoodies.uif.AbstractDialog
public abstract class AbstractDialog
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(); } }
ButtonBarFactory
,
Resizer
,
ValueModel
,
BufferedValueModel
,
Trigger
,
Serialized FormNested 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 java.awt.Dialog |
---|
addNotify, getModalityType, getTitle, hide, isModal, isResizable, isUndecorated, setModal, setModalityType, setResizable, setTitle, setUndecorated, setVisible, show, toBack |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final String PROPERTYNAME_TRIGGER_CHANNEL
getTriggerChannel()
,
setTriggerChannel(ValueModel)
,
Constant Field Valuesprotected static final Border DIALOG_BORDER
protected static final Border CARD_DIALOG_BORDER
Constructor Detail |
---|
public AbstractDialog()
public AbstractDialog(Frame owner)
AbstractDialog
with the given Frame
as its owner, using the application's default window title.
owner
- the dialog's parent framepublic AbstractDialog(Frame owner, String title)
AbstractDialog
with the given Frame
as its owner using the given window title.
owner
- the dialog's parent frametitle
- the window titlepublic AbstractDialog(Frame owner, String title, boolean modal)
AbstractDialog
with the given Frame
as its owner using the given window title and the specified modal state.
owner
- the dialog's parent frametitle
- the window titlemodal
- true for a model dialog, false for non-modalpublic AbstractDialog(Dialog owner)
AbstractDialog
with the given Dialog
as its owner using the application's default window title.
owner
- the dialog's parent dialogpublic AbstractDialog(Dialog owner, String title)
AbstractDialog
with the given
Dialog
as its owner using the given window title.
owner
- the dialog's parent dialogtitle
- the window titlepublic AbstractDialog(Dialog owner, String title, boolean modal)
AbstractDialog
with the given
Dialog
as its owner using the given window title
and the specified modal state.
owner
- the dialog's parent dialogtitle
- the window titlemodal
- true for a model dialog, false for non-modalMethod Detail |
---|
public ResourceMap getResourceMap()
protected String getString(String key)
key
- the key used to lookup the localized string
getResourceMap()
public static Mode getEscapeCancelsDefaultMode()
setEscapeCancelsMode
.
setEscapeCancelsDefaultMode(Mode)
,
getEscapeCancelsMode()
,
setEscapeCancelsMode(Mode)
public static void setEscapeCancelsDefaultMode(Mode defaultValue)
setEscapeCancelsMode
.
defaultValue
- the value to be set as defaultgetEscapeCancelsDefaultMode()
,
getEscapeCancelsMode()
,
setEscapeCancelsMode(Mode)
public Mode getEscapeCancelsMode()
The default value for this property can be specified using
#setEscapeCancelsDefaultMode
.
setEscapeCancelsMode(Mode)
,
getEscapeCancelsDefaultMode()
,
setEscapeCancelsDefaultMode(Mode)
public void setEscapeCancelsMode(Mode escapeCancelsMode)
The default value for this property can be specified using
#setEscapeCancelsDefaultMode
.
escapeCancelsMode
- true to bind the Escape key to the cancel actiongetEscapeCancelsMode()
,
getEscapeCancelsDefaultMode()
,
setEscapeCancelsDefaultMode(Mode)
public void setInitialComponent(Component initialComponent)
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.
initialComponent
- the Component to get the focus if this dialog
becomes visible the first timeFocusTraversalPolicy.getInitialComponent(Window)
,
UIFFocusTraversalPolicy.getInitialComponent(Window)
protected void build()
Subclasses should rarely override this method.
protected JComponent buildContentPane()
Subclasses will rarely override this method.
protected JComponent buildHeader()
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) ); }
protected abstract JComponent buildContent()
public void open()
public void close()
public boolean hasBeenCanceled()
protected void configureWindowClosing()
protected void resizeHook(JComponent component)
Resizer
.
component
- the component to be resizedprotected Border getDialogBorder()
Subclasses will typically use DIALOG_BORDER
or
CARD_DIALOG_BORDER
, which is more narrow than the default.
protected void setResizable()
protected void locateOnScreen()
Subclasses may choose to center the dialog or put it in a screen corner.
public final com.jgoodies.binding.value.BufferedValueModel buffer(com.jgoodies.binding.value.ValueModel valueModel)
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.
valueModel
- the value model to be buffered
BufferedValueModel
,
ValueModel
,
Trigger
public final com.jgoodies.binding.value.ValueModel getTriggerChannel()
#doApply
which is invoked by #doAccept
,
and it changes to false in #doReset
and
#doCancel
.
BufferedValueModel
,
ValueModel
,
setTriggerChannel(ValueModel)
public final void setTriggerChannel(com.jgoodies.binding.value.ValueModel newTriggerChannel)
#doApply, #doAccept, #doReset
and #doCancel
will trigger commit and flush events
using the new trigger channel.
newTriggerChannel
- the ValueModel to be set as the dialog's trigger channel
NullPointerException
- if the new trigger channel is null
BufferedValueModel
,
ValueModel
,
getTriggerChannel()
protected final void triggerCommit()
BufferedValueModel
instances that share
this trigger. By default this method is invoked in doApply()
.
triggerFlush()
,
doApply()
protected final void triggerFlush()
BufferedValueModel
instances that share
this trigger. By default this method is invoked in doReset()
.
triggerCommit()
,
doReset()
protected UIFButton createAcceptButton(String text, boolean isDefault)
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.
text
- the button's label textisDefault
- true to make the button the default button
doAccept()
,
createOKButton(boolean)
protected UIFButton createApplyButton()
ResourceID.BUTTON_APPLY_TEXT
.
doApply()
,
getApplyAction()
protected UIFButton createCancelButton()
ResourceID.BUTTON_CANCEL_TEXT
.
The button created by this method has the property
verifyInputWhenFocusTarget set to false
.
doCancel()
protected UIFButton createCloseButton(boolean isDefault)
ResourceID.BUTTON_CLOSE_TEXT
.
isDefault
- true to make this the default button
doClose()
protected UIFButton createOKButton(boolean isDefault)
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
.
isDefault
- true to make this the default button
doAccept()
,
doApply()
protected UIFButton createResetButton()
ResourceID.BUTTON_RESET_TEXT
.
doReset()
protected void setDefaultButton(JButton button)
button
- the button to be set as defaultprotected JComponent buildButtonBarWithClose()
createCloseButton(boolean)
protected JComponent buildButtonBarWithOKCancel()
createOKButton(boolean)
,
createCancelButton()
protected JComponent buildButtonBarWithOKCancelApply()
createOKButton(boolean)
,
createCancelButton()
,
createApplyButton()
public void doAccept()
#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.
public void doApply()
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.
doAccept()
,
doReset()
,
triggerCommit()
public void doCancel()
#createCancelButton
has been clicked.
Such buttons use a DispatchingActionListener that in turn
delegates the action perform to this method.
public void doClose()
#createCloseButton
has been clicked.
Such buttons use a DispatchingActionListener that in turn
delegates the action perform to this method.
protected void doCloseWindow()
#doCancel
.
public void doReset()
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.
doAccept()
,
doReset()
,
triggerFlush()
public Action getApplyAction()
createApplyButton()
,
buildButtonBarWithOKCancelApply()
public Action getCancelAction()
createCancelButton()
,
buildButtonBarWithOKCancel()
,
buildButtonBarWithOKCancelApply()
public Action getCloseAction()
createCloseButton(boolean)
,
buildButtonBarWithOKCancelApply()
public Action getOKAction()
createOKButton(boolean)
,
buildButtonBarWithOKCancel()
,
buildButtonBarWithOKCancelApply()
public Action getResetAction()
createResetButton()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |