edu.rice.cs.util.swing
Class ScrollableListSelectionDialog

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Window
              java.awt.Dialog
                  javax.swing.JDialog
                      edu.rice.cs.util.swing.ScrollableListSelectionDialog

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants

public class ScrollableListSelectionDialog
extends JDialog

The ScrollableListSelectionDialog is a popup dialog with a message and a scrollable list of items. Each item may be either selected or unselected. A ScrollableListSelectionDialog should be used when an operation needs to act on a variable number of items, for example, when saving modified files.

The message (also know as the leader text) is displayed above the items with an optional icon. The items are displayed in a scrollable table. A column of checkboxes allows selection of the items. Buttons are added below the list of items.

This dialog is somewhat styled after JOptionPane and uses the message-type constants from JOptionPane.

Since:

2007-04-08

Version:

$Id: ScrollableListSelectionDialog.java 5443 2011-08-17 04:58:50Z rcartwright $

Author:

Chris Warrington

See Also:

Serialized Form

Nested Class Summary

private class	ScrollableListSelectionDialog.SelectAllNoneActionListener An ActionListener that handles the "Select All" and "Select None" buttons.
static class	ScrollableListSelectionDialog.SelectionState A enumeration of the various selection states.

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

private static int	CHECKBOXES_COLUMN_INDEX The column index of the checkboxes column.
protected Vector<String>	dataAsStrings The items in the table.
private static int	DEFAULT_HEIGHT The default height for this dialog.
private static int	DEFAULT_WIDTH The default width for this dialog.
private static double	HEIGHT_RATIO The ratio of the screen height to use by default.
private static int	NUM_COLUMNS The number of columns in the table.
protected Vector<Boolean>	selectedItems The selected items in the table.
private static int	STRINGS_COLUMN_INDEX The column index of the strings column.
protected JTable	table The table displaying the items.
protected AbstractTableModel	tableModel The AbstractTableModel backing the table.
private static double	WIDTH_RATIO The ratio of the screen width to use by default.

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

	ScrollableListSelectionDialog(Frame owner, String dialogTitle, String leaderText, Collection<?> listItems, String itemDescription) Creates a new ScrollableListSelectionDialog with the given title, leader text, and items.
	ScrollableListSelectionDialog(Frame owner, String dialogTitle, String leaderText, Collection<?> listItems, String itemDescription, ScrollableListSelectionDialog.SelectionState defaultSelection, int messageType) Creates a new ScrollableListSelectionDialog with the given title, leader text, items, and message type.
	ScrollableListSelectionDialog(Frame owner, String dialogTitle, String leaderText, Collection<?> listItems, String itemDescription, ScrollableListSelectionDialog.SelectionState defaultSelection, int messageType, int width, int height, Icon icon) Creates a new ScrollableListSelectionDialog with the given title, leader text, items, message type, width, height, and icon.
private	ScrollableListSelectionDialog(Frame owner, String dialogTitle, String leaderText, Collection<?> listItems, String itemDescription, ScrollableListSelectionDialog.SelectionState defaultSelection, int messageType, int width, int height, Icon icon, boolean fitToScreen) Creates a new ScrollableListSelectionDialog with the given title, leader text, items, message type, width, height, and icon.

Method Summary

protected void	_addButtons(JPanel buttonPanel) Adds buttons to the bottom of the dialog.
private void	_addSelectButtons(JPanel selectButtonsPanel) Adds the "Select All" and "Select None" buttons to the given panel.
private Icon	_getIcon(int messageType) Lookup the icon associated with the given messageType.
private boolean	_isknownMessageType(int messageType) A method to check if they given message type is a know message type.
protected void	closeDialog() Should be called when the dialog should be closed.
static void	main(String[] args) A simple main method for testing purposes.
List<String>	selectedItems() Returns the string representation of those items that are currently selected.
void	showDialog() Shows the dialog.

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, 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

Field Detail

DEFAULT_WIDTH

private static final int DEFAULT_WIDTH

The default width for this dialog.

See Also:

Constant Field Values

DEFAULT_HEIGHT

private static final int DEFAULT_HEIGHT

The default height for this dialog.

See Also:

Constant Field Values

WIDTH_RATIO

private static final double WIDTH_RATIO

The ratio of the screen width to use by default.

See Also:

Constant Field Values

HEIGHT_RATIO

private static final double HEIGHT_RATIO

The ratio of the screen height to use by default.

See Also:

Constant Field Values

table

protected final JTable table

The table displaying the items.

tableModel

protected final AbstractTableModel tableModel

The AbstractTableModel backing the table.

NUM_COLUMNS

private static final int NUM_COLUMNS

The number of columns in the table.

See Also:

Constant Field Values

CHECKBOXES_COLUMN_INDEX

private static final int CHECKBOXES_COLUMN_INDEX

The column index of the checkboxes column.

See Also:

Constant Field Values

STRINGS_COLUMN_INDEX

private static final int STRINGS_COLUMN_INDEX

The column index of the strings column.

See Also:

Constant Field Values

dataAsStrings

protected final Vector<String> dataAsStrings

The items in the table.

selectedItems

protected final Vector<Boolean> selectedItems

The selected items in the table. This Vector maps to _dataAsStrings by index. This value may be accessed by multiple threads. Threads wishing to access it should acquire its intrinsic lock.

Constructor Detail

ScrollableListSelectionDialog

public ScrollableListSelectionDialog(Frame owner,
                                     String dialogTitle,
                                     String leaderText,
                                     Collection<?> listItems,
                                     String itemDescription)

Creates a new ScrollableListSelectionDialog with the given title, leader text, and items. The list of items is used to construct an internal string list that is not backed by the original list. Changes made to the list or items after dialog construction will not be reflected in the dialog.

The default sizing, message type, and icon are used. All the items are selected by default.

Parameters:

owner - The frame that owns this dialog. May be null.

dialogTitle - The text to use as the dialog title.

leaderText - Text to display before the list of items.

listItems - The items to display in the list.

itemDescription - A textual description of the items. This is used as the column heading for the items.

Throws:

IllegalArgumentException - if listItems is null.

ScrollableListSelectionDialog

public ScrollableListSelectionDialog(Frame owner,
                                     String dialogTitle,
                                     String leaderText,
                                     Collection<?> listItems,
                                     String itemDescription,
                                     ScrollableListSelectionDialog.SelectionState defaultSelection,
                                     int messageType)

Creates a new ScrollableListSelectionDialog with the given title, leader text, items, and message type. The list of items is used to construct an internal string list that is not backed by the original list. Changes made to the list or items after dialog construction will not be reflected in the dialog.

The message type must be one of the message types from JOptionPane. The message type controlls which default icon is used.

The default sizing and icon are used.

Parameters:

owner - The frame that owns this dialog. May be null.

dialogTitle - The text to use as the dialog title.

leaderText - Text to display before the list of items.

listItems - The items to display in the list.

itemDescription - A textual description of the items. This is used as the column heading for the items.

defaultSelection - The default selection state (selected or unselected) for the items.

messageType - The type of dialog message.

Throws:

IllegalArgumentException - if listItems is null.

IllegalArgumentException - if the message type is unknown or listItems is null.

ScrollableListSelectionDialog

public ScrollableListSelectionDialog(Frame owner,
                                     String dialogTitle,
                                     String leaderText,
                                     Collection<?> listItems,
                                     String itemDescription,
                                     ScrollableListSelectionDialog.SelectionState defaultSelection,
                                     int messageType,
                                     int width,
                                     int height,
                                     Icon icon)

Creates a new ScrollableListSelectionDialog with the given title, leader text, items, message type, width, height, and icon. The list of items is used to construct an internal string list that is not backed by the original list. Changes made to the list or items after dialog construction will not be reflected in the dialog.

The message type must be one of the message types from JOptionPane. The message type controlls which default icon is used. If icon is non-null, it is used instead of the default icon.

Parameters:

owner - The frame that owns this dialog. May be null.

dialogTitle - The text to use as the dialog title.

leaderText - Text to display before the list of items.

listItems - The items to display in the list.

itemDescription - A textual description of the items. This is used as the column heading for the items.

defaultSelection - The default selection state (selected or unselected) for the items.

messageType - The type of dialog message.

width - The width of the dialog box.

height - The height of the dialog box.

icon - The icon to display. May be null.

Throws:

IllegalArgumentException - if listItems is null.

IllegalArgumentException - if the message type is unknown or listItems is null.

ScrollableListSelectionDialog

private ScrollableListSelectionDialog(Frame owner,
                                      String dialogTitle,
                                      String leaderText,
                                      Collection<?> listItems,
                                      String itemDescription,
                                      ScrollableListSelectionDialog.SelectionState defaultSelection,
                                      int messageType,
                                      int width,
                                      int height,
                                      Icon icon,
                                      boolean fitToScreen)

Creates a new ScrollableListSelectionDialog with the given title, leader text, items, message type, width, height, and icon. The list of items is used to construct an internal string list that is not backed by the original list. Changes made to the list or items after dialog construction will not be reflected in the dialog.

The message type must be one of the message types from JOptionPane. The message type controlls which default icon is used. If icon is non-null, it is used instead of the default icon.

Parameters:

owner - The frame that owns this dialog. May be null.

dialogTitle - The text to use as the dialog title.

leaderText - Text to display before the list of items.

listItems - The items to display in the list.

itemDescription - A textual description of the items. This is used as the column heading for the items.

defaultSelection - The default selection state (selected or unselected) for the items.

messageType - The type of dialog message.

width - The width of the dialog box.

height - The height of the dialog box.

icon - The icon to display. May be null.

fitToScreen - If true, the width and height of the dialog will be calculated using the screen dimensions, WIDTH_RATIO, and HEIGHT_RATIO. If false, the provided width and height will be used.

Throws:

IllegalArgumentException - if listItems is null.

IllegalArgumentException - if the message type is unknown or listItems is null.

Method Detail

_isknownMessageType

private boolean _isknownMessageType(int messageType)

A method to check if they given message type is a know message type.

Parameters:

messageType - The message type to check

Returns:

true if the message type is known, false otherwise

_getIcon

private Icon _getIcon(int messageType)

Lookup the icon associated with the given messageType. The message type must be one of the message types from JOptionPane.

Parameters:

messageType - The message for which the icon is requested.

Returns:

The message's icon or null is no icon was found.

_addSelectButtons

private void _addSelectButtons(JPanel selectButtonsPanel)

Adds the "Select All" and "Select None" buttons to the given panel.

Parameters:

selectButtonsPanel - The panel that should contain the buttons.

_addButtons

protected void _addButtons(JPanel buttonPanel)

Adds buttons to the bottom of the dialog. By default, a single "OK" button is added that calls closeDialog(). It is also set as the dialog's default button. Inheritors should feel free the change settings of the panel such as the layout manager. However, no guarantees are made that every change will work with every version of this class.

Parameters:

buttonPanel - The JPanel that should contain the buttons.

showDialog

public void showDialog()

Shows the dialog.

closeDialog

protected void closeDialog()

Should be called when the dialog should be closed. The default implementation simply hides the dialog.

selectedItems

public List<String> selectedItems()

Returns the string representation of those items that are currently selected. The items will be in the same relative order as they were at construction time. The resultant collection may be empty. The resultant collection is unmodifiable. The resultant collection is simply a snapshot (i.e., It will not be updated as more items are selected.). This method may be called from non-event queue threads.

Returns:

The currently selected items.

main

public static void main(String[] args)

A simple main method for testing purposes.

Parameters:

args - Not used.