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: package org.itsnat.core.domutil;
014:
015: import org.w3c.dom.DocumentFragment;
016: import org.w3c.dom.Element;
017: import org.w3c.dom.Node;
018:
019: /**
020: * Represents a pattern based DOM tree node. A tree node contains (may contain)
021: * a handle, an icon and a label elements (these three are the node "content"),
022: * and may have child nodes. The tree node structure is used as pattern to create child tree nodes (by using a deep clone),
023: * so all child tree nodes have the same structure (same as the pattern), unless
024: * there is one child node in markup.
025: *
026: * <p>This interface supports "out the box" the typical DOM tree node structure
027: * with handle, icon and label elements:</p>
028: *
029: * <pre>
030: * <parent>
031: * <content><handle/><icon/><label>markup of label</label></content>
032: * <children>
033: * ...child tree nodes go here
034: * </children>
035: * </parent>
036: * </pre>
037: *
038: * <p>The label element is normally used to render below the value associated to node.
039: * The method {@link #setValue(Object)} is used to render this value, the structure and renderer
040: * objects are used to customize how and where this value is saved in the tree node
041: * beyond the default cases.</p>
042: *
043: * <p>A pattern based DOM tree node ever works in "master" mode, see {@link ElementListFree#isMaster()}.</p>
044: *
045: * @author Jose Maria Arranz Santamaria
046: * @see org.itsnat.core.ItsNatDocument#createElementTreeNode(org.w3c.dom.Element,boolean)
047: */
048: public interface ElementTreeNode extends ElementGroup {
049: /**
050: * Returns the current structure used by this tree node.
051: *
052: * @return the current structure.
053: */
054: public ElementTreeNodeStructure getElementTreeNodeStructure();
055:
056: /**
057: * Returns the current renderer used by this tree node.
058: *
059: * @return the current renderer.
060: */
061: public ElementTreeNodeRenderer getElementTreeNodeRenderer();
062:
063: /**
064: * Sets the renderer used by this tree node.
065: *
066: * @param renderer the new renderer.
067: */
068: public void setElementTreeNodeRenderer(
069: ElementTreeNodeRenderer renderer);
070:
071: /**
072: * Returns the parent tree node if exists.
073: *
074: * @return the parent tree node, null if this node is root or rootless tree.
075: */
076: public ElementTreeNode getElementTreeNodeParent();
077:
078: /**
079: * Returns the content element. This element usually contains the handle, icon and label elements.
080: * The current structure is used to obtain this element.
081: *
082: * @return the content element.
083: * @see #getElementTreeNodeStructure()
084: * @see ElementTreeNodeStructure#getContentElement(ElementTreeNode,Element)
085: */
086: public Element getContentElement();
087:
088: /**
089: * Returns the handle element. The current structure is used to obtain this element.
090: *
091: * @return the handle element.
092: * @see #getElementTreeNodeStructure()
093: * @see ElementTreeNodeStructure#getHandleElement(ElementTreeNode,Element)
094: */
095: public Element getHandleElement();
096:
097: /**
098: * Returns the icon element. The current structure is used to obtain this element.
099: *
100: * @return the icon element.
101: * @see #getElementTreeNodeStructure()
102: * @see ElementTreeNodeStructure#getIconElement(ElementTreeNode,Element)
103: */
104: public Element getIconElement();
105:
106: /**
107: * Returns the label element. The current structure is used to obtain this element.
108: *
109: * @return the label element.
110: * @see #getElementTreeNodeStructure()
111: * @see ElementTreeNodeStructure#getLabelElement(ElementTreeNode,Element)
112: */
113: public Element getLabelElement();
114:
115: /**
116: * Returns the parent element of the child tree nodes. The current structure is used to obtain this element.
117: *
118: * @return the parent of child nodes.
119: * @see #getElementTreeNodeStructure()
120: * @see ElementTreeNodeStructure#getChildListElement(ElementTreeNode,Element)
121: */
122: public Element getChildListElement();
123:
124: /**
125: * Renders the submitted value into the tree node markup using the current
126: * renderer.
127: *
128: * @param value the value to render.
129: * @see #getElementTreeNodeRenderer()
130: * @see ElementTreeNodeRenderer#renderTreeNode(ElementTreeNode,Object,Element,boolean)
131: */
132: public void setValue(Object value);
133:
134: /**
135: * Returns the index of this node as a child of its node parent.
136: *
137: * @return the position as child, -1 if root.
138: * @see #getElementTreeNodeParent()
139: */
140: public int getIndex();
141:
142: /**
143: * Returns the row index of this node seeing the tree as a list.
144: *
145: * @return the row index, 0 if root.
146: */
147: public int getRow();
148:
149: /**
150: * Returns the number of levels (parents) above.
151: *
152: * @return the number of levels, 0 if root or a child node of the root list in a rootless tree.
153: */
154: public int getDeepLevel();
155:
156: /**
157: * Informs whether this node is a leaf, it does not contain child nodes.
158: *
159: * @return true if this node is a leaf.
160: */
161: public boolean isLeaf();
162:
163: /**
164: * Returns this tree node or the tree node containing the specified node.
165: *
166: * @param node the node to search for.
167: * @return the tree node containing the specified node. Null if not contained by this tree node or child tree nodes.
168: */
169: public ElementTreeNode getElementTreeNodeFromNode(Node node);
170:
171: /**
172: * Returns the child tree node list of this tree node.
173: *
174: * @return the child tree node list
175: */
176: public ElementTreeNodeList getChildTreeNodeList();
177:
178: /**
179: * Returns the previous tree node in the logical order of the tree
180: * (seen as a list).
181: *
182: * @return the previous tree node.
183: */
184: public ElementTreeNode getPreviousTreeNode();
185:
186: /**
187: * Returns the next tree node in the logical order of the tree
188: * (seen as a list).
189: *
190: * @return the next tree node.
191: */
192: public ElementTreeNode getNextTreeNode();
193:
194: /**
195: * Returns the tree node immediately preceding this tree node (same level).
196: *
197: * @return the previous sibling or null if there is no such tree node.
198: */
199: public ElementTreeNode getPreviousSiblingTreeNode();
200:
201: /**
202: * Returns the tree node immediately following this tree node (same level).
203: *
204: * @return the next sibling or null if there is no such tree node.
205: */
206: public ElementTreeNode getNextSiblingTreeNode();
207:
208: /**
209: * Informs whether this node is part of a tree table.
210: *
211: * @return true if this node is part of a tree table.
212: */
213: public boolean isTreeTable();
214:
215: /**
216: * Informs whether the original (saved as pattern) markup is used to render.
217: *
218: * <p>The default value is defined by the parent tree node list if exists or
219: * by {@link org.itsnat.core.ItsNatDocument#isUsePatternMarkupToRender()}</p>
220: *
221: * @return true if the original markup is used.
222: * @see #setUsePatternMarkupToRender(boolean)
223: */
224: public boolean isUsePatternMarkupToRender();
225:
226: /**
227: * Sets whether the original (saved as pattern) markup is used to render.
228: *
229: * @param value true to enable the use of original markup to render.
230: * @see #isUsePatternMarkupToRender()
231: */
232: public void setUsePatternMarkupToRender(boolean value);
233:
234: /**
235: * Returns the pattern used to render values if {@link #isUsePatternMarkupToRender()}
236: * is true.
237: *
238: * @return the pattern used to render values.
239: */
240: public DocumentFragment getLabelContentPatternFragment();
241: }
|