public class Combobox extends Textbox
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).
Comboitem
,
Serialized FormModifier and Type | Class and Description |
---|---|
protected class |
Combobox.ExtraCtrl
A utility class to implement
HtmlBasedComponent.getExtraCtrl() . |
_value
Modifier and Type | Method and 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) . |
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(ComboitemRenderer<?> renderer)
Sets the renderer which is used to render each row
if
getModel() is not null. |
void |
setItemRenderer(String clsnm)
Sets the renderer by use of a class name.
|
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.
|
checkBeforeSetRows, coerceFromString, getRows, getType, getValue, isMultiline, isSubmitByEnter, isTabbable, setHeight, setSubmitByEnter, setTabbable, setType, setValue, setVflex
checkUserError, clearErrorMessage, clearErrorMessage, getCols, getConstraint, 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
getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes
addSclass, focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
addAnnotation, addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, enableBindingAnnotation, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, 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, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize
public Combobox()
public Combobox(String value) throws org.zkoss.zk.ui.WrongValueException
org.zkoss.zk.ui.WrongValueException
protected String coerceToString(Object value)
Textbox
Textbox.setValue(java.lang.String)
.
Default: convert null to an empty string.
coerceToString
in class Textbox
public <T> ListModel<T> getModel()
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)
.
ListSubModel.getSubModel(Object, int)
public void setModel(ListModel<?> model)
model
- the list model to associate, or null to dissociate
any previous model.org.zkoss.zk.ui.UiException
- if failed to initialize with the modelpublic void setEmptySearchMessage(String msg)
msg
- public <T> ComboitemRenderer<T> getItemRenderer()
public void setItemRenderer(ComboitemRenderer<?> renderer)
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.
renderer
- the renderer, or null to use the default.org.zkoss.zk.ui.UiException
- if failed to initialize with the modelpublic void setItemRenderer(String clsnm) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException
public void onInitRender(org.zkoss.zk.ui.event.Event data)
public boolean isAutodrop()
Default: false.
public void setAutodrop(boolean autodrop)
public boolean isAutocomplete()
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.
public void setAutocomplete(boolean autocomplete)
Comboitem
.public boolean isOpen()
Default: false.
public void setOpen(boolean open)
Comboitem
.
only works while visiblepublic void open()
Comboitem
.
It is the same as setOpen(true).public void close()
Comboitem
if it was
dropped down.
It is the same as setOpen(false).public boolean isButtonVisible()
Default: true.
public void setButtonVisible(boolean visible)
public boolean isInstantSelect()
Default: true
public void setInstantSelect(boolean instantSelect)
public List<Comboitem> getItems()
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.
public int getItemCount()
public Comboitem getItemAtIndex(int index)
public Comboitem removeItemAt(int index)
public Comboitem getSelectedItem()
public void setSelectedItem(Comboitem 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
.
public void setSelectedIndex(int jsel)
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
.
public int getSelectedIndex()
public String getPopupWidth()
public void setPopupWidth(String popupWidth)
popupWidth
- the width of the popup of this componentpublic void setMultiline(boolean multiline)
Textbox
setMultiline
in class Textbox
public void setRows(int rows)
Textbox
Note: Not allowed to set rows and height/vflex at the same time
public Object getExtraCtrl()
getExtraCtrl
in interface org.zkoss.zk.ui.sys.ComponentCtrl
getExtraCtrl
in class org.zkoss.zk.ui.HtmlBasedComponent
public void setIconSclass(String iconSclass)
iconSclass
- Stringpublic String getIconSclass()
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
renderProperties
in class Textbox
IOException
public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
Default: in addition to what are handled by InputElement.service(org.zkoss.zk.au.AuRequest, boolean)
,
it also handles onOpen and onSelect.
service
in interface org.zkoss.zk.ui.sys.ComponentCtrl
service
in class InputElement
public void beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
beforeChildAdded
in interface org.zkoss.zk.ui.sys.ComponentCtrl
beforeChildAdded
in class org.zkoss.zk.ui.AbstractComponent
protected boolean isChildable()
isChildable
in class InputElement
public void onChildAdded(org.zkoss.zk.ui.Component child)
onChildAdded
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onChildAdded
in class org.zkoss.zk.ui.AbstractComponent
public void onChildRemoved(org.zkoss.zk.ui.Component child)
onChildRemoved
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onChildRemoved
in class org.zkoss.zk.ui.AbstractComponent
public Object clone()
public void sessionWillPassivate(org.zkoss.zk.ui.Page page)
sessionWillPassivate
in interface org.zkoss.zk.ui.sys.ComponentCtrl
sessionWillPassivate
in class org.zkoss.zk.ui.AbstractComponent
public void sessionDidActivate(org.zkoss.zk.ui.Page page)
sessionDidActivate
in interface org.zkoss.zk.ui.sys.ComponentCtrl
sessionDidActivate
in class org.zkoss.zk.ui.AbstractComponent
public org.zkoss.zk.ui.sys.PropertyAccess getPropertyAccess(String prop)
getPropertyAccess
in interface org.zkoss.zk.ui.sys.ComponentCtrl
getPropertyAccess
in class Textbox
public void onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
onPageAttached
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onPageAttached
in class org.zkoss.zk.ui.AbstractComponent
public void onPageDetached(org.zkoss.zk.ui.Page page)
onPageDetached
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onPageDetached
in class org.zkoss.zk.ui.AbstractComponent
Copyright © 2019. All rights reserved.