Home » openjdk-7 » javax » swing » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package javax.swing;
   27   
   28   import java.util.EventObject;
   29   import javax.swing.event;
   30   
   31   /**
   32    * This interface defines the methods any general editor should be able
   33    * to implement. <p>
   34    *
   35    * Having this interface enables complex components (the client of the
   36    * editor) such as <code>JTree</code> and
   37    * <code>JTable</code> to allow any generic editor to
   38    * edit values in a table cell, or tree cell, etc.  Without this generic
   39    * editor interface, <code>JTable</code> would have to know about specific editors,
   40    * such as <code>JTextField</code>, <code>JCheckBox</code>, <code>JComboBox</code>,
   41    * etc.  In addition, without this interface, clients of editors such as
   42    * <code>JTable</code> would not be able
   43    * to work with any editors developed in the future by the user
   44    * or a 3rd party ISV. <p>
   45    *
   46    * To use this interface, a developer creating a new editor can have the
   47    * new component implement the interface.  Or the developer can
   48    * choose a wrapper based approach and provide a companion object which
   49    * implements the <code>CellEditor</code> interface (See
   50    * <code>JCellEditor</code> for example).  The wrapper approach
   51    * is particularly useful if the user want to use a 3rd party ISV
   52    * editor with <code>JTable</code>, but the ISV didn't implement the
   53    * <code>CellEditor</code> interface.  The user can simply create an object
   54    * that contains an instance of the 3rd party editor object and "translate"
   55    * the <code>CellEditor</code> API into the 3rd party editor's API.
   56    *
   57    * @see javax.swing.event.CellEditorListener
   58    *
   59    * @author Alan Chung
   60    */
   61   public interface CellEditor {
   62   
   63       /**
   64        * Returns the value contained in the editor.
   65        * @return the value contained in the editor
   66        */
   67       public Object getCellEditorValue();
   68   
   69       /**
   70        * Asks the editor if it can start editing using <code>anEvent</code>.
   71        * <code>anEvent</code> is in the invoking component coordinate system.
   72        * The editor can not assume the Component returned by
   73        * <code>getCellEditorComponent</code> is installed.  This method
   74        * is intended for the use of client to avoid the cost of setting up
   75        * and installing the editor component if editing is not possible.
   76        * If editing can be started this method returns true.
   77        *
   78        * @param   anEvent         the event the editor should use to consider
   79        *                          whether to begin editing or not
   80        * @return  true if editing can be started
   81        * @see #shouldSelectCell
   82        */
   83       public boolean isCellEditable(EventObject anEvent);
   84   
   85       /**
   86        * Returns true if the editing cell should be selected, false otherwise.
   87        * Typically, the return value is true, because is most cases the editing
   88        * cell should be selected.  However, it is useful to return false to
   89        * keep the selection from changing for some types of edits.
   90        * eg. A table that contains a column of check boxes, the user might
   91        * want to be able to change those checkboxes without altering the
   92        * selection.  (See Netscape Communicator for just such an example)
   93        * Of course, it is up to the client of the editor to use the return
   94        * value, but it doesn't need to if it doesn't want to.
   95        *
   96        * @param   anEvent         the event the editor should use to start
   97        *                          editing
   98        * @return  true if the editor would like the editing cell to be selected;
   99        *    otherwise returns false
  100        * @see #isCellEditable
  101        */
  102       public boolean shouldSelectCell(EventObject anEvent);
  103   
  104       /**
  105        * Tells the editor to stop editing and accept any partially edited
  106        * value as the value of the editor.  The editor returns false if
  107        * editing was not stopped; this is useful for editors that validate
  108        * and can not accept invalid entries.
  109        *
  110        * @return  true if editing was stopped; false otherwise
  111        */
  112       public boolean stopCellEditing();
  113   
  114       /**
  115        * Tells the editor to cancel editing and not accept any partially
  116        * edited value.
  117        */
  118       public void cancelCellEditing();
  119   
  120       /**
  121        * Adds a listener to the list that's notified when the editor
  122        * stops, or cancels editing.
  123        *
  124        * @param   l               the CellEditorListener
  125        */
  126       public void addCellEditorListener(CellEditorListener l);
  127   
  128       /**
  129        * Removes a listener from the list that's notified
  130        *
  131        * @param   l               the CellEditorListener
  132        */
  133       public void removeCellEditorListener(CellEditorListener l);
  134   }

Home » openjdk-7 » javax » swing » [javadoc | source]