|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zul.Listbox
public class Listbox
A listbox.
Event:
See Specification.
Besides creating Listitem
programmingly, you could assign a data
model (a ListModel
or GroupsModel
instance) to a listbox via
setModel(ListModel)
or setModel(GroupsModel)
and then the
listbox will retrieve data via ListModel.getElementAt(int)
when necessary.
Besides assign a list model, you could assign a renderer (a
ListitemRenderer
instance) to a listbox, such that the listbox will
use this renderer to render the data returned by
ListModel.getElementAt(int)
. If not assigned, the default renderer, which
assumes a label per list item, is used. In other words, the default renderer
adds a label to a Listitem 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
items to display in a page, use setPageSize(int)
.
If paging is used, the page controller is either created automatically or
assigned explicitly 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 listboxes.
Default getZclass()
: z-listbox.(since 3.5.0)
To have a list box without stripping, you can specify a non-existent style
class to setOddRowSclass(java.lang.String)
.
When used in a clustering environment, you have to make
ListitemRenderer
(setItemRenderer(org.zkoss.zul.ListitemRenderer)
) and ListModel
(
setModel(org.zkoss.zul.ListModel)
) either serializable or re-assign them when
sessionDidActivate(org.zkoss.zk.ui.Page)
is called.
For huge data, you can turn on Listbox's ROD to request ZK engine to load from
ListModel
only the required data chunk and create only the required
Listitem
s in memory and render only the required DOM elements in
browser. So it saves both the memory and the processing time in both server
and browser for huge data. If you don't use the ListModel
with the
Listbox, turn on the ROD will still have ZK engine to render only a chunk of
DOM elements in browser so it at least saves the memory and processing time
in browser. Note that ROD works only if the Listbox is configured to has a
limited "view port" height. That is, either the Listbox is in the "paging"
mold or you have to HtmlBasedComponent.setHeight(String)
,HtmlBasedComponent.setVflex(String)
,
or setRows(int)
of the Listbox to make ROD works.
You can turn on/off ROD for all Listboxes in the application or only for a specific Listbox. To turn on ROD for all Listboxes in the application, you have to specify the Library Property "org.zkoss.zul.listbox.rod" to "true" in WEB-INF/zk.xml. If you did not specify the Library Property, default is false.
org.zkoss.zul.listbox.rod
true
To turn on ROD for a specific Listbox, you have to specify the Listbox's attribute map with key "org.zkoss.zul.listbox.rod" to true. That is, for example, if in a zul file, you shall specify <custom-attributes> of the Listbox like this:
You can mix the Library Property and <custom-attributes> ways together. The <custom-attributes> way always takes higher priority. So you can turn OFF ROD in general and turn ON only some specific Listbox component. Or you can turn ON ROD in general and turn OFF only some specific Listbox component.
Since only partial Listitem
s are created and rendered in the
Listbox if you turn the ROD on, there will be some limitations on accessing
Listitem
s. For example, if you call
Listitem itemAt100 = (Listitem) getItemAtIndex(100);
The Listitem
in index 100 is not necessary created yet if it is
not in the current "view port" and you will get "null" instead.
And it is generally a bad idea to "cache" the created Listitem
in your application if you turn the ROD on because Listitems might be removed
later. Basically, you shall operate on the item of the ListModel
rather than on the Listitem
of the Listbox
if you use the
ListModel
and ROD.
To retrieve what are selected in ROD Listbox, you shall use
Selectable.getSelection()
to get what is currently selected object in
ListModel
rather than using getSelectedItems()
. That is,
you shall operate on the item of the ListModel
rather than on the
Listitem
of the Listbox
if you use the ListModel
and
ROD.
Set selection = ((Selectable)getModel()).getSelection();
ListModel
,
ListitemRenderer
,
ListitemRendererExt
,
Serialized FormNested Class Summary | |
---|---|
protected class |
Listbox.Children
|
protected class |
Listbox.ExtraCtrl
A utility class to implement AbstractComponent.getExtraCtrl() . |
Field Summary | |
---|---|
static java.lang.String |
LOADING_MODEL
|
static java.lang.String |
SYNCING_MODEL
|
Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent |
---|
_height, _left, _top, _width, _zclass |
Fields inherited from class org.zkoss.zk.ui.AbstractComponent |
---|
_visible |
Fields inherited from interface org.zkoss.zk.ui.Component |
---|
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE |
Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl |
---|
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE |
Constructor Summary | |
---|---|
Listbox()
|
Method Summary | |
---|---|
void |
addItemToSelection(Listitem item)
Selects the given item, without deselecting any other items that are already selected.. |
void |
addItemToSelectionApi(Listitem itemApi)
Selects the given item, without deselecting any other items that are already selected.. |
protected void |
afterInsert(Component comp)
Callback if a list item has been inserted. |
Listitem |
appendItem(java.lang.String label,
java.lang.String value)
Appends an item. |
Listitem |
appendItemApi(java.lang.String label,
java.lang.String value)
Appends an item. |
void |
beforeChildAdded(Component newChild,
Component refChild)
Default: does nothing. |
protected void |
beforeRemove(Component comp)
Callback if a list item will be removed (not removed yet). |
void |
clearSelection()
Clears the selection. |
java.lang.Object |
clone()
Clones the component. |
int |
getActivePage()
Returns the active page (starting from 0). |
Frozen |
getFrozen()
Returns the frozen child. |
int |
getGroupCount()
Returns the number of listgroup |
java.util.List |
getGroups()
Returns a list of all Listgroup . |
GroupsModel |
getGroupsModel()
Returns the groups model associated with this list box, or null if this list box is associated with a ListModel or not associated with
any list data model. |
java.util.Collection |
getHeads()
Returns a collection of heads, including getListhead() and
auxiliary heads (Auxhead ) (never null). |
int |
getIndexOfItem(Listitem item)
Returns the index of the specified item, or -1 if not found. |
int |
getIndexOfItemApi(Listitem itemApi)
Returns the index of the specified item, or -1 if not found. |
java.lang.String |
getInnerWidth()
Returns the inner width of this component. |
Listitem |
getItemAtIndex(int index)
Returns the item at the specified index. |
Listitem |
getItemAtIndexApi(int index)
Returns the item at the specified index. |
int |
getItemCount()
Returns the number of items. |
ListitemRenderer |
getItemRenderer()
Returns the renderer to render each item, or null if the default renderer is used. |
java.util.List |
getItems()
Returns a live list of all Listitem . |
Listfoot |
getListfoot()
Returns Listfoot belonging to this listbox, or null if no list
footers at all. |
Listfoot |
getListfootApi()
Returns Listfoot belonging to this listbox, or null if no list
footers at all. |
Listhead |
getListhead()
Returns Listhead belonging to this listbox, or null if no list
headers at all. |
Listhead |
getListheadApi()
Returns Listhead belonging to this listbox, or null if no list
headers at all. |
ListModel |
getListModel()
Returns the list model associated with this list box, or null if this list box is associated with a GroupsModel or not associated with
any list data model. |
int |
getMaxlength()
Returns the maximal length of each item's label. |
ListModel |
getModel()
Returns the model associated with this list box, or null if this list box is not associated with any list data model. |
java.lang.String |
getName()
Returns the name of this component. |
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 items per page. |
Paginal |
getPaginal()
Returns the paging controller, or null if not available. |
Paging |
getPagingChild()
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) . |
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) . |
java.lang.String |
getPagingPosition()
Returns how to position the paging of listbox at the client screen. |
int |
getPreloadSize()
Returns the number of items to preload when receiving the rendering request from the client. |
int |
getRows()
Returns the rows. |
int |
getSelectedCount()
Returns the number of items being selected. |
int |
getSelectedIndex()
Returns the index of the selected item (-1 if no one is selected). |
Listitem |
getSelectedItem()
Returns the selected item. |
Listitem |
getSelectedItemApi()
Returns the selected item. |
java.util.Set |
getSelectedItems()
Returns all selected items. |
java.lang.String |
getSeltype()
Returns the seltype. |
int |
getTabindex()
Returns the tab order of this component. |
java.util.Iterator |
getVisibleChildrenIterator()
Returns an iterator to iterate thru all visible children. |
int |
getVisibleItemCount()
Returns the number of visible descendant Listitem . |
java.lang.String |
getZclass()
Returns the ZK Cascading Style class(es) for this component. |
boolean |
hasGroup()
Returns whether listgroup exists. |
boolean |
insertBefore(Component newChild,
Component refChild)
Inserts a child before the reference child. |
boolean |
isCheckmark()
Returns whether the check mark shall be displayed in front of each item. |
boolean |
isDisabled()
Returns whether it is disabled. |
boolean |
isFixedLayout()
Deprecated. since 5.0.0, use ! isSizedByContent() instead |
boolean |
isMultiple()
Returns whether multiple selections are allowed. |
boolean |
isSizedByContent()
Returns whether sizing listbox column width by its content. |
boolean |
isVflex()
Returns whether to grow and shrink vertical to fit their given space, so called vertial flexibility. |
protected java.util.List |
newChildren()
Creates and returns the instance for storing child components. |
protected java.lang.Object |
newExtraCtrl()
Used by AbstractComponent.getExtraCtrl() to create a client control. |
void |
onInitRender()
Handles a private event, onInitRender. |
void |
onPageAttached(Page newpage,
Page oldpage)
Default: handles special event listeners. |
boolean |
removeChild(Component child)
If the child is a listgroup, its listgroupfoot will be removed at the same time. |
Listitem |
removeItemAt(int index)
Removes the child item in the list box at the given index. |
Listitem |
removeItemAtApi(int index)
Removes the child item in the list box at the given index. |
void |
removeItemFromSelection(Listitem item)
Deselects the given item without deselecting other items. |
void |
removeItemFromSelectionApi(Listitem itemApi)
Deselects the given item without deselecting other items. |
void |
renderAll()
Renders all Listitem if not loaded yet, with
getItemRenderer() . |
Listitem |
renderItem(Listitem li)
Renders the specified Listitem if not loaded yet, with
getItemRenderer() . |
Listitem |
renderItemApi(Listitem itemApi)
Renders the specified Listitem if not loaded yet, with
getItemRenderer() . |
void |
renderItems(java.util.Set items)
|
protected void |
renderProperties(ContentRenderer renderer)
Renders the content of this component, excluding the enclosing tags and children. |
void |
selectAll()
Selects all items. |
void |
selectItem(Listitem item)
Deselects all of the currently selected items and selects the given item. |
void |
selectItemApi(Listitem itemApi)
Deselects all of the currently selected items and selects the given item. |
void |
service(AuRequest request,
boolean everError)
Processes an AU request. |
void |
sessionDidActivate(Page page)
Notification that the session, which owns this component, has just been activated (aka., deserialized). |
void |
sessionWillPassivate(Page page)
Notification that the session, which owns this component, is about to be passivated (aka., serialized). |
void |
setActivePage(int pg)
Sets the active page (starting from 0). |
void |
setActivePage(Listitem item)
Sets the active page in which the specified item is. |
void |
setActivePage(Listitem itemApi)
Sets the active page in which the specified item is. |
void |
setCheckmark(boolean checkmark)
Sets whether the check mark shall be displayed in front of each item. |
void |
setDisabled(boolean disabled)
Sets whether it is disabled. |
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 |
setItemRenderer(ListitemRenderer renderer)
Sets the renderer which is used to render each item if getModel()
is not null. |
void |
setItemRenderer(java.lang.String clsnm)
Sets the renderer by use of a class name. |
void |
setMaxlength(int maxlength)
Sets the maximal length of each item's label. |
void |
setModel(GroupsModel model)
Sets the groups model associated with this list box. |
void |
setModel(ListModel model)
Sets the list model associated with this listbox. |
void |
setMold(java.lang.String mold)
Sets the mold to render this component. |
void |
setMultiple(boolean multiple)
Sets whether multiple selections are allowed. |
void |
setName(java.lang.String name)
Sets the name of this component. |
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 items per page. |
void |
setPaginal(Paginal pgi)
Specifies the paging controller. |
void |
setPagingPosition(java.lang.String pagingPosition)
Sets how to position the paging of listbox at the client screen. |
void |
setPreloadSize(int sz)
Sets the number of items to preload when receiving the rendering request from the client. |
void |
setRows(int rows)
Sets the rows. |
void |
setSelectedIndex(int jsel)
Deselects all of the currently selected items and selects the item with the given index. |
void |
setSelectedItem(Listitem item)
Deselects all of the currently selected items and selects the given item. |
void |
setSelectedItemApi(Listitem itemApi)
Deselects all of the currently selected items and selects the given item. |
void |
setSelectedItems(java.util.Set listItems)
Selects the given listitems. |
void |
setSeltype(java.lang.String seltype)
Sets the seltype. |
void |
setSizedByContent(boolean byContent)
Sets whether sizing listbox column width by its content. |
void |
setTabindex(int tabindex)
Sets the tab order of this component. |
void |
setVflex(boolean vflex)
Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility. |
protected void |
smartUpdate(java.lang.String attr,
java.lang.Object value)
Smart-updates a property of the peer widget associated with the component, running at the client, with the specified value. |
void |
toggleItemSelection(Listitem item)
If the specified item is selected, it is deselected. |
void |
toggleItemSelectionApi(Listitem itemApi)
If the specified item is selected, it is deselected. |
Methods inherited from class org.zkoss.zul.impl.XulElement |
---|
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip |
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent |
---|
focus, getDraggable, getDroppable, getHeight, getHflex, getLeft, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, setClass, setDraggable, setDroppable, setFocus, setHeight, setHflex, setLeft, setSclass, setStyle, setTooltiptext, setTop, setVflex, setWidth, setZclass, setZindex, setZIndex |
Methods inherited from class java.lang.Object |
---|
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
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, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex |
Methods inherited from interface org.zkoss.zk.ui.ext.Scope |
---|
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute |
Field Detail |
---|
public static final java.lang.String LOADING_MODEL
public static final java.lang.String SYNCING_MODEL
Constructor Detail |
---|
public Listbox()
Method Detail |
---|
protected java.util.List newChildren()
AbstractComponent
Default: it instantiates AbstractComponent.Children
.
newChildren
in class AbstractComponent
public void setFixedLayout(boolean fixedLayout)
setSizedByContent(boolean)
(!fixedLayout)
instead
Listbox
You can also specify the "fixed-layout" attribute of component in lang-addon.xml directly, it's a top priority.
setFixedLayout
in interface Listbox
fixedLayout
- true to outline this listbox by browserpublic boolean isFixedLayout()
isSizedByContent()
instead
Listbox
Default: false.
Note: if the "fixed-layout" attribute of component is specified, it's prior to the original value.
isFixedLayout
in interface Listbox
public void setSizedByContent(boolean byContent)
You can also specify the "sized-by-content" attribute of component in lang-addon.xml directly, it will then take higher priority.
setSizedByContent
in interface Listbox
byContent
- public boolean isSizedByContent()
Note: if the "sized-by-content" attribute of component is specified, it's prior to the original value.
isSizedByContent
in interface Listbox
setSizedByContent(boolean)
public Listhead getListhead()
Listhead
belonging to this listbox, or null if no list
headers at all.
public Listhead getListheadApi()
Listhead
belonging to this listbox, or null if no list
headers at all.
getListheadApi
in interface Listbox
public Listfoot getListfoot()
Listfoot
belonging to this listbox, or null if no list
footers at all.
public Frozen getFrozen()
public Listfoot getListfootApi()
Listfoot
belonging to this listbox, or null if no list
footers at all.
getListfootApi
in interface Listbox
public java.util.Collection getHeads()
getListhead()
and
auxiliary heads (Auxhead
) (never null).
getHeads
in interface Listbox
public boolean isCheckmark()
Default: false.
public void setCheckmark(boolean checkmark)
The check mark is a checkbox if isMultiple()
returns true. It is a
radio button if isMultiple()
returns false.
setCheckmark
in interface Listbox
public void setInnerWidth(java.lang.String innerWidth)
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.
setInnerWidth
in interface Listbox
innerWidth
- the inner width. If null, "100%" is assumed.public java.lang.String getInnerWidth()
Default: "100%"
getInnerWidth
in interface Listbox
setInnerWidth(java.lang.String)
public boolean isVflex()
Note: this attribute is ignored if setRows(int)
is specified
Default: false.
public void setVflex(boolean vflex)
Note: this attribute is ignored if setRows(int)
is specified
setVflex
in interface Listbox
public boolean isDisabled()
Default: false.
public void setDisabled(boolean disabled)
setDisabled
in interface Listbox
public int getTabindex()
Currently, only the "select" mold supports this property.
Default: -1 (means the same as browser's default).
getTabindex
in interface Listbox
public void setTabindex(int tabindex) throws WrongValueException
Currently, only the "select" mold supports this property.
setTabindex
in interface Listbox
WrongValueException
public int getRows()
Default: 0.
getRows
in interface Listbox
public void setRows(int rows) throws WrongValueException
Note: if both HtmlBasedComponent.setHeight(java.lang.String)
is specified with non-empty,
setRows(int)
is ignored
setRows
in interface Listbox
WrongValueException
public java.lang.String getSeltype()
Default: "single".
getSeltype
in interface Listbox
public void setSeltype(java.lang.String seltype) throws WrongValueException
setSeltype
in interface Listbox
WrongValueException
public boolean isMultiple()
Default: false.
isMultiple
in interface Listbox
public void setMultiple(boolean multiple)
setMultiple
in interface Listbox
public int getMaxlength()
getMaxlength
in interface Listbox
public void setMaxlength(int maxlength)
It is meaningful only for the select mold.
setMaxlength
in interface Listbox
public java.lang.String getName()
Default: null.
The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.
Don't use this method if your application is purely based on ZK's event-driven model.
getName
in interface Listbox
public void setName(java.lang.String name)
The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.
Don't use this method if your application is purely based on ZK's event-driven model.
setName
in interface Listbox
name
- the name of this component.public java.util.List getItems()
Listitem
. By live we mean you can add
or remove them directly with the List interface. In other words, you
could add or remove an item by manipulating the returned list directly.
getItems
in interface Listbox
public int getItemCount()
getItemCount
in interface Listbox
public Listitem getItemAtIndex(int index)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
public Listitem getItemAtIndexApi(int index)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
getItemAtIndexApi
in interface Listbox
public int getIndexOfItem(Listitem item)
public int getIndexOfItemApi(Listitem itemApi)
getIndexOfItemApi
in interface Listbox
itemApi
- assume as a Listitem
public int getSelectedIndex()
getSelectedIndex
in interface Listbox
public void setSelectedIndex(int jsel)
setSelectedIndex
in interface Listbox
public void selectItem(Listitem item)
It is the same as setSelectedItem(org.zkoss.zul.Listitem)
.
item
- the item to select. If null, all items are deselected.public void selectItemApi(Listitem itemApi)
It is the same as setSelectedItem(org.zkoss.zul.Listitem)
.
selectItemApi
in interface Listbox
itemApi
- assume as a Listitem
public void addItemToSelection(Listitem item)
public void addItemToSelectionApi(Listitem itemApi)
addItemToSelectionApi
in interface Listbox
itemApi
- assume as a Listitem
public void removeItemFromSelection(Listitem item)
public void removeItemFromSelectionApi(Listitem itemApi)
removeItemFromSelectionApi
in interface Listbox
itemApi
- assume as a Listitem
public void toggleItemSelection(Listitem item)
public void toggleItemSelectionApi(Listitem itemApi)
toggleItemSelectionApi
in interface Listbox
itemApi
- assume as a Listitem
public void clearSelection()
clearSelection
in interface Listbox
public void selectAll()
selectAll
in interface Listbox
public Listitem getSelectedItem()
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
public Listitem getSelectedItemApi()
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
getSelectedItemApi
in interface Listbox
public void setSelectedItem(Listitem item)
It is the same as selectItem(org.zkoss.zul.Listitem)
.
public void setSelectedItemApi(Listitem itemApi)
It is the same as selectItem(org.zkoss.zul.Listitem)
.
setSelectedItemApi
in interface Listbox
itemApi
- assume as a Listitem
public void setSelectedItems(java.util.Set listItems)
public java.util.Set getSelectedItems()
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
getSelectedItems
in interface Listbox
public int getSelectedCount()
getSelectedCount
in interface Listbox
public Listitem appendItem(java.lang.String label, java.lang.String value)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
public Listitem appendItemApi(java.lang.String label, java.lang.String value)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
appendItemApi
in interface Listbox
public Listitem removeItemAt(int index)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
public Listitem removeItemAtApi(int index)
Note: if live data is used (getModel()
is not null), the returned
item might NOT be loaded yet. To ensure it is loaded, you have to invoke
renderItem(org.zkoss.zul.Listitem)
.
removeItemAtApi
in interface Listbox
public void setPagingPosition(java.lang.String pagingPosition)
setPagingPosition
in interface Listbox
pagingPosition
- how to position. It can only be "bottom" (the default), or
"top", or "both".public java.lang.String getPagingPosition()
getPagingPosition
in interface Paginated
public Paginal getPaginal()
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 listbox will rely on the paging
controller to handle long-content instead of scrolling.
getPaginal
in interface Listbox
public void setPaginal(Paginal pgi)
Listbox
Component.getMold()
is "paging".
It is OK, though without any effect, to specify a paging controller even if mold is not "paging".
setPaginal
in interface Listbox
pgi
- the paging controller. If null and Component.getMold()
is
"paging", a paging controller is created automatically as a
child component (see Listbox.getPagingChildApi()
).public Paging getPagingChild()
setPaginal(org.zkoss.zul.ext.Paginal)
.
public Paging getPagingChildApi()
setPaginal(org.zkoss.zul.ext.Paginal)
.
getPagingChildApi
in interface Listbox
public int getPageSize()
getPageSize
in interface Listbox
java.lang.IllegalStateException
- if getPaginal()
returns null, i.e., mold is not
"paging" and no external controller is specified.public void setPageSize(int pgsz) throws WrongValueException
setPageSize
in interface Listbox
java.lang.IllegalStateException
- if getPaginal()
returns null, i.e., mold is not
"paging" and no external controller is specified.
WrongValueException
public int getPageCount()
getPageCount
in interface Listbox
public int getActivePage()
getActivePage
in interface Listbox
public void setActivePage(int pg) throws WrongValueException
setActivePage
in interface Listbox
WrongValueException
setActivePage(Listitem)
public void setActivePage(Listitem item)
item
- the item to show. If the item is null or doesn't belong to
this listbox, nothing happens.setActivePage(int)
public void setActivePage(Listitem itemApi)
setActivePage
in interface Listbox
itemApi
- assume as a Listitem
setActivePage(int)
public int getVisibleItemCount()
Listitem
.
getVisibleItemCount
in interface Listbox
public java.lang.String getOddRowSclass()
Default: getZclass()
-odd. (since 3.5.0)
getOddRowSclass
in interface Listbox
public void setOddRowSclass(java.lang.String scls)
setOddRowSclass
in interface Listbox
public int getGroupCount()
getGroupCount
in interface Listbox
public java.util.List getGroups()
Listgroup
.
getGroups
in interface Listbox
public boolean hasGroup()
hasGroup
in interface Listbox
protected void smartUpdate(java.lang.String attr, java.lang.Object value)
AbstractComponent
The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution.
This method has no effect if AbstractComponent.invalidate()
is ever invoked
(in the same execution), since AbstractComponent.invalidate()
assumes
the whole content shall be redrawn and all smart updates to
this components can be ignored,
Once AbstractComponent.invalidate()
is called, all invocations to AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)
will then be ignored, and AbstractComponent.redraw(java.io.Writer)
will be invoked later.
It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.
There are two ways to draw a component, one is to invoke
Component.invalidate()
, and the other is AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)
.
While Component.invalidate()
causes the whole content to redraw,
AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)
let component developer control which part
to redraw.
smartUpdate
in class AbstractComponent
value
- the new value.
If it is DeferredValue
, the value
will be retrieved (by calling DeferredValue.getValue()
)
in the rendering phase. It is useful if the value can not be determined now.
For some old application servers (example, Webshpere 5.1),
Execution.encodeURL(java.lang.String)
cannot be called in the event processing
thread. So, the developers have to use DeferredValue
or disable the use of the event processing thread
(by use of disable-event-thread
in zk.xml).
In addition, the value can be any kind of objects that the client accepts (marshaled by JSON).
AbstractComponent.updateByClient(java.lang.String, java.lang.Object)
public void beforeChildAdded(Component newChild, Component refChild)
AbstractComponent
beforeChildAdded
in interface ComponentCtrl
beforeChildAdded
in class AbstractComponent
newChild
- the child to be added (never null).refChild
- another child component that the new child
will be inserted before it. If null, the new child will be the
last child.ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)
public boolean insertBefore(Component newChild, Component refChild)
Component
You could use Component.setParent(org.zkoss.zk.ui.Component)
or Component.appendChild(org.zkoss.zk.ui.Component)
instead of this method, unless
you want to control where to put the child.
Note: Component.setParent(org.zkoss.zk.ui.Component)
always calls back Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)
and/or Component.removeChild(org.zkoss.zk.ui.Component)
,
while Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)
and Component.removeChild(org.zkoss.zk.ui.Component)
always calls back Component.setParent(org.zkoss.zk.ui.Component)
,
if the parent is changed. Thus, you don't need to override
both Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)
and Component.setParent(org.zkoss.zk.ui.Component)
, if you want
to customize the behavior.
insertBefore
in interface Component
insertBefore
in class AbstractComponent
newChild
- the new child to be inserted.refChild
- the child before which you want the new child
being inserted. If null, the new child is append to the end.
public boolean removeChild(Component child)
removeChild
in interface Component
removeChild
in class AbstractComponent
protected void afterInsert(Component comp)
Note: it won't be called if other kind of child is inserted.
When this method is called, the index is correct.
Default: invalidate if it is the paging mold and it affects the view of the active page.
protected void beforeRemove(Component comp)
Default: invalidate if it is the paging mold and it affects the view of the active page.
public java.util.Iterator getVisibleChildrenIterator()
getVisibleItemCount()
, it handles only the direct children.
Component developer only.
public ListModel getModel()
Note: if setModel(GroupsModel)
was called with a groups model,
this method returns an instance of ListModel
encapsulating it.
getModel
in interface Listbox
setModel(ListModel)
,
setModel(GroupsModel)
public ListModel getListModel()
GroupsModel
or not associated with
any list data model.
getListModel
in interface Listbox
setModel(ListModel)
public GroupsModel getGroupsModel()
ListModel
or not associated with
any list data model.
getGroupsModel
in interface Listbox
setModel(GroupsModel)
public void setModel(ListModel model)
setModel
in interface Listbox
model
- the list model to associate, or null to dis-associate any
previous model.
UiException
- if failed to initialize with the modelgetListModel()
,
setModel(GroupsModel)
public void setModel(GroupsModel model)
The groups model is used to represent a list of data with grouping.
setModel
in interface Listbox
model
- the groups model to associate, or null to dis-associate any
previous model.
UiException
- if failed to initialize with the modelsetModel(ListModel)
,
getGroupsModel()
public ListitemRenderer getItemRenderer()
getItemRenderer
in interface Listbox
public void setItemRenderer(ListitemRenderer renderer)
getModel()
is not null.
Note: changing a render will not cause the listbox 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.
setItemRenderer
in interface Listbox
renderer
- the renderer, or null to use the default.
UiException
- if failed to initialize with the modelpublic void setItemRenderer(java.lang.String clsnm) throws java.lang.ClassNotFoundException, java.lang.NoSuchMethodException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.reflect.InvocationTargetException
setItemRenderer
in interface Listbox
java.lang.ClassNotFoundException
java.lang.NoSuchMethodException
java.lang.IllegalAccessException
java.lang.InstantiationException
java.lang.reflect.InvocationTargetException
public int getPreloadSize()
Default: 7.
It is used only if live data (setModel(ListModel)
and not paging
(getPagingChild()
.
Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.(@since 3.0.4)
getPreloadSize
in interface Listbox
public void setPreloadSize(int sz)
It is used only if live data (setModel(ListModel)
and not paging
(getPagingChild()
.
setPreloadSize
in interface Listbox
sz
- the number of items to preload. If zero, no preload at all.
UiException
- if sz is negativepublic void onInitRender()
public Listitem renderItem(Listitem li)
Listitem
if not loaded yet, with
getItemRenderer()
.
It does nothing if getModel()
returns null. In other words, it is
meaningful only if live data model is used.
renderItems(java.util.Set)
,
renderAll()
public Listitem renderItemApi(Listitem itemApi)
Listitem
if not loaded yet, with
getItemRenderer()
.
It does nothing if getModel()
returns null. In other words, it is
meaningful only if live data model is used.
renderItemApi
in interface Listbox
itemApi
- assume as a Listitem
renderItems(java.util.Set)
,
renderAll()
public void renderAll()
Listitem
if not loaded yet, with
getItemRenderer()
.
renderAll
in interface Listbox
renderItem(org.zkoss.zul.Listitem)
,
renderItems(java.util.Set)
public void renderItems(java.util.Set items)
renderItems
in interface Listbox
public void setMold(java.lang.String mold)
Component
setMold
in interface Component
setMold
in class AbstractComponent
mold
- the mold. If null or empty, "default" is assumed.ComponentDefinition
public java.lang.String getZclass()
HtmlBasedComponent
Default: null (the default value depends on element).
HtmlBasedComponent.setZclass(java.lang.String)
) will completely replace the default style
of a component. In other words, the default style of a component
is associated with the default value of HtmlBasedComponent.getZclass()
.
Once it is changed, the default style won't be applied at all.
If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String)
instead.
getZclass
in interface HtmlBasedComponent
getZclass
in class HtmlBasedComponent
HtmlBasedComponent.getSclass()
public void onPageAttached(Page newpage, Page oldpage)
AbstractComponent
onPageAttached
in interface ComponentCtrl
onPageAttached
in class AbstractComponent
newpage
- the new page (never null).oldpage
- the previous page, if any, or null if it didn't
belong to any page.ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)
public java.lang.Object clone()
Component
clone
in interface Component
clone
in class AbstractComponent
public void sessionWillPassivate(Page page)
ComponentCtrl
Note: only root components are notified by this method.
sessionWillPassivate
in interface ComponentCtrl
sessionWillPassivate
in class AbstractComponent
public void sessionDidActivate(Page page)
ComponentCtrl
Note: only root components are notified by this method.
sessionDidActivate
in interface ComponentCtrl
sessionDidActivate
in class AbstractComponent
protected void renderProperties(ContentRenderer renderer) throws java.io.IOException
HtmlBasedComponent
See also Render Special Properties
renderProperties
in class XulElement
java.io.IOException
public void service(AuRequest request, boolean everError)
Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean)
,
it also handles onSelect.
service
in interface ComponentCtrl
service
in class HtmlBasedComponent
everError
- whether any error ever occured before
processing this request.AbstractComponent.setAuService(org.zkoss.zk.au.AuService)
protected java.lang.Object newExtraCtrl()
HtmlBasedComponent
AbstractComponent.getExtraCtrl()
to create a client control.
It is used only by component developers.
Defaut: creates an instance of HtmlBasedComponent.ExtraCtrl
.
newExtraCtrl
in class HtmlBasedComponent
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |