org.fife.ui
Class OptionsDialog

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 org.fife.ui.EscapableDialog
                          extended by org.fife.ui.OptionsDialog
All Implemented Interfaces:
java.awt.event.ActionListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.beans.PropertyChangeListener, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.event.TreeSelectionListener, javax.swing.RootPaneContainer, javax.swing.WindowConstants
Direct Known Subclasses:
OptionsDialog

public class OptionsDialog
extends EscapableDialog
implements java.awt.event.ActionListener, javax.swing.event.TreeSelectionListener, java.beans.PropertyChangeListener

An options dialog similar to those found in many Microsoft Windows applications. An OptionsDialog contains a list on its left-hand side containing options categories; clicking on a category displays all options related to that category.

Using this class along with OptionsDialogPanel will provide you with a framework for creating an Options dialog with error checking and instant-Apply functionality.

Version:
0.8
Author:
Robert Futrell
See Also:
OptionsDialogPanel, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JDialog
javax.swing.JDialog.AccessibleJDialog
 
Nested classes/interfaces inherited from class java.awt.Dialog
java.awt.Dialog.AccessibleAWTDialog, java.awt.Dialog.ModalExclusionType, java.awt.Dialog.ModalityType
 
Nested classes/interfaces inherited from class java.awt.Window
java.awt.Window.AccessibleAWTWindow
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
 
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
OptionsDialog(java.awt.Frame owner)
          Creates a new options dialog with no options panels.
OptionsDialog(java.awt.Frame owner, OptionsDialogPanel[] optionsPanels)
          Creates a new options dialog with the specified array of option panels.
 
Method Summary
 void actionPerformed(java.awt.event.ActionEvent e)
          Listens for action events in this dialog.
 boolean doApply(java.awt.Frame owner)
          Automatically called when the user clicks the "Apply" button and when the user first clicks the "OK" button before the dialog goes away.
protected  void escapePressed()
          Called when the Escape key is pressed in this dialog.
 java.lang.String getApplyButtonText()
          Returns the text on the "Apply" button.
 java.lang.String getCancelButtonText()
          Returns the text on the "Cancel" button.
 java.lang.String getOKButtonText()
          Returns the text on the "OK" button.
protected  OptionsDialogPanel[] getOptionsDialogPanels()
          Returns the option panels.
 void initialize()
          Initializes all fields/radio buttons/etc. in this options dialog with their proper states as obtained from the owner of this options dialog (as passed into the constructor).
 void propertyChange(java.beans.PropertyChangeEvent e)
          Listens for a property change in one of the option panels.
 void setApplyButtonEnabled(boolean enabled)
          Enables or disables the "Apply" button.
 void setApplyButtonText(java.lang.String text)
          Sets the text on the "Apply" button.
 void setCancelButtonText(java.lang.String text)
          Sets the text on the "Cancel" button.
 void setOKButtonText(java.lang.String text)
          Sets the text on the "OK" button.
 void setOptionsPanels(java.util.List<OptionsDialogPanel> optionsPanels)
          Sets the options panels available on this options dialog.
 void setOptionsPanels(OptionsDialogPanel[] optionsPanels)
          Sets the options panels available on this options dialog.
 boolean setSelectedOptionsPanel(java.lang.String name)
          Selects the options panel with the specified name.
 void setVisible(boolean visible)
          This method is overridden to ensure that all nodes in the tree are expanded (as if they're not, the size of the window and its widgets may be incorrect; not enough room for the tree).
 void valueChanged(javax.swing.event.TreeSelectionEvent e)
          Listens for the user to select values in the tree.
 
Methods inherited from class org.fife.ui.EscapableDialog
setEscapeClosesDialog
 
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, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, paint, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, toFront
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

OptionsDialog

public OptionsDialog(java.awt.Frame owner)
Creates a new options dialog with no options panels.

Parameters:
owner - The parent of this dialog.

OptionsDialog

public OptionsDialog(java.awt.Frame owner,
                     OptionsDialogPanel[] optionsPanels)
Creates a new options dialog with the specified array of option panels.

Parameters:
owner - The parent of this dialog.
optionsPanels - The option panels to add to this options dialog. Note that this array MUST have at least one panel in it; otherwise, this constructor will throw a NullPointerException.
See Also:
OptionsDialogPanel
Method Detail

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent e)
Listens for action events in this dialog.

Specified by:
actionPerformed in interface java.awt.event.ActionListener

escapePressed

protected void escapePressed()
Called when the Escape key is pressed in this dialog. Subclasses can override to handle any custom "Cancel" logic.

Overrides:
escapePressed in class EscapableDialog

doApply

public final boolean doApply(java.awt.Frame owner)
Automatically called when the user clicks the "Apply" button and when the user first clicks the "OK" button before the dialog goes away. This method first ensures all input is valid by calling ensureValidInputs on all option panels; then it actually applies the changes to the application. If all inputs were valid, then the Apply button is disabled and the "unsaved changes" flag for all Options panels is cleared. If there was a problem in any of the inputs, an error dialog is displayed.

Parameters:
owner - The parent frame that was specified in the constructor.
Returns:
true if all options checked out okay and the apply was successful; false if at least one option wasn't valid (and thus the Options dialog needs to stay up).

getApplyButtonText

public final java.lang.String getApplyButtonText()
Returns the text on the "Apply" button.

Returns:
The text on the Apply button.
See Also:
setApplyButtonText(java.lang.String)

getCancelButtonText

public final java.lang.String getCancelButtonText()
Returns the text on the "Cancel" button.

Returns:
The text on the Cancel button.
See Also:
setCancelButtonText(java.lang.String)

getOKButtonText

public final java.lang.String getOKButtonText()
Returns the text on the "OK" button.

Returns:
The text on the OK button.
See Also:
setOKButtonText(java.lang.String)

getOptionsDialogPanels

protected OptionsDialogPanel[] getOptionsDialogPanels()
Returns the option panels.

Returns:
The option panels.

initialize

public void initialize()
Initializes all fields/radio buttons/etc. in this options dialog with their proper states as obtained from the owner of this options dialog (as passed into the constructor). The "Apply" button will be disabled as a visual cue that nothing has been modified yet.


propertyChange

public void propertyChange(java.beans.PropertyChangeEvent e)
Listens for a property change in one of the option panels. This basically just listens for the user to change a value, so it can activate the "Apply" button.

Specified by:
propertyChange in interface java.beans.PropertyChangeListener

setApplyButtonEnabled

public void setApplyButtonEnabled(boolean enabled)
Enables or disables the "Apply" button.

Parameters:
enabled - Whether or not the Apply button should be enabled.

setApplyButtonText

public void setApplyButtonText(java.lang.String text)
Sets the text on the "Apply" button.

Parameters:
text - The text to use on the Apply button.
See Also:
getApplyButtonText()

setCancelButtonText

public void setCancelButtonText(java.lang.String text)
Sets the text on the "Cancel" button.

Parameters:
text - The text to use on the Cancel button.
See Also:
getCancelButtonText()

setOKButtonText

public void setOKButtonText(java.lang.String text)
Sets the text on the "OK" button.

Parameters:
text - The text to use on the OK button.
See Also:
getOKButtonText()

setOptionsPanels

public void setOptionsPanels(java.util.List<OptionsDialogPanel> optionsPanels)
Sets the options panels available on this options dialog.

Parameters:
optionsPanels - The options panels to be available.
See Also:
setOptionsPanels(OptionsDialogPanel[])

setOptionsPanels

public void setOptionsPanels(OptionsDialogPanel[] optionsPanels)
Sets the options panels available on this options dialog.

Parameters:
optionsPanels - The options panels to be available.
See Also:
setOptionsPanels(List)

setSelectedOptionsPanel

public boolean setSelectedOptionsPanel(java.lang.String name)
Selects the options panel with the specified name.

Parameters:
name - The name of the panel.
Returns:
Whether the panel was selected. This will only be false if name is not the name of an options panel added to this dialog.

setVisible

public void setVisible(boolean visible)
This method is overridden to ensure that all nodes in the tree are expanded (as if they're not, the size of the window and its widgets may be incorrect; not enough room for the tree).

Overrides:
setVisible in class java.awt.Dialog
Parameters:
visible - Whether or not this dialog should be visible.

valueChanged

public void valueChanged(javax.swing.event.TreeSelectionEvent e)
Listens for the user to select values in the tree.

Specified by:
valueChanged in interface javax.swing.event.TreeSelectionListener