jcombobox.java

gcc的组建

   * Sets editor for this JComboBox
   *
   * @param newEditor ComboBoxEditor for this JComboBox. This method fires
   *        PropertyChangeEvent when 'editor' property is changed.
   */
  public void setEditor(ComboBoxEditor newEditor)
  {
    if (editor == newEditor)
      return;

    if (editor != null)
      editor.removeActionListener(this);

    ComboBoxEditor oldEditor = editor;
    editor = newEditor;

    if (editor != null)
      editor.addActionListener(this);

    firePropertyChange("editor", oldEditor, editor);
  }

  /**
   * Returns editor component that is responsible for displaying/editing
   * selected item in the combo box.
   *
   * @return ComboBoxEditor
   */
  public ComboBoxEditor getEditor()
  {
    return editor;
  }

  /**
   * Forces combo box to select given item
   *
   * @param item element in the combo box to select.
   */
  public void setSelectedItem(Object item)
  {
    dataModel.setSelectedItem(item);
  }

  /**
   * Returns currently selected item in the combo box.
   * The result may be <code>null</code> to indicate that nothing is
   * currently selected.
   *
   * @return element that is currently selected in this combo box.
   */
  public Object getSelectedItem()
  {
    return dataModel.getSelectedItem();
  }

  /**
   * Forces JComboBox to select component located in the given index in the
   * combo box.
   * <p>If the index is below -1 or exceeds the upper bound an
   * <code>IllegalArgumentException</code> is thrown.<p/>
   * <p>If the index is -1 then no item gets selected.</p>
   *
   * @param index index specifying location of the component that  should be
   *        selected.
   */
  public void setSelectedIndex(int index)
  {
  	if (index < -1 || index >= dataModel.getSize())
      // Fails because index is out of bounds.
      throw new IllegalArgumentException("illegal index: " + index);
    else
       // Selects the item at the given index or clears the selection if the
       // index value is -1.
      setSelectedItem((index == -1) ? null : dataModel.getElementAt(index));
  }

  /**
   * Returns index of the item that is currently selected in the combo box. If
   * no item is currently selected, then -1 is returned.
   * <p>
   * Note: For performance reasons you should minimize invocation of this
   * method. If the data model is not an instance of
   * <code>DefaultComboBoxModel</code> the complexity is O(n) where n is the
   * number of elements in the combo box.
   * </p>
   * 
   * @return int Index specifying location of the currently selected item in the
   *         combo box or -1 if nothing is selected in the combo box.
   */
  public int getSelectedIndex()
  {
    Object selectedItem = getSelectedItem();

    if (selectedItem != null)
      {
        if (dataModel instanceof DefaultComboBoxModel)
          // Uses special method of DefaultComboBoxModel to retrieve the index.
          return ((DefaultComboBoxModel) dataModel).getIndexOf(selectedItem);
        else
          {
            // Iterates over all items to retrieve the index.
            int size = dataModel.getSize();

            for (int i = 0; i < size; i++)
              {
                Object o = dataModel.getElementAt(i);

                // XXX: Is special handling of ComparableS neccessary?
                if ((selectedItem != null) ? selectedItem.equals(o) : o == null)
                  return i;
              }
          }
      }

    // returns that no item is currently selected
    return -1;
  }

  /**
   * Returns an object that is used as the display value when calculating the 
   * preferred size for the combo box.  This value is, of course, never 
   * displayed anywhere.
   * 
   * @return The prototype display value (possibly <code>null</code>).
   * 
   * @since 1.4
   * @see #setPrototypeDisplayValue(Object)
   */
  public Object getPrototypeDisplayValue()
  {
    return prototypeDisplayValue;
  }

  /**
   * Sets the object that is assumed to be the displayed item when calculating
   * the preferred size for the combo box.  A {@link PropertyChangeEvent} (with
   * the name <code>prototypeDisplayValue</code>) is sent to all registered 
   * listeners. 
   * 
   * @param value  the new value (<code>null</code> permitted).
   * 
   * @since 1.4
   * @see #getPrototypeDisplayValue()
   */
  public void setPrototypeDisplayValue(Object value)
  {
    Object oldValue = prototypeDisplayValue;
    prototypeDisplayValue = value;
    firePropertyChange("prototypeDisplayValue", oldValue, value);
  }

  /**
   * This method adds given element to this JComboBox.
   * <p>A <code>RuntimeException</code> is thrown if the data model is not
   * an instance of {@link MutableComboBoxModel}.</p>
   *
   * @param element element to add
   */
  public void addItem(Object element)
  {
  	if (dataModel instanceof MutableComboBoxModel)
      ((MutableComboBoxModel) dataModel).addElement(element);
    else
      throw new RuntimeException("Unable to add the item because the data "
                                 + "model it is not an instance of "
                                 + "MutableComboBoxModel.");
  }

  /**
   * Inserts given element at the specified index to this JComboBox.
   * <p>A <code>RuntimeException</code> is thrown if the data model is not
   * an instance of {@link MutableComboBoxModel}.</p>
   *
   * @param element element to insert
   * @param index position where to insert the element
   */
  public void insertItemAt(Object element, int index)
  {
	if (dataModel instanceof MutableComboBoxModel)
      ((MutableComboBoxModel) dataModel).insertElementAt(element, index);
    else
      throw new RuntimeException("Unable to insert the item because the data "
                                 + "model it is not an instance of "
                                 + "MutableComboBoxModel.");
  }

  /**
   * This method removes given element from this JComboBox.
   * <p>A <code>RuntimeException</code> is thrown if the data model is not
   * an instance of {@link MutableComboBoxModel}.</p>
   *
   * @param element element to remove
   */
  public void removeItem(Object element)
  {
	if (dataModel instanceof MutableComboBoxModel)
      ((MutableComboBoxModel) dataModel).removeElement(element);
    else
      throw new RuntimeException("Unable to remove the item because the data "
                                 + "model it is not an instance of "
                                 + "MutableComboBoxModel.");
  }

  /**
   * This method remove element location in the specified index in the
   * JComboBox.
   * <p>A <code>RuntimeException</code> is thrown if the data model is not
   * an instance of {@link MutableComboBoxModel}.</p>
   *
   * @param index index specifying position of the element to remove
   */
  public void removeItemAt(int index)
  {
    if (dataModel instanceof MutableComboBoxModel)
      ((MutableComboBoxModel) dataModel).removeElementAt(index);
    else
      throw new RuntimeException("Unable to remove the item because the data "
                                 + "model it is not an instance of "
                                 + "MutableComboBoxModel.");
  }

  /**
   * This method removes all elements from this JComboBox.
   * <p>
   * A <code>RuntimeException</code> is thrown if the data model is not an
   * instance of {@link MutableComboBoxModel}.
   * </p>
   */
  public void removeAllItems()
  {
    if (dataModel instanceof DefaultComboBoxModel)
      // Uses special method if we have a DefaultComboBoxModel.
      ((DefaultComboBoxModel) dataModel).removeAllElements();
    else if (dataModel instanceof MutableComboBoxModel)
      {
        // Iterates over all items and removes each.
        MutableComboBoxModel mcbm = (MutableComboBoxModel) dataModel;

         // We intentionally remove the items backwards to support models which
         // shift their content to the beginning (e.g. linked lists)
        for (int i = mcbm.getSize() - 1; i >= 0; i--)
          mcbm.removeElementAt(i);
      }
    else
      throw new RuntimeException("Unable to remove the items because the data "
                                 +"model it is not an instance of "
                                 + "MutableComboBoxModel.");
  }

  /**
   * This method displays popup with list of combo box's items on the screen
   */
  public void showPopup()
  {
    setPopupVisible(true);
  }

  /**
   * This method hides popup containing list of combo box's items
   */
  public void hidePopup()
  {
    setPopupVisible(false);
  }

  /**
   * This method either displayes or hides the popup containing  list of combo
   * box's items.
   *
   * @param visible show popup if 'visible' is true and hide it otherwise
   */
  public void setPopupVisible(boolean visible)
  {
    getUI().setPopupVisible(this, visible);
  }

  /**
   * Checks if popup is currently visible on the screen.
   *
   * @return boolean true if popup is visible and false otherwise
   */
  public boolean isPopupVisible()
  {
    return getUI().isPopupVisible(this);
  }

  /**
   * This method sets actionCommand to the specified string. ActionEvent fired
   * to this JComboBox  registered ActionListeners will contain this
   * actionCommand.
   *
   * @param aCommand new action command for the JComboBox's ActionEvent
   */
  public void setActionCommand(String aCommand)
  {
    actionCommand = aCommand;
  }

  /**
   * Returns actionCommand associated with the ActionEvent fired by the
   * JComboBox to its registered ActionListeners.
   *
   * @return String actionCommand for the ActionEvent
   */
  public String getActionCommand()
  {
    return actionCommand;
  }

  /**
   * setAction
   *
   * @param a action to set
   */
  public void setAction(Action a)
  {
    Action old = action;
    action = a;
    configurePropertiesFromAction(action);
    if (action != null)
      // FIXME: remove from old action and add to new action 
      // PropertyChangeListener to listen to changes in the action
      addActionListener(action);
  }

  /**
   * This method returns Action that is invoked when selected item is changed
   * in the JComboBox.
   *
   * @return Action
   */
  public Action getAction()
  {
    return action;
  }

  /**
   * Configure properties of the JComboBox by reading properties of specified
   * action. This method always sets the comboBox's "enabled" property to the
   * value of the Action's "enabled" property.
   *
   * @param a An Action to configure the combo box from
   */
  protected void configurePropertiesFromAction(Action a)
  {
    if (a == null)
      {
        setEnabled(true);
        setToolTipText(null);
      }
    else
      {
        setEnabled(a.isEnabled());
        setToolTipText((String) (a.getValue(Action.SHORT_DESCRIPTION)));
      }
  }

  /**
   * Creates PropertyChangeListener to listen for the changes in comboBox's
   * action properties.
   *
   * @param action action to listen to for property changes
   *
   * @return a PropertyChangeListener that listens to changes in
   *         action properties.
   */
  protected PropertyChangeListener createActionPropertyChangeListener(Action action)
  {
    return new PropertyChangeListener()
      {
        public void propertyChange(PropertyChangeEvent e)
        {
          Action act = (Action) (e.getSource());
          configurePropertiesFromAction(act);
        }
      };
  }

  /**
   * This method fires ItemEvent to this JComboBox's registered ItemListeners.
   * This method is invoked when currently selected item in this combo box
   * has changed.
   *
   * @param e the ItemEvent describing the change in the combo box's
   *        selection.
   */
  protected void fireItemStateChanged(ItemEvent e)
  {
    ItemListener[] ll = getItemListeners();

    for (int i = 0; i < ll.length; i++)
      ll[i].itemStateChanged(e);
  }

  /**
   * This method fires ActionEvent to this JComboBox's registered
   * ActionListeners. This method is invoked when user explicitly changes
   * currently selected item.
   */
  protected void fireActionEvent()
  {
    ActionListener[] ll = getActionListeners();

    for (int i = 0; i < ll.length; i++)
      ll[i].actionPerformed(new ActionEvent(this,
                                            ActionEvent.ACTION_PERFORMED,
                                            actionCommand));
  }

  /**
   * Fires a popupMenuCanceled() event to all <code>PopupMenuListeners</code>.
   *
   * Note: This method is intended for use by plaf classes only.
   */
  public void firePopupMenuCanceled()
  {
    PopupMenuListener[] listeners = getPopupMenuListeners();
    PopupMenuEvent e = new PopupMenuEvent(this);
    for(int i = 0; i < listeners.length; i++)
      listeners[i].popupMenuCanceled(e);
  }

  /**
   * Fires a popupMenuWillBecomeInvisible() event to all 
   * <code>PopupMenuListeners</code>.
   *
   * Note: This method is intended for use by plaf classes only.
   */
  public void firePopupMenuWillBecomeInvisible()
  {
    PopupMenuListener[] listeners = getPopupMenuListeners();