1. /*
  2. * @(#)CellEditor.java 1.24 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.swing;
  8. import java.util.EventObject;
  9. import javax.swing.event.*;
  10. /**
  11. * This interface defines the methods any general editor should be able
  12. * to implement. <p>
  13. *
  14. * Having this interface enables complex components (the client of the
  15. * editor) such as <code>JList</code>, <code>JTree</code>, and
  16. * <code>JTable</code> to allow any generic editor to
  17. * edit values in a table cell, or tree cell, etc. Without this generic
  18. * editor interface, <code>JTable</code> would have to know about specific editors,
  19. * such as <code>JTextField</code>, <code>JCheckBox</code>, <code>JComboBox</code>,
  20. * etc. In addition, without this interface, clients of editors such as
  21. * <code>JTable</code> would not be able
  22. * to work with any editors developed in the future by the user
  23. * or a 3rd party ISV. <p>
  24. *
  25. * To use this interface, a developer creating a new editor can have the
  26. * new component implement the interface. Or the developer can
  27. * choose a wrapper based approach and provide a companion object which
  28. * implements the <code>CellEditor</code> interface (See
  29. * <code>JCellEditor</code> for example). The wrapper approach
  30. * is particularly useful if the user want to use a 3rd party ISV
  31. * editor with <code>JTable</code>, but the ISV didn't implement the
  32. * <code>CellEditor</code> interface. The user can simply create an object
  33. * that contains an instance of the 3rd party editor object and "translate"
  34. * the <code>CellEditor</code> API into the 3rd party editor's API.
  35. *
  36. * @see javax.swing.event.CellEditorListener
  37. *
  38. * @version 1.24 12/19/03
  39. * @author Alan Chung
  40. */
  41. public interface CellEditor {
  42. /**
  43. * Returns the value contained in the editor.
  44. * @return the value contained in the editor
  45. */
  46. public Object getCellEditorValue();
  47. /**
  48. * Asks the editor if it can start editing using <code>anEvent</code>.
  49. * <code>anEvent</code> is in the invoking component coordinate system.
  50. * The editor can not assume the Component returned by
  51. * <code>getCellEditorComponent</code> is installed. This method
  52. * is intended for the use of client to avoid the cost of setting up
  53. * and installing the editor component if editing is not possible.
  54. * If editing can be started this method returns true.
  55. *
  56. * @param anEvent the event the editor should use to consider
  57. * whether to begin editing or not
  58. * @return true if editing can be started
  59. * @see #shouldSelectCell
  60. */
  61. public boolean isCellEditable(EventObject anEvent);
  62. /**
  63. * Returns true if the editing cell should be selected, false otherwise.
  64. * Typically, the return value is true, because is most cases the editing
  65. * cell should be selected. However, it is useful to return false to
  66. * keep the selection from changing for some types of edits.
  67. * eg. A table that contains a column of check boxes, the user might
  68. * want to be able to change those checkboxes without altering the
  69. * selection. (See Netscape Communicator for just such an example)
  70. * Of course, it is up to the client of the editor to use the return
  71. * value, but it doesn't need to if it doesn't want to.
  72. *
  73. * @param anEvent the event the editor should use to start
  74. * editing
  75. * @return true if the editor would like the editing cell to be selected;
  76. * otherwise returns false
  77. * @see #isCellEditable
  78. */
  79. public boolean shouldSelectCell(EventObject anEvent);
  80. /**
  81. * Tells the editor to stop editing and accept any partially edited
  82. * value as the value of the editor. The editor returns false if
  83. * editing was not stopped; this is useful for editors that validate
  84. * and can not accept invalid entries.
  85. *
  86. * @return true if editing was stopped; false otherwise
  87. */
  88. public boolean stopCellEditing();
  89. /**
  90. * Tells the editor to cancel editing and not accept any partially
  91. * edited value.
  92. */
  93. public void cancelCellEditing();
  94. /**
  95. * Adds a listener to the list that's notified when the editor
  96. * stops, or cancels editing.
  97. *
  98. * @param l the CellEditorListener
  99. */
  100. public void addCellEditorListener(CellEditorListener l);
  101. /**
  102. * Removes a listener from the list that's notified
  103. *
  104. * @param l the CellEditorListener
  105. */
  106. public void removeCellEditorListener(CellEditorListener l);
  107. }