edu.neu.ccs.gui
Class SimpleArrayPanel

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  edu.neu.ccs.gui.DisplayPanel
                      edu.neu.ccs.gui.TablePanel
                          edu.neu.ccs.gui.SimpleArrayPanel

All Implemented Interfaces:

Accessible, AlertListener, Displayable, EventListener, ImageObserver, JPTConstants, MalformedDataListener, MenuContainer, Serializable, SwingConstants

public class SimpleArrayPanel

extends TablePanel

Class SimpleArrayPanel provides a panel that can hold one or more views of a given type with the number of such views under interactive user control. Although, as of 2.6.0a, no JPT class directly implements SimpleArrayPanel, the class PathListView uses this panel as an internal panel to display an array of PathNodeView objects. Of course, SimpleArrayPanel may be used much more generally.

The views are arranged in a 4-column vertical list with the following structure in each row:

• Column 0 contains an automatically generated row label.
• Column 1 contains a view whose type is supplied in the constructor as a TypedView Class object.
• Column 2 contains a button that will in effect insert a new row at that position.
• Column 3 contains a button that will in effect delete that particular row.

This 4-column vertical list is placed in a scroll pane. The designer can determine how many rows will be visible at once.

The interactive controls that permit the user to change the total number of views are placed in a panel underneath the scroll pane.

To construct a SimpleArrayPanel, the user must supply its viewType which is an object of type Class that defines the view that will be repeated in the panel.

The following restrictions on the viewType must hold:

• The viewType must not be null.
• The viewType must extend JComponent so a view may be directly inserted into its panel.
• The viewType must implement TypedView so the model data can be extracted from a view by the standard methods of the TypedView interface.
• Normally, the viewType class must have a default constructor.

If the method createViewForRow is overridden, that method may use a different constructor for the viewType class and it is then not necessary to have a default constructor.

The most common way to obtain a viewType is to take the name of a class, say FooView, that extends JComponent, implements TypedView, and has a default constructor, and then to use FooView.class for the viewType. Later in this introduction, we will use this notation for examples.

The SimpleArrayPanel class has several constructors that take optional parameters. We gather here a description of these optional parameters and their default values.

• initialIndex: Internally, rows are numbered from zero; for the user interface, rows will be labeled with index + initialIndex; the default value for initialIndex is 0.
• visibleViewCount: The visible view count is the number of views that should be visible in the scroll pane at one time; the minimum and the default value is 2.
• gap: The gap is the horizontal and vertical pixel gap to be used in the TablePanels made internally in the array panel; the minimum and the default value is 4.
• autoHalo: If true, then each view will be wrapped in a new Halo so that error highlighting will be localized around the view; the default is false since it may be the case that a view has its own error highlight strategy.

By default, the interactive controls that permit the user to change the number of views show the length of the array, that is, the total number of views. For some applications, this value may not be the most meaningful. For example, for a classic polynomial, the meaningful number is the degree which is the highest coefficient that is available. In this case, the degree equals length - 1. To accomodate this, the SimpleArrayPanel class maintains an internal value lengthOffset that is added to the length before it is displayed in the user interface. The following 2 calls would tweak the interface to make it suitable for polynomial coefficients:

    setLengthOffset(-1);

    setLengthButtonName("Set Degree");

The SimpleArrayPanel class smoothly handles the transition between the internal length and the number displayed in the interactive controls.

To obtain an object that collects all views into an array for internal manipulation, use the method getViews. This method returns an Object that is actually an array and that may be cast to an array of viewType.

For example, if viewType is FooView.class, then the return value of getViews may be cast to an array type FooView[].

Similarly, to obtain an object that uses the view states of the various views to create an array of corresponding data model objects, use either demandObjects or requestObjects. These methods return an Object that is actually an array that may be cast to an array of viewDataType.

For example, if viewType is FooView.class and its corresponding model data type is Foo, then the return value for either of the methods above may be cast to the array type Foo[].

Both demandObjects and requestObjects use any automatic error checking and correction that has been built in to the corresponding methods in the viewType class.

The class SimpleArrayPanel is similar to the existing class ArrayPanel but is simpler to use since the most common defaults are taken as given. More importantly, this class can be used as is since it is not abstract and sufficient tools are made available to manage the model-view interaction directly. Finally, the new interface controls that permit a user to insert or delete an individual row gives the user much more power than is available with the older ArrayPanel class.

The class SimpleArrayPanel does not itself implement the interface TypedView. The critical reason is that to implement TypedView, it would be necessary to define the following methods whose definitions cannot be done in a uniform manner:

    public Class getDataType()

    public Stringable demandObject()

    public Stringable requestObject() throws CancelledException

If the user of this class wishes to build a TypedView, then it is necessary to create or obtain a view class appropriate for an overall view and to define a derived class of this class that does implement the above three methods.

As a convenience, dummy implementations of the following methods of the interface TypedView have already been provided:

    public void setInputProperties(InputProperties properties)

    public InputProperties getInputProperties()

For backward compatibility, the older class ArrayPanel is still part of JPT and has been left basically as is. We recommend SimpleArrayPanel for all new code.

In 2.6.0a, it was decided that the call setLength(0) would be valid and that its effect would be to clear the array of all existing views and then reset the array to MINIMUM_LENGTH which is 1. The method clear() was defined to accomplish the same thing.

Since:

2.4.0

Version:

2.6.0a

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

protected int	arrayLength The actual length of the array, that is, the current number of input views in the array panel.
protected boolean	autoHalo Determines whether or not to wrap each view of the array panel in a Halo to localize error highlights.
protected TablePanel	controls The interactive controls panel.
protected SimpleAction	decrementLength The action to decrement the number of views.
static Paintable	deleteRowPaintable The Paintable to make the "delete one row icon".
protected int	gap The horizontal and vertical cell gap to be used for all TablePanel objects constructed directly in this array panel.
protected SimpleAction	incrementLength The action to increment the number of views.
protected int	initialIndex The initial index in the automatic labels of the input views in the array panel.
protected TablePanel	innerPanel The panel that contains the 2-column vertical list with a label in the left column of each row and a view in the right column of each row.
static Paintable	insertRowPaintable The Paintable to make the "insert one row icon".
protected int	labelWidth The preferred width of the labels and text field view.
protected int	lengthOffset The lengthTFV should display the user meaningful length of the array which equals arrayLength + lengthOffset.
protected TextFieldView	lengthTFV The lengthTFV is part of the interactive user controls; this field displays the user meaningful length of the array which equals arrayLength + lengthOffset.
static int	MINIMUM_GAP The minimum horizontal and vertical cell gap to be used for all TablePanel objects constructed directly in this array panel; the value is 4.
static int	MINIMUM_LENGTH The minimum number of views that must be in the array panel; the value is 1.
static int	MINIMUM_VISIBLE The minimum number of views that should be visible in the scroll pane without needing scrolling; the value is 2.
protected JPTScrollPane	scrollPane The scroll pane that contains the inner panel.
protected SimpleAction	setLengthFromGUI The action to set the array length from the user meaningful length in the lengthTFV; this action takes care of required adjustments.
protected Class	viewDataType The view data type is the data type associated with the view type via the method getDataType() of TypedView.
protected int	viewHeight The preferred height of a default instance of the view type.
protected Vector	viewList The vector to hold references to the views in this panel for ease of access by the methods of this class.
protected Class	viewType The view type is the type of each input view in the array panel; this type must extend the class JComponent, implement the interface TypedView, and have a public default constructor.
protected int	viewWidth The preferred width of a default instance of the view type.
protected int	visibleViewCount The number of views that should be visible in the scroll pane without needing scrolling; this number is used to set the minimum size of the scroll pane view port.

Fields inherited from class edu.neu.ccs.gui.TablePanel

DEFAULT_ALIGNMENT, DEFAULT_ORIENTATION, tg

Fields inherited from class edu.neu.ccs.gui.DisplayPanel

background, codec, CODEC

Fields inherited from class javax.swing.JPanel

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Container

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface edu.neu.ccs.gui.Displayable

DEFAULT_VIEW_STATE, VIEW_STATE

Fields inherited from interface edu.neu.ccs.util.JPTConstants

ABOVE, ALIGNMENT, BELOW, BOTTOM_LEFT, BOTTOM_RIGHT, DEFAULT, FONT, INPUT_PROPERTIES, MANDATORY, OPTIONAL, ORIENTATION, TOP_LEFT, TOP_RIGHT, VALUE

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

SimpleArrayPanel(Class viewType)
The 1-parameter constructor.

SimpleArrayPanel(Class viewType, int initialIndex)
The 2-parameter constructor.

SimpleArrayPanel(Class viewType, int initialIndex, int visibleViewCount)
The 3-parameter constructor.

SimpleArrayPanel(Class viewType, int initialIndex, int visibleViewCount, int gap)
The 4-parameter constructor.

SimpleArrayPanel(Class viewType, int initialIndex, int visibleViewCount, int gap, boolean autoHalo)
The 5-parameter constructor.

Method Summary

protected void	buildArrayPanel() Main method to build the array panel.
protected void	buildControls() Helper method to build the end user controls.
protected void	buildInnerPanel() Helper method to build the inner panel with labels and views.
protected void	buildScrollPane() Helper method to build the scroll pane.
void	clear() Clear the array and reset to its initial size.
String	createLabelForRow(int i) Returns the label String for the i-th row.
protected TypedView	createViewForRow(int i) Returns a new TypedView for the i-th row whose class is given by the view type.
void	decrementLength() A helper method to decrement the length by 1.
void	deleteRowAtIndex(int index) Delete a row at the given index by moving the contents of each cell at a higher position downward by one cell and then by deleting the the cell at the end of the array.
Stringable	demandObject(int i) Applies demandObject to the i-th view and returns the resulting Stringable.
Object	demandObjects() Returns an object that is actually an array that is populated by calling demandObject for each view.
Stringable[]	demandStringableArray() Returns an array of type Stringable[] that is populated by calling demandObject for each view.
String	getDefaultViewState() Gets the default view state of the panel as an encoded string.
String	getDefaultViewState(int i) Gets the default view state of the i-th view.
String[]	getDefaultViewStates() Gets the default view states of the views in this panel as items in a string data array.
Action	getDeleteRowAction(int index) Returns an action that deletes a row at the given index.
JButton	getDeleteRowButton(int index) Returns a button that deletes a row at the given index.
InputProperties	getInputProperties() This method returns null since the panel as a whole does not utilize input properties.
InputProperties	getInputProperties(int i) Gets the input properties of the i-th view.
InputProperties[]	getInputPropertiesByView() Gets the input properties object for each view and then returns this information in an array.
Action	getInsertRowAction(int index) Returns an action that inserts a row at the given index.
JButton	getInsertRowButton(int index) Returns a button that inserts a row at the given index.
int	getLength() Returns the number of views in this panel or, equivalently, the length of the array of views.
String	getLengthButtonName() Returns the text on the GUI button that sets the length of the array using the user meaningful length that is held in the corresponding GUI text field view.
int	getLengthOffset() Returns the constant that should be added to the length to obtain the length measure meaningful to the end user.
TypedView	getTypedView(int i) Returns the i-th view installed in this panel.
TypedView[]	getTypedViewArray() Returns an array of type TypedView[] with the views in the panel.
int	getUserLength() Returns the measure of the length of the array that is meaningful to the end user.
Class	getViewDataType() Returns the model data type associated with the views repeated in this panel.
Object	getViews() Returns an object that is actually an array with the list of views installed in the panel.
String	getViewState() Gets the view state of the panel as an encoded string.
String	getViewState(int i) Gets the view state of the i-th view.
String[]	getViewStates() Gets the view states of the views in this panel as items in a string data array.
Class	getViewType() Returns the type of the views repeated in this panel.
void	incrementLength() A helper method to increment the length by 1.
void	insertRowAtIndex(int index) Insert a row at the given index by inserting a row at the end of the array panel and then moving the contents of each cell upward by one cell starting at the index position.
static Paintable	makeDeleteRowPaintable() Method to make the Paintable for the "delete row icon".
static Paintable	makeInsertRowPaintable() Method to make the Paintable for the "insert row icon".
Stringable	requestObject(int i) Applies requestObject to the i-th view and returns the resulting Stringable.
Object	requestObjects() Returns an object that is actually an array that is populated by calling requestObject for each view.
Stringable[]	requestStringableArray() Returns an array of type Stringable[] that is populated by calling requestObject for each view.
void	reset() Resets each view to its default view state.
void	reset(int i) Resets the i-th view state to its default state.
protected void	setAutoHalo(boolean autoHalo) Sets whether or not each view should be wrapped in a Halo object before being inserted into the panel.
void	setCommonInputProperties(InputProperties properties) Sets the input properties of each view to the same input properties object.
void	setDefaultViewState(int i, String data) Sets the default view state of the i-th view to the given data.
void	setDefaultViewState(String data) Sets the default view state of the panel using the data encoded in the given string.
void	setDefaultViewStates(String[] data) Sets the default view states of the views in this panel to the corresponding strings in the data array.
protected void	setInitialIndex(int initialIndex) Sets the initial index for the GUI view labels.
void	setInputProperties(InputProperties properties) This method does nothing since the panel as a whole does not utilize input properties.
void	setInputProperties(int i, InputProperties properties) Applies setInputProperties to the i-th view.
void	setInputPropertiesByView(InputProperties[] properties) Sets the input properties of each view to the corresponding input properties object in the given array of properties.
void	setLength(int length) Sets the number of views in this panel or, equivalently, the length of the array of views.
void	setLengthButtonName(String name) Sets the text on the GUI button that sets the length of the array using the user meaningful length that is held in the corresponding GUI text field view.
protected void	setLengthFromGUI() Helper method to set the length using the end user length extracted from the GUI.
void	setLengthOffset(int offset) Sets the constant that should be added to the length to obtain the length measure meaningful to the end user.
protected void	setTableGap(int gap) Sets the horizontal and vertical gap for TablePanel objects constructed in this panel.
void	setUserLength(int userLength) Sets the number of views using the measure of length that is meaningful to the end user.
void	setViewState(int i, String data) Sets the view state of the i-th view to the given data.
void	setViewState(String data) Sets the view state of the panel using the data encoded in the given string.
void	setViewStates(String[] data) Sets the view states of the views in this panel to the corresponding strings in the data array.
protected void	setViewType(Class viewType) Method used in the constructor to set the view type of the views in this panel.
protected void	setVisibleViewCount(int visibleViewCount) Sets the number of views that should be visible in the scroll pane without needing scrolling.

Methods inherited from class edu.neu.ccs.gui.TablePanel

addObject, addObject, autoEmptyBorder, createCells, getCellAlignment, getCellAlignment, getColumnAlignment, getColumnCount, getComponentTable, getEffectiveCellAlignment, getEffectiveCellAlignment, getHorizontalGap, getMaximumSize, getMinimumColumnWidth, getMinimumRowHeight, getMinimumSize, getOrientation, getPreferredSize, getRowAlignment, getRowCount, getTableAlignment, getTableEntry, getTableEntry, getTableGenerator, getTableLayout, getVerticalGap, isEmptyColumn, isEmptyRow, isValidColumn, isValidRow, removeCells, resetPreferredSize, setAllMinimumColumnWidths, setAllMinimumRowHeights, setCellAlignment, setCellAlignment, setColumnAlignment, setColumns, setHorizontalGap, setLayout, setMinimumColumnWidth, setMinimumRowHeight, setOrientation, setRowAlignment, setRows, setTableAlignment, setVerticalGap, uniformizeCellHeight, uniformizeCellSize, uniformizeCellWidth

Methods inherited from class edu.neu.ccs.gui.DisplayPanel

add, add, add, add, add, addBorder, addObject, addObject, addObject, addObject, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, compoundBorder, compoundBorder, dataMalformed, emptyBorder, emptyBorder, emptyBorder, endAlert, etchBorderLowered, etchBorderLowered, etchBorderLowered, etchBorderRaised, etchBorderRaised, etchBorderRaised, frame, frame, frame, frame, frame, frame, generalDialog, generalDialog, generalDialog, generalDialog, getCodec, getDisplayables, lineBorder, lineBorder, lineBorder, lineBorder, makeComponent, matteBorder, matteBorder, matteBorder, matteBorder, matteBorder, matteBorder, OKCancelDialog, OKCancelDialog, OKDialog, OKDialog, refreshComponent, remove, remove, removeAll, removeBorder, sandwichBorder, setCodec, setDeepBackground, setDeepBackground, setEnabled, startAlert, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, uniformizeHeight, uniformizeSize, uniformizeWidth, YesNoCancelDialog, YesNoCancelDialog

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, 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, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

MINIMUM_LENGTH

public static final int MINIMUM_LENGTH

The minimum number of views that must be in the array panel; the value is 1.

See Also:

Constant Field Values

MINIMUM_VISIBLE

public static final int MINIMUM_VISIBLE

The minimum number of views that should be visible in the scroll pane without needing scrolling; the value is 2.

See Also:

Constant Field Values

MINIMUM_GAP

public static final int MINIMUM_GAP

The minimum horizontal and vertical cell gap to be used for all TablePanel objects constructed directly in this array panel; the value is 4.

See Also:

Constant Field Values

insertRowPaintable

public static final Paintable insertRowPaintable

The Paintable to make the "insert one row icon".

deleteRowPaintable

public static final Paintable deleteRowPaintable

The Paintable to make the "delete one row icon".

viewType

protected Class viewType

The view type is the type of each input view in the array panel; this type must extend the class JComponent, implement the interface TypedView, and have a public default constructor.

viewDataType

protected Class viewDataType

The view data type is the data type associated with the view type via the method getDataType() of TypedView.

arrayLength

protected int arrayLength

The actual length of the array, that is, the current number of input views in the array panel.

lengthOffset

protected int lengthOffset

The lengthTFV should display the user meaningful length of the array which equals arrayLength + lengthOffset.

initialIndex

protected int initialIndex

The initial index in the automatic labels of the input views in the array panel.

visibleViewCount

protected int visibleViewCount

The number of views that should be visible in the scroll pane without needing scrolling; this number is used to set the minimum size of the scroll pane view port.

gap

protected int gap

The horizontal and vertical cell gap to be used for all TablePanel objects constructed directly in this array panel.

autoHalo

protected boolean autoHalo

Determines whether or not to wrap each view of the array panel in a Halo to localize error highlights.

viewWidth

protected int viewWidth

The preferred width of a default instance of the view type.

viewHeight

protected int viewHeight

The preferred height of a default instance of the view type.

labelWidth

protected int labelWidth

The preferred width of the labels and text field view.

innerPanel

protected TablePanel innerPanel

The panel that contains the 2-column vertical list with a label in the left column of each row and a view in the right column of each row.

scrollPane

protected JPTScrollPane scrollPane

The scroll pane that contains the inner panel.

controls

protected TablePanel controls

The interactive controls panel.

lengthTFV

protected TextFieldView lengthTFV

The lengthTFV is part of the interactive user controls; this field displays the user meaningful length of the array which equals arrayLength + lengthOffset.

incrementLength

protected SimpleAction incrementLength

The action to increment the number of views.

decrementLength

protected SimpleAction decrementLength

The action to decrement the number of views.

setLengthFromGUI

protected SimpleAction setLengthFromGUI

The action to set the array length from the user meaningful length in the lengthTFV; this action takes care of required adjustments.

viewList

protected Vector viewList

The vector to hold references to the views in this panel for ease of access by the methods of this class.

Constructor Detail

SimpleArrayPanel

public SimpleArrayPanel(Class viewType)

The 1-parameter constructor.

For a complete discussion of contructor parameters and defaults, see the introduction to this class.

Parameters:

viewType - the type of view to use in this panel

SimpleArrayPanel

public SimpleArrayPanel(Class viewType,
                        int initialIndex)

The 2-parameter constructor.

For a complete discussion of contructor parameters and defaults, see the introduction to this class.

Parameters:

viewType - the type of view to use in this panel

initialIndex - the initial index in the labels

SimpleArrayPanel

public SimpleArrayPanel(Class viewType,
                        int initialIndex,
                        int visibleViewCount)

The 3-parameter constructor.

For a complete discussion of contructor parameters and defaults, see the introduction to this class.

Parameters:

viewType - the type of view to use in this panel

initialIndex - the initial index in the labels

visibleViewCount - the number of views to show at once

SimpleArrayPanel

public SimpleArrayPanel(Class viewType,
                        int initialIndex,
                        int visibleViewCount,
                        int gap)

The 4-parameter constructor.

For a complete discussion of contructor parameters and defaults, see the introduction to this class.

Parameters:

viewType - the type of view to use in this panel

initialIndex - the initial index in the labels

visibleViewCount - the number of views to show at once

gap - the pixel gap between cells

SimpleArrayPanel

public SimpleArrayPanel(Class viewType,
                        int initialIndex,
                        int visibleViewCount,
                        int gap,
                        boolean autoHalo)

The 5-parameter constructor.

For a complete discussion of contructor parameters and defaults, see the introduction to this class.

Parameters:

viewType - the type of view to use in this panel

initialIndex - the initial index in the labels

visibleViewCount - the number of views to show at once

gap - the pixel gap between cells

autoHalo - whether or not to auto-halo the views

Method Detail

getViewType

public final Class getViewType()

Returns the type of the views repeated in this panel.

getViewDataType

public final Class getViewDataType()

Returns the model data type associated with the views repeated in this panel.

getTypedView

public final TypedView getTypedView(int i)

Returns the i-th view installed in this panel.

Returns null if i is out of range.

Parameters:

i - the view index

setViewState

public final void setViewState(int i,
                               String data)

Sets the view state of the i-th view to the given data.

Does nothing if i is out of range or the given data is null.

Parameters:

i - the view index

data - the desired view state

getViewState

public final String getViewState(int i)

Gets the view state of the i-th view.

Returns null if i is out of range.

Parameters:

i - the view index

setDefaultViewState

public final void setDefaultViewState(int i,
                                      String data)

Sets the default view state of the i-th view to the given data.

Does nothing if i is out of range or the given data is null.

Parameters:

i - the view index

data - the desired default view state

getDefaultViewState

public final String getDefaultViewState(int i)

Gets the default view state of the i-th view.

Returns null if i is out of range.

Parameters:

i - the view index

reset

public final void reset(int i)

Resets the i-th view state to its default state.

Does nothing if i is out of range.

Parameters:

i - the view index

demandObject

public final Stringable demandObject(int i)

Applies demandObject to the i-th view and returns the resulting Stringable.

Returns null if i is out of range.

Parameters:

i - the view index

requestObject

public final Stringable requestObject(int i)
                               throws CancelledException

Applies requestObject to the i-th view and returns the resulting Stringable.

Returns null if i is out of range.

Throws CancelledException if the user cancels when an error has been detected.

Parameters:

i - the view index

Throws:

CancelledException

setInputProperties

public final void setInputProperties(int i,
                                     InputProperties properties)

Applies setInputProperties to the i-th view.

Does nothing if i is out of range.

Parameters:

i - the view index

getInputProperties

public final InputProperties getInputProperties(int i)

Gets the input properties of the i-th view.

Returns null if i is out of range.

Parameters:

i - the view index

getViews

public final Object getViews()

Returns an object that is actually an array with the list of views installed in the panel.

Assume, for example, that viewType is FooView.class and that number is the number of views in the panel. Then the return value may be cast to an array FooView[] and the length of this array will be number.

The array is constructed by the following Java call that, in effect, uses reflection:

    Array.newInstance(viewType, number)

This array is then populated by calls to the method getTypedView(i).

demandObjects

public final Object demandObjects()

Returns an object that is actually an array that is populated by calling demandObject for each view.

Assume, for example, that viewType is FooView.class, that viewDataType is Foo.class, and that number is the number of views in the panel. Then the return value may be cast to an array Foo[] and the length of this array will be number.

The array is constructed by the following Java call that, in effect, uses reflection:

    Array.newInstance(viewDataType, number)

This array is then populated by calls to the method demandObject(i).

requestObjects

public final Object requestObjects()
                            throws CancelledException

Returns an object that is actually an array that is populated by calling requestObject for each view.

Assume, for example, that viewType is FooView.class, that viewDataType is Foo.class, and that number is the number of views in the panel. Then the return value may be cast to an array Foo[] and the length of this array will be number.

The array is constructed by the following Java call that, in effect, uses reflection:

    Array.newInstance(viewDataType, number)

This array is then populated by calls to the method requestObject(i).

Throws CancelledException if the user cancels when an error has been detected.

Throws:

CancelledException

getTypedViewArray

public final TypedView[] getTypedViewArray()

Returns an array of type TypedView[] with the views in the panel.

This method is less useful than getViews() since the array returned cannot be directly cast to an array of the actual viewType due to basic restrictions on how Java constructs arrays. Therefore, this method is only useful in so far as you wish to treat the views simply as TypedView objects.

demandStringableArray

public final Stringable[] demandStringableArray()

Returns an array of type Stringable[] that is populated by calling demandObject for each view.

This method is less useful than demandObjects() since the array returned cannot be directly cast to an array of the actual viewDataType due to basic restrictions on how Java constructs arrays. Therefore, this method is only useful in so far as you wish to treat the objects simply as Stringable objects.

requestStringableArray

public final Stringable[] requestStringableArray()
                                          throws CancelledException

Returns an array of type Stringable[] that is populated by calling requestObject for each view.

This method is less useful than requestObjects() since the array returned cannot be directly cast to an array of the actual viewDataType due to basic restrictions on how Java constructs arrays. Therefore, this method is only useful in so far as you wish to treat the objects simply as Stringable objects.

Throws CancelledException if the user cancels when an error has been detected.

Throws:

CancelledException

setViewStates

public final void setViewStates(String[] data)

Sets the view states of the views in this panel to the corresponding strings in the data array.

Overrides:

setViewStates in class DisplayPanel

Parameters:

data - the desired view state array

getViewStates

public final String[] getViewStates()

Gets the view states of the views in this panel as items in a string data array.

Overrides:

getViewStates in class DisplayPanel

setDefaultViewStates

public final void setDefaultViewStates(String[] data)

Sets the default view states of the views in this panel to the corresponding strings in the data array.

Overrides:

setDefaultViewStates in class DisplayPanel

Parameters:

data - the desired default view state array

getDefaultViewStates

public final String[] getDefaultViewStates()

Gets the default view states of the views in this panel as items in a string data array.

Overrides:

getDefaultViewStates in class DisplayPanel

setCommonInputProperties

public final void setCommonInputProperties(InputProperties properties)

Sets the input properties of each view to the same input properties object.

Parameters:

properties - the common input properties for all views

setInputPropertiesByView

public final void setInputPropertiesByView(InputProperties[] properties)

Sets the input properties of each view to the corresponding input properties object in the given array of properties.

Parameters:

properties - the array of input properties for all views

getInputPropertiesByView

public final InputProperties[] getInputPropertiesByView()

Gets the input properties object for each view and then returns this information in an array.

setViewState

public final void setViewState(String data)

Sets the view state of the panel using the data encoded in the given string.

Equivalent to:

    setViewStates(Strings.decode(data))

Specified by:

setViewState in interface Displayable

Overrides:

setViewState in class DisplayPanel

Parameters:

data - the encoded view state

getViewState

public final String getViewState()

Gets the view state of the panel as an encoded string.

Equivalent to:

    return CodecUtilities.encode(getViewStates())

Specified by:

getViewState in interface Displayable

Overrides:

getViewState in class DisplayPanel

setDefaultViewState

public final void setDefaultViewState(String data)

Sets the default view state of the panel using the data encoded in the given string.

Equivalent to:

    setDefaultViewStates(Strings.decode(data))

Specified by:

setDefaultViewState in interface Displayable

Overrides:

setDefaultViewState in class DisplayPanel

Parameters:

data - the encoded default view state

getDefaultViewState

public final String getDefaultViewState()

Gets the default view state of the panel as an encoded string.

Equivalent to:

    return CodecUtilities.encode(getDefaultViewStates())

Specified by:

getDefaultViewState in interface Displayable

Overrides:

getDefaultViewState in class DisplayPanel

reset

public final void reset()

Resets each view to its default view state.

Specified by:

reset in interface Displayable

Overrides:

reset in class DisplayPanel

setInputProperties

public final void setInputProperties(InputProperties properties)

This method does nothing since the panel as a whole does not utilize input properties.

Implemented trivially in case the user wants to create a derived class that implements TypedView.

Parameters:

properties - ignored

getInputProperties

public final InputProperties getInputProperties()

This method returns null since the panel as a whole does not utilize input properties.

Implemented trivially in case the user wants to create a derived class that implements TypedView.

getLength

public final int getLength()

Returns the number of views in this panel or, equivalently, the length of the array of views.

getUserLength

public final int getUserLength()

Returns the measure of the length of the array that is meaningful to the end user.

Equivalent to:

    getLength() + getLengthOffest()

getLengthOffset

public final int getLengthOffset()

Returns the constant that should be added to the length to obtain the length measure meaningful to the end user.

getLengthButtonName

public final String getLengthButtonName()

Returns the text on the GUI button that sets the length of the array using the user meaningful length that is held in the corresponding GUI text field view.

setLength

public final void setLength(int length)

Sets the number of views in this panel or, equivalently, the length of the array of views.

The actual length set will be at least 1.

This method is responsible for adding labels, views, and the "insert one row" and "delete one row" buttons if the length will be increased. To do this, this method calls:

    String createLabelForRow(int i)

    TypedView createViewForRow(int i)

These methods may be overridden in a derived class if the user of this class wants non-default behavior but the constraints discussed in this class must be observed.

This method is responsible for removing labels, views, and buttons if the length will be decreased.

Parameters:

length - the desired number of views in this panel

setUserLength

public final void setUserLength(int userLength)

Sets the number of views using the measure of length that is meaningful to the end user.

Parameters:

userLength - the user meaningful length

setLengthOffset

public final void setLengthOffset(int offset)

Sets the constant that should be added to the length to obtain the length measure meaningful to the end user.

Parameters:

offset - the offset used to adjust the length

setLengthButtonName

public final void setLengthButtonName(String name)

Sets the text on the GUI button that sets the length of the array using the user meaningful length that is held in the corresponding GUI text field view.

Parameters:

name - the text for the button that sets the length

incrementLength

public final void incrementLength()

A helper method to increment the length by 1.

decrementLength

public final void decrementLength()

A helper method to decrement the length by 1.

clear

public final void clear()

Clear the array and reset to its initial size.

Equivalent to setLength(0).

createLabelForRow

public String createLabelForRow(int i)

Returns the label String for the i-th row.

By default, this method returns:

    "" + (i + initialIndex)

May be overridden in a derived class if the designer wants to create a different label String.

Parameters:

i - the row index

createViewForRow

protected TypedView createViewForRow(int i)

Returns a new TypedView for the i-th row whose class is given by the view type.

By default, this method returns:

    (TypedView) viewType.newInstance()

In particular, this implementation does not use the index i.

May be overridden in a derived class if the designer wants to use a non-default constructor for the view.

The view returned must be assignable to the view type used to construct the array panel.

Furthermore, the view returned by this method must have the same preferred size independent of the index i.

Parameters:

i - the row index

setViewType

protected final void setViewType(Class viewType)

Method used in the constructor to set the view type of the views in this panel.

Performs error checks to verify the constraints that are discussed in the introduction to this class.

Extracts the model data type corresponding to the view type and determines the dimensions of a typical view.

Parameters:

viewType - the class of the views in this panel

setInitialIndex

protected final void setInitialIndex(int initialIndex)

Sets the initial index for the GUI view labels.

Parameters:

initialIndex - the initial index for the labels

setVisibleViewCount

protected final void setVisibleViewCount(int visibleViewCount)

Sets the number of views that should be visible in the scroll pane without needing scrolling.

This number is used to set the minimum size of the scroll pane view port.

Parameters:

visibleViewCount - the number of views visible at once

setTableGap

protected final void setTableGap(int gap)

Sets the horizontal and vertical gap for TablePanel objects constructed in this panel.

Parameters:

gap - the standard pixel gap in tables

setAutoHalo

protected final void setAutoHalo(boolean autoHalo)

Sets whether or not each view should be wrapped in a Halo object before being inserted into the panel.

Parameters:

autoHalo - whether or not to automatically halo

buildArrayPanel

protected final void buildArrayPanel()

Main method to build the array panel.

buildInnerPanel

protected final void buildInnerPanel()

Helper method to build the inner panel with labels and views.

buildScrollPane

protected final void buildScrollPane()

Helper method to build the scroll pane.

buildControls

protected final void buildControls()

Helper method to build the end user controls.

setLengthFromGUI

protected final void setLengthFromGUI()

Helper method to set the length using the end user length extracted from the GUI.

insertRowAtIndex

public final void insertRowAtIndex(int index)

Insert a row at the given index by inserting a row at the end of the array panel and then moving the contents of each cell upward by one cell starting at the index position.

Changes the contents of the cell at index to its default view state.

Does nothing unless 0 <= index <getLength().

Parameters:

index - the index at which to insert a row

deleteRowAtIndex

public final void deleteRowAtIndex(int index)

Delete a row at the given index by moving the contents of each cell at a higher position downward by one cell and then by deleting the the cell at the end of the array.

Does nothing if the array length is 1.

Does nothing unless 0 <= index <getLength().

Parameters:

index - the index at which to delete a row

getInsertRowAction

public Action getInsertRowAction(int index)

Returns an action that inserts a row at the given index.

Parameters:

index - the index at which to insert a row

getDeleteRowAction

public Action getDeleteRowAction(int index)

Returns an action that deletes a row at the given index.

Parameters:

index - the index at which to delete a row

getInsertRowButton

public JButton getInsertRowButton(int index)

Returns a button that inserts a row at the given index.

Parameters:

index - the index at which to insert a row

getDeleteRowButton

public JButton getDeleteRowButton(int index)

Returns a button that deletes a row at the given index.

Parameters:

index - the index at which to delete a row

makeInsertRowPaintable

public static Paintable makeInsertRowPaintable()

Method to make the Paintable for the "insert row icon".

makeDeleteRowPaintable

public static Paintable makeDeleteRowPaintable()

Method to make the Paintable for the "delete row icon".