001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.comp;
015:
016: import org.itsnat.comp.ui.ItsNatTableUI;
017: import javax.swing.ListSelectionModel;
018: import javax.swing.table.TableModel;
019:
020: /**
021: * Is the base interface of table based components.
022: *
023: * <p>A table component manages a <code>javax.swing.table.TableModel</code>
024: * data model, table cell values are rendered as markup using a special object, the renderer,
025: * and may be optionally edited "in place" using a user defined editor.</p>
026: *
027: * <p>Any change to the data model is notified to the component and the markup
028: * is rendered again. The data model ever mandates over the markup,
029: * any initial markup content (initial rows) is removed.</p>
030: *
031: * <p>Almost a row with a cell must be present in the markup, this row and cell are used as patterns
032: * to create new table rows/cells, and is removed because by default the data model is empty.</p>
033: *
034: * <p>This component family uses two <code>javax.swing.ListSelectionModel</code> selection models,
035: * one for columns, another for rows, to keep track of selection states.
036: * When a cell is selected (usually by clicking it) the selection
037: * state is updated accordingly using both selection models (notifying to registered listeners).
038: *
039: * <p>ItsNat tables support all selection modes that Swing JTable supports,
040: * as in JTable {@link #setRowSelectionAllowed(boolean)} and {@link #setColumnSelectionAllowed(boolean)}
041: * control whether the complete row and column are selected when a cell is selected.</p>
042: *
043: * <p>There is no default decoration of table cell selection,
044: * selection model listeners may be used to decorate the table markup when its
045: * selection state changes.</p>
046: *
047: * <p>By default this component uses the default renderer and editor and
048: * a <code>javax.swing.table.DefaultTableModel</code> data model.</p>
049: *
050: * <p>Row and column indexes start in 0.</p>
051: *
052: * <p>This component family is the "componentized" version of {@link org.itsnat.core.domutil.ElementTable} and
053: * follows a similar philosophy (note the component version provides table header support).</p>
054: *
055: * @author Jose Maria Arranz Santamaria
056: */
057: public interface ItsNatTable extends ItsNatElementComponent {
058: /**
059: * Returns the current data model of this component.
060: *
061: * @return the current data model
062: * @see #setTableModel(javax.swing.table.TableModel)
063: */
064: public TableModel getTableModel();
065:
066: /**
067: * Changes the data model of this component.
068: *
069: * <p>Current data model is disconnected from this component, and the new
070: * data model is bound to this component, every change is tracked and
071: * updates the user interfaces accordingly.</p>
072: *
073: * <p>If the specified data model is the same instance as the current data model,
074: * then is reset, component listener is removed and added again. Use this technique if
075: * you want to add a data model listener to be executed <i>before</i> the default component listener.
076: *
077: * @param dataModel the new data model.
078: */
079: public void setTableModel(TableModel dataModel);
080:
081: /**
082: * Returns the table header sub-component.
083: *
084: * @return the table header. Null if this table does not have a header.
085: */
086: public ItsNatTableHeader getItsNatTableHeader();
087:
088: /**
089: * Returns the user interface manager of this component.
090: *
091: * @return the user interface manager.
092: */
093: public ItsNatTableUI getItsNatTableUI();
094:
095: /**
096: * Creates a data model instance appropriated to this component. This instance
097: * is not bound to the component.
098: *
099: * @return a new data model instance.
100: */
101: public TableModel createDefaultTableModel();
102:
103: /**
104: * Returns the current row selection model.
105: *
106: * @return the current row selection model. By default a <code>javax.swing.DefaultListSelectionModel</code> instance.
107: * @see #setRowSelectionModel(javax.swing.ListSelectionModel)
108: */
109: public ListSelectionModel getRowSelectionModel();
110:
111: /**
112: * Sets the new row selection model.
113: *
114: * <p>If the new selection model is the current defined then is "reset",
115: * component listener is removed and added again. Use this technique if
116: * you want to add a listener to be executed <i>before</i> the default component listener.
117: *
118: * @param selectionModel the new row selection model.
119: * @see #getRowSelectionModel()
120: */
121: public void setRowSelectionModel(ListSelectionModel selectionModel);
122:
123: /**
124: * Returns the current column selection model.
125: *
126: * @return the current column selection model. By default a <code>javax.swing.DefaultListSelectionModel</code> instance.
127: * @see #setColumnSelectionModel(javax.swing.ListSelectionModel)
128: */
129: public ListSelectionModel getColumnSelectionModel();
130:
131: /**
132: * Sets the new column selection model.
133: *
134: * <p>If the new selection model is the current defined then is "reset",
135: * component listener is removed and added again. Use this technique if
136: * you want to add a listener to be executed <i>before</i> the default component listener.
137: *
138: * @param selectionModel the new column selection model.
139: * @see #getColumnSelectionModel()
140: */
141: public void setColumnSelectionModel(
142: ListSelectionModel selectionModel);
143:
144: /**
145: * Clears any row or column selection.
146: *
147: * <p>Calls <code>ListSelectionModel.clearSelection()</code> method
148: * of both, row and column, selection models.
149: */
150: public void clearSelection();
151:
152: /**
153: * Sets a new selection mode to the row and column selection models.
154: *
155: * <p>Calls <code>ListSelectionModel.setSelectionMode()</code> method
156: * of both, row and column, selection models. </p>
157: *
158: * @param selectionMode new selection mode value.
159: */
160: public void setSelectionMode(int selectionMode);
161:
162: /**
163: * Informs whether row selection is allowed.
164: *
165: * @return if row selection is allowed, true by default.
166: * @see #setRowSelectionAllowed(boolean)
167: */
168: public boolean isRowSelectionAllowed();
169:
170: /**
171: * Sets whether row selection is allowed.
172: *
173: * @param rowSelectionAllowed true if row selection is allowed.
174: * @see #isRowSelectionAllowed()
175: * @see #isCellSelected(int,int)
176: */
177: public void setRowSelectionAllowed(boolean rowSelectionAllowed);
178:
179: /**
180: * Informs whether column selection is allowed.
181: *
182: * @return if column selection is allowed, true by default.
183: * @see #setColumnSelectionAllowed(boolean)
184: */
185: public boolean isColumnSelectionAllowed();
186:
187: /**
188: * Sets whether column selection is allowed.
189: *
190: * @param columnSelectionAllowed true if column selection is allowed.
191: * @see #isColumnSelectionAllowed()
192: * @see #isCellSelected(int,int)
193: */
194: public void setColumnSelectionAllowed(boolean columnSelectionAllowed);
195:
196: /**
197: * Informs whether cell selection is enabled. A cell may be selected
198: * if row or column (or both) selection is enabled.
199: *
200: * @return if cell selection is enabled. By default is true.
201: * @see #setCellSelectionEnabled(boolean)
202: */
203: public boolean isCellSelectionEnabled();
204:
205: /**
206: * Enables/disables cell selection. If cell selection is enabled
207: * row and column selection are enabled too (if disabled are disabled too).
208: *
209: * @param cellSelectionEnabled true if cell selection is enabled.
210: * @see #isCellSelectionEnabled()
211: */
212: public void setCellSelectionEnabled(boolean cellSelectionEnabled);
213:
214: /**
215: * Informs whether the specified cell is selected.
216: *
217: * <p>A cell is selected if cell selection is enabled ({@link #isCellSelectionEnabled()} returns true)
218: * and row selection OR column selection is enabled (not both) and the cell is
219: * part of a selected row or column. If row selection AND column selection
220: * are enabled the cell is selected only if cell row AND column are selected,
221: * this mode (row and column selection enabled) allows selecting individual cells.</p>
222: *
223: * <p>Summary:</p>
224: * <ul>
225: * <li>To select complete rows: row selection enabled and column disabled.
226: * A single cell selection selects all remaining cells in the row</li>
227: * <li>To select complete columns: column selection enabled and row disabled.</li>
228: * A single cell selection selects all remaining cells in the column</li>
229: * <li>To select individual cells: column and row selection enabled.</li>
230: * </ul>
231: *
232: * @param row row position of the cell.
233: * @param column column position of the cell.
234: * @return true if the specified cell is selected.
235: * @see #isCellSelectionEnabled()
236: */
237: public boolean isCellSelected(int row, int column);
238:
239: /**
240: * Informs whether the specified row contains almost a cell selected.
241: *
242: * <p>This method simply delegates to <code>getRowSelectionModel().isSelectedIndex(row)</code>.</p>
243: *
244: * @param row the row index.
245: * @return true if the specified row is selected.
246: */
247: public boolean isRowSelected(int row);
248:
249: /**
250: * Informs whether the specified column contains almost a cell selected.
251: *
252: * <p>This method simply delegates to <code>getColumnSelectionModel().isSelectedIndex(column)</code>.</p>
253: *
254: * @param column the column index.
255: * @return true if the specified column is selected.
256: */
257: public boolean isColumnSelected(int column);
258:
259: /**
260: * Sets a new row selection interval specifying an index range.
261: *
262: * <p>This method simply delegates to <code>getRowSelectionModel().setSelectionInterval(index0,index1)</code>.</p>
263: *
264: * @param index0 one end of the interval.
265: * @param index1 other end of the interval
266: */
267: public void setRowSelectionInterval(int index0, int index1);
268:
269: /**
270: * Sets a new column selection interval specifying an index range.
271: *
272: * <p>This method simply delegates to <code>getColumnSelectionModel().setSelectionInterval(index0,index1)</code>.</p>
273: *
274: * @param index0 one end of the interval.
275: * @param index1 other end of the interval
276: */
277: public void setColumnSelectionInterval(int index0, int index1);
278:
279: /**
280: * Returns an array with indices of the current selected rows.
281: *
282: * @return an array with the current selected rows.
283: * @see #setSelectedRows(int[])
284: */
285: public int[] getSelectedRows();
286:
287: /**
288: * Sets the current selected rows.
289: *
290: * @param indices index array of the new selected rows.
291: * @see #getSelectedRows()
292: */
293: public void setSelectedRows(int[] indices);
294:
295: /**
296: * Returns an array with indices of the current selected columns.
297: *
298: * @return an array with the current selected columns.
299: * @see #setSelectedColumns(int[])
300: */
301: public int[] getSelectedColumns();
302:
303: /**
304: * Sets the current selected columns.
305: *
306: * @param indices index array of the new selected columns.
307: * @see #getSelectedColumns()
308: */
309: public void setSelectedColumns(int[] indices);
310:
311: /**
312: * Returns the index of the first selected row. If several rows are
313: * selected returns the first one.
314: *
315: * @return index of the first selected row. -1 if none is selected.
316: */
317: public int getSelectedRow();
318:
319: /**
320: * Returns the index of the first selected column. If several columns are
321: * selected returns the first one.
322: *
323: * @return index of the first selected column. -1 if none is selected.
324: */
325: public int getSelectedColumn();
326:
327: /**
328: * Updates the selection models of the table, depending on the state of the
329: * two flags: <code>toggle</code> and <code>extend</code>. Most changes
330: * to the selection are the result of mouse events received
331: * by the UI are channeled through this method.
332: * <p>
333: * This implementation uses the following conventions:
334: * <ul>
335: * <li> <code>toggle</code>: <em>false</em>, <code>extend</code>: <em>false</em>.
336: * Clear the previous selection and ensure the new cell is selected.
337: * This state is used to change the selection by clicking a cell (no shift and ctrl keys held)
338: * <li> <code>toggle</code>: <em>false</em>, <code>extend</code>: <em>true</em>.
339: * Extend the previous selection from the anchor to the specified cell,
340: * clearing all other selections.
341: * This state is used to change the selection by clicking a cell with shift key held.
342: * <li> <code>toggle</code>: <em>true</em>, <code>extend</code>: <em>false</em>.
343: * If the specified cell is selected, deselect it. If it is not selected, select it.
344: * This state is used to change the selection by clicking a cell with ctrl key held.
345: * <li> <code>toggle</code>: <em>true</em>, <code>extend</code>: <em>true</em>.
346: * Leave the selection state as it is, but move the anchor index to the specified location.
347: * This state is used to change the selection by clicking a cell with shift and ctrl keys held.
348: * </ul>
349: *
350: * <p>Note: original documentation (modified) obtained from <code>JTable.changeSelection</code> (Sun JDK 1.5).</p>
351: *
352: * @param rowIndex affects the selection at <code>row</code>
353: * @param columnIndex affects the selection at <code>column</code>
354: * @param toggle see description above
355: * @param extend if true, extend the current selection
356: */
357: public void changeSelection(int rowIndex, int columnIndex,
358: boolean toggle, boolean extend);
359:
360: /**
361: * Selects all cells in the table.
362: */
363: public void selectAll();
364:
365: /**
366: * Returns the component structure.
367: *
368: * @return the component structure.
369: */
370: public ItsNatTableStructure getItsNatTableStructure();
371:
372: /**
373: * Returns the current component renderer. This renderer converts a table cell value to markup.
374: *
375: * @return the current renderer. By default uses the default renderer ({@link ItsNatComponentManager#createDefaultItsNatTableCellRenderer()})
376: * @see #setItsNatTableCellRenderer(ItsNatTableCellRenderer)
377: */
378: public ItsNatTableCellRenderer getItsNatTableCellRenderer();
379:
380: /**
381: * Sets the component renderer.
382: *
383: * @param renderer the new renderer.
384: * @see #getItsNatTableCellRenderer()
385: */
386: public void setItsNatTableCellRenderer(
387: ItsNatTableCellRenderer renderer);
388:
389: /**
390: * Returns the current table cell editor. This object is used to edit in place
391: * a table cell value.
392: *
393: * @return the current editor. By default uses the default editor
394: * calling ({@link ItsNatComponentManager#createDefaultItsNatTableCellEditor(ItsNatComponent)}) with a null parameter.
395: * @see #setItsNatTableCellEditor(ItsNatTableCellEditor)
396: */
397: public ItsNatTableCellEditor getItsNatTableCellEditor();
398:
399: /**
400: * Sets the table cell editor.
401: *
402: * <p>Table cell edition works very much the same as label edition
403: * (see {@link ItsNatLabel#setItsNatLabelEditor(ItsNatLabelEditor)}).</p>
404: *
405: * <p>Some differences:</p>
406: *
407: * <p>The edition process starts programmatically by calling {@link #startEditingAt(int,int)}.</p>
408: *
409: * <p>The edition takes place inside the cell <i>content</i> element
410: * as returned by {@link ItsNatTableStructure#getCellContentElement(ItsNatTable,int,int,org.w3c.dom.Element)}.</p>
411: *
412: * <p>The new cell value is set to the data model
413: * calling <code>javax.swing.table.TableModel.setValueAt(Object,int,int)</code>.</p>
414: *
415: * @param editor the new editor. May be null (edition disabled).
416: * @see #getItsNatTableCellEditor()
417: */
418: public void setItsNatTableCellEditor(ItsNatTableCellEditor editor);
419:
420: /**
421: * Used to start programmatically a table cell edition process "in place".
422: *
423: * @see #isEditing()
424: */
425: public void startEditingAt(int row, int column);
426:
427: /**
428: * Informs whether a table cell value is being edited.
429: *
430: * @return true if a table cell value is being edited.
431: *
432: * @see #startEditingAt(int,int)
433: */
434: public boolean isEditing();
435:
436: /**
437: * Returns the row of the cell being edited.
438: *
439: * @return the row of the cell being edited. -1 if none is being edited.
440: */
441: public int getEditingRow();
442:
443: /**
444: * Returns the column of the cell being edited.
445: *
446: * @return the column of the cell being edited. -1 if none is being edited.
447: */
448: public int getEditingColumn();
449:
450: /**
451: * Returns the event type used to activate the table cell edition process by the user.
452: *
453: * @return the event type used to activate the edition. By default is "dblclick".
454: * @see #setEditorActivatorEvent(String)
455: */
456: public String getEditorActivatorEvent();
457:
458: /**
459: * Sets the event type used to activate the table cell edition process by the user.
460: *
461: * @param eventType the event type used to activate the edition.
462: * @see #getEditorActivatorEvent()
463: */
464: public void setEditorActivatorEvent(String eventType);
465: }
|