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.ui;
015:
016: import org.itsnat.comp.ItsNatList;
017: import org.w3c.dom.Element;
018: import org.w3c.dom.Node;
019:
020: /**
021: * Is the base interface of the User Interface of a list component.
022: *
023: * <p>List items are managed as a DOM element list, using the current list structure
024: * and renderer.</p>
025: *
026: * <p>Current implementation does not use the data model and relays heavily on
027: * {@link org.itsnat.core.domutil.ElementList}.</p>
028: *
029: * <p>Indexes are 0 based.</p>
030: *
031: * @author Jose Maria Arranz Santamaria
032: * @see ItsNatList#getItsNatListUI()
033: * @see ItsNatList#getItsNatListCellRenderer()
034: * @see ItsNatList#getItsNatListStructure()
035: */
036: public interface ItsNatListUI extends ItsNatElementComponentUI {
037: /**
038: * Returns the associated component object.
039: *
040: * @return the component object.
041: */
042: public ItsNatList getItsNatList();
043:
044: /**
045: * Returns the number of child elements.
046: *
047: * @return the number of child elements.
048: * @see org.itsnat.core.domutil.ElementList#getLength()
049: */
050: public int getLength();
051:
052: /**
053: * Increases or shrinks the list to fit the new size.
054: *
055: * <p>If the new size is bigger new elements are added at the end, if the size
056: * is lower tail elements are removed.</p>
057: *
058: * @param len the new number of child elements.
059: * @see org.itsnat.core.domutil.ElementList#setLength(int)
060: */
061: public void setLength(int len);
062:
063: /**
064: * Informs whether the list is empty (no elements).
065: *
066: * @return true if the list is empty.
067: * @see org.itsnat.core.domutil.ElementListBase#isEmpty()
068: */
069: public boolean isEmpty();
070:
071: /**
072: * Inserts a new child element at the specified position rendering
073: * the specified item value.
074: *
075: * @param index index of the new child element.
076: * @param value the item value to render as markup.
077: * @return the new element.
078: * @see org.itsnat.core.domutil.ElementList#insertElementAt(int,Object)
079: */
080: public Element insertElementAt(int index, Object value);
081:
082: /**
083: * Removes the specified child element.
084: *
085: * @param index index of the element to remove.
086: * @return the removed element or null if index is out of bounds.
087: * @see org.itsnat.core.domutil.ElementListBase#removeElementAt(int)
088: */
089: public Element removeElementAt(int index);
090:
091: /**
092: * Removes the child elements between the specified indexes.
093: *
094: * @param fromIndex low index (inclusive).
095: * @param toIndex high index (inclusive).
096: * @see org.itsnat.core.domutil.ElementListBase#removeElementRange(int,int)
097: */
098: public void removeElementRange(int fromIndex, int toIndex);
099:
100: /**
101: * Removes all child elements. The list is now empty.
102: * @see org.itsnat.core.domutil.ElementListBase#removeAllElements()
103: */
104: public void removeAllElements();
105:
106: /**
107: * Renders the specified value into the child element with the given position.
108: *
109: * @param index index of the element.
110: * @param value the value to render.
111: * @param isSelected if this child element is selected.
112: * @param hasFocus if this child element has the focus. Current ItsNat implementation ever passes false.
113: * @see org.itsnat.core.domutil.ElementList#setElementValueAt(int,Object)
114: */
115: public void setElementValueAt(int index, Object value,
116: boolean isSelected, boolean hasFocus);
117:
118: /**
119: * Returns the child element at the specified index.
120: *
121: * @param index index of the child element to search.
122: * @return the element in this position or null if index is out of range.
123: * @see org.itsnat.core.domutil.ElementListBase#getElementAt(int)
124: */
125: public Element getElementAt(int index);
126:
127: /**
128: * Returns the "content" element, this element is used to render below
129: * the associated value of the child element. This element is obtained
130: * using the current structure.
131: *
132: * @param index index of the element.
133: * @return the content element.
134: * @see org.itsnat.comp.ItsNatListStructure#getContentElement(org.itsnat.comp.ItsNatList,int,Element)
135: * @see org.itsnat.core.domutil.ElementList#getContentElementAt(int)
136: */
137: public Element getContentElementAt(int index);
138:
139: /**
140: * Returns an object info of the child element at the specified position.
141: *
142: * @param index index of the element to search for.
143: * @return the object info of the matched child element. Null if index is out of range.
144: * This object is ever the same per list item and may be used to save any context data.
145: * @see #getItsNatListCellUIFromNode(Node)
146: * @see org.itsnat.core.domutil.ElementListBase#getListElementInfoAt(int)
147: */
148: public ItsNatListCellUI getItsNatListCellUIAt(int index);
149:
150: /**
151: * Returns an object info of the child element containing the specified node (or the node
152: * is itself an element of the list).
153: *
154: * @param node the node to search for.
155: * @return the object info of the matched child element. Null if this node is not contained by the list.
156: * This object is ever the same per list item and may be used to save any context data.
157: * @see #getItsNatListCellUIAt(int)
158: * @see org.itsnat.core.domutil.ElementListBase#getListElementInfoFromNode(Node)
159: */
160: public ItsNatListCellUI getItsNatListCellUIFromNode(Node node);
161:
162: /**
163: * Informs whether the original (saved as pattern) markup is used to render.
164: *
165: * <p>The default value is defined by {@link org.itsnat.core.ItsNatDocument#isUsePatternMarkupToRender()}</p>
166: *
167: * @return true if the original markup is used.
168: * @see #setUsePatternMarkupToRender(boolean)
169: */
170: public boolean isUsePatternMarkupToRender();
171:
172: /**
173: * Sets whether the original (saved as pattern) markup is used to render.
174: *
175: * @param value true to enable the use of original markup to render.
176: * @see #isUsePatternMarkupToRender()
177: */
178: public void setUsePatternMarkupToRender(boolean value);
179: }
|