|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface 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 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
items 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 listboxes.
Default HtmlBasedComponent.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)
.
ListModel
,
ListitemRenderer
,
ListitemRendererExt
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 | |
---|---|
void |
addItemToSelectionApi(Listitem item)
Selects the given item, without deselecting any other items that are already selected.. |
Listitem |
appendItemApi(java.lang.String label,
java.lang.String value)
Appends an item. |
void |
clearSelection()
Clears the selection. |
int |
getActivePage()
Returns the active page (starting from 0). |
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 getListheadApi() and
auxiliary heads (Auxhead ) (never null). |
int |
getIndexOfItemApi(Listitem item)
Returns the index of the specified item, or -1 if not found. |
java.lang.String |
getInnerWidth()
Returns the inner width of this component. |
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 |
getListfootApi()
Returns Listfoot belonging to this listbox, or null if no list
footers 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 |
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 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 |
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. |
int |
getVisibleItemCount()
Returns the number of visible descendant Listitem . |
boolean |
hasGroup()
Returns whether listgroup exists. |
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. |
Listitem |
removeItemAtApi(int index)
Removes the child item in the list box at the given index. |
void |
removeItemFromSelectionApi(Listitem item)
Deselects the given item without deselecting other items. |
void |
renderAll()
Renders all Listitem if not loaded yet, with
getItemRenderer() . |
Listitem |
renderItemApi(Listitem li)
Renders the specified Listitem if not loaded yet, with
getItemRenderer() . |
void |
renderItems(java.util.Set items)
|
void |
selectAll()
Selects all items. |
void |
selectItemApi(Listitem item)
Deselects all of the currently selected items and selects the given item. |
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 |
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 |
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 |
setSelectedItemApi(Listitem item)
Deselects all of the currently selected items and selects the given item. |
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. |
void |
toggleItemSelectionApi(Listitem item)
If the specified item is selected, it is deselected. |
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.ext.Scope |
---|
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute |
Methods inherited from interface org.zkoss.zul.ext.Paginated |
---|
getPagingPosition |
Method Detail |
---|
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.
byContent
- boolean isSizedByContent()
Note: if the "sized-by-content" attribute of component is specified, it's prior to the original value.
setSizedByContent(boolean)
void setFixedLayout(boolean fixedLayout)
setSizedByContent(boolean)
(!fixedLayout) instead
You can also specify the "fixed-layout" attribute of component in lang-addon.xml directly, it's a top priority.
boolean isFixedLayout()
isSizedByContent()
instead
Default: false.
Note: if the "fixed-layout" attribute of component is specified, it's prior to the original value.
Listhead getListheadApi()
Listhead
belonging to this listbox, or null if no list
headers at all.
Listfoot getListfootApi()
Listfoot
belonging to this listbox, or null if no list
footers at all.
java.util.Collection getHeads()
getListheadApi()
and
auxiliary heads (Auxhead
) (never null).
void setCheckmark(boolean checkmark)
The check mark is a checkbox if isMultiple()
returns true. It is a
radio button if isMultiple()
returns false.
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.
innerWidth
- the inner width. If null, "100%" is assumed.java.lang.String getInnerWidth()
Default: "100%"
setInnerWidth(java.lang.String)
void setVflex(boolean vflex)
Note: this attribute is ignored if setRows(int)
is specified
void setDisabled(boolean disabled)
int getTabindex()
Currently, only the "select" mold supports this property.
Default: -1 (means the same as browser's default).
void setTabindex(int tabindex) throws WrongValueException
Currently, only the "select" mold supports this property.
WrongValueException
int getRows()
Default: 0.
void setRows(int rows) throws WrongValueException
Note: if both HtmlBasedComponent.setHeight(java.lang.String)
is specified with non-empty,
setRows(int)
is ignored
WrongValueException
java.lang.String getSeltype()
Default: "single".
void setSeltype(java.lang.String seltype) throws WrongValueException
WrongValueException
boolean isMultiple()
Default: false.
void setMultiple(boolean multiple)
int getMaxlength()
void setMaxlength(int maxlength)
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.
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.
name
- the name of this component.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.
int getItemCount()
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
renderItemApi(org.zkoss.zul.api.Listitem)
.
int getIndexOfItemApi(Listitem item)
int getSelectedIndex()
void setSelectedIndex(int jsel)
void selectItemApi(Listitem item)
It is the same as setSelectedItemApi(org.zkoss.zul.api.Listitem)
.
item
- the item to select. If null, all items are deselected.void addItemToSelectionApi(Listitem item)
void removeItemFromSelectionApi(Listitem item)
void toggleItemSelectionApi(Listitem item)
void clearSelection()
void selectAll()
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
renderItemApi(org.zkoss.zul.api.Listitem)
.
void setSelectedItemApi(Listitem item)
It is the same as selectItemApi(org.zkoss.zul.api.Listitem)
.
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
renderItemApi(org.zkoss.zul.api.Listitem)
.
int getSelectedCount()
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
renderItemApi(org.zkoss.zul.api.Listitem)
.
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
renderItemApi(org.zkoss.zul.api.Listitem)
.
void setPagingPosition(java.lang.String pagingPosition)
pagingPosition
- how to position. It can only be "bottom" (the default), or
"top", or "both".Paginal getPaginal()
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 listbox will rely on the paging
controller to handle long-content instead of scrolling.
void setPaginal(Paginal pgi)
Component.getMold()
is "paging".
It is OK, though without any effect, to specify a paging controller even if mold is not "paging".
pgi
- the paging controller. If null and Component.getMold()
is
"paging", a paging controller is created automatically as a
child component (see getPagingChildApi()
).Paging getPagingChildApi()
setPaginal(org.zkoss.zul.ext.Paginal)
.
int getPageSize()
java.lang.IllegalStateException
- if getPaginal()
returns null, i.e., mold is not
"paging" and no external controller is specified.void setPageSize(int pgsz) throws WrongValueException
java.lang.IllegalStateException
- if getPaginal()
returns null, i.e., mold is not
"paging" and no external controller is specified.
WrongValueException
int getPageCount()
int getActivePage()
void setActivePage(int pg) throws WrongValueException
WrongValueException
setActivePage(Listitem)
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)
int getVisibleItemCount()
Listitem
.
java.lang.String getOddRowSclass()
Default: HtmlBasedComponent.getZclass()
-odd. (since 3.5.0)
void setOddRowSclass(java.lang.String scls)
int getGroupCount()
java.util.List getGroups()
Listgroup
.
boolean hasGroup()
ListModel getModel()
Note: if setModel(GroupsModel)
was called with a groups model,
this method returns an instance of ListModel
encapsulating it.
setModel(ListModel)
,
setModel(GroupsModel)
ListModel getListModel()
GroupsModel
or not associated with
any list data model.
setModel(ListModel)
GroupsModel getGroupsModel()
ListModel
or not associated with
any list data model.
setModel(GroupsModel)
void setModel(ListModel model)
model
- the list model to associate, or null to dis-associate any
previous model.
UiException
- if failed to initialize with the modelgetListModel()
,
setModel(GroupsModel)
void setModel(GroupsModel model)
The groups model is used to represent a list of data with grouping.
model
- the groups model to associate, or null to dis-associate any
previous model.
UiException
- if failed to initialize with the modelsetModel(ListModel)
,
getGroupsModel()
ListitemRenderer getItemRenderer()
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.
renderer
- the renderer, or null to use the default.
UiException
- if failed to initialize with the modelvoid setItemRenderer(java.lang.String clsnm) throws java.lang.ClassNotFoundException, java.lang.NoSuchMethodException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.reflect.InvocationTargetException
java.lang.ClassNotFoundException
java.lang.NoSuchMethodException
java.lang.IllegalAccessException
java.lang.InstantiationException
java.lang.reflect.InvocationTargetException
int getPreloadSize()
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
void setPreloadSize(int sz)
It is used only if live data (setModel(ListModel)
and not paging
(getPagingChildApi()
.
sz
- the number of items to preload. If zero, no preload at all.
UiException
- if sz is negativeListitem renderItemApi(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()
void renderAll()
Listitem
if not loaded yet, with
getItemRenderer()
.
Listbox.renderItem(org.zkoss.zul.Listitem)
,
renderItems(java.util.Set)
void renderItems(java.util.Set items)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |