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:

  • 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