org.zkoss.zul.api
Interface Grid

All Superinterfaces:
java.lang.Cloneable, Component, HtmlBasedComponent, Paginated, Scope, java.io.Serializable, XulElement
All Known Implementing Classes:
Grid

public interface Grid
extends XulElement, Paginated

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 or GroupsModel instance) to a grid via setModel(ListModel) or setModel(GroupsModel) 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 Component.getMold() is "default", scrolling is used if HtmlBasedComponent.setHeight(java.lang.String) is called and too much content to display. If Component.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.getZclass(): z-grid.(since 3.5.0)

To have a grid without stripping, you can specify a non-existent style class to setOddRowSclass(java.lang.String).

Since:
3.5.2
Author:
tomyeh
See Also:
ListModel, RowRenderer, RowRendererExt

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 int getActivePage()
          Returns the active page (starting from 0).
 java.lang.String getAlign()
          Deprecated. As of release 5.0, use CSS instead.
 Component getCell(int row, int col)
          Returns the specified cell, or null if not available.
 Columns getColumnsApi()
          Returns the columns.
 Foot getFootApi()
          Returns the foot.
 GroupsModel getGroupsModel()
          Returns the groups model associated with this grid, or null if this grid is associated with a ListModel or not associated with any list data model.
 java.util.Collection getHeads()
          Returns a collection of heads, including getColumnsApi() and auxiliary heads (Auxhead) (never null).
 java.lang.String getInnerWidth()
          Returns the inner width of this component.
 ListModel getListModel()
          Returns the list model associated with this grid, or null if this grid is associated with a GroupsModel or not associated with any list data model.
 ListModel getModel()
          Returns the model associated with this grid, or null if this grid is not associated with any list data model.
 java.lang.String getOddRowSclass()
          Returns the style class for the odd rows.
 int getPageCount()
          Returns the number of pages.
 int getPageSize()
          Returns the page size, aka., the number rows per page.
 Paginal getPaginal()
          Returns the paging controller, or null if not available.
 Paging getPagingChildApi()
          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 getRowsApi()
          Returns the rows.
 boolean isFixedLayout()
          Deprecated. since 5.0.0, use !isSizedByContent() instead
 boolean isSizedByContent()
          Returns whether sizing grid column width by its content.
 void renderAll()
          Renders all Row if not loaded yet, with getRowRenderer().
 void renderItems(java.util.Set rows)
           
 void renderRowApi(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 setActivePage(int pg)
          Sets the active page (starting from 0).
 void setAlign(java.lang.String align)
          Deprecated. As of release 5.0, use CSS instead.
 void setFixedLayout(boolean fixedLayout)
          Deprecated. since 5.0.0, use setSizedByContent(boolean)(!fixedLayout) instead
 void setInnerWidth(java.lang.String innerWidth)
          Sets the inner width of this component.
 void setModel(GroupsModel model)
          Sets the groups model associated with this grid.
 void setModel(ListModel model)
          Sets the list model associated with this grid.
 void setOddRowSclass(java.lang.String scls)
          Sets the style class for the odd rows.
 void setPageSize(int pgsz)
          Sets the page size, aka., the number rows per page.
 void setPaginal(Paginal pgi)
          Specifies the paging controller.
 void setPagingPosition(java.lang.String pagingPosition)
          Sets how to position the paging of grid at the client screen.
 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.
 void setSizedByContent(boolean byContent)
          Sets whether sizing grid column width by its content.
 void setVflex(boolean vflex)
          Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility.
 
Methods inherited from interface org.zkoss.zul.impl.api.XulElement
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent
focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex
 
Methods inherited from interface org.zkoss.zk.ui.Component
addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zul.ext.Paginated
getPagingPosition
 

Method Detail

setVflex

void setVflex(boolean vflex)
Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility.


setSizedByContent

void setSizedByContent(boolean byContent)
Sets whether sizing grid column width by its content. Default is false, i.e. the outline of grid is dependent on browser. It means, we don't calculate the width of each cell. If set to true, the outline will count on the content of body. In other words, the outline of grid will be like ZK version 2.4.1 that the header's width is only for reference.

You can also specify the "sized-by-content" attribute of component in lang-addon.xml directly, it will then take higher priority.

Parameters:
byContent -
Since:
5.0.0

isSizedByContent

boolean isSizedByContent()
Returns whether sizing grid column width by its content. Default is false.

Note: if the "sized-by-content" attribute of component is specified, it's prior to the original value.

Since:
5.0.0
See Also:
setSizedByContent(boolean)

setFixedLayout

void setFixedLayout(boolean fixedLayout)
Deprecated. since 5.0.0, use setSizedByContent(boolean)(!fixedLayout) instead

Sets the outline of grid whether is fixed layout. If true, the outline of grid will be depended on browser. It means, we don't calculate the width of each cell. Otherwise, the outline will count on the content of body. In other words, the outline of grid is like ZK 2.4.1 version that the header's width is only for reference.

You can also specify the "fixed-layout" attribute of component in lang-addon.xml directly, it's a top priority.


isFixedLayout

boolean isFixedLayout()
Deprecated. since 5.0.0, use !isSizedByContent() instead

Returns the outline of grid whether is fixed layout.

Default: false.

Note: if the "fixed-layout" attribute of component is specified, it's prior to the original value.


getRowsApi

Rows getRowsApi()
Returns the rows.


getColumnsApi

Columns getColumnsApi()
Returns the columns.


getFootApi

Foot getFootApi()
Returns the foot.


getHeads

java.util.Collection getHeads()
Returns a collection of heads, including getColumnsApi() and auxiliary heads (Auxhead) (never null).


getCell

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

java.lang.String getAlign()
Deprecated. As of release 5.0, use CSS instead.


setAlign

void setAlign(java.lang.String align)
Deprecated. As of release 5.0, use CSS instead.


setPagingPosition

void setPagingPosition(java.lang.String pagingPosition)
Sets how to position the paging of grid at the client screen. It is meaningless if the mold is not in "paging".

Parameters:
pagingPosition - how to position. It can only be "bottom" (the default), or "top", or "both".

getPaginal

Paginal getPaginal()
Returns the paging controller, or null if not available. Note: the paging controller is used only if Component.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 Component.setMold(java.lang.String) with "paging"), the grid will rely on the paging controller to handle long-content instead of scrolling.


setPaginal

void setPaginal(Paginal pgi)
Specifies the paging controller. Note: the paging controller is used only if Component.getMold() is "paging".

It is OK, though without any effect, to specify a paging controller even if mold is not "paging".

Parameters:
pgi - the paging controller. If null and Component.getMold() is "paging", a paging controller is created automatically as a child component (see getPagingChildApi()).

getPagingChildApi

Paging getPagingChildApi()
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

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

void setPageSize(int pgsz)
                 throws WrongValueException
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.
WrongValueException

getPageCount

int getPageCount()
Returns the number of pages. Note: there is at least one page even no item at all.


getActivePage

int getActivePage()
Returns the active page (starting from 0).


setActivePage

void setActivePage(int pg)
                   throws WrongValueException
Sets the active page (starting from 0).

Throws:
WrongValueException

getModel

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

Note: if setModel(GroupsModel) was called with a groups model, this method returns an instance of ListModel encapsulating it.

See Also:
setModel(ListModel), setModel(GroupsModel)

getListModel

ListModel getListModel()
Returns the list model associated with this grid, or null if this grid is associated with a GroupsModel or not associated with any list data model.

See Also:
setModel(ListModel)

getGroupsModel

GroupsModel getGroupsModel()
Returns the groups model associated with this grid, or null if this grid is associated with a ListModel or not associated with any list data model.

See Also:
setModel(GroupsModel)

setModel

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:
UiException - if failed to initialize with the model
See Also:
getListModel(), setModel(GroupsModel)

setModel

void setModel(GroupsModel model)
Sets the groups 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.

The groups model is used to represent a list of data with grouping.

Parameters:
model - the groups model to associate, or null to dis-associate any previous model.
Throws:
UiException - if failed to initialize with the model
See Also:
setModel(ListModel), getGroupsModel()

getRowRenderer

RowRenderer getRowRenderer()
Returns the renderer to render each row, or null if the default renderer is used.


setRowRenderer

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:
UiException - if failed to initialize with the model

setRowRenderer

void setRowRenderer(java.lang.String clsnm)
                    throws java.lang.ClassNotFoundException,
                           java.lang.NoSuchMethodException,
                           java.lang.IllegalAccessException,
                           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.IllegalAccessException
java.lang.InstantiationException
java.lang.reflect.InvocationTargetException

getPreloadSize

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(ListModel) and not paging (getPagingChildApi().

Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.


setPreloadSize

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(ListModel) and not paging (getPagingChildApi().

Parameters:
sz - the number of rows to preload. If zero, no preload at all.
Throws:
UiException - if sz is negative

setInnerWidth

void setInnerWidth(java.lang.String innerWidth)
Sets the inner width of this component. The inner width is the width of the inner table. By default, it is 100%. That is, it is the same as the width of this component. However, it is changed when the user is sizing the column's width.

Application developers rarely call this method, unless they want to preserve the widths of sizable columns changed by the user. To preserve the widths, the developer have to store the widths of all columns and the inner width (getInnerWidth()), and then restore them when re-creating this component.

Parameters:
innerWidth - the inner width. If null, "100%" is assumed.

getInnerWidth

java.lang.String getInnerWidth()
Returns the inner width of this component. The inner width is the width of the inner table.

Default: "100%"

See Also:
setInnerWidth(java.lang.String)

renderRowApi

void renderRowApi(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

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


renderRows

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


renderItems

void renderItems(java.util.Set rows)

getOddRowSclass

java.lang.String getOddRowSclass()
Returns the style class for the odd rows.

Default: HtmlBasedComponent.getZclass()-odd. (since 3.5.0)


setOddRowSclass

void setOddRowSclass(java.lang.String scls)
Sets the style class for the odd rows. If the style class doesn't exist, the striping effect disappears. You can provide different effects by providing the proper style classes.



Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo