com.sssw.shr.page
Class AgpListBase

java.lang.Object
 |
 +--com.sssw.shr.page.AgpTag
       |
       +--com.sssw.shr.page.AgpControlBase
             |
             +--com.sssw.shr.page.AgpListBase

All Implemented Interfaces:

AgiJavaScriptEnhanced, AgiPageControl, AgiRowSetManager, Cloneable, Externalizable, Serializable

Direct Known Subclasses:

AgpChoice, AgpList

public abstract class AgpListBase

extends AgpControlBase

implements AgiRowSetManager

Internal SilverStream class: methods shared between AgpList and AgpChoice. All AgpListBase controls present items in a list format that allows the user to select one of the items. Each item can have a value associated with it, of any Object type. For instance, a control might display employee names to the user, and associate an employee id with each name. The items and values of an AgpListBase control can be set up in several different ways. At design time, they can be set to static values or loaded from a database column using the Property Inspector. At run time, they can be added individually using the add() and insert() methods, or they can be loaded from a data source using the loadFromRowCursor() method. The value of an AgpListBase control can be bound to a data source such as a database column so that the user selection automatically displays and updates the source's data.

See Also:

Serialized Form

Fields inherited from class com.sssw.shr.page.AgpTag

UNIT_PERCENT, UNIT_PIXEL

Constructor Summary

AgpListBase()

Method Summary

void	add(String item) Adds a new item with the specified item text.
void	add(String item, Object value) Adds a new item with the specified item text and value.
void	deselect(int index) Deselects the specified item.
String	getItem(int index) Returns the text of the specified item.
int	getItemCount() Returns the number of items in the control.
String[]	getItems() Returns an array listing all the items in the control.
Object	getItemValue(int index) Returns the value of the item at the specified index.
Object[]	getItemValues() Returns an array listing the value of each item in the control.
int	getSelectedIndex() Returns the index of the first selected item.
boolean	getSubmitOnChange() Returns whether a Submit request is sent to the server when the control's value changes.
Object	getValue() Returns the current value of a list.
boolean	getValueInOptionTag()
void	insert(String item, int index) Inserts a new item into the control at the specified index.
void	insert(String item, Object value, int index) Inserts a new item into the control at the specified index.
boolean	isSelected(int index) Returns whether the specified item is selected.
void	loadFromRowCursor(AgiRowCursor rc, int displaycol, int valuecol) Reloads the items from an AgiRowCursor source.
void	remove(int index) Removes the specified item from the control.
void	removeAll() Removes all items from this list or choice control.
void	replaceItem(String newTitle, int index) Replaces the displayed text of the specified item.
void	replaceItem(String newTitle, Object newValue, int index) Replaces both the item text and the value of the specified item.
void	select(int index) Selects the specified item.
void	setSubmitOnChange(boolean submit_on_change) Specifies whether a Submit request is sent to the server when the end user selects an item in the control.
void	setValue(Object value) Sets the value of the control.
void	setValueInOptionTag(boolean b)

Methods inherited from class com.sssw.shr.page.AgpControlBase

getName

Methods inherited from class com.sssw.shr.page.AgpTag

getBoolProperty, getEnableHTMLGeneration, getIntArrayProperty, getIntProperty, getIntPropertyUnit, getProperty, getStringArrayProperty, invalidateHTML, removeProperty, setEnableHTMLGeneration, setIntProperty, setProperty

Methods inherited from class java.lang.Object

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

Methods implemented from interface com.sssw.shr.page.AgiJavaScriptEnhanced

generateFunction, generateRepaintScript, generateScriptInitializers, getFunctionNameForMethod, getFunctionNames, getMethodNames, getScriptObjectName, isHTMLRepaintPending, isJavaScriptRepaintPending

Methods implemented from interface com.sssw.shr.page.AgiPageControl

generateHTML, getPrefix, notifyPageLoaded, notifyPageRequestBegin, notifyPageRequestEnd, notifyPostValue, notifyPostValues

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

clearRows, haveRowsChanged, query, query, refreshRows, updateRows

Methods implemented from interface java.io.Externalizable

readExternal, writeExternal

Constructor Detail

AgpListBase

public AgpListBase()

Method Detail

getSubmitOnChange

public boolean getSubmitOnChange()

Returns whether a Submit request is sent to the server when the control's value changes.

Example:

 		// Display or hide a "Submit" button on the page, depending on whether the control
 		// named Choice1 is going to handle its own submits
 		if (Choice1.getSubmitOnChange())
 		{
 			// Choice1 will submit, don't show the button
 			btnSubmit.setEnableHTMLGeneration(false);
 		}
 		else
 		{
 			// Choice1 will not submit, so we need the button
 			btnSubmit.setEnableHTMLGeneration(true);
 		}
 
 

See Also:

AgpListBase.setSubmitOnChange(boolean submit_on_change)

setSubmitOnChange

public void setSubmitOnChange(boolean submit_on_change)

Specifies whether a Submit request is sent to the server when the end user selects an item in the control. This functionality depends on JavaScript. It will not work in all browsers.

Parameters:

submit_on_change - true if a Submit request should be sent, otherwise false.

Example:

List1.setSubmitOnChange(true);

See Also:

AgpListBase.getSubmitOnChange()

getValueInOptionTag

public boolean getValueInOptionTag()

setValueInOptionTag

public void setValueInOptionTag(boolean b)

add

public void add(String item)

Adds a new item with the specified item text. The item will be placed at the end of the list. The value of the added item will be the same as the text.

Parameters:

item - the text for the new item.

Example:

 		// Add an entry for "all of the above" at the end of List1.
 		List1.add("All of the above");
 

See Also:

AgpListBase.remove(int index), AgpListBase.removeAll()

add

public void add(String item,
                Object value)

Adds a new item with the specified item text and value. The new item will be placed at the end of the list. The text will be displayed in the control on the page. When the item is selected, the associated value will be used as the value of the list box.

Parameters:

item - the text for the new item.

value - the new value.

Example:

 		// Fill a list box with entries for three URLs
 		URLList.add("SilverStream HQ", new URL("http://www.silverstream.com");
 		URLList.add("PC Week", new URL("http://www.zdnet.com/pcweek");
 		URLLIST.add("CNN", new URL("http://www.cnn.com");
 

See Also:

AgpListBase.remove(int index), AgpListBase.removeAll()

insert

public void insert(String item,
                   int index)

Inserts a new item into the control at the specified index. The index must be less than or equal to the number of items in the control. If necessary, other items in the control will be shifted up by one to make room for the newly-inserted item.

The control will use the given text to display the item. The text will also be used as the value for the item.

Parameters:

item - the text for the new item.

index - the index for the new item.

Example:

 		// Put an item for "No selection" at the top of the choice control
 		Choice1.insert("No selection", 0);
 
 

See Also:

AgpListBase.remove(int index), AgpListBase.removeAll()

insert

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

Inserts a new item into the control at the specified index. The index must be less than or equal to the number of items in the control. If necessary, other items in the control will be shifted up by one to make room for the newly-inserted item.
The control will use the given text to display the item. The given value will be associated with the item.

Parameters:

item - the text for the new item.

value - the value for the new item.

index - the index for the new item.

Example:

 		// Put an item for "No selection" at the top of the choice control,
 		// assigning it a value of -1
 		Choice1.insert("No selection", new Integer(-1), 0);
 
 

See Also:

AgpListBase.remove(int index), AgpListBase.removeAll()

replaceItem

public void replaceItem(String newTitle,
                        int index)

Replaces the displayed text of the specified item. The value remains unchanged.

Parameters:

newTitle - the replacement text.

index - the index of the item.

Example:

 		// Truncate each displayed entry to its first ten letters
 		// (so that it takes up less space on the screen)
 		for (int i = 0; i < List1.getItemCount(); i++)
 		{
 			String itemText = List1.getItem(i);
 			String shortText = itemText.substring(0, 9);
 			List1.replaceItem(shortText, i);
 		}
 
 

See Also:

AgpListBase.add(String item), AgpListBase.insert(String item, int index), AgpListBase.remove(int index), AgpListBase.removeAll()

replaceItem

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

Replaces both the item text and the value of the specified item.

Parameters:

newTitle - the replacement text.

newValue - the replacement value.

index - the index of the item.

Example:

 		// Change the third item in this listbox to refer to SilverStream's web site
 		URLList.replaceItem("SilverStream", new URL("http://www.silverstream.com"), 2);
 

See Also:

AgpListBase.add(String item, Object value), AgpListBase.insert(String item, Object value, int index), AgpListBase.remove(int index), AgpListBase.removeAll()

remove

public void remove(int index)

Removes the specified item from the control.

Parameters:

index - the index of the item to remove.

Example:

 		// truncate the list to the first ten entries.
 		for (int i = List1.getItemCount() - 1; i >= 10; i--)
 		{
 			List1.remove(i);
 		}
See Also: 
AgpListBase.removeAll(), 
AgpListBase.replaceItem(String newTitle, Object newValue, int index)

removeAll

public void removeAll()

Removes all items from this list or choice control.

Example:

 		Choice1.removeAll();
 

See Also:

AgpListBase.remove(int index)

getItemCount

public int getItemCount()

Returns the number of items in the control.

Example:

 		// Loop over all the items in the list and
 		// make sure that the one labeled "Blue" is selected
 		for (int i = 0; i < List1.getItemCount(); i++)
 		{
 			String item = List1.getItem(i);
 			if (item.equals("Blue"))
 			{
 				List1.select(i);
 				break;
 			}
 		}
 

getItem

public String getItem(int index)

Returns the text of the specified item. This is the string that is displayed in the control on the page.

Parameters:

index - the index of the item to retrieve.

Example:

 		// Loop over all the items in the list and
 		// make sure that the one labeled "Blue" is selected
 		for (int i = 0; i < List1.getItemCount(); i++)
 		{
 			String item = List1.getItem(i);
 			if (item.equals("Blue"))
 			{
 				List1.select(i);
 				break;
 			}
 		}
 

See Also:

AgpListBase.getItems(), AgpListBase.getItemValue(int index), AgpListBase.getValue()

getItemValue

public Object getItemValue(int index)

Returns the value of the item at the specified index.

Parameters:

index - the index of the item to retrieve.

Example:

 		// if any items have a value of "null" set the value to the empty string instead
 		for (int i = 0; i < List1.getItemCount(); i++)
 		{
 			if (List1.getItemValue(i) == null)
 			{
 				String item = List1.getItem(i);
 				List1.replaceItem(item, "", i);
 			}
 		}
 
 

See Also:

AgpListBase.getItem(int index), AgpListBase.getItemValues(), AgpListBase.getValue()

getValue

public Object getValue()

Returns the current value of a list. If a single item is selected, the current value is the value associated with that item. If the control is in multiple-selection mode, and more than one item is selected, the current value is an array of Objects containing the value associated with each selected item. If a call to setValue has occurred more recently than any user selection, the current value is the same as the argument passed in setValue.

Example:

 		// Get the current value of a list and call a method on it; if more than one item is
 		// selected, call a (hypothetical) method named "process" on each of them. Assumes
 		// that all the values are Strings.
 
 		Object currentValue = List1.getValue();
 		if (currentValue instanceof String)
 		{
 			process((String)currentValue);
 		}
 		else if (currentValue instanceof Object[])
 		{
 			Object[] currentValueArray = (Object[])currentValue;
 			for (int i = 0; i < currentValueArray.length; i++)
 			{
 				process((String)currentValueArray[i]);
 			}
 		}
 
 

See Also:

AgpListBase.getItem(int index), AgpListBase.getItemValue(int index), AgpListBase.getItemValues(), AgpListBase.setValue(Object value)

setValue

public void setValue(Object value)

Sets the value of the control. If the given value is associated with one of the items in the control, that item will be selected. If the control is in multiple-selection mode and the given value is an array of Objects, any items associated with those values will be selected. Whether or not an item in the control is associated with the given value, calling getValue on the control will return the value, until the user changes it by making a new selection, or another call to setValue changes it.

Parameters:

value - the new value for the control

Example:

 		List1.setValue(new Integer(23));
 

See Also:

AgpListBase.getValue()

getItems

public String[] getItems()

Returns an array listing all the items in the control. This is a copy of the information kept by the control, so changing this array will not change the items displayed by the control.

Example:

 		// Keep a copy of the items and values that are currently in the control
 		// before making modifications
 		String itemArray[] = List1.getItems();
 		Object valueArray[] = List1.getItemValues();
 		List1.add("twenty-three", new Integer(23));
 
 

See Also:

AgpListBase.getItem(int index), AgpListBase.getItemValues()

getItemValues

public Object[] getItemValues()

Returns an array listing the value of each item in the control. This is a copy of the information kept by the control, so changing this array will not change the items displayed by the control.

Example:

 		// Keep a copy of the items and values that are currently in the control
 		// before making modifications
 		String itemArray[] = List1.getItems();
 		Object valueArray[] = List1.getItemValues();
 		List1.add("twenty-three", new Integer(23));
 
 

See Also:

AgpListBase.getItems(), AgpListBase.getValue()

getSelectedIndex

public int getSelectedIndex()

Returns the index of the first selected item.

Example:

 		// URLList is a list of URLs - go to the one that's been selected
 		int i = URLList.getSelectedIndex();
 		java.net.URL selectedURL = (java.net.URL)URLList.getItemValue(i);
 		if (selectedURL != null)
 			showPage(selectedURL.toString());
 
 

select

public void select(int index)

Selects the specified item. If the control is in single-selection mode, any previous selection is cleared. If the control is in multiple-selection mode, this item is added to the current selection.

Parameters:

index - the index of the item to select.

Example:

 		// Select the topmost item in the Choice control
 		Choice1.select(0);
 
 

See Also:

AgpListBase.deselect(int index), AgpListBase.isSelected(int index)

deselect

public void deselect(int index)

Deselects the specified item.

Parameters:

index - the index of the item to deselect.

Example:

See Also:

AgpListBase.isSelected(int index), AgpListBase.select(int index)

isSelected

public boolean isSelected(int index)

Returns whether the specified item is selected.

Parameters:

index - the index of the item to check.

Example:

 		// we happen to know that the third item in the list says "SilverStream"
 		int iSilverStream = 3;
 		// if the "SilverStream" item is selected, display a label containing
 		// a link to the SilverStream web site
 		if (List1.isSelected(iSilverStream))
 			SilverStreamLink.setEnableHTMLGeneration(true);
 

See Also:

AgpListBase.deselect(int index), AgpListBase.select(int index)

loadFromRowCursor

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

Reloads the items from an AgiRowCursor source.

Parameters:

rc - an instance of AgiRowCursor.

displaycol - the index of the source's column where the display text for each item is stored

valuecol - the index of the source's column where the value for each item is stored.

Example:

 		// Initialize a choice control from an AgpData control,
 		// using the "Name" column for display and the "EmployeeID" column for the value
 
 		int nameIndex = agpData.getPropertyIndex("Name");
 		int empIDIndex = agpData.getPropertyIndex("EmployeeID");
 		Choice1.loadFromRowCursor(agpData1, nameIndex, empIDIndex);