com.sssw.rt.jform
Class AgcJList

java.lang.Object
 |
 +--java.awt.Component
       |
       +--java.awt.Container
             |
             +--javax.swing.JComponent
                   |
                   +--javax.swing.JList
                         |
                         +--com.sssw.rt.jform.AgcJList

All Implemented Interfaces:

Accessible, AgiHelpInfo, AgiRowSetManager, EventListener, ImageObserver, ListSelectionListener, MenuContainer, Scrollable, Serializable

public class AgcJList

extends JList

implements AgiRowSetManager, ListSelectionListener, AgiHelpInfo

A lightweight component that displays a scrollable list of values and allows the user to select one or more objects from the list. The component can be data-bound, which associates the selected item in the list with a database column.

When the control is bound to a database column via the Data Column property, the value in the current row sets the initially selected item in the list. If the user makes a different selection, that item becomes the value associated with the current row. Each list item can have a display value and storage value. The display value is a String, but the storage value can be any Object. If there is no separate display value, the Object is converted to a String for display. The storage value is the value sent to the database when you call updateRows() for the form.

In addition to being data-bound, the control is a data-loaded control; which means a database table or other data source can provide the list items. You can use methods of AgiRowSetManager to navigate the list. However, changes to the list items do not affect the underlying data; therefore, calling updateRows() is not allowed. If you call it for the control, updateRows() throws AgoUnsupportedOperationException.

AgcJList uses a model to represent the contents of the list. SilverStream builds the model from information you specify in the Form Designer. On the property sheet for the list control, you can specify either a static list of values or a database table from which the list retrieves the values. If you create the list programmatically, you can specify either your own model or a list of values in the constructor.

Properties:

Automatic Query, Choices, Control Type, Data Column, Display Value, Distinct, Enabled, Font Name, Font Size, Font Style, Height, Help Page, Left, Limit Rows, Load Choices, Maximum Rows, Name, Order By, Storage Value, Table, Tool Tip, Top, Values, Visible, Where Clause, Width

Events:

focusGained, focusLost, keyPressed, keyReleased, keyTyped, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, validationFailed, validationTest, valueChanged

See Also:

Serialized Form

Inner classes inherited from class javax.swing.JList

JList.AccessibleJList

Inner classes inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

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.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Constructor Summary

AgcJList()
Initializes an AgcJList control with an empty list.

AgcJList(ListModel m)
Initializes the control with list items from a DefaultListModel.

AgcJList(Object[] items)
Initializes the control with a DefaultListModel whose values are specified in the items array.

AgcJList(Vector items)
Initializes the control with a DefaultListModel whose values are specified in the items Vector.

Method Summary

void	addItem(Object obj) Appends an item to the list.
void	addItem(String title, Object value) Appends an item to the list, with values for the display text and storage value.
String	getItemAt(int index) Gets the displayed text for the item at the specified index.
int	getItemCount() Gets the number of items in the list.
Object	getItemValue(int index) Gets the storage value of the item at the specified index.
Object	getValue() Gets the storage value of the selected item.
void	insertItemAt(Object obj, int index) Adds an item to the list at the specified index.
void	insertItemAt(String title, Object value, int index) Adds an item at the specified index in the List, specifying separate values for the display text and storage value.
void	loadFromRowCursor(AgiRowCursor rc, int displaycol, int valuecol) Creates list items from an AgiRowCursor source.
void	removeAllItems() Removes all items from the list.
void	removeItemAt(int index) Removes the item at the specified position from the list.
void	setValue(Object value) Selects the item whose storage value matches the specified value.

Methods inherited from class javax.swing.JList

addListSelectionListener, addSelectionInterval, clearSelection, createSelectionModel, ensureIndexIsVisible, fireSelectionValueChanged, getAccessibleContext, getAnchorSelectionIndex, getCellBounds, getCellRenderer, getFirstVisibleIndex, getFixedCellHeight, getFixedCellWidth, getLastVisibleIndex, getLeadSelectionIndex, getMaxSelectionIndex, getMinSelectionIndex, getModel, getPreferredScrollableViewportSize, getPrototypeCellValue, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedIndex, getSelectedIndices, getSelectedValue, getSelectedValues, getSelectionBackground, getSelectionForeground, getSelectionMode, getSelectionModel, getUI, getUIClassID, getValueIsAdjusting, getVisibleRowCount, indexToLocation, isSelectedIndex, isSelectionEmpty, locationToIndex, paramString, removeListSelectionListener, removeSelectionInterval, setCellRenderer, setFixedCellHeight, setFixedCellWidth, setListData, setListData, setModel, setPrototypeCellValue, setSelectedIndex, setSelectedIndices, setSelectedValue, setSelectionBackground, setSelectionForeground, setSelectionInterval, setSelectionMode, setSelectionModel, setUI, setValueIsAdjusting, setVisibleRowCount, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setCursor, setLayout, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

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

Methods implemented from interface com.sssw.rt.form.AgiHelpInfo

getHelpInfo, setHelpInfo

Methods implemented from interface com.sssw.rt.util.AgiRowSetManager

clearRows, haveRowsChanged, query, query, refreshRows, updateRows

Methods implemented from interface javax.swing.event.ListSelectionListener

valueChanged

Constructor Detail

AgcJList

public AgcJList()

Initializes an AgcJList control with an empty list.

AgcJList

public AgcJList(ListModel m)

Initializes the control with list items from a DefaultListModel.

Parameters:

m - a DefaultListModel that has been initialized with list items

AgcJList

public AgcJList(Object[] items)

Initializes the control with a DefaultListModel whose values are specified in the items array.

Parameters:

items - an array of Objects where each element becomes an item in the list

AgcJList

public AgcJList(Vector items)

Initializes the control with a DefaultListModel whose values are specified in the items Vector.

Parameters:

items - a Vector object whose elements become the displayed list

Method Detail

addItem

public void addItem(Object obj)

Appends an item to the list.

Parameters:

obj - an Object to be added to the end of the list

Usage:

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.addItem(String, Object), AgcJList.insertItemAt(Object, int), AgcJList.insertItemAt(String, Object, int)

insertItemAt

public void insertItemAt(Object obj,
                         int index)

Adds an item to the list at the specified index.

Parameters:

obj - an Object you want to add to the list. The Object is the storage value. It is converted to a String for the display value.

index - an int specifying the position for the Object in the list. Index must be between 0 and one less than the size of the list (0 <= index < size). If the index is out of range, this method throws an ArrayOutOfBoundsException.

Usage:

To append an item to the end of the list when you don't know the list size, call AgcJList.addItem(Object) or AgcJList.addItem(String, Object).

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.addItem(Object), AgcJList.addItem(String, Object), AgcJList.insertItemAt(String, Object, int)

addItem

public void addItem(String title,
                    Object value)

Appends an item to the list, with values for the display text and storage value.

Parameters:

title - a String specifying the item's display value

value - an Object specifying the item's storage value. The storage value may be null.

Usage:

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.addItem(Object), AgcJList.insertItemAt(Object, int), AgcJList.insertItemAt(String, Object, int)

insertItemAt

public void insertItemAt(String title,
                         Object value,
                         int index)

Adds an item at the specified index in the List, specifying separate values for the display text and storage value.

Parameters:

title - a String specifying the item's display value

value - an Object specifying the item's storage value. The storage value may be null.

index - an int specifying the position for the Object in the list. Index must be between 0 and one less than the size of the list (0 <= index < size). If the index is out of range, this method throws an ArrayOutOfBoundsException.

Usage:

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.addItem(Object), AgcJList.addItem(String, Object), AgcJList.insertItemAt(Object, int)

removeItemAt

public void removeItemAt(int index)

Removes the item at the specified position from the list.

Parameters:

index - an int specifying the position of the item to be removed. Index must be between 0 and one less than the size of the list (0 <= index < size). If the index is out of range, this method throws an ArrayOutOfBoundsException.

Usage:

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.removeAllItems(), AgcJList.insertItemAt(Object, int), AgcJList.insertItemAt(String, Object, int)

removeAllItems

public void removeAllItems()

Removes all items from the list.

Usage:

This method works only if the AgcJList object uses the default data model. AgcJList uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJList.removeItemAt(int)

getItemAt

public String getItemAt(int index)

Gets the displayed text for the item at the specified index.

Parameters:

index - an int specifying the item's position in the list. Index must be between 0 and one less than the size of the list (0 <= index < size). If the index is out of range, this method throws an ArrayOutOfBoundsException.

Returns:

a String that is the display value for the item

See Also:

AgcJList.getItemValue(int), AgcJList.getValue()

getItemValue

public Object getItemValue(int index)

Gets the storage value of the item at the specified index.

Parameters:

index - an int specifying the item's position in the list. Index must be between 0 and one less than the size of the list (0 <= index < size). If the index is out of range, this method throws an ArrayOutOfBoundsException.

Returns:

an Object, which is the item's value

See Also:

AgcJList.getItemAt(int), AgcJList.getValue()

getItemCount

public int getItemCount()

Gets the number of items in the list.

Returns:

an int specifying the size of the list

getValue

public Object getValue()

Gets the storage value of the selected item.

Returns:

an Object that is the storage value of the selected item

See Also:

AgcJList.setValue(Object), AgcJList.getItemAt(int), AgcJList.getItemValue(int)

setValue

public void setValue(Object value)

Selects the item whose storage value matches the specified value.

Parameters:

value - an Object whose value matches the storage value of the item you want to select.

See Also:

AgcJList.getValue()

loadFromRowCursor

public void loadFromRowCursor(AgiRowCursor rc,
                              int displaycol,
                              int valuecol)
                       throws AgoSecurityException,
                              AgoTransientSystemException,
                              AgoUnrecoverableSystemException

Creates list items from an AgiRowCursor source. Each row becomes an item. This is similar to specifying in the Form Designer that you want to load list values from a table.

Parameters:

rc - the AgiRowCursor object whose data you want to be the list

displaycol - an int specifying the number of a column in the AgiRowCursor object whose values will be the display values for the list items

valuecol - an int specifying the number of a column in the AgiRowCursor object whose values will be the storage values for the list items