org.zkoss.zkmax.zul

Class Searchbox<E>

java.lang.Object

org.zkoss.zk.ui.AbstractComponent

org.zkoss.zk.ui.HtmlBasedComponent

org.zkoss.zkmax.zul.Searchbox<E>

Type Parameters:

E - Element type in model

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, Disable, Scope, ComponentCtrl

public class Searchbox<E>
extends HtmlBasedComponent
implements Disable

A dropdown list that allows users to search and select items.

Available in ZK EE.

Default getZclass(): z-searchbox.

Events: onOpen, onSelect, onSearching, onAfterRender

Besides assign a list model, you could assign a renderer (a ItemRenderer instance) to a searchbox, such that the searchbox will use this renderer to render the data returned by ListModel.getElementAt(int). If not assigned, the default renderer, which assumes a label per item, is used.

Since:

9.0.0

Author:

rudyhuang

See Also:

Serialized Form

Nested Class Summary

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

HtmlBasedComponent.ExtraCtrl

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

AbstractComponent.Children

Field Summary

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_PAGE_ATTACHED, AFTER_PAGE_DETACHED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Constructors

Constructor and Description
Searchbox()

Method Summary

Modifier and Type	Method and Description
void	clearSelection() Clears the selection.
java.lang.Object	clone() Clones the component.
Converter<java.util.Collection<E>,java.lang.String>	getItemConverter() Returns the converter that generates the label text shown in the searchbox from selected items, or null to use the default implementation.
ItemRenderer<E>	getItemRenderer() Returns the renderer to render each item, or null if the default renderer is used.
ListModel<E>	getModel() Returns the model associated with this searchbox, or null if this searchbox is not associated with any list data model.
java.lang.String	getPlaceholder() Returns the placeholder text.
java.lang.String	getSearchMessage() Returns the placeholder message of the search text field, or null to use the default message.
int	getSelectedCount() Returns the number of items being selected.
E	getSelectedItem() Returns the selected item, or null if no item is selected.
java.util.Set<E>	getSelectedItems() Returns all selected items.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
void	invalidate() Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later.
boolean	isAutoclose() Returns whether to automatically close the list if a user is selected any item.
protected boolean	isChildable() Returns whether this component can have a child.
boolean	isDisabled() Returns whether it is disabled.
boolean	isMultiple() Returns whether multiple selections are allowed.
boolean	isOpen() Returns whether this searchbox is open.
void	onInitRender() Handles a private event, onInitRender.
void	onPageAttached(Page newpage, Page oldpage) Default: handles special event listeners.
void	onPageDetached(Page page) Default: handles special event listeners.
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	service(AuRequest request, boolean everError) Processes an AU request.
void	sessionDidActivate(Page page) Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
void	setAutoclose(boolean autoclose) Sets whether to automatically close the list if a user is selected any item.
void	setDisabled(boolean disabled) Sets whether it is disabled.
void	setItemConverter(Converter<java.util.Collection<E>,java.lang.String> converter) Sets the converter that generates the label text shown in the searchbox from selected items.
void	setItemConverter(java.lang.String clsnm) Sets the converter by use of a class name.
void	setItemRenderer(ItemRenderer<E> 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	setModel(ListModel<E> model) Sets the list model associated with this searchbox.
void	setMultiple(boolean multiple) Sets whether multiple selections are allowed.
void	setOpen(boolean open) Drops down or closes the list of items.
void	setPlaceholder(java.lang.String placeholder) Sets the placeholder text that is displayed when the selected item is empty.
void	setSearchMessage(java.lang.String searchMessage) Sets the placeholder message of the search text field.
void	setSelectedItem(E item) Deselects all of the currently selected items and selects the given item.
void	setSelectedItems(java.util.Collection<E> selectedItems) Selects the given items.

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

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

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

addAnnotation, addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, 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, invalidatePartial, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onWrongValue, 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

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

invalidatePartial

Constructor Detail

Searchbox

public Searchbox()

Method Detail

getModel

public ListModel<E> getModel()

Returns the model associated with this searchbox, or null if this searchbox is not associated with any list data model.

setModel

public void setModel(ListModel<E> model)

Sets the list model associated with this searchbox.

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

onInitRender

public void onInitRender()

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

getItemRenderer

public ItemRenderer<E> getItemRenderer()

Returns the renderer to render each item, or null if the default renderer is used.

setItemRenderer

public void setItemRenderer(ItemRenderer<E> renderer)

Sets the renderer which is used to render each item if getModel() is not null.

Note: changing a render will cause the searchbox to re-render.

Parameters:

renderer - the renderer, or null to use the default.

setItemRenderer

public void setItemRenderer(java.lang.String clsnm)
                     throws java.lang.ReflectiveOperationException

Sets the renderer by use of a class name. It creates an instance automatically.

Parameters:

clsnm - The class name

Throws:

java.lang.ReflectiveOperationException - if failed to initialize the renderer

getItemConverter

public Converter<java.util.Collection<E>,java.lang.String> getItemConverter()

Returns the converter that generates the label text shown in the searchbox from selected items, or null to use the default implementation. (joining by commas, i.g. "A, B, C")

setItemConverter

public void setItemConverter(Converter<java.util.Collection<E>,java.lang.String> converter)

Sets the converter that generates the label text shown in the searchbox from selected items.

Parameters:

converter - the converter, or null to use the default implementation.

setItemConverter

public void setItemConverter(java.lang.String clsnm)
                      throws java.lang.ReflectiveOperationException

Sets the converter by use of a class name. It creates an instance automatically.

Parameters:

clsnm - The class name

Throws:

java.lang.ReflectiveOperationException - if failed to initialize the converter

getSearchMessage

public java.lang.String getSearchMessage()

Returns the placeholder message of the search text field, or null to use the default message.

setSearchMessage

public void setSearchMessage(java.lang.String searchMessage)

Sets the placeholder message of the search text field.

getPlaceholder

public java.lang.String getPlaceholder()

Returns the placeholder text.

setPlaceholder

public void setPlaceholder(java.lang.String placeholder)

Sets the placeholder text that is displayed when the selected item is empty.

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

isOpen

public boolean isOpen()

Returns whether this searchbox is open.

Default: false.

setOpen

public void setOpen(boolean open)

Drops down or closes the list of items.

isDisabled

public boolean isDisabled()

Description copied from interface: Disable

Returns whether it is disabled.

Default: false.

Specified by:

isDisabled in interface Disable

setDisabled

public void setDisabled(boolean disabled)

Description copied from interface: Disable

Sets whether it is disabled.

Specified by:

setDisabled in interface Disable

isAutoclose

public boolean isAutoclose()

Returns whether to automatically close the list if a user is selected any item.

Default: false

setAutoclose

public void setAutoclose(boolean autoclose)

Sets whether to automatically close the list if a user is selected any item.

getSelectedItems

public java.util.Set<E> getSelectedItems()

Returns all selected items.

setSelectedItems

public void setSelectedItems(java.util.Collection<E> selectedItems)

Selects the given items. Must be non-null values.

getSelectedItem

public E getSelectedItem()

Returns the selected item, or null if no item is selected.

setSelectedItem

public void setSelectedItem(E item)

Deselects all of the currently selected items and selects the given item.

getSelectedCount

public int getSelectedCount()

Returns the number of items being selected.

clearSelection

public void clearSelection()

Clears the selection.

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException

Description copied from class: HtmlBasedComponent

Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:

renderProperties in class HtmlBasedComponent

Throws:

java.io.IOException

service

public void service(AuRequest request,
                    boolean everError)

Description copied from class: HtmlBasedComponent

Processes an AU request.

Default: it handles onClick, onDoubleClick, onRightClick onMove, onSize, onZIndex.

Specified by:

service in interface ComponentCtrl

Overrides:

service in class HtmlBasedComponent

everError - whether any error ever occurred before processing this request.

See Also:

AbstractComponent.setAuService(org.zkoss.zk.au.AuService)

getZclass

public java.lang.String getZclass()

Description copied from class: HtmlBasedComponent

Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (AbstractComponent.getMold()).

Default: null (the default value depends on element).

HtmlBasedComponent.setZclass(java.lang.String)) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of HtmlBasedComponent.getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String) instead.

Overrides:

getZclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getSclass()

isChildable

protected boolean isChildable()

Description copied from class: AbstractComponent

Returns whether this component can have a child.

Default: return true (means it can have children).

Overrides:

isChildable in class AbstractComponent

onPageAttached

public void onPageAttached(Page newpage,
                           Page oldpage)

Description copied from class: AbstractComponent

Default: handles special event listeners.

Specified by:

onPageAttached in interface ComponentCtrl

Overrides:

onPageAttached in class AbstractComponent

Parameters:

newpage - the new page (never null).

oldpage - the previous page, if any, or null if it didn't belong to any page.

See Also:

ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)

onPageDetached

public void onPageDetached(Page page)

Description copied from class: AbstractComponent

Default: handles special event listeners.

Specified by:

onPageDetached in interface ComponentCtrl

Overrides:

onPageDetached in class AbstractComponent

Parameters:

page - the previous page (never null)

See Also:

ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

invalidate

public void invalidate()

Description copied from interface: Component

Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.

Specified by:

invalidate in interface Component

Overrides:

invalidate in class AbstractComponent

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 HtmlBasedComponent

Returns:

the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

sessionWillPassivate

public void sessionWillPassivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).

Note: only root components are notified by this method.

Specified by:

sessionWillPassivate in interface ComponentCtrl

Overrides:

sessionWillPassivate in class AbstractComponent

sessionDidActivate

public void sessionDidActivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).

Note: only root components are notified by this method.

Specified by:

sessionDidActivate in interface ComponentCtrl

Overrides:

sessionDidActivate in class AbstractComponent