001: /* ListitemRendererExt.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Mon Feb 5 10:10:12 2007, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2007 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.zul;
020:
021: /**
022: * Provides additional control to {@link ListitemRenderer}.
023: *
024: * @author tomyeh
025: * @see ListitemRenderer
026: */
027: public interface ListitemRendererExt {
028: /** Creates an instance of {@link Listitem} for rendering.
029: * The created component will be passed to {@link ListitemRenderer#render}.
030: *
031: * <p>Note: remember to invoke {@link Listitem#applyProperties} to initialize
032: * the properties, defined in the component definition, properly.
033: *
034: * <p>If null is returned, the default list item is created as follow.
035: <pre><code>
036: final Listitem item = new Listitem();
037: item.applyProperties();
038: return item;
039: </code></pre>
040: *
041: * <p>Note: DO NOT call {@link Listitem#setParent}.
042: *
043: * @return the list item if you'd like to create it differently, or null
044: * if you want {@link Listbox} to create it for you
045: */
046: public Listitem newListitem(Listbox listbox);
047:
048: /** Create an instance of {@link Listcell} as the first cell of the list item.
049: *
050: * <p>Note: remember to invoke {@link Listcell#applyProperties} to initialize
051: * the properties, defined in the component definition, properly.
052: *
053: * <p>Note: DO NOT call {@link Listitem#setParent}.
054: * Don't create cells for other columns.
055: *
056: * <p>If null is returned, the default list cell is created as follow.
057: <pre><code>
058: final Listcell cell = new Listcell();
059: cell.applyProperties();
060: return cell;
061: </code></pre>
062: *
063: * <p>Note: DO NOT call {@link Listcell#setParent}.
064: *
065: * @param item the list item. It is the same as that is returned
066: * by {@link #newListitem}
067: * @return the list cell if you'd like to create it differently, or null
068: * if you want {@link Listbox} to create it for you
069: */
070: public Listcell newListcell(Listitem item);
071:
072: /** Returned by {@link #getControls} to indicate
073: * to detach the list cell adde by {@link #newListcell}.
074: *
075: * <p>To simplify the implementation of {@link ListitemRenderer#render},
076: * {@link Listbox}, by default, detached the list cell before calling
077: * {@link ListitemRenderer#render} -- as if this flag is returned.
078: *
079: * <p>If you don't specify this flag, the implementation of
080: * {@link ListitemRenderer#render} must be aware of the existence of
081: * the first cell
082: * (of the passed list item).
083: */
084: public static final int DETACH_ON_RENDER = 0x0001;
085: /** Returned by {@link #getControls} to indicate
086: * whether to detach a rendered item when unloading it.
087: *
088: * <p>When an item has to be cleaned up
089: * (so it can be re-rendered again), the list box
090: * checks whether this flag is returned.
091: * For example, when a new data model is assigned, all rendered items
092: * (i.e., generated by {@link ListitemRenderer#render}) will be cleaned up.
093: *
094: *<p>To have the best performance,
095: * the list box, by default, keep using the same list item and
096: * the first list cell (other list cells, if any, are removed).
097: *
098: * <p>Sometimes it could be an issue. For example, you assign attributes
099: * or annotations to a rendered item.
100: * Then, you'd better to return this flag to indicate that.
101: * a new list item shall be created (by calling {@link #newListitem} and {@link #newListcell})
102: * to replace the renderred item.
103: */
104: public static final int DETACH_ON_UNLOAD = 0x0002;
105:
106: /** Returns how a listbox shall render the live data.
107: *
108: * <p>Note: if this interface is not implemented, {@link #DETACH_ON_RENDER}
109: * is assumed.
110: *
111: * @return a combination of {@link #DETACH_ON_RENDER} and
112: * {@link #DETACH_ON_UNLOAD} to indicate how to render the live data.
113: */
114: public int getControls();
115: }
|