com.sssw.rt.form
Class AgcList

java.lang.Object
 |
 +--java.awt.Component
       |
       +--java.awt.List
             |
             +--com.sssw.rt.atlas.AtList
                   |
                   +--com.sssw.rt.form.AgcList

All Implemented Interfaces:

AgiControl, AgiHelpInfo, AgiRowSetManager, ImageObserver, ItemSelectable, MenuContainer, Serializable

public class AgcList

extends com.sssw.rt.atlas.AtList

implements AgiRowSetManager, AgiControl

The AgcList control (List) is a data-bound list control that displays a list of values to users. Users can browse the list of values and select a value from it. The AgcList class exposes the AWT list control as a com.sssw.rt.form control.

When the control is bound to a database column via the Data Column property, the value in the database sets the initially selected item in the list. If the user makes a different selection, that value becomes the value associated with the current row. The selected value is saved to the database when you call updateRows() for the form.

In addition to being data-bound, the control is a data-loaded control in which a database table or other data source can provide the list of values. 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.

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:

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

See Also:

Serialized Form

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface com.sssw.rt.form.AgiControl

IMAGE_MODE_CENTERED, IMAGE_MODE_NORMAL, IMAGE_MODE_STRETCH, IMAGE_MODE_TILED

Constructor Summary

AgcList()

Method Summary

void	add(String title, Object value) Appends an item to the list, specifying both the display text and the list item's value.
void	addRow(String title) Deprecated. replaced by List.add(String) method.
int	countRows() Deprecated. replaced by List.getItemCount() method.
void	deselect(int index) Deselects a row.
Color	getBackgroundColor() Deprecated. replaced by Component.getBackground().
AgoFontIdentifier	getFontIdentifier() Returns the SilverStream font object (AgoFontIdentifier) for the control's text.
Object	getItemValue(int index) Get the value of the item at the specified index.
String	getRowText(int index) Deprecated. replaced by List.getItem(int) method.
Object	getRowValue(int index) Deprecated. use AgcList.getItemValue(int) to obtain the value of the specified row.
Object	getValue() Returns the control's value.
void	insert(String title, int index) Provides the same functionality as the java.awt.List add(title, index) method.
void	insert(String title, Object value, int index) Inserts an item at the specified index in the AgcList, specifying both the display text and the list item's value (may be null).
void	removeAllRows() Deprecated. replaced by List.removeAll().
void	removeRow(int index) Deprecated. replaced by List.remove(int) method.
void	replaceItem(String newTitle, int index) Replace the text for the item at the specified index.
void	replaceItem(String newTitle, Object newValue, int index) Replace the text and value for the item at the specified index.
void	replaceRow(String newTitle, int index) Deprecated. replaced by AgcList.replaceItem(String,int) method.
void	select(int index) Selects the specified row.
void	setBackgroundColor(Color backgroundcolor) Deprecated. replaced by Component.setBackground(Color).
void	setFontIdentifier(AgoFontIdentifier fontidentifier) Assigns the SilverStream font object (AgoFontIdentifier) to the control's text.
void	setValue(Object value) Selects the row whose value is equal to the specified value.

Methods inherited from class com.sssw.rt.atlas.AtList

deliverMouseEvent, deliverMouseMoveEvent, doAtCommand, enableAtCommands, getHelper, getToolTipText, getToolTipText, grabFocus, isFocusTraversable, isRequestFocusEnabled, preprocessKeyEvent, processEvent, requestFocus, setRequestFocusEnabled, setToolTipText

Methods inherited from class java.awt.List

add, add, addActionListener, addItem, addItem, addItemListener, addNotify, allowsMultipleSelections, clear, countItems, delItem, delItems, getItem, getItemCount, getItems, getMinimumSize, getMinimumSize, getPreferredSize, getPreferredSize, getRows, getSelectedIndex, getSelectedIndexes, getSelectedItem, getSelectedItems, getSelectedObjects, getVisibleIndex, isIndexSelected, isMultipleMode, isSelected, makeVisible, minimumSize, minimumSize, paramString, preferredSize, preferredSize, processActionEvent, processItemEvent, remove, remove, removeActionListener, removeAll, removeItemListener, removeNotify, setMultipleMode, setMultipleSelections

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getName, getParent, getPeer, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, postEvent, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate

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

getBackgroundImage, getBackgroundImageMode, getComponent, getHelpInfo, setBackgroundImage, setBackgroundImageMode, setHelpInfo

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

clearRows, haveRowsChanged, query, query, refreshRows, updateRows

Constructor Detail

AgcList

public AgcList()

Method Detail

getFontIdentifier

public AgoFontIdentifier getFontIdentifier()

Returns the SilverStream font object (AgoFontIdentifier) for the control's text.

Usage:

The AgoFontIdentifier object consists of three parts: a Font Name, a Font Style and a Font Size. The Font Name can be one of these values: Dialog, SansSerif, Serif, Monospaced, Helvetica, TimesRoman, Courier, DialogInput, Zapfdingbats. At runtime, Java translates this value to the appropriate font installed on the system.

The Font Style can be one of these values:

• AgoFontIdentifier.PLAIN
• AgoFontIdentifier.BOLD
• AgoFontIdentifier.ITALIC
• AgoFontIdentifier.BOLD + AgoFontIdentifier.ITALIC

The Font Size can be any integer.

Example:

The following code fragment illustrates how to construct a new AgoFontIdentifier object (called newFont) and how to call the getFontIdentifier() method:

  AgoFontIdentifier font;
  font = ControlName1.getFontIdentifier();
 

See Also:

AgcList.setFontIdentifier(AgoFontIdentifier)

setFontIdentifier

public void setFontIdentifier(AgoFontIdentifier fontidentifier)

Assigns the SilverStream font object (AgoFontIdentifier) to the control's text.

Parameters:

fontidentifier - specifies the AgoFontIdentifier object that assigns the font for the control.

Usage:

The AgoFontIdentifier object consists of three parts: a Font Name, a Font Style and a Font Size. The Font Name can be one of these values: Dialog, SansSerif, Serif, Monospaced, Helvetica, TimesRoman, Courier, DialogInput, Zapfdingbats. At runtime, Java translates this value to the appropriate font installed on the system.

The Font Style can be one of these values:

• AgoFontIdentifier.PLAIN
• AgoFontIdentifier.BOLD
• AgoFontIdentifier.ITALIC
• AgoFontIdentifier.BOLD + AgoFontIdentifier.ITALIC

The Font Size can be any integer.

Example:

This code fragment illustrates how to construct a new AgoFontIdentifier object (called newFont) and how to call the setFontIdentifier() method:

  AgoFontIdentifier     newFont;
  String		   newName;
  int	           newSize;
  int		   newStyle;
 
  newName="TimesRoman";
  newSize=20;
  newStyle=AgoFontIdentifier.ITALIC;
  newFont=new AgoFontIdentifier(newName, newStyle, newSize);
 
  ControlName1.setFontIdentifier(newFont);
 

See Also:

AgcList.getFontIdentifier()

getBackgroundColor

public Color getBackgroundColor()

Deprecated. replaced by Component.getBackground().

setBackgroundColor

public void setBackgroundColor(Color backgroundcolor)

Deprecated. replaced by Component.setBackground(Color).

Parameters:

backgroundcolor -

addRow

public void addRow(String title)

Deprecated. replaced by List.add(String) method.

Adds a row to the end of the current list.

Parameters:

title - specifies the text of the row to add.

Usage:

The addRow() method adds a row dynamically at runtime. Rows added dynamically are not saved across sessions or instances of the control in the way that rows added as properties of the control are.

See Also:

AgcList.removeRow(int), AgcList.removeAllRows()

insert

public void insert(String title,
                   int index)

Provides the same functionality as the java.awt.List add(title, index) method.

Parameters:

title -

index -

add

public void add(String title,
                Object value)

Appends an item to the list, specifying both the display text and the list item's value.

Parameters:

title - specifies the text of the row to add.

value - specifies the value of the row to add.

Usage:

The add() method adds a row dynamically at runtime. Rows added dynamically are not saved across sessions or instances of the control in the way that rows added as properties of the control are.

Example:

  ControlName1.add("One", new Integer(1));
  ControlName1.add("Two", new Integer(2));
 

See Also:

AgcList.removeRow(int), AgcList.removeAllRows()

insert

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

Inserts an item at the specified index in the AgcList, specifying both the display text and the list item's value (may be null).

Parameters:

title - the display text.

value - the item's value.

index - where to add the item.

Usage:

If 'index' is -1, the item is added as the last item.

removeRow

public void removeRow(int index)

Deprecated. replaced by List.remove(int) method.

Removes the specified row from the list.

Parameters:

index - specifies the index of the row to remove.

Usage:

The rows are zero-based.

Example:

The following code fragment illustrates how to remove the row whose index is three.

  ControlName1.removeRow(3);
 

See Also:

AgcList.addRow(String)

replaceRow

public void replaceRow(String newTitle,
                       int index)

Deprecated. replaced by AgcList.replaceItem(String,int) method.

Replaces a row.

Parameters:

newText - the replacement text.

index - the index of the row to replace.

Usage:

Row indexes are zero-based.

replaceItem

public void replaceItem(String newTitle,
                        int index)

Replace the text for the item at the specified index.

Overrides:

replaceItem in class List

Parameters:

newTitle -

index -

replaceItem

public void replaceItem(String newTitle,
                        Object newValue,
                        int index)

Replace the text and value for the item at the specified index.

Parameters:

newTitle - String for new title.

newValue - Object that specifies new value.

index - An int that specifies the index of the item in the list.

removeAllRows

public void removeAllRows()

Deprecated. replaced by List.removeAll().

Clears all rows from the list.

Example:

The following code fragment illustrates how to use the removeAllRows() method.

  ControlName1.removeAllRows();
 

See Also:

AgcList.addRow(String), AgcList.removeRow(int)

countRows

public int countRows()

Deprecated. replaced by List.getItemCount() method.

Returns the number of rows.

Usage:

The rows are zero-based.

getRowText

public String getRowText(int index)

Deprecated. replaced by List.getItem(int) method.

Returns the text of the specified row.

Parameters:

index - specifies the index of the row whose text is desired.

Usage:

The rows are zero-based.

getRowValue

public final Object getRowValue(int index)

Deprecated. use AgcList.getItemValue(int) to obtain the value of the specified row.

Parameters:

index - specifies the index of the row whose value is desired.

Usage:

The rows are zero-based.

See Also:

AgcList.getItemValue(int)

getItemValue

public Object getItemValue(int index)

Get the value of the item at the specified index.

Parameters:

index - specifies the index of the row whose value is desired.

Usage:

The indexes are zero-based.

Example:

  Object value;
  value = ControlName1.getItemValue(3);
 

select

public void select(int index)

Selects the specified row.

Overrides:

select in class List

Parameters:

index - specifies the row to select.

Usage:

The rows are zero-based.

Example:

The following code fragment illustrates how to select a row.

 ControlName1.select(3);
 

See Also:

AgcList.addRow(String), AgcList.removeRow(int)

deselect

public void deselect(int index)

Deselects a row.

Overrides:

deselect in class List

Parameters:

index - specifies the index of the row to deselect.

Usage:

Only useful if setMultipleMode(true). Rows are zero-based.

Example:

The following code fragment illustrates how to deselect the row whose index is three.

  ControlName1.deselect(3); 
 

See Also:

AgcList.select(int)

getValue

public Object getValue()

Returns the control's value.

Usage:

This is the internal value associated with the selected node. If the internal value is null, then the selected node's text is returned as a String. If no node is selected, then null is returned.

Example:

  Object value;
  value = ControlName1.getValue();
 

See Also:

AgcList.setValue(Object)

setValue

public void setValue(Object value)

Selects the row whose value is equal to the specified value.

Parameters:

value - specifies an internal value that specifies which row to select.

Usage:

At design time the contents of the internal value can be established using the Property Inspector. It can be static or retrieved from the database. Each row can have its own internal value.

If the control is populated from a static list of data (that is the Load Choices property is set to Statically), the internal values can be specified using the Values property.

If the control is populated from the database (that is the Load Choices property is set to From Table), the internal values can be specifed using the Storage value property.

Example:

Suppose a control is loaded statically:

• The displayed text values are: Apple, Banana, Orange
• The internal values are: 1, 2, 3

The following code fragment illustrates how to make Orange the selected item using setValue().

  int x=3;
  ControlName1.setValue(new Integer(x));
 

Note that this example uses the Integer class instead of the int primitive data type because an Object cannot be cast to an int.

See Also:

AgcList.getValue()