package nxm.sys.inc;

import nxm.sys.lib.Table;

/** This is the public API for nxm.sys.libg MJList that is used by <code>LIST2</code>.

    @author  J. Czechowski IV
    @version $Id: ListInterface.java,v 1.15 2014/10/21 18:29:58 ntn Exp $
    @since   NeXtMidas 2.5.0
 */
public interface ListInterface {
  /** The available selection modes ({@value}). See {@link #setSelectMode} and {@link #getSelectMode} for details.
      @since NeXtMidas 2.5.5
   */
  String selectModeList = "Single,SingleInterval,MultipleInterval";

  /** The available options for {@link #selectRow(long, String)} and {@link #selectRowByColVal(String, String, String)}
      MSG    means send a message back to the macro <br>
      CLEAR  means clear out any existing selections
      IGNORECASE means ignore case when selecting by value (Since 3.1.0)
   */
  String selectList = "MSG,CLEAR,IGNORECASE";   // default

  /** Sets the message handler used. This is typically the <code>LIST2</code> primitive (i.e.
      <code>list2.java</code>). Change this only with extreme care!
      @param msgHandler The message handler.
      @since NeXtMidas 2.5.0
   */
  void setMessageHandler (MessageHandler msgHandler);

  /** Gets the message handler used.
      @since NeXtMidas 2.5.0
      @return the message handler in use.
   */
  MessageHandler getMessageHandler ();

  /** Gets the names of the visible column as a comma-separated list in the order that they
      are displayed on the screen.
      @return the names of the visible columns as a comma-separated list in the order that they
      are displayed on the screen.
      @since NeXtMidas 2.5.0
   */
  String getColumnOrder ();

  /** Gets the names of the columns in the file. This returns the official names of the columns
      not the column labels set in the template.
      @since NeXtMidas 2.5.0
      @return names of columns set in the template.
   */
  String[] getColumnNames ();

  /** Gets the row offset. Returns 0 for 0-based row numbers, 1 for 1-based row numbers, etc.
      @since NeXtMidas 2.5.0
      @return value of the row offset.
   */
  long getRowOffset ();

  /** Gets the col offset. Returns 0 for 0-based col numbers, 1 for 1-based col numbers, etc. This
      is not used nearly as much as {@link #getRowOffset()} since most columns are accessed by name.
      @return value of the color offset.
   */
  long getColOffset ();

  /** Adds a row to the end of the file.
      @param data The data for the row.
   */
  void addRow (Table data);

  /** Adds a row.
      @param row  The row number to insert at (-1 to insert at end of file).
      @param data The data for the row.
   */
  void addRow (long row, Table data);

  /** Adds rows to the table.
     @param row  The row number to insert at (-1 to insert at end of file).
     @param rows The table of rows to insert.
   */
  void addRows (long row, Table[] rows);

  /** Adds rows to the table.
      @param rows The table of rows to insert.
   */
  void addRows (Table[] rows);

  /** Adds rows to the table. Rows are ordered as they appear in the Table.
      @param rows The table of rows to insert. Each row is a table of col values.
   */
  void addRows (Table rows);

  /** Gets all rows from the file.
   *  @return a table of all rows from the file.
   */

  Table getAllRows ();

  /** Gets all of the selected rows as a table where the key is the row number and the value is all
      of the data in that row.
      @return a table of all selected rows.
   */
  Table getAllSelectedRows ();

  /** Gets the current file being listed.
   *  @return the current file being listed
   */
  ListFile getListFile ();

  /** Gets the number of rows in the file.
      @return the number of rows in the file.
   */
  long getNumberOfRows ();

  /** Gets a row from the file.
      @param row The row number.
      @return the row at the indicated index
   */
  Table getRow (long row);

  /** Gets a row from the file
      @param row Table containing the key
      @return The row as a Table
      @since NeXtMidas 2.7.3
   */
  Table getRow (Table row);

  /** Gets a copy of the current template. Note that this is only a COPY, any updates to a template
      MUST go through either {@link #setTemplate(Table)} or {@link #updateTemplate(Table)}, any
      changes made to the table returned by this method will be ignored.
      @return a copy of the current template.
   */
  Table getTemplate ();

  /** Polls for new/updated data.
      @param poll If true checks for new data (added to end of file) and changed data in the file.
                  If false checks only for new data.
      @return The number of rows read.
   */
  double pollData (boolean poll);

  /** Removes all rows. */
  void removeAllRows ();

  /** Removes a row. This is the same as removeRows(row,row).
      @param row The row number to remove.
   */
  void removeRow (long row);

  /** Removes a row. This is the same as removeRows(row,row).
      @param data The row to remove
      @since NeXtMidas 2.7.3
   */
  void removeRow (Table data);

  /** Removes a set of rows.
      @param rowNumbers A list of row numbers (usually passed in as a {@link java.util.Vector}).
      @since NeXtMidas 2.3.0
   */
  void removeRows (java.util.List<?> rowNumbers);

  /** Removes a set of rows.
      @param rowNumbers A list of row numbers (e.g. "1,13,47,5").
      @since NeXtMidas 2.3.0
   */
  void removeRows (String rowNumbers);

  /** Removes a set of rows.
      @param start The first row to remove (inclusive).
      @param end   The last row to remove (inclusive).
   */
  void removeRows (long start, long end);

  /** Sets the value of a cell.
      @param row The row number.
      @param col The column name.
      @param val The value.
   */
  void setCell (long row, String col, Object val);

  /** This method is for backwards compatibility with LIST / GridSheet from macro language.
      Consider this method deprecated since it's initial version in NeXtMidas 2.1.0, instead use
      {@link #setCell(long,String,Object)}.
      @param tbl Table with key/values for "ROW"/long, "COLUMN"/String or "COL"/String, and "VALUE"/Object.
   */
  void setCell (Table tbl);

  /** Sets the current file. This is the same as using setListFile(listFile,false).
      @param listFile The file.
   */
  void setListFile (ListFile listFile);

  /** Sets the current file.
      @param listFile The file.
      @param readOnly If this is set no further attempt will be made to open the file in INOUT mode.
                      (Note: This does not remove the INOUT or OUTPUT flag if it is already set in
                      listFile, nor does it force a file to be INOUT if readOnly=false.) Setting
                      this to false says that this method can try to reopen the file as INOUT if
                      the file looks like it can be opened as INOUT.
   */
  void setListFile (ListFile listFile, boolean readOnly);

  /** Enables or disables sorting.
      @param enabled If this is false all sorting is disabled.
      @see #setSort(String)
   */
  void setSortingEnabled (boolean enabled);

  /** Indicates if sorting is enabled.
      @return true if enable, false if not.
   */
  boolean getSortingEnabled ();

  /** Sorts the data by column name.  This is an in-memory sort, not be used for
      large files.
      @param column  The name of the column to sort by prefixed by a '+' for ASCENDING or a
                     '-' for DESCENDING. Use a null string or "" to disable sorting.
      @see #setSortingEnabled(boolean)
   */
  void setSort (String column);

  /** Sorts the data file (this sorts the underlying file, not just the view). Keys are listed in
      order of weight and may have an optional '+' prefix for ascending sort or '-' for descending
      sort (if neither '+' or '-' is specified than ascending sort is assumed).
      @param keys The keys to sort by (e.g. "+FREQ|-AMP" or "FREQ,AMP").
   */
  void sortData (String keys);

  /** Sorts the data file (this sorts the underlying file, not just the view). Keys are listed in
      order of weight and may have an optional '+' prefix for ascending sort or '-' for descending
      sort (if neither '+' or '-' is specified than ascending sort is assumed).
      @param keys The keys to sort by.
   */
  void sortData (String[] keys);

  /** Sets the active template, any previous template settings will be discarded.
      @param template The template.
   */
  void setTemplate (Table template);

  /** Trigger a redraw of a row or rows.
      @param row The row to redraw
      @since NeXtMidas 2.9.1
   */
  void redraw (long row);

  /** Trigger a redraw of a row or rows.
      @param startRow First row to redraw
      @param endRow Last row to redraw
      @since NeXtMidas 2.9.1
   */
  void redraw (long startRow, long endRow);

  /** Sets all the values in a row. Values not included in the <code>data</code> will be set to
      <code>0</code> or <code>""</code> (depending on type).
      @param row  The row number.
      @param data The data for the row.
      @see #updateRow(long,Table)
   */
  void setRow (long row, Table data);

  /** Sets all the values in a row. Values not included in the <code>data</code> will be set to
      <code>0</code> or <code>""</code> (depending on type). <br>
      <br>
      The row to be updated will be specified in the <code>data</code> via a "primary key" (see
      {@link #updateRow(Table)} for details).
      @param data The data for the row.
      @see #setRow(long,Table)
      @see #updateRow(Table)
      @since NeXtMidas 2.5.0
   */
  void setRow (Table data);

  /** Updates values in a row. Values not included in the <code>data</code> will remain unchanged.
      @param row  The row number.
      @param data The data for the row.
      @see #setRow(long,Table)
      @see #updateRow(Table)
      @since NeXtMidas 2.5.0
   */
  void updateRow (long row, Table data);

  /** Updates values in a row. Values not included in the <code>data</code> will remain unchanged.<br>
      <br>
      The row to be updated will be specified in the <code>data</code> via a "primary key." If
      {@link #getPrimaryKey()} is null the table will need to have a <code>ROW=</code> entry,
      otherwise the table will need to have a key that matches the primary key given by
      {@link #getPrimaryKey()}.
      @param data The data for the row.
      @see #updateRow(long,Table)
      @see #updateRows(Table[])
      @since NeXtMidas 2.5.0
   */
  void updateRow (Table data);

  /** Updates values in a set of rows. This just calls {@link #updateRow(Table)} for each of the
      entries in the array.
      @param rows The data for the rows.
      @see #updateRow(Table)
      @since NeXtMidas 2.5.0
   */
  void updateRows (Table[] rows);

  /** Updates the current template by adding additional (or overriding) entries. Any previous
      template settings will be kept (if not overridden).
      @param template The template.
   */
  void updateTemplate (Table template);

  /** Sets the primary key for the table. This key is used with {@link #updateRow(Table)}, and
      the values in this column should not have any duplicates.
      @param key The new primary key (or null to disable).
   */
  void setPrimaryKey (String key);

  /** Gets the primary key for the table or null if not used.
      @return the primary key for the table if set, null if not.
   */
  String getPrimaryKey ();

  /** Select a row by row number clearing any existing selections. This is the same as
      <code>selectRow(row,true)</code>.
      @param row The row number to select.
      @throws IllegalArgumentException when row number is less than 0
   */
  void selectRow (long row) throws IllegalArgumentException;

  /** Select a row by row number. Whether the number is zero or one-based depends on the base
      index given when this list was constructed (see {@link #getRowOffset()}).
      @param row                   The row number to select.
      @param clearCurrentSelection Should the current selection be cleared first?
      @throws IllegalArgumentException when row number is less than 0
   */
  void selectRow (long row, boolean clearCurrentSelection) throws IllegalArgumentException;

  /** Select a row by a column value
      @param column The name of the column
      @param value The data to be matched
      @param ignoreCase Ignore case in comparison
   */
  void selectRow (String column, String value, boolean ignoreCase);

  /** Select a row by a column value
      @param column The name of the column
      @param value The data to be matched
      @param flags Mask of Selection Options (see {@link #selectList})
      @since NeXtMidas 3.1.0
   */
  void selectRowByColVal (String column, String value, String flags);

  /** Select a row by row number.
      @param row The row number
      @param flags Mask of Selection Options (see {@link #selectList})
      @since NeXtMidas 2.8.1
      @throws IllegalArgumentException when row number is less than 0
   */
  void selectRow (long row, String flags) throws IllegalArgumentException;

  /** Makes a given cell visible.
      @param row    The cell row.
      @param column The cell column.
   */
  void showCell (long row, long column);

  /** Clears the current selection. */
  void clearSelection ();

  /** Sets the selection mode.
      @param mode One of {@link javax.swing.ListSelectionModel#SINGLE_SELECTION},
                         {@link javax.swing.ListSelectionModel#SINGLE_INTERVAL_SELECTION}, or
                         {@link javax.swing.ListSelectionModel#MULTIPLE_INTERVAL_SELECTION}.
      @since NeXtMidas 2.5.5
      @see javax.swing.JTable#setSelectionMode(int)
   */
  void setSelectionMode (int mode);

  /** Gets the selection mode.
      @return One of {@link javax.swing.ListSelectionModel#SINGLE_SELECTION},
                     {@link javax.swing.ListSelectionModel#SINGLE_INTERVAL_SELECTION}, or
                     {@link javax.swing.ListSelectionModel#MULTIPLE_INTERVAL_SELECTION}.
      @since NeXtMidas 2.5.5
      @see javax.swing.JTable#setSelectionMode(int)
   */
  int getSelectionMode ();

  /** Sets the selection mode.
      @param mode One of the entries in {@link #selectModeList}.
      @since NeXtMidas 2.5.5
      @see javax.swing.JTable#setSelectionMode(int)
   */
  void setSelectMode (String mode);

  /** Gets the selection mode.
      @return One of the entries in {@link #selectModeList}.
      @since NeXtMidas 2.5.5
      @see javax.swing.JTable#setSelectionMode(int)
   */
  String getSelectMode ();


  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param modelIndex the row index as viewed by JTable.
      @return the row index into the data file (always 0-based).
   */
  long getRealRowIndex(int modelIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param realIndex the row index into the data file (always 0-based).
      @return the row index as viewed by JTable.
   */
  int  getModelRowIndex(long realIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param viewIndex the column index as viewed on the display.
      @return the column index as viewed by JTable.
   */
  int  getModelColIndex(int viewIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param modelIndex the column index as viewed by JTable.
      @return the column index into the data file (always 0-based).
   */
  long getRealColIndex(int modelIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param realIndex the column index into the data file (always 0-based).
      @return the column index  as viewed by JTable.
   */
  int  getModelColIndex(long realIndex);

/** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param viewIndex the column index as viewed on the display.
      @return the column index as viewed on the display.
   */
  int  getViewColIndex(int viewIndex);


  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param fileIndex the row index into the data file (always 0-based).
      @return the row index as used by the NeXtMidas macro.
   */
  long getMacroRowIndex(long fileIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param macroIndex the row index as used by the NeXtMidas macro.
      @return the row index into the data file (always 0-based).
   */
  long getRealRowIndex(long macroIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param fileIndex the column index into the data file (always 0-based).
      @return the column index as used by the NeXtMidas macro.
   */
  long getMacroColIndex(long fileIndex);

  /** See "Indexing" at top of nxm.sys.libg LargeJTable
      @param macroIndex the column index as used by the NeXtMidas macro.
      @return the column index into the data file (always 0-based).
   */
  long getRealColIndex(long macroIndex);
}
