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 }