001    /*
002     * Created on Jun 8, 2008
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2008-2010 the original author or authors.
015     */
016    package org.fest.swing.cell;
017    
018    import java.awt.Component;
019    
020    import javax.swing.JTable;
021    
022    import org.fest.swing.annotation.RunsInEDT;
023    import org.fest.swing.exception.ActionFailedException;
024    
025    /**
026     * Understands how to edit the value of a cell in a <code>{@link JTable}</code>.
027     *
028     * @author Yvonne Wang
029     * @author Alex Ruiz
030     */
031    @RunsInEDT
032    public interface JTableCellWriter {
033    
034      /**
035       * Enters the given value at the given cell of the <code>{@link JTable}</code>. To edit a cell using this method,
036       * it is not necessary to call <code>{@link #startCellEditing(JTable, int, int)}</code> or
037       * <code>{@link #stopCellEditing(JTable, int, int)}</code>.
038       * @param table the target <code>JTable</code>.
039       * @param row the row index of the cell.
040       * @param column the column index of the cell.
041       * @param value the value to enter.
042       * @throws IllegalStateException if the <code>JTable</code> is disabled.
043       * @throws IllegalStateException if the <code>JTable</code> is not showing on the screen.
044       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
045       * @throws IndexOutOfBoundsException if any of the indices (row and column) is out of bounds.
046       * @throws ActionFailedException if an editor for the given cell cannot be found or cannot be activated.
047       */
048      void enterValue(JTable table, int row, int column, String value);
049    
050      /**
051       * Starts editing the given cell of the <code>{@link JTable}</code>. This method should be called before manipulating
052       * the <code>{@link Component}</code> returned by <code>{@link #editorForCell(JTable, int, int)}</code>.
053       * @param table the target <code>JTable</code>.
054       * @param row the row index of the cell.
055       * @param column the column index of the cell.
056       * @throws IllegalStateException if the <code>JTable</code> is disabled.
057       * @throws IllegalStateException if the <code>JTable</code> is not showing on the screen.
058       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
059       * @throws IndexOutOfBoundsException if any of the indices (row and column) is out of bounds.
060       * @throws ActionFailedException if an editor for the given cell cannot be found or cannot be activated.
061       * @see #editorForCell(JTable, int, int)
062       */
063      void startCellEditing(JTable table, int row, int column);
064    
065      /**
066       * Stops editing the given cell of the <code>{@link JTable}</code>. This method should be called after manipulating
067       * the <code>{@link Component}</code> returned by <code>{@link #editorForCell(JTable, int, int)}</code>.
068       * @param table the target <code>JTable</code>.
069       * @param row the row index of the cell.
070       * @param column the column index of the cell.
071       * @throws IllegalStateException if the <code>JTable</code> is disabled.
072       * @throws IllegalStateException if the <code>JTable</code> is not showing on the screen.
073       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
074       * @throws IndexOutOfBoundsException if any of the indices (row and column) is out of bounds.
075       * @throws ActionFailedException if an editor for the given cell cannot be found or cannot be activated.
076       * @see #editorForCell(JTable, int, int)
077       */
078      void stopCellEditing(JTable table, int row, int column);
079    
080      /**
081       * Cancels editing the given cell of the <code>{@link JTable}</code>. This method should be called after manipulating
082       * the <code>{@link Component}</code> returned by <code>{@link #editorForCell(JTable, int, int)}</code>.
083       * @param table the target <code>JTable</code>.
084       * @param row the row index of the cell.
085       * @param column the column index of the cell.
086       * @throws IllegalStateException if the <code>JTable</code> is disabled.
087       * @throws IllegalStateException if the <code>JTable</code> is not showing on the screen.
088       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
089       * @throws IndexOutOfBoundsException if any of the indices (row and column) is out of bounds.
090       * @throws ActionFailedException if an editor for the given cell cannot be found or cannot be activated.
091       * @see #editorForCell(JTable, int, int)
092       */
093      void cancelCellEditing(JTable table, int row, int column);
094    
095      /**
096       * Returns the <code>{@link Component}</code> used as editor of the given cell. To manipulate the returned
097       * <code>Component</code>, <code>{@link #startCellEditing(JTable, int, int)}</code> should be called first.
098       * <p>
099       * Example:
100       *
101       * <pre>
102       * Component editor = writer.editorForCell(table, 6, 8);
103       * // assume editor is a JTextField
104       * JTextComponentFixture editorFixture = new JTextComponentFixture(robot, (JTextField) editor);
105       * writer.{@link #startCellEditing(JTable, int, int) startCellEditing}(table, 6, 8);
106       * editorFixture.enterText(&quot;Hello&quot;);
107       * writer.{@link #stopCellEditing(JTable, int, int) stopCellEditing}(table, 6, 8);
108       * </pre>
109       *
110       * </p>
111       * @param table the target <code>JTable</code>.
112       * @param row the row index of the cell.
113       * @param column the column index of the cell.
114       * @return the <code>Component</code> used as editor of the given cell.
115       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
116       * @throws IndexOutOfBoundsException if any of the indices (row and column) is out of bounds.
117       * @throws IllegalStateException if the <code>JTable</code> cell is not editable.
118       */
119      Component editorForCell(JTable table, int row, int column);
120    }