001: /* RowRendererExt.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Thu Mar 8 10:57:52 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: import org.zkoss.zk.ui.Component;
022:
023: /**
024: * Provides additional control to {@link RowRenderer}.
025: *
026: * @author tomyeh
027: */
028: public interface RowRendererExt {
029: /** Creates an instance of {@link Row} for rendering.
030: * The created component will be passed to {@link RowRenderer#render}.
031: *
032: * <p>Note: remember to invoke {@link Row#applyProperties} to initialize
033: * the properties, defined in the component definition, properly.
034: *
035: * <p>If null is returned, the default row is created as follow.
036: <pre><code>
037: final Row row = new Row();
038: row.applyProperties();
039: return row;
040: </code></pre>
041: *
042: * <p>Note: DO NOT call {@link Row#setParent}.
043: *
044: * @return the row if you'd like to create it differently, or null
045: * if you want {@link Grid} to create it for you
046: */
047: public Row newRow(Grid grid);
048:
049: /** Create a component as the first cell of the row.
050: *
051: * <p>Note: remember to invoke {@link Component#applyProperties} to
052: * initialize the properties, defined in the component definition, properly,
053: * if you create an instance instead of returning null.
054: *
055: * <p>Note: DO NOT call {@link Row#setParent}.
056: *
057: * <p>If null is returned, the default cell is created as follow.
058: <pre><code>
059: final Label cell = new Label();
060: cell.applyProperties();
061: return cell;
062: </code></pre>
063: *
064: * <p>Note: DO NOT call {@link Component#setParent}.
065: * Don't create cells for other columns.
066: *
067: * @param row the row. It is the same as that is returned
068: * by {@link #newRow}
069: * @return the cell if you'd like to create it differently, or null
070: * if you want {@link Grid} to create it for you
071: */
072: public Component newCell(Row row);
073:
074: /** Returned by {@link #getControls} to indicate
075: * to detach the cell adde by {@link #newCell}.
076: *
077: * <p>To simplify the implementation of {@link RowRenderer#render},
078: * {@link Listbox}, by default, detached the cell before calling
079: * {@link RowRenderer#render} -- as if this flag is returned.
080: *
081: * <p>If you don't specify this flag, the implementation of
082: * {@link RowRenderer#render} must be aware of the existence of
083: * the first cell
084: * (of the passed row).
085: */
086: public static final int DETACH_ON_RENDER = 0x0001;
087: /** Returned by {@link #getControls} to indicate
088: * whether to detach a rendered row when unloading it.
089: *
090: * <p>When a row has to be cleaned up
091: * (so it can be re-rendered again), the grid
092: * checks whether this flag is returned.
093: * For example, when a new data model is assigned, all rendered rows
094: * (i.e., generated by {@link RowRenderer#render}) will be cleaned up.
095: *
096: *<p>To have the best performance,
097: * the grid, by default, keep using the same row and
098: * the first cell (other cells, if any, are removed).
099: *
100: * <p>Sometimes it could be an issue. For example, you assign attributes
101: * or annotations to a rendered row.
102: * Then, you'd better to return this flag to indicate that.
103: * a new row shall be created (by calling {@link #newRow} and {@link #newCell})
104: * to replace the renderred row.
105: */
106: public static final int DETACH_ON_UNLOAD = 0x0002;
107:
108: /** Returns how a grid shall render the live data.
109: *
110: * <p>Note: if this interface is not implemented, {@link #DETACH_ON_RENDER}
111: * is assumed.
112: *
113: * @return a combination of {@link #DETACH_ON_RENDER} and
114: * {@link #DETACH_ON_UNLOAD} to indicate how to render the live data.
115: */
116: public int getControls();
117: }
|