Home Button
Contents
Swing Logo

Swinging Duke
Feedback Button
Left ArrowRight Arrow

 

Swing Combo Box Controls

The Swing component set provides two classes for creating and managing combo boxes: the JComboBox class and the JChoice class.

Both of these classes are available in this release.

The JComboBox class implements a generic combo box with the following features:

In the interest of backwards compatibility, JChoice uses exactly the same API as AWT's Choice class, even though JChoice is a subclass of JComboBox.

The JComboBox Data Model

JComboBox uses a specific data model: ComboBoxDataModel

ComboBoxDataModel extends ListDataModel and adds two methods:

   void setCurrentValue(Object anObject) 
    Object getCurrentValue()

ComboBox's current value is the value that has been selected among possible values. The reason it is added in the data model is that an editable JComboBox can have a current value that is not recognized as a possible value.

JComboBox UI

      JComboBox's UI is a subclass of ComponentUI that should implement the following methods:

   /** This method is called when the maximum number of rows is changing **/ 
    void maximumRowCountChanged();
    /** This method is called when the editable property changes **/ 
    void editablePropertyChanged();
    /** This method is called when the enabled property changes **/ 
    void enablePropertyChanged();
    /** This method request the UI to show the popup **/ 
    void showPopup();
    /** This method request the UI to hide the popup **/ 
    void hidePopup();

    JComboBox UI  leverages JComboBox and ComboBoxDataModel events to update.

The JComboBox API

The JComboBox class definition follows:

public class JComboBox extends JComponent  {

    /*
     * Create a JComboBox that takes its values from an existing ComboBoxDataModel
     */
    public JComboBox(ComboBoxDataModel aModel);

    /*
     * Create a JComboBox. The new JComboBox will create a default data model.
     * The default data model is an empty list of object. Use addPossibleValue to add some
     * values in the list of possible values
     */
    public JComboBox();
 
    /*
     * Set the UI that should be used by the receiving JComboBox
     */
    public void setUI(ComboBoxUI ui);

    /**
     * Overridden from JComponent to change the UI according to the default factory
     */
    public void updateUI();

    /*
     * Return the UI currently used by the receiving JComboBox
     */
    public ComboBoxUI getUI();

    /*
     * Set the data model that the receiving JComboBox uses.
     */
    public void setModel(ComboBoxDataModel aModel);

    /*
     * Return the model currently used by the receiving JComboBox
     */
    public ComboBoxDataModel getModel();

    /*
     * Set whether the receiving JComboBox is editable. An editable JComboBox will
     * allow the user to edit its current value. It will use the editor to display
     * the current value. A non editable JComboBox will use the renderer to display its
     * current value. 
     */
    public void setEditable(boolean aFlag);

    /*
     * Return whether the receiving JComboBox is editable
     */
    public boolean isEditable();

    /*
     * Set the maximum number of rows the receiving JComboBox should allow.
     * If the number of object in the model is greater than count,
     * the combo box will start to use a scrollbar.
     */
    public void setMaximumRowCount(int count);

    /*
     * Return the maximum number of rows the receiving combo box should allow 
     * before using a scrollbar
     */
    public int getMaximumRowCount();

    /*
     * Set the renderer that should be used to display objects in the list 
     * of possible values. The default renderer displays some strings and
     * will call Object.toString()
     */
    public void setRenderer(Renderer aRenderer);

    /*
     * Return the renderer used to display objects in the list of possible values
     */
    public Renderer getRenderer();

    /*
     * This method is called before a renderer is painted. If you use a custom
     * renderer, override this method to configure it.
     */
    public void configureCurrentValueRenderer(Renderer aRenderer,Object aValue);

    /*
     * Set the editor that should be used to display and edit the current value
     * The editor is used only if the receiving JComboBox is editable. If not editable,
     * the combo box will use the renderer to draw the current value
     */
    public void setEditor(ComboBoxEditor anEditor);

    /*
     * Return the editor that should be used to display and edit the current value
     */
    public ComboBoxEditor getEditor();

    /*
     * The value is called just before starting an editing session. Override this
     * method if you use a custom editor and you need to change some of it states
     * just before editing
     */
    public void configureCurrentValueEditor(ComboBoxEditor anEditor,Object aValue);

    /** Set the receiving JComboBox currentValue. If anObject is in the list of possible values,
     *  the list will display anObject selected
     */
    public void setCurrentValue(Object anObject);

    /*
     * Return the current value
     */
    public Object getCurrentValue();

    /*
     * Convenience to make the object at index anIndex in the list of possible
     * values the current value.
     */
    public void setCurrentValueFromIndex(int anIndex);

    /*
     * Convenience to return the index of the current value. This convenience is not always
     * defined if the receiving JComboBox box allows values that are not in the possible values list.
     * Return -1 if the receiving JComboBox has no current value or if the current value is not
     * in the list of possible values
     */
    public int getCurrentValueIndex();

    /** Add a value in the list of possible values.
     * This method works only if the receiving JComboBox uses the default JComboBox data model.
     * JComboBox uses the default JComboBox data model when created with the empty constructor
     * and no other model has been set.
     */
    public void addPossibleValue(Object anObject);

    /** Insert a possible value at a given index 
     */
    public void insertPossibleValue(Object anObject, int index);
                                                                 
    /** Remove a value in the list of possible values.
     * This method works only if the receiving JComboBox uses the default JComboBox data model.
     * JComboBox uses the default JComboBox data model when created with the empty constructor
     * and no other model has been set.
     */
    public void removePossibleValue(Object anObject);

    /** Remove the possible value given an index **/
    public void removePossibleValueAt(int anIndex);

    /** Convenience to remove all possible values
     * This method works only if the receiving JComboBox uses the default JComboBox data model.
     * JComboBox uses the default JComboBox data model when created with the empty constructor
     * and no other model has been set.
     */
    public void removeAllPossibleValues();

    /** Add an ItemListener. aListener will receive an event when
     *  the current value changes
     */
    public void addItemListener(ItemListener aListener);
    
    /** Remove an ItemListener **/
    public void removeItemListener(ItemListener aListener);

    /** Set the KeySelectionManager. The KeySelectionManager is the object responsible for
      * changing the selection when the popup is open and the user press a key. The default 
      * implementation will select the next available row starting with the pressed character.
      */
    public void setKeySelectionManager(KeySelectionManager aManager);

    /** Return the KeySelectionManager for this combo box **/
    public KeySelectionManager getKeySelectionManager();

    /** Convenience to access the model. Return the number of possible values **/
    public int getPossibleValuesCount() {
        return dataModel.getSize();
    }

    /** Convenience to access the model. Return the possible value at index anIndex **/
    public Object getPossibleValueAt(int index) {
        return dataModel.getElementAt(index);
    }

Arrows


Version 0.4. Last modified 09/04/97.
Copyright © 1995-97 Sun Microsystems, Inc. All Rights Reserved.

Sun's Home Page