    001package org.vishia.gral.ifc;
    002
    003import java.util.List;
    004
    005import org.vishia.util.TreeNode_ifc;
    006
    007
    008/**Interface to a table widget.
    009 * @author hartmut
    010 *
    011 * @param <UserData> Type of the data which is associated with a table line.
    012 */
    013public interface GralTable_ifc<UserData> extends GralWidget_ifc
    014{
    015  /**Version, history and license.
    016   * <ul>
    017   * <li>2013-09-15 Hartmut new: Definition of {@link #setBackColor(GralColor, int)} parallel to the
    018   *   {@link GralWidget_ifc#getBackColor(int)} with special comments for usage of the int parameter.
    019   *   See {@link #kAllLines}, {@link #kEmptyArea}. Adequate {@link #getBackColor(int)}.
    020   * <li>2013-09-05 Hartmut chg: {@link #getMarkedLines(int)} now has that 1 argument for mark mask.
    021   * <li>2013-06-11 Hartmut new Now the {@link GralTable}, the {@link GralTable.TableLineData} and this
    022   *   interface are marked with the generic type UserData.
    023   * <li>2012-08-22 Hartmut new {@link #setCurrentLine(int)} with int, it isn't new because it was able to set with
    024   *   {@link #setCurrentCell(int, int)} with -1 as second parameter.
    025   * <ul>2011-11-20 Hartmut new {@link #getMarkedLines()}
    026   * <li>2011-10-01 Hartmut new: {@link #clearTable()}
    027   * <li>2011-09-03 Hartmut chg: method {@link #insertLine(String, int)} returns now the instance of {@link GralTableLine_ifc}
    028   *   The user doesn't create a line instance, an extra factory isn't necessary. The implementing instance
    029   *   can be determined by the implementer of this interface.
    030   * <li>2011-05-11 Hartmut new: creation. Tables are a relevant medium to present GUIs. The implementation of tables
    031   *   in SWT or swing are strong different. It needs a simple interface to work with tables.
    032   * </ul>
    033   *
    034   * <b>Copyright/Copyleft</b>:<br>
    035   * For this source the LGPL Lesser General Public License,
    036   * published by the Free Software Foundation is valid.
    037   * It means:
    038   * <ol>
    039   * <li> You can use this source without any restriction for any desired purpose.
    040   * <li> You can redistribute copies of this source to everybody.
    041   * <li> Every user of this source, also the user of redistribute copies
    042   *    with or without payment, must accept this license for further using.
    043   * <li> But the LPGL is not appropriate for a whole software product,
    044   *    if this source is only a part of them. It means, the user
    045   *    must publish this part of source,
    046   *    but doesn't need to publish the whole source of the own product.
    047   * <li> You can study and modify (improve) this source
    048   *    for own using or for redistribution, but you have to license the
    049   *    modified sources likewise under this LGPL Lesser General Public License.
    050   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
    051   * </ol>
    052   * If you intent to use this source without publishing its usage, you can get
    053   * a second license subscribing a special contract with the author.
    054   *
    055   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
    056   */
    057  public static final int version = 20130528;
    058
    059
    060  /**Identify number for some methods which have a line number parameter.
    061   * Execute for all lines and the empty area.
    062   */
    063  public static final int kAllLines = -1;
    064
    065  /**Identify number for some methods which have a line number parameter.
    066   * Execute only for the empty area (not existing lines)
    067   */
    068  public static final int kEmptyArea = -2;
    069
    070  /**Sets the background color of the table or one line.
    071   * @param ix >=0 sets for one line only,
    072   *   {@link #kAllLines}: Sets for all lines and the table background,
    073   *   {@link #kEmptyArea}: Only for table background.
    074   * @see org.vishia.gral.ifc.GralWidget_ifc#setBackColor(org.vishia.gral.ifc.GralColor, int)
    075   */
    076  @Override void setBackColor(GralColor color, int ix);
    077
    078
    079  @Override GralColor getBackColor(int ix);
    080
    081
    082  /**Returns the currently selected line or null if nothing is selected. */
    083  public abstract GralTableLine_ifc<UserData> getCurrentLine();
    084
    085
    086  /**Sets the line which is the current one. The current row is unchanged.
    087   * @param key The key of the line, given by {@link #insertLine(String, int, String[], Object)}.
    088   * @return true if found.
    089   */
    090  boolean setCurrentLine(String key);
    091
    092  /**Sets the line which is the current one. The current row is unchanged.
    093   * @param line from 0 for the first (top) line
    094   *   A number greater than the number of lines, especially Integer.MAX_VALUE selects the last line.
    095   *   The value -1 let the current line in the table unchanged.
    096   * @return true if found.
    097   */
    098  //boolean setCurrentLine(int line);
    099
    100  /**Sets the cell which is the current one in the given line.
    101   * @param line The line which should be selected.
    102   * @param ixline the index in the visible are of table where the line should be present.
    103   *   If the index is negative, it is the index from end of visible area. -1 means the last line.
    104   *   if the index is outside of the area, it will be set inside.
    105   * @param ixcolumn from 0 for the left column, if -1 then let the current row of table unchanged.
    106   */
    107  void setCurrentLine(GralTableLine_ifc<UserData> line, int ixline, int ixcolumn);
    108  //boolean setCurrentCell(int line, int column);
    109
    110  /**Returns the line at row.
    111   * @param row 0 is the first row. Must not be negative.
    112   * @return null if the row isn't exists.
    113   */
    114  //public abstract GralTableLine_ifc<UserData> getLine(int row);
    115
    116  /**Get the line which is designated with the requested key.
    117   * Background: The lines of a table can be sorted in view. To get a line
    118   * which is sorted in another row a originally set a key is necessary.
    119   * The table data model contains a sorted map with keys and the associated lines.
    120   * The keys can, but may not shown as user visible data.
    121   * @param key The key to find out the row.
    122   * @return null if such line isn't found.
    123   */
    124  public abstract GralTableLine_ifc<UserData> getLine(String key);
    125
    126  /**Inserts a line in the table.
    127   * @param key The key to get it.
    128   * @param row The row where the line should be inserted before. 0 - insert on top.
    129   *        Integer.MAXINT or number greater as number of rows: append on end.
    130   * @return instance to add info.
    131   */
    132  //public abstract GralTableLine_ifc insertLine(String key, int row);
    133
    134
    135  /**Inserts a line in the table with given content.
    136   * @param key The key to get it.
    137   * @param row The row where the line should be inserted before. 0 - insert on top.
    138   *        negative or Integer.MAXINT or number greater as number of rows: append on end.
    139   * @param cellTexts texts of the cells. May be null.
    140   * @param userData data assigned to the line, able to get with {@link GralTableLine_ifc#getUserData()}.
    141   * @return instance to add info.
    142   * @see {@link GralTableLine_ifc} to add content.
    143   */
    144  public abstract GralTableLine_ifc<UserData> insertLine(String key, int row, String[] cellTexts, UserData userData);
    145
    146  /**Inserts a line in the table with given content.
    147   * @param key The key to get it.
    148   * @param cellTexts texts of the cells. May be null.
    149   * @param userData data assigned to the line, maybe null, able to get with {@link GralTableLine_ifc#getUserData()}.
    150   * @return instance to add info.
    151   * @see {@link GralTableLine_ifc} to add content.
    152   */
    153  public abstract GralTableLine_ifc<UserData> addLine(String key, String[] cellTexts, UserData userData);
    154
    155
    156
    157  /**Deletes a line in the table.
    158   *
    159   */
    160  public abstract void deleteLine(  GralTableLine_ifc<UserData> line);
    161
    162
    163  /**Replaces the key associated to the given line.
    164   * It replaces the key stored in the line data and additional the map key-line
    165   * in the table's key-line-index {@link #idxLine}.
    166   * @param line The line, not a new line, an existing one.
    167   * @param keyNew The new key for this line.
    168   */
    169  //public void replaceLineKey(GralTableLine_ifc<UserData> line, String keyNew);
    170
    171  /**Returns the number of active lines of the table.
    172   * @return
    173   */
    174  int size();
    175
    176  public abstract void clearTable();
    177
    178
    179  /**Search where this line is shown.
    180   * @param key
    181   * @return -1 if the key isn't found in the table. 0... row where this line is shown in table.
    182   */
    183  //public abstract int searchLine(String key);
    184
    185
    186
    187  /**Returns all marked lines. It returns an empty list if no line is marked.
    188   */
    189  List<GralTableLine_ifc<UserData>> getMarkedLines(int mask);
    190
    191
    192  /**Returns all lines. Note: This returns the original container of lines without backup.
    193   * It means the list will be changed if any {@link #insertLine(String, int, String[], Object)}
    194   * or {@link #deleteLine(GralTableLine_ifc)} will be called. Do not call any modification of this list
    195   * for example {@link java.util.List#add(Object)} or {@link java.util.List#remove(int)}, use the methods
    196   * of this interface to change the content of the table. Elsewhere the graphical presentation of the data
    197   * may be corrupted.
    198   *
    199   * See {@link #getListContent()}.
    200   */
    201  TreeNode_ifc<?, UserData> getAllLines();
    202
    203  /**Returns all content of lines. This makes a snapshot of the lines in calling time. If the table
    204   * will be changed in another thread while this routine runs, a {@link java.util.ConcurrentModificationException}
    205   * will be thrown. But after them the list is able to use independently.
    206   */
    207  List<UserData> getListContent();
    208
    209
    210  /**Returns the first line from top of the table which is marked or null if no line is marked.   */
    211  GralTableLine_ifc<UserData> getFirstMarkedLine(int mask);
    212
    213
    214
    215
    216
    217}