package util.swing;

import javax.swing.table.*;

import java.io.Serializable;

import java.util.Comparator;

/**
  * Strategy that describes how individual records of an {@link util.swing.AbstractTableModel} are to be
  * split up into columns of a table and how the individual cells are to be displayed and edited.
  *
  * <p>You should think of a TableEntryDescriptor as a device that is given a record and splits this
  * record into individual values, that correspond to cells.</p>
  *
  * <p>When implementing this interface, you might want to subclass {@link AbstractTableEntryDescriptor}, that
  * will already give you a head start with some of the more common tasks.</p>
  *
  * @see JAbstractTable
  *
  * @author Steffen Zschaler
  * @version 2.0 27/07/1999
  * @since v2.0
  */
public interface TableEntryDescriptor extends Serializable {

  /**
    * Return the number of columns each record will consist of.
    *
    * @return the number of columns each record will consist of.
    *
    * @override Always
    */
  public int getColumnCount();

  /**
    * Return the text to be printed in the header of the given column.
    *
    * @param nIdx the index of the column for which to return the header. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return the text to be printed in the header of the given column.
    *
    * @override Always
    */
  public String getColumnName (int nIdx);

  /**
    * Return the class of objects that make up the values of cells of the given column. This will be used to
    * determine the cell renderer and editor unless you specify otherwise through {@link #getCellEditor} and
    * {@link #getCellRenderer}.
    *
    * @param nIdx the index of the column for which to return the value class. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return the class of objects that make up the values of cells of the given column.
    *
    * @override Always
    */
  public Class getColumnClass (int nIdx);

  /**
    * Return the cell renderer to be used for cells in the given column.
    *
    * @param nIdx the index of the column for which to return the renderer. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return the cell renderer to be used for cells in the given column. You can return <code>null</code> to
    * indicate that the default cell renderer for the {@link #getColumnClass column class} should be used.
    *
    * @override Always
    */
  public TableCellRenderer getCellRenderer (int nIdx);

  /**
    * Return the cell editor to be used for cells in the given column. This is only effective if
    * {@link #isElementEditable} returns true for the column and a given record.
    *
    * @param nIdx the index of the column for which to return the editor. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return the cell editor to be used for cells in the given column. You can return <code>null</code> to
    * indicate that the default cell editor for the {@link #getColumnClass column class} should be used.
    *
    * @override Always
    */
  public TableCellEditor getCellEditor (int nIdx);

  /**
    * Get the value to be printed in the given column for the given record.
    *
    * @param oRecord the record for which to determine the value. The actual class depends on the
    * {@link util.swing.AbstractTableModel} you are working with. It will be declared in the documentation for
    * the {@link util.swing.AbstractTableModel#getRecord} method of that class.
    * @param nIdx the index of the column for which to return the cell value. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return the value to be printed in the given column for the given record. The actual class must be
    * a subclass of what was returned by {@link #getColumnClass} or that class itself.
    *
    * @override Always
    */
  public Object getValueAt (Object oRecord, int nIdx);

  /**
    * Return whether a given column is editable for a given record.
    *
    * @param oRecord the record for which to determine editability. The actual class depends on the
    * {@link util.swing.AbstractTableModel} you are working with. It will be declared in the documentation for
    * the {@link util.swing.AbstractTableModel#getRecord} method of that class.
    * @param nIdx the index of the column for which to determine editability. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    *
    * @return whether the given column is editable for the given record.
    *
    * @override Always
    */
  public boolean isElementEditable (Object oRecord, int nIdx);

  /**
    * Set the value of the given column for the given record.
    *
    * <p>This method will only be invoked if {@link #isElementEditable} returned true for the given cell and if
    * the user actually edited the given cell.</p>
    *
    * <p>Note that changes will only become visible if they result in an event being fired to the JTable that
    * uses the model.</p>
    *
    * @param oRecord the record for which to determine the value. The actual class depends on the
    * {@link util.swing.AbstractTableModel} you are working with. It will be declared in the documentation for
    * the {@link util.swing.AbstractTableModel#getRecord} method of that class.
    * @param nIdx the index of the column for which to return the cell value. Indices run from 0 to
    * {@link #getColumnCount getColumnCount() - 1}.
    * @param oValue the value to become the new value of the cell. The class of this object depends on the
    * editor used for editing the cell. Normally, this will be determined by {@link #getCellEditor}.
    *
    * @override Always
    */
  public void setValueAt (Object oRecord, int nIdx, Object oValue);
  
  /**
    * Return true if the records can be sorted by the specified column. If true, {@link #getColumnOrder}
    * must return a valid comparator for the specified column.
    *
    * @param nIdx the index of the column concerned.
    *
    * @return whether or not records can be sorted by the specified column.
    *
    * @override Always
    *
    * @since v3.0 12/14/2000
    */
  public boolean canSortByColumn (int nIdx);
    
  /**
    * Return a comparator to be used when ordering records by the specified column. Depending on the
    * specific TableModel, the comparator compares records or elements of records.
    *
    * @param nIdx the index of the column concerned.
    *
    * @override Always
    *
    * @since v3.0 12/14/2000
    */
  public Comparator getColumnOrder (int nIdx);
}