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.ItsNatListUI;
017: import javax.swing.ListModel;
018:
019: /**
020: * Is the base interface of list based components.
021: *
022: * <p>A generic list component manages a <code>javax.swing.ListModel</code>
023: * data list, item values are rendered as markup using a special object, the renderer,
024: * and may be optionally edited "in place" using a user defined editor.</p>
025: *
026: * <p>Any change to the data model is notified to the component and the markup
027: * is rendered again. The data model ever mandates over the markup, any initial markup content (initial child elements) is removed.</p>
028: *
029: * <p>This component family is the "componentized" version of {@link org.itsnat.core.domutil.ElementList} and
030: * follows a similar philosophy.</p>
031: *
032: * @author Jose Maria Arranz Santamaria
033: */
034: public interface ItsNatList extends ItsNatElementComponent {
035: /**
036: * Returns the user interface manager of this component.
037: *
038: * @return the user interface manager.
039: */
040: public ItsNatListUI getItsNatListUI();
041:
042: /**
043: * Returns the current data model of this component.
044: *
045: * @return the current data model
046: * @see #setListModel(javax.swing.ListModel)
047: */
048: public ListModel getListModel();
049:
050: /**
051: * Changes the data model of this component.
052: *
053: * <p>Current data model is disconnected from this component, and the new
054: * data model is bound to this component, every change is tracked and
055: * updates the user interfaces accordingly.</p>
056: *
057: * <p>If the specified data model is the same instance as the current data model,
058: * then is reset, component listener is removed and added again. Use this technique if
059: * you want to add a data model listener to be executed <i>before</i> the default component listener.
060: *
061: * @param dataModel the new data model.
062: * @see #getListModel()
063: */
064: public void setListModel(ListModel dataModel);
065:
066: /**
067: * Creates a data model instance appropriated to this component. This instance
068: * is not bound to the component.
069: *
070: * @return a new data model instance.
071: */
072: public ListModel createDefaultListModel();
073:
074: /**
075: * Returns the index of the first selected list item. If the component
076: * allows multiple selection returns the first one.
077: *
078: * @return index of the first selected list item. -1 if none is selected.
079: */
080: public int getSelectedIndex();
081:
082: /**
083: * Selects the specified list item. If this component allows multiple selection,
084: * the current selection is cleared before.
085: *
086: * @param index the index of the item to select
087: */
088: public void setSelectedIndex(int index);
089:
090: /**
091: * Returns the zero based position in the list of the specified value.
092: * If the value is repeated returns the first position.
093: *
094: * @param obj the object value to search.
095: * @return the zero based position of the value, -1 if not in the list.
096: */
097: public int indexOf(Object obj);
098:
099: /**
100: * Returns the component structure.
101: *
102: * @return the component structure.
103: */
104: public ItsNatListStructure getItsNatListStructure();
105:
106: /**
107: * Returns the current component renderer. This renderer converts a list item value to markup.
108: *
109: * @return the current renderer. By default uses the default renderer ({@link ItsNatComponentManager#createDefaultItsNatListCellRenderer()})
110: * @see #setItsNatListCellRenderer(ItsNatListCellRenderer)
111: */
112: public ItsNatListCellRenderer getItsNatListCellRenderer();
113:
114: /**
115: * Sets the component renderer.
116: *
117: * @param renderer the new renderer.
118: * @see #getItsNatListCellRenderer()
119: */
120: public void setItsNatListCellRenderer(
121: ItsNatListCellRenderer renderer);
122:
123: /**
124: * Returns the current list item editor. This object is used to edit in place
125: * a list item value.
126: *
127: * @return the current editor. By default uses the default editor
128: * calling ({@link ItsNatComponentManager#createDefaultItsNatListCellEditor(ItsNatComponent)}) with a null parameter.
129: * @see #setItsNatListCellEditor(ItsNatListCellEditor)
130: */
131: public ItsNatListCellEditor getItsNatListCellEditor();
132:
133: /**
134: * Sets the list item editor.
135: *
136: * <p>List item edition works very much the same as label edition
137: * (see {@link ItsNatLabel#setItsNatLabelEditor(ItsNatLabelEditor)}).</p>
138: *
139: * <p>Some differences:</p>
140: *
141: * <p>The edition process starts programmatically by calling {@link #startEditingAt(int)}.</p>
142: *
143: * <p>The edition takes place inside the list item <i>content</i> element
144: * as returned by {@link ItsNatListStructure#getContentElement(ItsNatList,int,org.w3c.dom.Element)}.</p>
145: *
146: * <p>The new item value is set to the data model
147: * calling <code>javax.swing.DefaultListModel.setElementAt(Object,int)</code>,
148: * if the data model is not <code>DefaultListModel</code> is the programmer responsibility
149: * to set the new value to the data model (detecting when the editor stops editing,
150: * see <code>javax.swing.CellEditor.addCellEditorListener(javax.swing.event.CellEditorListener)</code>).
151: * </p>
152: *
153: * @param editor the new editor. May be null (edition disabled).
154: * @see #getItsNatListCellEditor()
155: */
156: public void setItsNatListCellEditor(ItsNatListCellEditor editor);
157:
158: /**
159: * Used to start programmatically a list item edition process "in place".
160: *
161: * @see #isEditing()
162: */
163: public void startEditingAt(int index);
164:
165: /**
166: * Informs whether a list item value is being edited.
167: *
168: * @return true if a list item value is being edited.
169: *
170: * @see #startEditingAt(int)
171: */
172: public boolean isEditing();
173:
174: /**
175: * Returns the index of the list item being edited.
176: *
177: * @return the index of the list item being edited. -1 if none is being edited.
178: */
179: public int getEditingIndex();
180:
181: /**
182: * Returns the event type used to activate the list item edition process by the user.
183: *
184: * @return the event type used to activate the edition. By default is "dblclick".
185: * @see #setEditorActivatorEvent(String)
186: */
187: public String getEditorActivatorEvent();
188:
189: /**
190: * Sets the event type used to activate the list item edition process by the user.
191: *
192: * @param eventType the event type used to activate the edition.
193: * @see #getEditorActivatorEvent()
194: */
195: public void setEditorActivatorEvent(String eventType);
196: }
|