Package org.zkoss.zul

Class Combobox

java.lang.Object
org.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zul.impl.InputElement
org.zkoss.zul.Textbox
org.zkoss.zul.Combobox
All Implemented Interfaces:
Serializable, Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.ext.Disable, org.zkoss.zk.ui.ext.Readonly, org.zkoss.zk.ui.ext.Scope, org.zkoss.zk.ui.sys.ComponentCtrl, Constrainted
public class Combobox extends Textbox
A combobox.

Non-XUL extension. It is used to replace XUL menulist. This class is more flexible than menulist, such as setAutocomplete(boolean) setAutodrop(boolean).

Default getZclass(): z-combobox.(since 3.5.0)

Events: onOpen, onSelect, onAfterRender
Developers can listen to the onOpen event and initializes it when OpenEvent.isOpen() is true, and/or clean up if false.
onAfterRender is sent when the model's data has been rendered.(since 5.0.4)

Besides assign a list model, you could assign a renderer (a ComboitemRenderer instance) to a combobox, such that the combobox will use this renderer to render the data returned by ListModel.getElementAt(int). If not assigned, the default renderer, which assumes a label per combo 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). (since 3.0.2)

Note: to have better performance, onOpen is sent only if a non-deferrable event listener is registered (see Deferrable).

Like Datebox, the value of a read-only comobobox (InputElement.isReadonly()) can be changed by dropping down the list and selecting an combo item (though users cannot type anything in the input box).

Author:
tomyeh
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected class 
    Combobox.ExtraCtrl
    A utility class to implement HtmlBasedComponent.getExtraCtrl().

    Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

    org.zkoss.zk.ui.AbstractComponent.Children, org.zkoss.zk.ui.AbstractComponent.ForwardInfo, org.zkoss.zk.ui.AbstractComponent.TargetInfo

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ICON_SCLASS
     

    Fields inherited from class org.zkoss.zul.impl.InputElement

    _cols, _value

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

    _zclass

    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

    AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

  • Constructor Summary

    Constructors
    Constructor
    Description
    Combobox()
     
    Combobox(String value)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Comboitem
    appendItem(String label)
    Appends an item.
    void
    beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
     
    Object
    clone()
     
    void
    close()
    Closes the list of combo items (Comboitem if it was dropped down.
    protected String
    coerceToString(Object value)
    Coerces the value passed to Textbox.setValue(java.lang.String).
    String
    getEmptySearchMessage()
    Returns the empty search message if any.
    Object
    getExtraCtrl()
     
    String
    getIconSclass()
    Returns the iconSclass name of this Combobox.
    Comboitem
    getItemAtIndex(int index)
    Returns the item at the specified index.
    int
    getItemCount()
    Returns the number of items.
    <T> ComboitemRenderer<T>
    getItemRenderer()
    Returns the renderer to render each row, or null if the default renderer is used.
    List<Comboitem>
    getItems()
    Returns a 'live' list of all Comboitem.
    <T> ListModel<T>
    getModel()
    Returns the list model associated with this combobox, or null if this combobox is not associated with any list data model.
    String
    getPopupWidth()
     
    org.zkoss.zk.ui.sys.PropertyAccess
    getPropertyAccess(String prop)
     
    int
    getSelectedIndex()
    Returns the index of the selected item, or -1 if not selected.
    Comboitem
    getSelectedItem()
    Returns the selected item.
    String
    getZclass()
     
    boolean
    isAutocomplete()
    Returns whether to automatically complete this text box by matching the nearest item (Comboitem.
    boolean
    isAutodrop()
    Returns whether to automatically drop the list if users is changing this text box.
    boolean
    isButtonVisible()
    Returns whether the button (on the right of the textbox) is visible.
    protected boolean
    isChildable()
    Childable.
    boolean
    isInstantSelect()
    Returns true if onSelect event is sent as soon as user selects using keyboard navigation.
    boolean
    isOpen()
    Returns whether this combobox is open.
    void
    onChildAdded(org.zkoss.zk.ui.Component child)
     
    void
    onChildRemoved(org.zkoss.zk.ui.Component child)
     
    void
    onInitRender(org.zkoss.zk.ui.event.Event data)
    Handles a private event, onInitRender.
    void
    onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
     
    void
    onPageDetached(org.zkoss.zk.ui.Page page)
     
    void
    open()
    Drops down the list of combo items (Comboitem.
    Comboitem
    removeItemAt(int index)
    Removes the child item in the list box at the given index.
    protected void
    renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
     
    void
    service(org.zkoss.zk.au.AuRequest request, boolean everError)
    Processes an AU request.
    void
    sessionDidActivate(org.zkoss.zk.ui.Page page)
     
    void
    sessionWillPassivate(org.zkoss.zk.ui.Page page)
     
    void
    setAutocomplete(boolean autocomplete)
    Sets whether to automatically complete this text box by matching the nearest item (Comboitem.
    void
    setAutodrop(boolean autodrop)
    Sets whether to automatically drop the list if users is changing this text box.
    void
    setButtonVisible(boolean visible)
    Sets whether the button (on the right of the textbox) is visible.
    void
    setEmptySearchMessage(String msg)
    Sets empty search message.
    void
    setIconSclass(String iconSclass)
    Sets the iconSclass name of this Combobox.
    void
    setInstantSelect(boolean instantSelect)
    Sets the instantSelect attribute.
    void
    setItemRenderer(String clsnm)
    Sets the renderer by use of a class name.
    void
    setItemRenderer(ComboitemRenderer<?> renderer)
    Sets the renderer which is used to render each row if getModel() is not null.
    void
    setModel(ListModel<?> model)
    Sets the list model associated with this combobox.
    void
    setMultiline(boolean multiline)
    Sets whether it is multiline.
    void
    setOpen(boolean open)
    Drops down or closes the list of combo items (Comboitem.
    void
    setPopupWidth(String popupWidth)
    Sets the width of the popup of this component.
    void
    setRows(int rows)
    Sets the rows.
    void
    setSelectedIndex(int jsel)
    Deselects the currently selected items and selects the item with the given index.
    void
    setSelectedItem(Comboitem item)
    Deselects the currently selected items and selects the given item.

    Methods inherited from class org.zkoss.zul.Textbox

    checkBeforeSetRows, coerceFromString, getRows, getType, getValue, isMultiline, isSubmitByEnter, isTabbable, setHeight, setSubmitByEnter, setTabbable, setType, setValue, setVflex

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

    checkUserError, clearErrorMessage, clearErrorMessage, getCols, getConstraint, getConstraintString, getErrorboxIconSclass, getErrorboxSclass, getErrorMessage, getInputAttributes, getInstant, getMaxlength, getName, getPlaceholder, getRawText, getRawValue, getTargetValue, getText, isDisabled, isInplace, isInstant, isReadonly, isValid, marshall, onWrongValue, select, setCols, setConstraint, setConstraint, setDisabled, setErrorboxIconSclass, setErrorboxSclass, setErrorMessage, setInplace, setInputAttributes, setInputAttributes, setInsertedText, setInstant, setMaxlength, setName, setPlaceholder, setRawValue, setReadonly, setSelectedText, setSelectionRange, setText, setValueDirectly, showCustomError, unmarshall, validate

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

    getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes

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

    addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getSkeleton, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setSkeleton, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

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

    addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getStubonlyDescendants, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onParentChanged, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setStubonlyDescendants, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • Combobox

      public Combobox()

    • Combobox

      public Combobox(String value) throws org.zkoss.zk.ui.WrongValueException
      Throws:
      org.zkoss.zk.ui.WrongValueException

  • Method Details

    • coerceToString

      protected String coerceToString(Object value)
      Description copied from class: Textbox
      Coerces the value passed to Textbox.setValue(java.lang.String).

      Default: convert null to an empty string.

      Overrides:
      coerceToString in class Textbox

    • getModel

      public <T> ListModel<T> getModel()
      Returns the list model associated with this combobox, or null if this combobox is not associated with any list data model.

      Note: for implementation of auto-complete, the result of getItemCount() is a subset of model. So, if the model implemented ListSubModel interface, you can't use the index of model to find the comboitem by getItemAtIndex(int).

      Since:
      3.0.2
      See Also:

    • setModel

      public void setModel(ListModel<?> model)
      Sets the list model associated with this combobox. 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 dissociate any previous model.
      Throws:
      org.zkoss.zk.ui.UiException - if failed to initialize with the model
      Since:
      3.0.2

    • setEmptySearchMessage

      public void setEmptySearchMessage(String msg)
      Sets empty search message. This message would be displayed, when no matching results was found. Note: it's meaningless if no model case.
      Parameters:
      msg -
      Since:
      8.5.1

    • getEmptySearchMessage

      public String getEmptySearchMessage()
      Returns the empty search message if any. Default: null
      Since:
      10.0.0

    • getItemRenderer

      public <T> ComboitemRenderer<T> getItemRenderer()
      Returns the renderer to render each row, or null if the default renderer is used.
      Since:
      3.0.2

    • setItemRenderer

      public void setItemRenderer(ComboitemRenderer<?> renderer)
      Sets the renderer which is used to render each row if getModel() is not null.

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

      Parameters:
      renderer - the renderer, or null to use the default.
      Throws:
      org.zkoss.zk.ui.UiException - if failed to initialize with the model
      Since:
      3.0.2

    • setItemRenderer

      public void setItemRenderer(String clsnm) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException
      Sets the renderer by use of a class name. It creates an instance automatically.
      Throws:
      ClassNotFoundException
      NoSuchMethodException
      IllegalAccessException
      InstantiationException
      InvocationTargetException
      Since:
      3.0.2

    • onInitRender

      public void onInitRender(org.zkoss.zk.ui.event.Event data)
      Handles a private event, onInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.
      Since:
      3.0.2

    • isAutodrop

      public boolean isAutodrop()
      Returns whether to automatically drop the list if users is changing this text box.

      Default: false.

    • setAutodrop

      public void setAutodrop(boolean autodrop)
      Sets whether to automatically drop the list if users is changing this text box.

    • isAutocomplete

      public boolean isAutocomplete()
      Returns whether to automatically complete this text box by matching the nearest item (Comboitem. It is also known as auto-type-ahead.

      Default: true (since 5.0.0).

      If true, the nearest item will be searched and the text box is updated automatically. If false, user has to click the item or use the DOWN or UP keys to select it back.

      Don't confuse it with the auto-completion feature mentioned by other framework. Such kind of auto-completion is supported well by listening to the onChanging event.

    • setAutocomplete

      public void setAutocomplete(boolean autocomplete)
      Sets whether to automatically complete this text box by matching the nearest item (Comboitem.

    • isOpen

      public boolean isOpen()
      Returns whether this combobox is open.

      Default: false.

      Since:
      6.0.0

    • setOpen

      public void setOpen(boolean open)
      Drops down or closes the list of combo items (Comboitem. only works while visible
      Since:
      3.0.1

    • open

      public void open()
      Drops down the list of combo items (Comboitem. It is the same as setOpen(true).
      Since:
      3.0.1

    • close

      public void close()
      Closes the list of combo items (Comboitem if it was dropped down. It is the same as setOpen(false).
      Since:
      3.0.1

    • isButtonVisible

      public boolean isButtonVisible()
      Returns whether the button (on the right of the textbox) is visible.

      Default: true.

    • setButtonVisible

      public void setButtonVisible(boolean visible)
      Sets whether the button (on the right of the textbox) is visible.

    • isInstantSelect

      public boolean isInstantSelect()
      Returns true if onSelect event is sent as soon as user selects using keyboard navigation.

      Default: true

      Since:
      8.6.1

    • setInstantSelect

      public void setInstantSelect(boolean instantSelect)
      Sets the instantSelect attribute. When the attribute is true, onSelect event will be fired as soon as user selects using keyboard navigation. If the attribute is false, user needs to press Enter key to finish the selection using keyboard navigation.
      Since:
      8.6.1

    • getItems

      public List<Comboitem> getItems()
      Returns a 'live' list of all Comboitem. By live we mean you can add or remove them directly with the List interface.

      Currently, it is the same as AbstractComponent.getChildren(). However, we might add other kind of children in the future.

    • getItemCount

      public int getItemCount()
      Returns the number of items.

    • getItemAtIndex

      public Comboitem getItemAtIndex(int index)
      Returns the item at the specified index.

    • appendItem

      public Comboitem appendItem(String label)
      Appends an item.

    • removeItemAt

      public Comboitem removeItemAt(int index)
      Removes the child item in the list box at the given index.
      Returns:
      the removed item.

    • getSelectedItem

      public Comboitem getSelectedItem()
      Returns the selected item.
      Since:
      2.4.0

    • setSelectedItem

      public void setSelectedItem(Comboitem item)
      Deselects the currently selected items and selects the given item.

      Note: if the label of comboitem has the same more than one, the first comboitem will be selected at client side, it is a limitation of Combobox and it is different from Listbox.

      Since:
      3.0.2

    • setSelectedIndex

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

      Note: if the label of comboitem has the same more than one, the first comboitem will be selected at client side, it is a limitation of Combobox and it is different from Listbox.

      Since:
      3.0.2

    • getSelectedIndex

      public int getSelectedIndex()
      Returns the index of the selected item, or -1 if not selected.
      Since:
      3.0.1

    • getPopupWidth

      public String getPopupWidth()
      Returns:
      the width of the popup of this component
      Since:
      8.0.3

    • setPopupWidth

      public void setPopupWidth(String popupWidth)
      Sets the width of the popup of this component. If the input is a percentage, the popup width will be calculated by multiplying the width of this component with the percentage. (e.g. if the input string is 130%, and the width of this component is 300px, the popup width will be 390px = 300px * 130%) Others will be set directly.
      Parameters:
      popupWidth - the width of the popup of this component
      Since:
      8.0.3

    • setMultiline

      public void setMultiline(boolean multiline)
      Description copied from class: Textbox
      Sets whether it is multiline.
      Overrides:
      setMultiline in class Textbox

    • setRows

      public void setRows(int rows)
      Description copied from class: Textbox
      Sets the rows.

      Note: Not allowed to set rows and height/vflex at the same time

      Overrides:
      setRows in class Textbox

    • getExtraCtrl

      public Object getExtraCtrl()
      Specified by:
      getExtraCtrl in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent

    • setIconSclass

      public void setIconSclass(String iconSclass)
      Sets the iconSclass name of this Combobox.
      Parameters:
      iconSclass - String
      Since:
      8.6.2

    • getIconSclass

      public String getIconSclass()
      Returns the iconSclass name of this Combobox.
      Returns:
      the iconSclass name
      Since:
      8.6.2

    • getZclass

      public String getZclass()
      Overrides:
      getZclass in class Textbox

    • renderProperties

      protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
      Overrides:
      renderProperties in class Textbox
      Throws:
      IOException

    • service

      public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
      Processes an AU request.

      Default: in addition to what are handled by InputElement.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onOpen and onSelect.

      Specified by:
      service in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      service in class InputElement
      Since:
      5.0.0

    • beforeChildAdded

      public void beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
      Specified by:
      beforeChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      beforeChildAdded in class org.zkoss.zk.ui.AbstractComponent

    • isChildable

      protected boolean isChildable()
      Childable.
      Overrides:
      isChildable in class InputElement

    • onChildAdded

      public void onChildAdded(org.zkoss.zk.ui.Component child)
      Specified by:
      onChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onChildAdded in class org.zkoss.zk.ui.AbstractComponent

    • onChildRemoved

      public void onChildRemoved(org.zkoss.zk.ui.Component child)
      Specified by:
      onChildRemoved in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onChildRemoved in class org.zkoss.zk.ui.AbstractComponent

    • clone

      public Object clone()
      Specified by:
      clone in interface org.zkoss.zk.ui.Component
      Overrides:
      clone in class Textbox

    • sessionWillPassivate

      public void sessionWillPassivate(org.zkoss.zk.ui.Page page)
      Specified by:
      sessionWillPassivate in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      sessionWillPassivate in class org.zkoss.zk.ui.AbstractComponent

    • sessionDidActivate

      public void sessionDidActivate(org.zkoss.zk.ui.Page page)
      Specified by:
      sessionDidActivate in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      sessionDidActivate in class org.zkoss.zk.ui.AbstractComponent

    • getPropertyAccess

      public org.zkoss.zk.ui.sys.PropertyAccess getPropertyAccess(String prop)
      Specified by:
      getPropertyAccess in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getPropertyAccess in class Textbox

    • onPageAttached

      public void onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
      Specified by:
      onPageAttached in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onPageAttached in class org.zkoss.zk.ui.AbstractComponent

    • onPageDetached

      public void onPageDetached(org.zkoss.zk.ui.Page page)
      Specified by:
      onPageDetached in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onPageDetached in class org.zkoss.zk.ui.AbstractComponent