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}