org.springframework.richclient.dialog
Class ApplicationDialog

Show UML class diagram

java.lang.Object
  org.springframework.richclient.application.support.ApplicationServicesAccessor
      org.springframework.richclient.dialog.ApplicationDialog

All Implemented Interfaces:

Guarded, TitleConfigurable

Direct Known Subclasses:

AboutBox.AboutDialog, AbstractSelectionDialog, BasicApplicationDialog, ButtonStackBarSample, ConfirmationDialog, InputApplicationDialog, MessageDialog, TitledApplicationDialog, TitledWidgetApplicationDialog, ToolbarSample

public abstract class ApplicationDialog
extends ApplicationServicesAccessor
implements TitleConfigurable, Guarded

Abstract Base Class for a dialog with standard layout, buttons, and behavior.

Use of this class will apply a standard appearance to dialogs in the application.

Subclasses implement the body of the dialog (wherein business objects are manipulated), and the action taken by the OK button. Aside from creating the dialog's contentj with createDialogContentPane(), a proper disposing should be implemented in disposeDialogContentPane().

Services of a ApplicationDialog include:

• centering on the parent frame
• reusing the parent's icon
• standard layout and border spacing, based on Java Look and Feel guidelines.
• uniform naming style for dialog title
• OK and Cancel buttons at the bottom of the dialog -OK is the default, and the Escape key activates Cancel (the latter works only if the dialog receives the escape keystroke, and not one of its components)
• by default, modal
• enabling & disabling of resizing
• will be shown in taskbar if no parent window has been set, and no applicationwindow is open

Note: Default close behaviour is to dispose the graphical dialog when it closes, you can set the CloseAction to hide if needed.

Author:

Keith Donald, Jan Hoskens

Field Summary

protected static String	DEFAULT_CANCEL_COMMAND_ID
protected static String	DEFAULT_FINISH_COMMAND_ID
protected static String	DEFAULT_FINISH_SUCCESS_MESSAGE_KEY
protected static String	DEFAULT_FINISH_SUCCESS_TITLE_KEY
protected org.apache.commons.logging.Log	logger
protected static String	SUCCESS_FINISH_MESSAGE_KEY
protected static String	SUCCESS_FINISH_TITLE_KEY

Constructor Summary

ApplicationDialog()
Create dialog with default closeAction CloseAction.DISPOSE.

ApplicationDialog(String title, Component parent)
Create dialog with default closeAction CloseAction.DISPOSE.

ApplicationDialog(String title, Component parent, CloseAction closeAction)
Creates a new application dialog.

Method Summary

protected void	addActionKeyBinding(KeyStroke key, String actionKey) Add an action key binding to this dialog.
protected void	addActionKeyBinding(KeyStroke key, String actionKey, Action action) Add an action key binding to this dialog.
protected void	addDialogComponents() Subclasses may override to customize how this dialog is built.
protected void	attachListeners() Attach the handler that invokes the lifecycle methods on the ApplicationDialog.
protected void	componentsChanged() Subclasses should call if layout of the dialog components changes.
protected JComponent	createButtonBar() Return a standardized row of command buttons, right-justified and all of the same size, with OK as the default button, and no mnemonics used, as per the Java Look and Feel guidelines.
protected void	createDialog() Builds/initializes the dialog and all of its components.
protected abstract JComponent	createDialogContentPane() Return the GUI which allows the user to manipulate the business objects related to this dialog.
protected void	dispose() Close and dispose of the visual dialog.
protected void	disposeDialogContentPane() Cleanup any components/objects that are created during createDialogContentPane().
protected ActionMap	getActionMap() Return the ActionMap of the dialog.
protected ActionCommand	getCallingCommand() Returns the command that opened this dialog.
protected ActionCommand	getCancelCommand() Returns the cancel command.
protected String	getCancelCommandId() Returns the id for the cancel command.
protected Object[]	getCommandGroupMembers() Template getter method to return the commands to populate the dialog button bar.
JDialog	getDialog() Return the JDialog, create it if needed (lazy).
protected Container	getDialogContentPane() Return the contentPane of the dialog.
protected boolean	getDisplayFinishSuccessMessage() Return the message that needs to be set on a succesful finish.
protected ActionCommand	getFinishCommand() Returns the finish command.
protected String	getFinishCommandId() Subclasses may override to return a custom message key, default is "okCommand", corresponding to the "&OK" label.
protected String	getFinishSecurityControllerId() Subclasses may override to return a security controller id to be attached to the finish command.
protected String	getFinishSuccessMessage() Returns the message to use upon succesful finish.
protected Object[]	getFinishSuccessMessageArguments() Returns the arguments to use in the succesful finish message.
protected String	getFinishSuccessTitle() Returns the title to use upon succesful finish.
protected Object[]	getFinishSuccessTitleArguments() Returns the arguments to use in the finish succesful title.
protected InputMap	getInputMap() Return the InputMap of the dialog.
protected Point	getLocation() Return the location of the dialog.
protected Component	getLocationRelativeTo() Return the relative location of the dialog.
Component	getParentComponent() Returns the parent Component.
Window	getParentWindow() Returns the parent window based on the internal parent Component.
protected Dimension	getPreferredSize() Return the preferred size for the dialog.
protected String	getTitle() Returns the title of this dialog.
static Window	getWindowForComponent(Component parentComponent) --jh-- This method is copied from JOptionPane.
protected void	hide() Hide the dialog.
protected void	init() Hook called in constructor.
boolean	isControlCreated() Returns true if the JDialog is constructed.
boolean	isEnabled() Returns whether this Dialog is enabled.
boolean	isShowing() Returns true if the JDialog is showing.
protected void	onAboutToShow() Template lifecycle method invoked right before the dialog is to become visible.
protected void	onCancel() Handle a dialog cancellation request.
protected abstract boolean	onFinish() Request invocation of the action taken when the user hits the OK (finish) button.
protected void	onInitialized() Template lifecycle method invoked after the dialog control is initialized.
protected void	onWindowActivated() Template lifecycle method invoked when the dialog is activated.
protected void	onWindowClosing() Template lifecycle method invoked when the dialog's window is closing.
protected void	onWindowGainedFocus() Template lifecycle method invoked when the dialog gains focus.
protected void	onWindowLostFocus() Template lifecycle method invoked when the dialog loses focus.
protected void	registerCancelCommandAsDefault() Register the cancel button as the default dialog button.
protected void	registerDefaultCommand() Register the finish button as the default dialog button.
protected void	registerDefaultCommand(ActionCommand command) Register the provided button as the default dialog button.
void	setCallingCommand(ActionCommand callingCommand) Set the command that opened this dialog.
void	setCloseAction(CloseAction action) Set the CloseAction of this dialog.
void	setDefaultEnabled(boolean enabled) When opening the dialog, the finish button can be enabled by default.
void	setDisplayFinishSuccessMessage(boolean displayFinishSuccessMessage) Message to show upon succesful completion.
void	setEnabled(boolean enabled) Enable/disable the finish command of the dialog.
protected void	setFinishEnabled(boolean enabled) Enable/disable the finish command.
void	setLocation(Point location) Set a specific location for the JDialog to popup.
void	setLocationRelativeTo(Component locationRelativeTo) Set a relative location for the JDialog to popup.
void	setModal(boolean modal) Set the modal property of the dialog.
void	setParentComponent(Component parentComponent) The parent Component that will be used to extract the Frame/Dialog owner for the JDialog at creation.
void	setPreferredSize(Dimension preferredSize) Set the preferrred size for the JDialog.
void	setResizable(boolean resizable) Set the resizable property of the dialog.
void	setTitle(String title) Sets the title.
void	showDialog() Show the dialog.
protected void	showFinishSuccessMessageDialog() Opens a dialog which contains the sussesful finish message.

Methods inherited from class org.springframework.richclient.application.support.ApplicationServicesAccessor

getActiveWindow, getApplication, getApplicationContext, getApplicationName, getApplicationServices, getCommandConfigurer, getComponentFactory, getConversionService, getIconSource, getImageSource, getMessage, getMessage, getMessage, getMessage, getMessages, getMessageSource, getObjectConfigurer, getService

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FINISH_COMMAND_ID

protected static final String DEFAULT_FINISH_COMMAND_ID

See Also:

Constant Field Values

DEFAULT_CANCEL_COMMAND_ID

protected static final String DEFAULT_CANCEL_COMMAND_ID

See Also:

Constant Field Values

DEFAULT_FINISH_SUCCESS_MESSAGE_KEY

protected static final String DEFAULT_FINISH_SUCCESS_MESSAGE_KEY

See Also:

Constant Field Values

DEFAULT_FINISH_SUCCESS_TITLE_KEY

protected static final String DEFAULT_FINISH_SUCCESS_TITLE_KEY

See Also:

Constant Field Values

SUCCESS_FINISH_MESSAGE_KEY

protected static final String SUCCESS_FINISH_MESSAGE_KEY

See Also:

Constant Field Values

SUCCESS_FINISH_TITLE_KEY

protected static final String SUCCESS_FINISH_TITLE_KEY

See Also:

Constant Field Values

logger

protected final org.apache.commons.logging.Log logger

Constructor Detail

ApplicationDialog

public ApplicationDialog()

Create dialog with default closeAction CloseAction.DISPOSE. No parent or title set.

See Also:

init()

ApplicationDialog

public ApplicationDialog(String title,
                         Component parent)

Create dialog with default closeAction CloseAction.DISPOSE.

Parameters:

title - text that will appear on dialog's titlebar.

parent - component serving as parent in it's hierarchy.

See Also:

init()

ApplicationDialog

public ApplicationDialog(String title,
                         Component parent,
                         CloseAction closeAction)

Creates a new application dialog. The actual UI is not initialized until showDialog() is called.

Parameters:

title - text which appears in the title bar after the name of the application.

parent - frame to which this dialog is attached.

closeAction - sets the behaviour of the dialog upon close. Default closeAction is CloseAction.DISPOSE.

See Also:

init()

Method Detail

init

protected void init()

Hook called in constructor. Add specific initialization code here.

setTitle

public void setTitle(String title)

Sets the title.

Specified by:

setTitle in interface TitleConfigurable

Parameters:

title - the title

getTitle

protected String getTitle()

Returns the title of this dialog. If no specific title has been set, the calling command's text will be used. If that doesn't yield a result, the default title is returned.

See Also:

getCallingCommandText(), DEFAULT_DIALOG_TITLE

setParentComponent

public void setParentComponent(Component parentComponent)

The parent Component that will be used to extract the Frame/Dialog owner for the JDialog at creation. You may pass a Window/Frame that will be used directly as parent for the JDialog, or you can pass the component which has one of both in it's parent hierarchy. The latter option can be handy when you're locally implementing Components without a direct -connection to/notion of- a Window/Frame.

Parameters:

parentComponent - Component that is a Frame/Window or has one in its parent hierarchy.

getParentComponent

public Component getParentComponent()

Returns the parent Component.

Returns:

See Also:

setParentComponent(Component)

setCloseAction

public void setCloseAction(CloseAction action)

Set the CloseAction of this dialog. Default action is CloseAction.DISPOSE which disposes the visual dialog upon closing. When using CloseAction.HIDE the visual components are cached and reused.

Parameters:

action - the CloseAction to use when closing the dialog.

setDefaultEnabled

public void setDefaultEnabled(boolean enabled)

When opening the dialog, the finish button can be enabled by default.

Parameters:

enabled - true when the finish button should be enabled by default, false otherwise.

setModal

public void setModal(boolean modal)

Set the modal property of the dialog.

See Also:

Dialog.setModal(boolean)

setResizable

public void setResizable(boolean resizable)

Set the resizable property of the dialog.

See Also:

Dialog.setResizable(boolean)

setLocation

public void setLocation(Point location)

Set a specific location for the JDialog to popup.

Parameters:

location - point on screen where to place the JDialog.

setLocationRelativeTo

public void setLocationRelativeTo(Component locationRelativeTo)

Set a relative location for the JDialog to popup.

See Also:

Window.setLocationRelativeTo(Component)

setPreferredSize

public void setPreferredSize(Dimension preferredSize)

Set the preferrred size for the JDialog.

See Also:

JComponent.setPreferredSize(Dimension)

setEnabled

public void setEnabled(boolean enabled)

Enable/disable the finish command of the dialog.

Specified by:

setEnabled in interface Guarded

Parameters:

enabled - true to enable the object, false to disable it.

setDisplayFinishSuccessMessage

public void setDisplayFinishSuccessMessage(boolean displayFinishSuccessMessage)

Message to show upon succesful completion.

setCallingCommand

public void setCallingCommand(ActionCommand callingCommand)

Set the command that opened this dialog.

See Also:

getFinishSuccessMessage(), getFinishSuccessTitle()

setFinishEnabled

protected void setFinishEnabled(boolean enabled)

Enable/disable the finish command.

isEnabled

public boolean isEnabled()

Returns whether this Dialog is enabled.

Specified by:

isEnabled in interface Guarded

Returns:

if the object is in an enabled state, otherwise.

isShowing

public boolean isShowing()

Returns true if the JDialog is showing.

See Also:

Window.isShowing()

isControlCreated

public boolean isControlCreated()

Returns true if the JDialog is constructed.

getDialog

public JDialog getDialog()

Return the JDialog, create it if needed (lazy).

getDialogContentPane

protected Container getDialogContentPane()

Return the contentPane of the dialog.

See Also:

JDialog.getContentPane()

showDialog

public void showDialog()

Show the dialog. The dialog will be created if it doesn't exist yet. Before setting the dialog visible, a hook method onAboutToShow is called and the location will be set.

When showing the dialog several times, it will always be opened on the location that has been set, or relative to the parent. (former location will not persist)

componentsChanged

protected void componentsChanged()

Subclasses should call if layout of the dialog components changes.

createDialog

protected final void createDialog()

Builds/initializes the dialog and all of its components.

Follows the Java Look and Feel guidelines for spacing elements.

getWindowForComponent

public static Window getWindowForComponent(Component parentComponent)
                                    throws HeadlessException

--jh-- This method is copied from JOptionPane. I'm still trying to figure out why they chose to have a static method with package visibility for this one instead of just making it public.

Returns the specified component's toplevel Frame or Dialog.

Parameters:

parentComponent - the Component to check for a Frame or Dialog

Returns:

the Frame or Dialog that contains the component, or the default frame if the component is null, or does not have a valid Frame or Dialog parent

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless returns true

See Also:

GraphicsEnvironment.isHeadless()

getFinishCommandId

protected String getFinishCommandId()

Subclasses may override to return a custom message key, default is "okCommand", corresponding to the "&OK" label.

Returns:

The message key to use for the finish ("ok") button

getFinishSecurityControllerId

protected String getFinishSecurityControllerId()

Subclasses may override to return a security controller id to be attached to the finish command. The default is null, no controller.

Returns:

security controller id, or null if none

onFinish

protected abstract boolean onFinish()

Request invocation of the action taken when the user hits the OK (finish) button.

Returns:

true if action completed successfully; false otherwise.

getDisplayFinishSuccessMessage

protected boolean getDisplayFinishSuccessMessage()

Return the message that needs to be set on a succesful finish.

showFinishSuccessMessageDialog

protected void showFinishSuccessMessageDialog()

Opens a dialog which contains the sussesful finish message.

See Also:

getFinishSuccessTitle(), getFinishSuccessMessage()

getFinishSuccessMessage

protected String getFinishSuccessMessage()

Returns the message to use upon succesful finish.

getCallingCommand

protected ActionCommand getCallingCommand()

Returns the command that opened this dialog.

getFinishSuccessMessageArguments

protected Object[] getFinishSuccessMessageArguments()

Returns the arguments to use in the succesful finish message.

getFinishSuccessTitle

protected String getFinishSuccessTitle()

Returns the title to use upon succesful finish.

getFinishSuccessTitleArguments

protected Object[] getFinishSuccessTitleArguments()

Returns the arguments to use in the finish succesful title.

getCancelCommandId

protected String getCancelCommandId()

Returns the id for the cancel command.

getFinishCommand

protected ActionCommand getFinishCommand()

Returns the finish command.

getCancelCommand

protected ActionCommand getCancelCommand()

Returns the cancel command.

addActionKeyBinding

protected void addActionKeyBinding(KeyStroke key,
                                   String actionKey)

Add an action key binding to this dialog.

Parameters:

key - the KeyStroke that triggers the command/action.

actionKey - id of command that will be triggered by the KeyStroke.

See Also:

addActionKeyBinding(KeyStroke, String, Action)

addActionKeyBinding

protected void addActionKeyBinding(KeyStroke key,
                                   String actionKey,
                                   Action action)

Add an action key binding to this dialog.

Parameters:

key - the KeyStroke that triggers the command/action.

actionKey - id of the action.

action - Action that will be triggered by the KeyStroke.

See Also:

getActionMap(), getInputMap(), ActionMap.put(Object, Action), InputMap.put(KeyStroke, Object)

getActionMap

protected ActionMap getActionMap()

Return the ActionMap of the dialog.

See Also:

JComponent.getActionMap()

getInputMap

protected InputMap getInputMap()

Return the InputMap of the dialog.

See Also:

JComponent.getInputMap(int)

addDialogComponents

protected void addDialogComponents()

Subclasses may override to customize how this dialog is built.

getLocation

protected Point getLocation()

Return the location of the dialog.

getLocationRelativeTo

protected Component getLocationRelativeTo()

Return the relative location of the dialog.

getPreferredSize

protected Dimension getPreferredSize()

Return the preferred size for the dialog.

createDialogContentPane

protected abstract JComponent createDialogContentPane()

Return the GUI which allows the user to manipulate the business objects related to this dialog. This GUI will be placed above the OK and Cancel buttons, in a standard manner.

Any components/objects created at this point need to be disposed in disposeDialogContentPane().

See Also:

disposeDialogContentPane()

attachListeners

protected final void attachListeners()

Attach the handler that invokes the lifecycle methods on the ApplicationDialog.

See Also:

DialogEventHandler

createButtonBar

protected JComponent createButtonBar()

Return a standardized row of command buttons, right-justified and all of the same size, with OK as the default button, and no mnemonics used, as per the Java Look and Feel guidelines.

getCommandGroupMembers

protected Object[] getCommandGroupMembers()

Template getter method to return the commands to populate the dialog button bar.

Returns:

The array of commands (may also be a separator or glue identifier)

registerDefaultCommand

protected void registerDefaultCommand()

Register the finish button as the default dialog button.

registerCancelCommandAsDefault

protected final void registerCancelCommandAsDefault()

Register the cancel button as the default dialog button.

registerDefaultCommand

protected final void registerDefaultCommand(ActionCommand command)

Register the provided button as the default dialog button. The button must be present on the dialog.

Parameters:

command - The button to become the default.

onInitialized

protected void onInitialized()

Template lifecycle method invoked after the dialog control is initialized.

onAboutToShow

protected void onAboutToShow()

Template lifecycle method invoked right before the dialog is to become visible.

onWindowGainedFocus

protected void onWindowGainedFocus()

Template lifecycle method invoked when the dialog gains focus.

onWindowActivated

protected void onWindowActivated()

Template lifecycle method invoked when the dialog is activated.

onWindowLostFocus

protected void onWindowLostFocus()

Template lifecycle method invoked when the dialog loses focus.

onWindowClosing

protected void onWindowClosing()

Template lifecycle method invoked when the dialog's window is closing.

onCancel

protected void onCancel()

Handle a dialog cancellation request.

dispose

protected final void dispose()

Close and dispose of the visual dialog. This forces the dialog to be re-built on the next show. Any subclasses that are creating visual components and holding references to them should dispose them when the surrounding dialog is disposed by implementing disposeDialogContentPane(). Any other objects that are created in createDialogContentPane() can be handled here as well.

See Also:

disposeDialogContentPane()

disposeDialogContentPane

protected void disposeDialogContentPane()

Cleanup any components/objects that are created during createDialogContentPane(). This method is called if the CloseAction is set to CloseAction.DISPOSE and the dialog is being closed. This ensures that when disposing the surrounding dialog, the content pane can be disposed as well.

See Also:

createDialogContentPane(), dispose()

hide

protected final void hide()

Hide the dialog. This differs from dispose in that the dialog control stays cached in memory.

getParentWindow

public Window getParentWindow()

Returns the parent window based on the internal parent Component. Will search for a Window in the parent hierarchy if needed (when parent Component isn't a Window).

Returns:

the parent window