org.zkoss.zul
Class Grid

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.Grid

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.sys.ComponentCtrl

public class Grid
extends XulElement

A grid is an element that contains both rows and columns elements. It is used to create a grid of elements. Both the rows and columns are displayed at once although only one will typically contain content, while the other may provide size information.

Besides creating Row programmingly, you can assign a data model (a ListModel instance) to a grid via setModel(org.zkoss.zul.ListModel) and then the grid will retrieve data by calling ListModel.getElementAt(int) when necessary.

Besides assign a list model, you could assign a renderer (a RowRenderer instance) to a grid, such that the grid will use this renderer to render the data returned by ListModel.getElementAt(int). If not assigned, the default renderer, which assumes a label per row, is used. In other words, the default renderer adds a label to a row by calling toString against the object returned by ListModel.getElementAt(int)

There are two ways to handle long content: scrolling and paging. If AbstractComponent.getMold() is "default", scrolling is used if HtmlBasedComponent.setHeight(java.lang.String) is called and too much content to display. If AbstractComponent.getMold() is "paging", paging is used if two or more pages are required. To control the number of rows to display in a page, use setPageSize(int).

If paging is used, the page controller is either created automatically or assigned explicity by setPaginal(org.zkoss.zul.ext.Paginal). The paging controller specified explicitly by setPaginal(org.zkoss.zul.ext.Paginal) is called the external page controller. It is useful if you want to put the paging controller at different location (other than as a child component), or you want to use the same controller to control multiple grids.

Default HtmlBasedComponent.getSclass(): grid. To have a grid withoug stripping, you might specify grid-no-striped as the sclass. To have a grid without stripping and grid lines, you can specify any name, other than grid and grid-on-striped, as the sclass.

Author:

tomyeh

See Also:

ListModel, RowRenderer, RowRendererExt, Serialized Form

Nested Class Summary

protected class

Grid.ExtraCtrl A utility class to implement AbstractComponent.getExtraCtrl().

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

Grid()

Method Summary

java.lang.Object	clone()
java.lang.String	getAlign() Returns the horizontal alignment of the whole grid.
org.zkoss.zk.ui.Component	getCell(int row, int col) Returns the specified cell, or null if not available.
Columns	getColumns() Returns the columns.
Foot	getFoot() Returns the foot.
ListModel	getModel() Returns the list model associated with this grid, or null if this grid is not associated with any list data model.
java.lang.String	getOuterAttrs()
int	getPageSize() Returns the page size, aka., the number rows per page.
Paginal	getPaginal() Returns the paging controller, or null if not available.
Paging	getPaging() Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).
int	getPreloadSize() Returns the number of rows to preload when receiving the rendering request from the client.
RowRenderer	getRowRenderer() Returns the renderer to render each row, or null if the default renderer is used.
Rows	getRows() Returns the rows.
boolean	insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
protected java.lang.Object	newExtraCtrl()
void	onInitRender() Handles a private event, onInitRender.
void	onPaging() Called when the onPaging event is received (from getPaginal()).
boolean	removeChild(org.zkoss.zk.ui.Component child)
void	renderAll() Renders all Row if not loaded yet, with getRowRenderer().
void	renderItems(java.util.Set rows)
void	renderRow(Row row) Renders the specified Row if not loaded yet, with getRowRenderer().
void	renderRows(java.util.Set rows) Renders a set of specified rows.
void	setAlign(java.lang.String align) Sets the horizontal alignment of the whole grid.
void	setModel(ListModel model) Sets the list model associated with this grid.
void	setMold(java.lang.String mold)
void	setPageSize(int pgsz) Sets the page size, aka., the number rows per page.
void	setPaginal(Paginal pgi)
void	setPreloadSize(int sz) Sets the number of rows to preload when receiving the rendering request from the client.
void	setRowRenderer(RowRenderer renderer) Sets the renderer which is used to render each row if getModel() is not null.
void	setRowRenderer(java.lang.String clsnm) Sets the renderer by use of a class name.

Methods inherited from class org.zkoss.zul.impl.XulElement

getAction, getAllOnClickAttrs, getContext, getInnerAttrs, getPopup, getTooltip, setAction, setContext, setPopup, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

addEventListener, appendAsapAttr, focus, getDraggable, getDroppable, getHeight, getLeft, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZIndex, isAsapRequired, removeEventListener, setClass, setDraggable, setDroppable, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZIndex

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getEventHandler, getExtraCtrl, getFellow, getFellowIfAny, getId, getListenerIterator, getMold, getMoldURI, getNamespace, getPage, getParent, getPropagatee, getRoot, getSpaceOwner, getUuid, getVariable, invalidate, isChildable, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onDrawNewChild, onWrongValue, redraw, removeAttribute, removeAttribute, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setPage, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, toString, unsetVariable

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Grid

public Grid()

Method Detail

getRows

public Rows getRows()

Returns the rows.

getColumns

public Columns getColumns()

Returns the columns.

getFoot

public Foot getFoot()

Returns the foot.

getCell

public org.zkoss.zk.ui.Component getCell(int row,
                                         int col)

Returns the specified cell, or null if not available.

Parameters:

row - which row to fetch (starting at 0).

col - which column to fetch (starting at 0).

getAlign

public java.lang.String getAlign()

Returns the horizontal alignment of the whole grid.

Default: null (system default: left unless CSS specified).

setAlign

public void setAlign(java.lang.String align)

Sets the horizontal alignment of the whole grid.

Allowed: "left", "center", "right"

getPaginal

public Paginal getPaginal()

Returns the paging controller, or null if not available. Note: the paging controller is used only if AbstractComponent.getMold() is "paging".

If mold is "paging", this method never returns null, because a child paging controller is created automcatically (if not specified by developers with setPaginal(org.zkoss.zul.ext.Paginal)).

If a paging controller is specified (either by setPaginal(org.zkoss.zul.ext.Paginal), or by setMold(java.lang.String) with "paging"), the grid will rely on the paging controller to handle long-content instead of scrolling.

setPaginal

public void setPaginal(Paginal pgi)

onPaging

public void onPaging()

Called when the onPaging event is received (from getPaginal()).

Default: getRows().invalidate().

getPaging

public Paging getPaging()

Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).

getPageSize

public int getPageSize()

Returns the page size, aka., the number rows per page.

Throws:

java.lang.IllegalStateException - if getPaginal() returns null, i.e., mold is not "paging" and no external controller is specified.

setPageSize

public void setPageSize(int pgsz)

Sets the page size, aka., the number rows per page.

Throws:

java.lang.IllegalStateException - if getPaginal() returns null, i.e., mold is not "paging" and no external controller is specified.

getModel

public ListModel getModel()

Returns the list model associated with this grid, or null if this grid is not associated with any list data model.

setModel

public void setModel(ListModel model)

Sets the list model associated with this grid. If a non-null model is assigned, no matter whether it is the same as the previous, it will always cause re-render.

Parameters:

model - the list model to associate, or null to dis-associate any previous model.

Throws:

org.zkoss.zk.ui.UiException - if failed to initialize with the model

getRowRenderer

public RowRenderer getRowRenderer()

Returns the renderer to render each row, or null if the default renderer is used.

setRowRenderer

public void setRowRenderer(RowRenderer renderer)

Sets the renderer which is used to render each row if getModel() is not null.

Note: changing a render will not cause the grid to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an ListDataEvent event.

Parameters:

renderer - the renderer, or null to use the default.

Throws:

org.zkoss.zk.ui.UiException - if failed to initialize with the model

setRowRenderer

public void setRowRenderer(java.lang.String clsnm)
                    throws java.lang.ClassNotFoundException,
                           java.lang.NoSuchMethodException,
                           java.lang.InstantiationException,
                           java.lang.reflect.InvocationTargetException

Sets the renderer by use of a class name. It creates an instance automatically.

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.InstantiationException

java.lang.reflect.InvocationTargetException

getPreloadSize

public int getPreloadSize()

Returns the number of rows to preload when receiving the rendering request from the client.

Default: 7.

It is used only if live data (setModel(org.zkoss.zul.ListModel) and not paging (getPaging().

Since:

2.4.1

setPreloadSize

public void setPreloadSize(int sz)

Sets the number of rows to preload when receiving the rendering request from the client.

It is used only if live data (setModel(org.zkoss.zul.ListModel) and not paging (getPaging().

Parameters:

sz - the number of rows to preload. If zero, no preload at all.

Throws:

org.zkoss.zk.ui.UiException - if sz is negative

Since:

2.4.1

onInitRender

public void onInitRender()

Handles a private event, onInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

renderRow

public void renderRow(Row row)

Renders the specified Row if not loaded yet, with getRowRenderer().

It does nothing if getModel() returns null. In other words, it is meaningful only if live data model is used.

renderAll

public void renderAll()

Renders all Row if not loaded yet, with getRowRenderer().

renderRows

public void renderRows(java.util.Set rows)

Renders a set of specified rows. It is the same as renderItems(java.util.Set).

renderItems

public void renderItems(java.util.Set rows)

setMold

public void setMold(java.lang.String mold)

Specified by:

setMold in interface org.zkoss.zk.ui.Component

Overrides:

setMold in class org.zkoss.zk.ui.AbstractComponent

getOuterAttrs

public java.lang.String getOuterAttrs()

Overrides:

getOuterAttrs in class XulElement

insertBefore

public boolean insertBefore(org.zkoss.zk.ui.Component newChild,
                            org.zkoss.zk.ui.Component refChild)

Specified by:

insertBefore in interface org.zkoss.zk.ui.Component

Overrides:

insertBefore in class org.zkoss.zk.ui.AbstractComponent

removeChild

public boolean removeChild(org.zkoss.zk.ui.Component child)

Specified by:

removeChild in interface org.zkoss.zk.ui.Component

Overrides:

removeChild in class org.zkoss.zk.ui.AbstractComponent

clone

public java.lang.Object clone()

Specified by:

clone in interface org.zkoss.zk.ui.Component

Overrides:

clone in class org.zkoss.zk.ui.AbstractComponent

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Overrides:

newExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent