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}