All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sgi.sysadm.ui.ItemFinder

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----javax.swing.JComponent
                           |
                           +----javax.swing.JComboBox
                                   |
                                   +----com.sgi.sysadm.ui.ItemFinder

public class ItemFinder
extends JComboBox
implements ExtraCleanup
A subclass of JComboBox that displays the Items in a Category.

The ItemFinder displays a drop-down menu of the names of Items in a particular Category. The ItemFinder also allows the user to type in the name of an Item instead of choosing it from the menu. The ItemFinder does not prevent the user from typing in the name of an Item that does not exist, but allows client code to detect that state via the ItemFinderState.

The ItemFinder can use one of two ways to determine the name which will be displayed for each Item in the drop-down menu. The easy way is to pass it a String which will be used as an Attribute key; the name displayed for each Item will be its value of that Attribute. For more control over the names displayed, you can pass your own implementation of ItemDisplayNameRenderer which determines the name to display for each Item.

The Items can be filtered in two ways. The first is to pass an Association that contains only the Items to display to the setCategory method. The other possibility is to pass an ItemTester to the ItemFinder constructor. Only Items that pass the ItemTester will be displayed in the ItemFinder.

In some cases, it may be desireable to display one or more strings in the ItemFinder that do not correspond directly to Items. One example would be an "All Items" string that the user could choose to specify that they wished to choose all the available Items. These strings can be passed to the constructor as the headers parameter, or set via the setHeaders method. These headers will always be displayed at the top of the menu.

ItemFinder uses a monospace font defined in a properties file. Using a monospace font in a text field assures that the number of input characters displayed is equal to the column width of the text field. The font resource is shared with RPasswordField and RTextField.

See Also:
JComboBox, RPasswordField, RTextField

Variable Index

 o ALWAYS_CLEAR
Pass this value to setClearBehavior to specify that the ItemFinder should clear the text when the Category is set via the setCategory method.
 o CLEAR_IF_SWITCHING
Pass this value to setClearBehavior to specify that the ItemFinder should clear the text field only if it used to be displaying a Category, and setCategory was called again.
 o FONT
A resource Field.font specifies the font to be used in the text area.
 o NEVER_CLEAR
Pass this value to setClearBehavior to specify that the ItemFinder should not clear the text when the Category it set via the setCategory method.

Constructor Index

 o ItemFinder(ItemTester, ItemDisplayNameRenderer, String[])
Construct an ItemFinder with a default width.
 o ItemFinder(ItemTester, ItemDisplayNameRenderer, String[], int)
Construct an ItemFinder with a particular width.
 o ItemFinder(ItemTester, String)
Construct an ItemFinder which will display the given Attribute's value as each Item's name.
 o ItemFinder(ItemTester, String, int)
Construct an ItemFinder which will display the given Attribute's value as each Item's name.

Method Index

 o addItemFinderListener(ItemFinderListener)
Add an ItemFinderListener to this ItemFinder
 o extraCleanup()
Called by RFrame when a TaskFrame is closed.
 o getItemFinderState()
Returns the current state of the ItemFinder
 o removeItemFinderListener(ItemFinderListener)
Removes an ItemFinderListener from the list of listeners
 o selectedItemChanged()
This is a copy of the JComboBox method of the same name, with minor tweaks for better performance We avoid sending a DESELECTED event because it's not necessary and it results in more notificiations than necessary.
 o setCategory(Category)
Sets the Category that this ItemFinder is listening to.
 o setClearBehavior(int)
Sets the way that the ItemFinder reacts when setCategory is called.
 o setHeaders(String[])
Sets the headers to be displayed at the top of the list of Items in the ItemFinder.
 o setItemTester(ItemTester)
Sets the ItemTester that will be used to filter the Items.
 o setSelectedIndex(int)
Overridden method that catches and ignores the IllegalArgumentException so that the ItemFinder doesn't die if a refresh() occurs when the popup is showing.
 o setTextByName(String)
Sets the text that is shown in the ItemFinder.
 o setTextBySelector(String)
Sets the Item being displayed in the ItemFinder.

Variables

 o FONT
 public static final String FONT
A resource Field.font specifies the font to be used in the text area. The resource is defined in com.sgi.sysadm.ui.SysadmUIP.properties, and may be overridden in {package}/PackageP.properties, but please note that this resource is shared with RPasswordField and RTextField.

 o ALWAYS_CLEAR
 public static final int ALWAYS_CLEAR
Pass this value to setClearBehavior to specify that the ItemFinder should clear the text when the Category is set via the setCategory method.

 o NEVER_CLEAR
 public static final int NEVER_CLEAR
Pass this value to setClearBehavior to specify that the ItemFinder should not clear the text when the Category it set via the setCategory method.

 o CLEAR_IF_SWITCHING
 public static final int CLEAR_IF_SWITCHING
Pass this value to setClearBehavior to specify that the ItemFinder should clear the text field only if it used to be displaying a Category, and setCategory was called again.

Constructors

 o ItemFinder
 public ItemFinder(ItemTester itemTester,
                   ItemDisplayNameRenderer itemDisplayNameRenderer,
                   String headers[],
                   int width)
Construct an ItemFinder with a particular width.

Parameters:
itemTester - An ItemTester that is used to decide which Items to display. Pass null to use no ItemTester, which will result in all the Items in the Category passed to setCategory being displayed.
itemDisplayNameRenderer - the Object to use to convert the Items into "user friendly" names for display in this ItemFinder. Pass null to use the selectors as display strings. This renderer must provide unique names for the Items in the ItemFinder to avoid duplicate menu items.
headers - An array of Strings that will be displayed, in order, at the top of the ItemFinder regardless of any other Items that are displayed. Pass null to display no header strings.
width - The width (in pixels) of the ItemFinder. Must be > 0, or a default size will be used.
 o ItemFinder
 public ItemFinder(ItemTester itemTester,
                   ItemDisplayNameRenderer itemDisplayNameRenderer,
                   String headers[])
Construct an ItemFinder with a default width.

Parameters:
itemTester - An ItemTester that is used to decide which Items to display. Pass null to use no ItemTester, which will result in all the Items in the Category passed to setCategory being displayed.
itemDisplayNameRenderer - the Object to use to convert the Items into "user friendly" names for display in this ItemFinder. Pass null to use the selectors as display strings. This renderer must provide unique names for the Items in the ItemFinder to avoid duplicate menu items.
headers - An array of Strings that will be displayed, in order, at the top of the ItemFinder regardless of any other Items that are displayed. Pass null to display no header strings.
 o ItemFinder
 public ItemFinder(ItemTester itemTester,
                   String itemDisplayNameAttrKey)
Construct an ItemFinder which will display the given Attribute's value as each Item's name. It will be created with a default width. For backwards compatibility, this constructor doesn't take a String[] of headers (it would have broken delivered code which was calling new ItemTester(null, null, null)); if necessary, you can call setHeaders(String[]) after creating the ItemTester (or use one of the other constructors).

Parameters:
itemTester - An ItemTester that is used to decide which Items to display. Pass null to use no ItemTester, which will result in all the Items in the Category passed to setCategory being displayed.
itemDisplayNameAttrKey - The key of the Item Attribute whose value will be displayed as each Item's name in this ItemFinder. The values of this Attribute must be unique among the Items in this ItemFinder to avoid duplicate menu items.
 o ItemFinder
 public ItemFinder(ItemTester itemTester,
                   String itemDisplayNameAttrKey,
                   int width)
Construct an ItemFinder which will display the given Attribute's value as each Item's name. It will be created with the given width. For backwards compatibility, this constructor doesn't take a String[] of headers (it would have broken delivered code which was calling new ItemTester(null, null, null, width)); if necessary, you can call setHeaders(String[]) after creating the ItemTester (or use one of the other constructors).

Parameters:
itemTester - An ItemTester that is used to decide which Items to display. Pass null to use no ItemTester, which will result in all the Items in the Category passed to setCategory being displayed.
itemDisplayNameAttrKey - The key of the Item Attribute whose value will be displayed as each Item's name in this ItemFinder. The values of this Attribute must be unique among the Items in this ItemFinder to avoid duplicate menu items.
width - The width (in pixels) of the ItemFinder. Must be > 0, or a default size will be used.

Methods

 o setClearBehavior
 public void setClearBehavior(int clearBehavior)
Sets the way that the ItemFinder reacts when setCategory is called. ItemFinder defaults to CLEAR_IF_SWITCHING.

Parameters:
clearSelection - Pass either ALWAYS_CLEAR, NEVER_CLEAR, or CLEAR_IF_SWITCHING to control what happens to the text that is displayed in the ItemFinder text area when setCategory is called.
 o addItemFinderListener
 public void addItemFinderListener(ItemFinderListener listener)
Add an ItemFinderListener to this ItemFinder

Parameters:
listener - The listener that will be notified when the state of the ItemFinder changes.
 o removeItemFinderListener
 public void removeItemFinderListener(ItemFinderListener listener)
Removes an ItemFinderListener from the list of listeners

Parameters:
listener - The listener to remove
 o setHeaders
 public void setHeaders(String headers[])
Sets the headers to be displayed at the top of the list of Items in the ItemFinder.

Parameters:
headers - An array of Strings to use as headers. You can use null to clear any headers that are currently set. Any headers previously set are discarded.
 o setItemTester
 public void setItemTester(ItemTester tester)
Sets the ItemTester that will be used to filter the Items. Pass null to show all the Items.

Parameters:
tester - The ItemTester
 o setTextByName
 public void setTextByName(String text)
Sets the text that is shown in the ItemFinder. If the text matches the name of an Item (as returned by the getDisplayName method of the ItemDisplayNameRenderer object passed to the constructor - or the Item's selector if the ItemDisplayNameRenderer is null) that is currently displayed in the ItemFinder, then that Item is selected. If the name doesn't match any Item, then the text is simply displayed in the text field. ItemFinderListeners are notified just as if a user had typed text into the ItemFinder.

Parameters:
text - The text to display
 o setTextBySelector
 public void setTextBySelector(String selector)
Sets the Item being displayed in the ItemFinder. Generates an assertion if the Item represented by the selector doesn't exist, or if that Item has been rejected by the ItemFilter. ItemFinderListeners are notified just as if a user had selected the Item.

Parameters:
selector - The selector of the Item.
 o getItemFinderState
 public ItemFinderState getItemFinderState()
Returns the current state of the ItemFinder

Returns:
An ItemFinderState object that describes the current state.
 o setSelectedIndex
 public void setSelectedIndex(int anIndex)
Overridden method that catches and ignores the IllegalArgumentException so that the ItemFinder doesn't die if a refresh() occurs when the popup is showing. This works around a bug in Java's Swing code. (4135319)

Overrides:
setSelectedIndex in class JComboBox
 o extraCleanup
 public void extraCleanup()
Called by RFrame when a TaskFrame is closed. Clean up so that garbage collection can occur.

 o setCategory
 public void setCategory(Category category)
Sets the Category that this ItemFinder is listening to.

Parameters:
category - The category to use. You can pass null to not use any Category and clear the ItemFinder
 o selectedItemChanged
 protected void selectedItemChanged()
This is a copy of the JComboBox method of the same name, with minor tweaks for better performance We avoid sending a DESELECTED event because it's not necessary and it results in more notificiations than necessary.

Overrides:
selectedItemChanged in class JComboBox

All Packages  Class Hierarchy  This Package  Previous  Next  Index