001 package org.springframework.richclient.widget.table;
002
003 import org.springframework.richclient.command.AbstractCommand;
004 import org.springframework.richclient.widget.Widget;
005
006 import javax.swing.*;
007 import javax.swing.event.TableModelListener;
008 import java.util.Collection;
009 import java.util.List;
010 import java.util.Observer;
011
012 /**
013 * TableWidget describes the needed functionality for widgets
014 * that produce tables.
015 *
016 * The TableWidget manages a data-list of objects whose properties
017 * are shown in one or more different columns of the table.
018 *
019 * Some methods of TableWidget (remove, select) assume correct implementation
020 * of {@link java.lang.Object#equals(java.lang.Object)} and
021 * {@link java.lang.Object#hashCode()} for the data-list's objects.
022 */
023 public interface TableWidget<T> extends Widget
024 {
025 /**
026 * Sets the rows to be shown in the table
027 *
028 * @param newRows
029 * The list of row objects
030 */
031 void setRows(Collection<T> newRows);
032
033 /**
034 * Returns the current list of objects behind the table. It does not
035 * take into account local filtering and/or sorting.
036 *
037 * @return List the list with objects
038 * @see #getVisibleRows()
039 */
040 List<T> getRows();
041
042 /**
043 * Returns the current list of objects visible in the table. It takes into
044 * account local filtering and/or sorting.
045 *
046 * @return List the visible rows
047 * @see #getRows()
048 */
049 List<T> getVisibleRows();
050
051 /**
052 * Numbers of rows in the table
053 *
054 * @return
055 */
056 int nrOfRows();
057
058 /**
059 * @return true if the data-list is empty
060 */
061 boolean isEmpty();
062
063 /**
064 * Local addition of a single object to the data-list of the table
065 *
066 * @param newObject
067 * The object to add
068 */
069 void addRowObject(T newObject);
070
071 /**
072 * Local addition of a collection of objects to the data-list of the table
073 *
074 * @param rows
075 * The collection of objects to add
076 */
077 void addRows(Collection<T> rows);
078
079 /**
080 * Local removal of a single object to the data-list of the table
081 *
082 * @param objectToRemove
083 * The object to remove
084 */
085 void removeRowObject(T objectToRemove);
086
087 /**
088 * Selects the row of a given object and notifies the registered selection
089 * observers. The second argument allows 1 observer to be excluded from
090 * the notification (needed if the observer is the caller).
091 *
092 * @param toPointTo
093 * row-object that needs to be selected
094 * @param originatingObserver
095 * Optional observer that doesn't want to be notified of the
096 * selection
097 * @return int index of the object in the shown list
098 *
099 * @see #addSelectionObserver(java.util.Observer)
100 */
101 int selectRowObject(T toPointTo, Observer originatingObserver);
102
103 /**
104 * Selects a row on the given index
105 *
106 * @param index
107 * index of the row that needs to be selected
108 * @param originatingObserver
109 * Optional observer that doesn't want to be notified of the
110 * selection
111 */
112 void selectRowObject(int index, Observer originatingObserver);
113
114 /**
115 * Adds an array of objects to the current selection
116 *
117 * @param rows
118 * Array with row objects
119 * @param originatingObserver
120 * Optional observer that doesn't want to be notified of the
121 * selection
122 */
123 void addSelection(T[] rows, Observer originatingObserver);
124
125 /**
126 * Replaces an object in the table
127 *
128 * @param oldObject
129 * The object to be replaced
130 * @param newObject
131 * The replacing object
132 * @param originatingObserver
133 * Optional observer that doesn't want to be notified of the
134 * replacement
135 */
136 void replaceRowObject(T oldObject, T newObject, Observer originatingObserver);
137
138 /**
139 * Replaces a collection of objects in the table.
140 *
141 * @param oldObject
142 * The collection of objects to be replaced
143 * @param newObject
144 * The replacing collection of objects
145 */
146 void replaceRows(Collection<T> oldObject, Collection<T> newObject);
147
148 /**
149 * Deselects all rows
150 */
151 void unSelectAll();
152
153 /**
154 * @return Array of objects that are currently selected
155 */
156 Object[] getSelectedRows();
157
158 /**
159 * @return true if there is an active selection
160 */
161 boolean hasSelection();
162
163 /**
164 * Registers a listener that will receive events on selection of an object
165 * in the table.
166 *
167 * @see #selectRowObject(Object, Observer)
168 */
169 void addSelectionObserver(Observer observer);
170
171 /**
172 * Removes a selection listener
173 *
174 * @param observer
175 */
176 void removeSelectionObserver(Observer observer);
177
178 /**
179 * Registers a listener for changes made to TableModel
180 *
181 * @param listener
182 */
183 void addTableModelListener(TableModelListener listener);
184
185 /**
186 * Remove the given listener from the TableModel.
187 *
188 * @param listener
189 */
190 void removeTableModelListener(TableModelListener listener);
191
192 /**
193 * Forces a re-read of the data-list for the table
194 */
195 void updateTable();
196
197 /*
198 * VISUAL COMPONENTS & COMMANDS
199 */
200
201 /**
202 * Indices of the navigate-commands in the list
203 * {@link #getNavigationCommands()}.
204 */
205 public static final int NAVIGATE_FIRST = 0;
206 public static final int NAVIGATE_PREVIOUS = 1;
207 public static final int NAVIGATE_NEXT = 2;
208 public static final int NAVIGATE_LAST = 3;
209
210 /**
211 * Id's for the selection commands.
212 */
213 public static final String SELECT_ALL_ID = "select.all";
214 public static final String SELECT_NONE_ID = "select.none";
215 public static final String SELECT_INVERSE_ID = "select.inverse";
216
217 /**
218 * Command Id's for the navigation commands for the table
219 * {@link #getNavigationCommands()}.
220 */
221 public static final String NAVIGATE_LASTROW_CMDID = "lastrow";
222 public static final String NAVIGATE_NEXTROW_CMDID = "nextrow";
223 public static final String NAVIGATE_PREVIOUSROW_CMDID = "previousrow";
224 public static final String NAVIGATE_FIRSTROW_CMDID = "firstrow";
225
226 /**
227 * Spring-RCP commands to navigate through the table
228 *
229 * @see #NAVIGATE_FIRST
230 * @see #NAVIGATE_PREVIOUS
231 * @see #NAVIGATE_NEXT
232 * @see #NAVIGATE_LAST
233 */
234 AbstractCommand[] getNavigationCommands();
235
236 /**
237 * The {@link #getNavigationCommands() navigation-commands} as button bar
238 */
239 JComponent getNavigationButtonBar();
240
241 /**
242 * Buttonbar with three buttons: select all, select none and select inverse
243 */
244 JComponent getSelectButtonBar();
245
246 /**
247 * Combination of the navigation button bar and the selection button bar
248 */
249 JComponent getButtonBar();
250
251 /**
252 * Returns the table, getComponent() does not need to return only table
253 * (a scrollpane can be returned too containing the table), as this method
254 * will enable you to get to the table.
255 *
256 * @return The table
257 * @see Widget#getComponent()
258 */
259 JTable getTable();
260
261 /**
262 * @return A textfield that enables full-text filtering n the contents of the table
263 * or null if this feature is not supported
264 */
265 JTextField getTextFilterField();
266
267 /**
268 * @return A label on which the index, the selected row count and the row count is shown
269 */
270 public JLabel getListSummaryLabel();
271 }