TOC

Bean at a Glance

Bean Overview

public class ObjectComboBox
extends java.awt.Panel
implements java.awt.event.ItemListener, java.awt.event.KeyListener, java.awt.event.FocusListener, java.awt.event.TextListener, java.awt.event.MouseListener

This bean presents a graphical interface to the user and allows the user to select or edit the items in the list. The ObjectComboBox is a text field with an attached drop-down list box. It can add not only the string item but also any object item into the list directly. It may be editable and searchable. Editable means the user can enter any desired text into the text field and searchable means ObjectComboBox will highlight the selected item when the user enters text into the text field as long as it matches one of the existing list items.


previousCommonly used Methods, Events and Properties

Creation Methods

ObjectComboBox()

Key Properties

Enable
Editable
Searchable
CaseSensitive
InstantSearch
AutoIncreasing
MaxListRows
SelectedIndex
ListItems
Font

Commonly used Methods

addItem(Object item)
     Adds an item as the last record in the ObjectComboBox. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
addItem(Object item, String name)
     Adds an item with specified display name as the last record in the ObjectComboBox. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
insertItemAt(Object item, int index)
     Inserts an item to the ObjectComboBox at the specified position. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
insertItemAt(Object item, String name, int index)
     Inserts an item with specified display name to the ObjectComboBox at the specified position. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
removeItem(Object item)

     Removes an item from the ObjectComboBox.
removeItemAt(int index)
     Removes an item at the specified position from the ObjectComboBox.
removeAllItems()
     Removes all items from the ObjectComboBox.
replaceItemAt(Object item, int index)
     Replaces an old item with a new one at the specified position in the ObjectComboBox. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
replaceItemAt(Object item, String name, int index)

     Replaces an old item with a new one at the specified position in the ObjectComboBox. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
getItemAt(int index)

     Gets an item at the specified position in the ObjectComboBox.
getItemIndex(Object item)
     Gets an item's index in the ObjectComboBox.
getItemCount()
     Gets the number of items in the ObjectComboBox.
getItems()
    Gets the items in the ObjectComboBox.
setItems(Object[ ] items)
    Sets all the items in the list with a specified array of items.
setDisplayName(String name, Object item)
     Sets the item's name displayed in the list of the ObjectComboBox. If the same display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
getDisplayName(Object item)

     Gets the item's name displayed in the list of the ObjectComboBox.
setDisplayNameAt(String name, int index)
     Sets the item's name displayed in the list of the ObjectComboBox at the specified position. If the same display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.
getDisplayName(int index)

     Gets the item's name displayed in the list of the ObjectComboBox at the specified position.
getSelectedItem()
     Gets the selected item of the ObjectComboBox .
getSelectedDisplayName()

     Gets the selected item's display name of the ObjectComboBox .
select(Object item)

     Selects an item in the ObjectComboBox.
select(int index)
     Selects an item at specified position in the ObjectComboBox .
deselect()
     Deselects any item of the ObjectComboBox .

Commonly used Events

ComboBoxListEvent - The event is fired when the ObjectComboBox list's state changes. The event has four types: ADD_ITEM, REMOVE_ITEM, SELECT_ITEM and VALUE_CHANGE.

Note: when an item is added to the list, the value returned by getType() is ADD_ITEM; when an item is removed from the list, the value returned by getType() is REMOVE_ITEM; when an item is selected in the list, the value returned by getType() is SELECT_ITEM; when an item is changed, the value returned by getType() is VALUE_CHANGE. When all items are added to or removed from the list, getIndex() returns ALL_ITEMS.


previous Copyrights And Trademarks

Copyright © 1998 IBM Corp.

All rights reserved.

IBM and VisualAge are trademarks of International Business Machines in the United States and/or other countries.

* Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc, in the U.S. and other countries.


up

Bean Description

Functionality Overview

The ObjectComboBox Bean can insert not only the string item but also any object item into the list directly. It may be editable and searchable. Editable means the ObjectComboBox allows the user to enter any desired text into the text field and searchable means the ObjectComboBox will highlight the selected item when the user enters text into the text field as long as it matches one of the existing list items.

The ObjectComboBox Bean allows


previousDependencies

None.


previousSecurity

No special Java security restrictions will apply.


previousUser Interface

This section describes the user interface of the ObjectComboBox bean.

As shown in Figure 1, the ObjectComboBox bean is rather a simple bean, just like the ComboBox in Windows system. Figure 1 - ObjectComboBox

The ObjectComboBox contains a Text Field and a Drop-down List. Whenever the Enter key is pressed, the record in the Text Field is added to the Drop-down list as the last item. Note that when the user attempts to add the same record twice, the ObjectComboBox ignores the latter. If the record entered to the Text Field is a part of one of the items in the list, the ObjectComboBox highlights the item in the Text Field.


previousIntrospection

public class ObjectComboBoxBeanInfo


previousCustomization

The ObjectComboBox has the following properties to be customized in design time:

Enable
Editable
Searchable
CaseSensitive
InstantSearch
AutoIncreasing
MaxListRows
SelectedIndex
ListItems
Font


up

Summaries

Property Summary

<Name> <Datatype> [Constrained| Bound|Indexed ] <Description> <Default value> <Access type> 
Enable boolean Bound A flag indicating whether or not the component is enabled. The component does not interact with the user when it's disabled.  true Read / Write
Editable boolean Bound A flag indicating whether or not the component is editable. true Read / Write
Searchable boolean Bound A flag indicating whether or not the items in the component is searchable.Search process falls to two kinds: normal search and instant search. Normal search works when searchable property is set to true and instantSearch property is set to false. Once the user presses the drop-down button, the search process happens. If there is a item in the list matches the text entered, the content in the text field is then highlighted. true Read / Write
CaseSensitive boolean Bound  A flag indicating whether or not the search process is case-sensitive. false Read / Write
InstantSearch boolean Bound A flag indicating whether or not to search through the list instantly. It only works when the ObjectComboBox’s searchable property is set to true. Soon after the user types any character in run time, the instant search mode can instantly search through the items in the list and find which item matches the text entered. The part of the string which matches those characters entered will be display normally, but the additional part of the string will be highlighted, so it can't affect your further typing. true Read / Write
AutoIncreasing boolean Bound A flag indicating whether or not the component can increase items at run time. true Read / Write
MaxListRows int Bound Maximum number of rows. If item count exceeds this value, scrollbar will appear.  8 Read / Write
SelectedIndex int Bound The selected item's index in the component. -1 Read / Write
ListItems String[ ] Bound| Indexed The string array of items in the list of the component (commonly an array of strings is used for the convenience of users, but if other kinds of object are expected, just call setItems() or addItem() ). Null Read / Write
Font Font Bound The font property of the component.
Note: the ObjectComboBox size changes according to the font size.
Dialog, PLAIN, 12 Read / Write


previousMethod Summary


previousEvent Summary

As Source :


up

Alphabetic Reference to Properties


up

Alphabetic Reference to Methods

public void addComboBoxListListener(ComboBoxListListener l)

Adds the specified list listener to receive list state messages from ObjectComboBox.

         Parameters:
            l- the list state listener.

public void addItem(Object item)

Adds an item as the last record of the ObjectComboBox. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            item- the item to be added.

public void addItem(Object item, String name)

Adds an item with specified display name as the last record of the ObjectComboBox. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:
            item- the item to be added.
            name- the display name of the item.

public void addTextListener(TextListener l)

Adds the specified text listener to receive text value changing messages from the ObjectComboBox.

         Parameters:
            I- the list state listener.

public void deselect()

Deselects any item of the ObjectComboBox.

public String getDisplayName(Object item)

Gets an item's name displayed in the list of the ObjectComboBox.

public String getDisplayNameAt(int index)

Gets an item's name displayed in the list of the ObjectComboBox.

         Parameters:
            index- the index of the specified item.
         Returns:
            the item's name displayed in the list of the ObjectComboBox.

public Font getFont()

Gets the font of the ObjectComboBox.

         Returns:
            the font of the ObjectComboBox.

public Object getItemAt(int index)

Gets an item at the specified position in the ObjectComboBox.

public int getItemCount()

Gets the number of items in the ObjectComboBox.

     Returns:
          the number of items in the ObjectComboBox.

public int getItemIndex(Object item)

Gets an item's index in the ObjectComboBox.

public Object[ ] getItems()

Gets the items of the ObjectComboBox.

         Returns:
            the items of the ObjectComboBox.

public String[ ] getListItems()

Gets the string array of the items in the list of the ObjectComboBox.

         Returns:
            the string array of the items in the list of the ObjectComboBox.

public int getMaxListRows()

Gets the maximum number of rows in the list of the ObjectComboBox.

         Returns:
            the maximum number of rows in the list of the ObjectComboBox.

public string getSelectedDisplayName()

Gets the selected item's display name of the ObjectComboBox.

         Returns:
            the selected item's display name of the ObjectComboBox.

public int getSelectedIndex()

Gets the selected item's index of the ObjectComboBox.

         Returns:
            the selected item's index of the ObjectComboBox.

public Object getSelectedItem()

Gets the selected item of the ObjectComboBox.

         Returns:
            the selected item of the ObjectComboBox.

public void insertItemAt(Object item, int index)

Inserts an item at the specified position into the ObjectComboBox. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            item- the item to be inserted.
            index - the position at which the item should be inserted.

public void insertItemAt(Object item, String name , int index)

Inserts an item with specified display name at the specified position into the ObjectComboBox. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            item- the item to be inserted.
            name- the display name of the item.
            index - the position at which the item should be inserted.

public boolean isAutoIncreasing()

Gets the flag which indicates whether or not the ObjectComboBox can increase items at run time.

         Returns:
            the auto-increasing state of the ObjectComboBox.

public boolean isCaseSensitive()

Gets the flag indicating whether or not the search is case-sensitive.

         Returns:
            the case-sensitive state of the ObjectComboBox.

public boolean isEditable()

Gets the flag indicating whether or not the ObjectComboBox is editable.

         Returns:
            the editable state of the ObjectComboBox.

public boolean isEnabled()

Gets the flag indicating whether or not the ObjectComboBox is enabled.

         Returns:
            the enable state of the ObjectComboBox.

public boolean isInstantSearch()

Gets the flag indicating whether or not to search through the list instantly.

         Returns:
            the instant state of the search.

public boolean isSearchable()

Gets the flag indicating whether or not the ObjectComboBox is searchable.

         Returns:
            the searchable state of the ObjectComboBox.

public ObjectComboBox()

Constructor for ObjectComboBox. Constructs an ObjectComboBox with default settings.

public void removeAllItems()

Removes all the items from the ObjectComboBox.

public void removeComboBoxListListener(ComboBoxListListener l)

Removes the specified list listener so that it will no longer receive the list messages from the ObjectComboBox.

         Parameters:
            l- the list state listener.

public void removeItem(Object item)

Removes an item from the ObjectComboBox.

         Parameters:
            item- the item to be removed from the ObjectComboBox.

public void removeItemAt(int index)

Removes an item at the specified index from the ObjectComboBox.

         Parameters:
            index - the position at which the item should be removed.

public void removeTextListListener(TextListener l)

Removes the specified text listener so that it will no longer receive the text messages from ObjectComboBox.

         Parameters:
            l- the text state listener.

public void replaceItemAt(Object item, int index)

Replaces an old item with a new one at the specified position in the ObjectComboBox. If the same item already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            item- the new item which is going to replace the old one.
            index - the position at which the item should be replaced.

public void replaceItemAt(Object item, String name , int index)

Replaces an old item with a new one at the specified position in the ObjectComboBox. If the same item or display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            item- the new item which is going to replace the old one.
            name- the display name of the item.
            index - the position at which the item should be replaced.

public void select(int index)

Selects an item at the specified position in the ObjectComboBox.

         Parameters:
            index- the index of the item to be selected from the ObjectComboBox.

public void select(Object item)

Selects an item in the ObjectComboBox.

         Parameters:
            item- the item to be selected from the ObjectComboBox.

public void setAutoIncreasing(boolean b)

Sets the specified boolean to indicate whether or not the ObjectComboBox can increase string items at run time. If the ObjectComboBox isn't editable, this property doesn't work.

         Parameters:
            b- the auto-increasing state flag.

public void setCaseSensitive(boolean b)

Sets the specified boolean to indicate whether or not the search is case-sensitive.

         Parameters:
            b- the case-sensitive state flag.

public void setDisplayName(String name, Object item)

Sets the item's name displayed in list of the ObjectComboBox. If the display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            name- the display name of the item.
            item- the item whose display name is to be changed.
 
public void setDisplayNameAt(String name, int index)

Sets the item's name displayed in the list of the ObjectComboBox. If the same display name already exists in the ObjectComboBox, the ObjectComboBox ignores the latter.

         Parameters:

            name- the display name of the item.
            index- the index of the item whose display name is to be changed.

public void setEditable(boolean b)

Sets the specified boolean to indicate whether or not the ObjectComboBox is editable.

         Parameters:
            b- the editable state flag.

public void setEnabled(boolean b)

Sets the specified boolean to indicate whether or not the ObjectComboBox is enabled.

         Parameters:
            b- the enable state flag.

public void setFont(java.awt.Font font)

Sets the font of the ObjectComboBox. Note: the ObjectComboBox size changes according to the font size.

         Parameters:

           font- the font of the ObjectComboBox.

public void setInstantSearch(boolean b)

Sets the specified boolean to indicate whether or not search through the list instantly. It only works when the ObjectComboBox’s searchable property is set to true. Soon after the user types any character in run time, the instant search mode can instantly search through the items in the list and find which item matches the text entered. The part of the string which matches those characters entered will be display normally, but the additional part of the string will be highlighted, so it can't affect your further typing.

         Parameters:

            b- the instant state flag.

public void setItems(Object[ ] items)

Sets the items of the ObjectComboBox.

         Parameters:

            items- the specified items

public void setListItems(String[ ] data)

Sets the string array of items in the list of the component (commonly an array of strings is used for the convenience of users, but if other kinds of object are desired, just call setItems() or addItem() ).

         Parameters:
            data- the specified string array of items.

public void setMaxListRows(int rows)

Sets the maximum number of rows in the list of the ObjectComboBox ( if the value is zero, the list cannot be dropped down; if the value is negative, rows is set to default value).

         Parameters:
           rows- the maximum number of rows in the list of the ObjectComboBox.

public void setSearchable(boolean b)

Sets the specified boolean to indicate whether or not the ObjectComboBox is searchable. If the ObjectComboBox isn't editable, this property doesn't work. Search process falls to two kinds: normal search and instant search. Normal search works when searchable property is set to true and instantSearch property is set to false. Once the user presses the drop-down button, the search process happens. If there is a item in the list matches the text entered, the content in the text field is then highlighted.

         Parameters:

            b- the searchable state flag.

public void setSelectedIndex(int index)

Sets the selected item index of the ObjectComboBox.

         Parameters:
           index- the selected item's index of the ObjectComboBox.


up

Alphabetic Reference to Events

The ObjectComboBoxBean fires the following events:

  1. ComboBoxListEvent.
  2. PropertyChangeEvent for conveying any changes in the bound property status.

As Source

  1. public class ComboBoxListEvent
  2. extends java.util.EventObject

    This event is fired when a ObjectComboBox list's state is changed. The event has four types : ADD_ITEM, REMOVE_ITEM, SELECT_ITEM and VALUE_CHANGE.

    Note: when an item is added to the list, the value returned by getType() is ADD_ITEM; when an item is removed from the list, the value returned by getType() is REMOVE_ITEM; when an item is selected in the list, the value returned by getType() is SELECT_ITEM; when an item is changed, the value retruned by getType() is VALUE_CHANGE. When all items are added to or removed from the list, getIndex() returns ALL_ITEMS.

                 The event type indicator for "add_item".

                 The event type indicator for "remove_item".

                 The event type indicator for "select_item".

                 The event type indicator for "value_change".

                  Gets the event type value(0--ADD , 1--REMOVE, 2--SELECT, 3--VALUE_CHANGE).

                           Returns:
                              the event type value.

                  Gets the index of item (when all items are added to or removed from the the ObjectComboBox,             returns ALL_ITEMS).

                           Returns:
                              the index of item.

  3. public interface ComboBoxListListener
  4. extends java.util.EventListener

    Event listener interface for ComboBoxListEvent. The methods contained in this interface are:


up

Support Classes

None.


up

See Also

Java Programming Language

Java Beans Specifications


This document is last updated in v1.0 on 04/06/1998