Package org.zkoss.zul

Class Listbox

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl, Paginated
    public class Listbox
extends MeshElement
    A listbox.

    Event:

    1. SelectEvent is sent when user changes the selection.
    2. onAfterRender is sent when the model's data has been rendered.(since 5.0.4)
    3. onCheckSelectAll is sent when user click on selectAll checkbox.(since 6.5.5)

    See Specification.

    Besides creating Listitem programmatically, 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)

    To retrieve what are selected in Listbox with a Selectable ListModel, 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 Selectable ListModel.

    
 Set selection = ((Selectable)getModel()).getSelection();

    [Since 6.0.0] If a model is set, whether the listbox allows the multiple selection depends on Selectable.setMultiple(boolean). In other words, the application shall not access listbox directly if a model is assigned. Rather, the application shall access the model directly.

    There are two ways to handle long content: scrolling and paging. If AbstractComponent.getMold() is "default", scrolling is used if 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).

    Clustering and Serialization

    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.

    Render on Demand (rod)

    [ZK EE] [Since 5.0.0]

    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 Listitems 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 setHeight(String),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.

    
	<library-property>
		<name>org.zkoss.zul.listbox.rod</name>
		<value>true</value>
	</library-property>

    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:

    
	<listbox ...>
    <custom-attributes org.zkoss.zul.listbox.rod="true"/>
  </listbox>

    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 Listitems are created and rendered in the Listbox if you turn the ROD on, there will be some limitations on accessing Listitems. 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.

    Custom Attributes

    org.zkoss.zul.listbox.rightSelect
    Specifies whether the selection shall be toggled when user right clicks on item, if the checkmark (isCheckmark()) is enabled.
    Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
    org.zkoss.zul.listbox.rod
    Specifies whether to enable ROD (render-on-demand).
    Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
    org.zkoss.zul.listbox.autoSort
    .(since 5.0.7)
    Specifies whether to sort the model when the following cases:
    1. setModel(org.zkoss.zul.ListModel<?>) is called and Listheader.setSortDirection(java.lang.String) is set.
    2. Listheader.setSortDirection(java.lang.String) is called.
    3. Model receives ListDataEvent and Listheader.setSortDirection(java.lang.String) is set.
    If you want to ignore sort when receiving ListDataEvent, you can specifies the value as "ignore.change".
    Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
    org.zkoss.zul.listbox.groupSelect
    Specifies whether Listgroups under this Listbox are selectable. Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited. Default value is false.
    org.zkoss.zul.listbox.preloadSize
    .(since 5.0.8)
    Specifies the number of items to preload when receiving the rendering request from the client.

    It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

    org.zkoss.zul.listbox.initRodSize
    .(since 5.0.8)
    Specifies the number of items rendered when the Listbox first render.

    It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

    org.zkoss.zul.listbox.selectOnHighlight.disabled
    .(since 7.0.4)
    Sets whether to disable select functionality when highlighting text content with mouse dragging or not.
    Author:
    tomyeh
    See Also:
    ListModel, ListitemRenderer, ListitemRendererExt, Serialized Form

    • Constructor Detail

      • Listbox

        public Listbox()

    • Method Detail

      • getListhead

        public Listhead getListhead()
        Returns Listhead belonging to this listbox, or null if no list headers at all.

      • getListfoot

        public Listfoot getListfoot()
        Returns Listfoot belonging to this listbox, or null if no list footers at all.

      • getFrozen

        public Frozen getFrozen()
        Returns the frozen child.
        Since:
        5.0.0

      • getHeads

        public java.util.Collection<Component> getHeads()
        Returns a collection of heads, including getListhead() and auxiliary heads (Auxhead) (never null).
        Since:
        3.0.0

      • isCheckmark

        public boolean isCheckmark()
        Returns whether the check mark shall be displayed in front of each item.

        Default: false.

      • setCheckmark

        public void setCheckmark​(boolean checkmark)
        Sets whether the check mark shall be displayed in front of each item.

        The check mark is a checkbox if isMultiple() returns true. It is a radio button if isMultiple() returns false.

      • setInnerWidth

        public 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.
        Since:
        3.0.0

      • getInnerWidth

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

        Default: "100%"

        Since:
        3.0.0
        See Also:
        setInnerWidth(java.lang.String)

      • isVflex

        public boolean isVflex()
        Returns whether to grow and shrink vertical to fit their given space, so called vertical flexibility.

        Note: this attribute is ignored if setRows(int) is specified

        Default: false.

      • setVflex

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

        Note: this attribute is ignored if setRows(int) is specified

      • setVflex

        public void setVflex​(java.lang.String flex)
        Description copied from class: HtmlBasedComponent
        Sets vertical flexibility hint of this component.

        Number flex indicates how this component's container distributes remaining empty space among its children vertically. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, according to their flex ratios.

        Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

        Special flex hint, "min", indicates that the minimum space shall be given to this flexible component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

        Overrides:
        setVflex in class HtmlBasedComponent
        Parameters:
        flex - the vertical flex hint.
        See Also:
        HtmlBasedComponent.setHflex(java.lang.String), HtmlBasedComponent.getVflex()

      • isDisabled

        public boolean isDisabled()
        Returns whether it is disabled.

        Default: false.

      • setDisabled

        public void setDisabled​(boolean disabled)
        Sets whether it is disabled.

        Note that it is only applied when mold is "select".

      • getRows

        public int getRows()
        Returns the rows. Zero means no limitation.

        Default: 0.

      • getSeltype

        public java.lang.String getSeltype()
        Returns the seltype.

        Default: "single".

      • isMultiple

        public boolean isMultiple()
        Returns whether multiple selections are allowed.

        Default: false.

      • setMultiple

        public void setMultiple​(boolean multiple)
        Sets whether multiple selections are allowed.

        Notice that, if a model is assigned, it will change the model's state (by Selectable.setMultiple(boolean)).

      • getMaxlength

        public int getMaxlength()
        Returns the maximal length of each item's label.

        It is meaningful only for the select mold.

      • setMaxlength

        public void setMaxlength​(int maxlength)
        Sets the maximal length of each item's label.

        It is meaningful only for the select mold.

      • getName

        public java.lang.String getName()
        Returns the name of this component.

        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.

      • setName

        public void setName​(java.lang.String name)
        Sets the name of this component.

        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.

        Parameters:
        name - the name of this component.

      • setNonselectableTags

        public void setNonselectableTags​(java.lang.String tags)
        Sets a list of HTML tag names that shall not cause the list item being selected if they are clicked.

        Default: null (it means button, input, textarea and a). If you want to select no matter which tag is clicked, please specify an empty string.

        Parameters:
        tags - a list of HTML tag names that will not cause the list item being selected if clicked. Specify null to use the default and "" to indicate none.
        Since:
        5.0.5

      • getNonselectableTags

        public java.lang.String getNonselectableTags()
        Returns a list of HTML tag names that shall not cause the list item being selected if they are clicked.

        Refer to setNonselectableTags(java.lang.String) for details.

        Since:
        5.0.5

      • getItems

        public java.util.List<Listitem> getItems()
        Returns a live list of all 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.

      • getItemCount

        public int getItemCount()
        Returns the number of items.

      • getItemAtIndex

        public Listitem getItemAtIndex​(int index)
        Returns the item at the specified 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).

      • getIndexOfItem

        public int getIndexOfItem​(Listitem item)
        Returns the index of the specified item, or -1 if not found.

      • getSelectedIndex

        public int getSelectedIndex()
        Returns the index of the selected item (-1 if no one is selected).

      • setSelectedIndex

        public void setSelectedIndex​(int jsel)
        Deselects all of the currently selected items and selects the item with the given index.

      • selectItem

        public void selectItem​(Listitem item)
        Deselects all of the currently selected items and selects the given item.

        It is the same as setSelectedItem(org.zkoss.zul.Listitem).

        Parameters:
        item - the item to select. If null, all items are deselected.

      • addItemToSelection

        public void addItemToSelection​(Listitem item)
        Selects the given item, without deselecting any other items that are already selected..

        Notice that if you assign a model to a listbox (setModel(org.zkoss.zul.ListModel<?>)), you shall not invoke this method directly. Rather, use Selectable instead.

      • removeItemFromSelection

        public void removeItemFromSelection​(Listitem item)
        Deselects the given item without deselecting other items.

        Notice that if you assign a model to a listbox (setModel(org.zkoss.zul.ListModel<?>)), you shall not invoke this method directly. Rather, use Selectable instead.

      • toggleItemSelection

        public void toggleItemSelection​(Listitem item)
        If the specified item is selected, it is deselected. If it is not selected, it is selected. Other items in the list box that are selected are not affected, and retain their selected state.

      • clearSelection

        public void clearSelection()
        Clears the selection.

      • selectAll

        public void selectAll()
        Selects all items.

      • setSelectedItems

        public void setSelectedItems​(java.util.Set<Listitem> listItems)
        Selects the given listitems.
        Since:
        3.6.0

      • getSelectedItems

        public java.util.Set<Listitem> getSelectedItems()
        Returns all selected items.

        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).

      • getSelectedCount

        public int getSelectedCount()
        Returns the number of items being selected.

      • appendItem

        public Listitem appendItem​(java.lang.String label,
                           java.lang.String value)
        Appends an item.

        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).

      • removeItemAt

        public Listitem removeItemAt​(int index)
        Removes the child item in the list box at the given 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).

        Returns:
        the removed item.

      • setPaginal

        public void setPaginal​(Paginal pgi)
        Specifies the paging controller. Note: the paging controller is used only if AbstractComponent.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 AbstractComponent.getMold() is "paging", a paging controller is created automatically as a child component (see getPagingChild()).

      • getPagingChild

        public 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).
        Since:
        3.0.7

      • pgi

        protected Paginal pgi()
        Description copied from class: MeshElement
        Returns the instance of the @{link Paginal}
        Specified by:
        pgi in class MeshElement

      • setActivePage

        public void setActivePage​(Listitem item)
        Sets the active page in which the specified item is. The active page will become the page that contains the specified item.
        Parameters:
        item - the item to show. If the item is null or doesn't belong to this listbox, nothing happens.
        Since:
        3.0.4
        See Also:
        setActivePage(int)

      • getVisibleItemCount

        public int getVisibleItemCount()
        Returns the number of visible descendant Listitem.
        Since:
        3.5.1

      • getOddRowSclass

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

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

        Since:
        3.0.0

      • setOddRowSclass

        public 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.
        Since:
        3.0.0

      • getGroupCount

        public int getGroupCount()
        Returns the number of listgroup
        Since:
        3.5.0

      • getGroups

        public java.util.List<Listgroup> getGroups()
        Returns a list of all Listgroup.
        Since:
        3.5.0

      • hasGroup

        public boolean hasGroup()
        Returns whether listgroup exists.
        Since:
        3.5.0

      • removeChild

        public boolean removeChild​(Component child)
        If the child is a listgroup, its listgroupfoot will be removed at the same time.
        Specified by:
        removeChild in interface Component
        Overrides:
        removeChild in class AbstractComponent
        Returns:
        true if child is removed successfully; false if it doesn't have the specified child

      • afterInsert

        protected void afterInsert​(Component comp)
        Callback if a list item has been inserted.

        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.

        Since:
        3.0.5

      • beforeRemove

        protected void beforeRemove​(Component comp)
        Callback if a list item will be removed (not removed yet). Note: it won't be called if other kind of child is removed.

        Default: invalidate if it is the paging mold and it affects the view of the active page.

        Since:
        3.0.5

      • getListModel

        public <T> ListModel<T> 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.
        Since:
        3.5.0
        See Also:
        setModel(ListModel)

      • getGroupsModel

        public <D,​G,​F> GroupsModel<D,​G,​F> 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.
        Since:
        3.5.0
        See Also:
        setModel(GroupsModel)

      • setModel

        public void setModel​(ListModel<?> model)
        Sets the list model associated with this listbox. 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. If not null, it must implement Selectable.
        Throws:
        UiException - if failed to initialize with the model
        See Also:
        getListModel(), setModel(GroupsModel)

      • setModel

        public void setModel​(GroupsModel<?,​?,​?> model)
        Sets the groups model associated with this list box. 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
        Since:
        3.5.0
        See Also:
        setModel(ListModel), getGroupsModel()

      • getItemRenderer

        public <T> ListitemRenderer<T> getItemRenderer()
        Returns the renderer to render each item, or null if the default renderer is used.

      • setItemRenderer

        public void setItemRenderer​(ListitemRenderer<?> renderer)
        Sets the renderer which is used to render each item if 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.

        Parameters:
        renderer - the renderer, or null to use the default.
        Throws:
        UiException - if failed to initialize with the model

      • setItemRenderer

        public void setItemRenderer​(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

      • onInitRender

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

      • onPagingInitRender

        public void onPagingInitRender()
        Handles a private event, onPagingInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

      • renderItems

        public void renderItems​(java.util.Set<? extends Listitem> items)
        Renders the given set of list items.

      • setMold

        public void setMold​(java.lang.String mold)
        Sets the mold to render this component.
        Specified by:
        setMold in interface Component
        Overrides:
        setMold in class AbstractComponent
        Parameters:
        mold - the mold. If null or empty, "default" is assumed. Allowed values: default, select, paging
        See Also:
        ComponentDefinition

      • getEmptyMessage

        public java.lang.String getEmptyMessage()
        Returns the message to display when there are no items
        Returns:
        String
        Since:
        5.0.7

      • setEmptyMessage

        public void setEmptyMessage​(java.lang.String emptyMessage)
        Sets the message to display when there are no items
        Parameters:
        emptyMessage -
        Since:
        5.0.7

      • clone

        public java.lang.Object clone()
        Description copied from interface: Component
        Clones the component. All of its children and descendants are cloned. Also, ID are preserved.
        Specified by:
        clone in interface Component
        Overrides:
        clone in class XulElement
        Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

      • isSelectOnHighlightDisabled

        protected boolean isSelectOnHighlightDisabled()

      • getPropertyAccess

        public PropertyAccess getPropertyAccess​(java.lang.String prop)
        Description copied from interface: ComponentCtrl
        Returns the corresponding property access object from the given property name, if any.
        Specified by:
        getPropertyAccess in interface ComponentCtrl
        Overrides:
        getPropertyAccess in class XulElement
        Parameters:
        prop - the name of the property
        Returns:
        null it means not to support for the property name.

      • onAfterRender

        public void onAfterRender()

      • scrollToIndex

        public void scrollToIndex​(int index)
        Scroll to the specified item by the given index.
        Parameters:
        index - the index of item
        Since:
        8.5.2

      • shallUpdateScrollPos

        public void shallUpdateScrollPos​(boolean shallUpdateScrollPos)
        Sets whether to update the scroll position on init

        Default: false.

        Note: internal use only

        Parameters:
        shallUpdateScrollPos - whether update the scroll position on init
        Since:
        8.6.0