listitemrendererext.java

ZK 基础介绍 功能操作 模块 结合数据库操作

/* ListitemRendererExt.java

{{IS_NOTE
	Purpose:
		
	Description:
		
	History:
		Mon Feb  5 10:10:12     2007, Created by tomyeh
}}IS_NOTE

Copyright (C) 2007 Potix Corporation. All Rights Reserved.

{{IS_RIGHT
	This program is distributed under GPL Version 2.0 in the hope that
	it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/
package org.zkoss.zul;

/**
 * Provides additional control to {@link ListitemRenderer}.
 *
 * @author tomyeh
 * @see ListitemRenderer
 */
public interface ListitemRendererExt {
	/** Creates an instance of {@link Listitem} for rendering.
	 * The created component will be passed to {@link ListitemRenderer#render}.
	 *
	 * <p>Note: remember to invoke {@link Listitem#applyProperties} to initialize
	 * the properties, defined in the component definition, properly.
	 *
	 * <p>If null is returned, the default list item is created as follow.
<pre><code>
final Listitem item = new Listitem();
item.applyProperties();
return item;
</code></pre>
	 *
	 * <p>Note: DO NOT call {@link Listitem#setParent}.
	 *
	 * @return the list item if you'd like to create it differently, or null
	 * if you want {@link Listbox} to create it for you
	 */
	public Listitem newListitem(Listbox listbox);
	/** Create an instance of {@link Listcell} as the first cell of the list item.
	 *
	 * <p>Note: remember to invoke {@link Listcell#applyProperties} to initialize
	 * the properties, defined in the component definition, properly.
	 *
	 * <p>Note: DO NOT call {@link Listitem#setParent}.
	 * Don't create cells for other columns.
	 *
	 * <p>If null is returned, the default list cell is created as follow.
<pre><code>
final Listcell cell = new Listcell();
cell.applyProperties();
return cell;
</code></pre>
	 *
	 * <p>Note: DO NOT call {@link Listcell#setParent}.
	 *
	 * @param item the list item. It is the same as that is returned
	 * by {@link #newListitem}
	 * @return the list cell if you'd like to create it differently, or null
	 * if you want {@link Listbox} to create it for you
	 */
	public Listcell newListcell(Listitem item);

	/** Returned by {@link #getControls} to indicate
	 * to detach the list cell adde by {@link #newListcell}.
	 *
	 * <p>To simplify the implementation of {@link ListitemRenderer#render},
	 * {@link Listbox}, by default, detached the list cell before calling
	 * {@link ListitemRenderer#render} -- as if this flag is returned.
	 *
	 * <p>If you don't specify this flag, the implementation of 
	 * {@link ListitemRenderer#render} must be aware of the existence of
	 * the first cell
	 * (of the passed list item).
	 */
	public static final int DETACH_ON_RENDER = 0x0001;
	/** Returned by {@link #getControls} to indicate
	 * whether to detach a rendered item when unloading it.
	 *
	 * <p>When an item has to be cleaned up
	 * (so it can be re-rendered again), the list box
	 * checks whether this flag is returned.
	 * For example, when a new data model is assigned, all rendered items
	 * (i.e., generated by {@link ListitemRenderer#render}) will be cleaned up.
	 *
	 *<p>To have the best performance,
	 * the list box, by default, keep using the same list item and
	 * the first list cell (other list cells, if any, are removed).
	 *
	 * <p>Sometimes it could be an issue. For example, you assign attributes
	 * or annotations to a rendered item.
	 * Then, you'd better to return this flag to indicate that.
	 * a new list item shall be created (by calling {@link #newListitem} and {@link #newListcell})
	 * to replace the renderred item.
	 */
	public static final int DETACH_ON_UNLOAD = 0x0002;
	/** Returns how a listbox shall render the live data.
	 *
	 * <p>Note: if this interface is not implemented, {@link #DETACH_ON_RENDER}
	 * is assumed.
	 *
	 * @return a combination of {@link #DETACH_ON_RENDER} and
	 * {@link #DETACH_ON_UNLOAD} to indicate how to render the live data.
	 */
	public int getControls();
}