1 /* 2 * Copyright (c) 1997, 2014, 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} and 37 * {@code JTable} 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} would have to know about specific editors, 40 * such as {@code JTextField}, {@code JCheckBox}, {@code JComboBox}, 41 * etc. In addition, without this interface, clients of editors such as 42 * {@code JTable} 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} interface (See 50 * {@code DefaultCellEditor} for example). The wrapper approach 51 * is particularly useful if the user want to use a 3rd party ISV 52 * editor with {@code JTable}, but the ISV didn't implement the 53 * {@code CellEditor} 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} API into the 3rd party editor's API. 56 * 57 * @see javax.swing.event.CellEditorListener 58 * 59 * @author Alan Chung 60 * @since 1.2 61 */ 62 public interface CellEditor { 63 64 /** 65 * Returns the value contained in the editor. 66 * @return the value contained in the editor 67 */ 68 public Object getCellEditorValue(); 69 70 /** 71 * Asks the editor if it can start editing using {@code anEvent}. 72 * {@code anEvent} is in the invoking component coordinate system. 73 * The editor can not assume the Component returned by 74 * {@code getCellEditorComponent} is installed. This method 75 * is intended for the use of client to avoid the cost of setting up 76 * and installing the editor component if editing is not possible. 77 * If editing can be started this method returns true. 78 * 79 * @param anEvent the event the editor should use to consider 80 * whether to begin editing or not 81 * @return true if editing can be started 82 * @see #shouldSelectCell 83 */ 84 public boolean isCellEditable(EventObject anEvent); 85 86 /** 87 * Returns true if the editing cell should be selected, false otherwise. 88 * Typically, the return value is true, because is most cases the editing 89 * cell should be selected. However, it is useful to return false to 90 * keep the selection from changing for some types of edits. 91 * eg. A table that contains a column of check boxes, the user might 92 * want to be able to change those checkboxes without altering the 93 * selection. (See Netscape Communicator for just such an example) 94 * Of course, it is up to the client of the editor to use the return 95 * value, but it doesn't need to if it doesn't want to. 96 * 97 * @param anEvent the event the editor should use to start 98 * editing 99 * @return true if the editor would like the editing cell to be selected; 100 * otherwise returns false 101 * @see #isCellEditable 102 */ 103 public boolean shouldSelectCell(EventObject anEvent); 104 105 /** 106 * Tells the editor to stop editing and accept any partially edited 107 * value as the value of the editor. The editor returns false if 108 * editing was not stopped; this is useful for editors that validate 109 * and can not accept invalid entries. 110 * 111 * @return true if editing was stopped; false otherwise 112 */ 113 public boolean stopCellEditing(); 114 115 /** 116 * Tells the editor to cancel editing and not accept any partially 117 * edited value. 118 */ 119 public void cancelCellEditing(); 120 121 /** 122 * Adds a listener to the list that's notified when the editor 123 * stops, or cancels editing. 124 * 125 * @param l the CellEditorListener 126 */ 127 public void addCellEditorListener(CellEditorListener l); 128 129 /** 130 * Removes a listener from the list that's notified 131 * 132 * @param l the CellEditorListener 133 */ 134 public void removeCellEditorListener(CellEditorListener l); 135 }