SilverStream
Application Server 3.5

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

SilverStream
Application Server 3.5