org.zkoss.zul
Class Listitem

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.Listitem

All Implemented Interfaces:

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

Direct Known Subclasses:

Listgroup, Listgroupfoot

public class Listitem
extends XulElement

A list item.

Default getZclass(): z-listitem (since 5.0.0)

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

Listitem.ExtraCtrl A utility class to implement HtmlBasedComponent.getExtraCtrl().

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

CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Listitem()

Listitem(java.lang.String label)

Listitem(java.lang.String label, T value)

Method Summary

protected void	addMoved(Component oldparent, Page oldpg, Page newpg) Called when this component is moved from the specified parent and/or page to the new page.
void	beforeChildAdded(Component child, Component refChild) Default: does nothing.
void	beforeParentChanged(Component parent) Default: does nothing.
java.lang.Object	clone() Clones the component.
java.lang.Object	getExtraCtrl() Returns the client control for this component.
java.lang.String	getImage() Returns the image of the Listcell it contains.
int	getIndex() Returns the index of this item (a.k.a., the order in the listbox).
java.lang.String	getLabel() Returns the label of the Listcell it contains, or null if no such cell.
Listbox	getListbox() Returns the list box that it belongs to.
Listgroup	getListgroup() Returns the listgroup that this item belongs to, or null.
int	getMaxlength() Returns the maximal length of each item's label.
java.lang.String	getMold() Returns the mold used to render this component.
java.lang.String	getSrc() Deprecated. As of release 3.5.0, it is redundant since it is the same getImage().
<T> T	getValue() Returns the value.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	isCheckable() Returns whether it is checkable.
boolean	isDisabled() Returns whether it is disabled.
boolean	isLoaded() Returns whether the content of this item is loaded.
boolean	isSelected() Returns whether it is selected.
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	setCheckable(boolean checkable) Sets whether it is checkable.
void	setDisabled(boolean disabled) Sets whether it is disabled.
void	setHflex(java.lang.String flex) Deprecated. as of release 6.0.0. To control the size of Listbox related components, please refer to Listbox and Listheader instead.
void	setImage(java.lang.String image) Sets the image of the Listcell it contains.
protected void	setIndex(int index)
void	setLabel(java.lang.String label) Sets the label of the Listcell it contains.
void	setSelected(boolean selected) Sets whether it is selected.
void	setSrc(java.lang.String src) Deprecated. As of release 3.5.0, it is redundant since it is the same getSrc().
void	setStubonly(boolean stubonly) Deprecated. as of release 7.0.3.
void	setStubonly(java.lang.String stubonly) Deprecated. as of release 7.0.3.
<T> void	setValue(T value) Sets the value.
boolean	setVisible(boolean visible) Sets whether this component is visible.
void	setWidth(java.lang.String width) Deprecated. as of release 6.0.0. To control the size of Listbox related components, please refer to Listbox and Listheader instead.
protected void	smartUpdate(java.lang.String name, boolean value) A special smart update to update a value in boolean.
protected void	smartUpdate(java.lang.String name, int value) A special smart update to update a value in int.
protected void	smartUpdate(java.lang.String name, java.lang.Object value) Smart-updates a property of the peer widget associated with the component, running at the client, with the given value.

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

getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

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

focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, service, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

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

addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setTemplate, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

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

Constructor Detail

Listitem

public Listitem()

Listitem

public Listitem(java.lang.String label)

Listitem

public Listitem(java.lang.String label,
                T value)

Method Detail

getListbox

public Listbox getListbox()

Returns the list box that it belongs to.

It is the same as AbstractComponent.getParent().

getListgroup

public Listgroup getListgroup()

Returns the listgroup that this item belongs to, or null.

Since:

3.5.0

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

isCheckable

public boolean isCheckable()

Returns whether it is checkable.

Default: true.

Since:

3.0.4

setCheckable

public void setCheckable(boolean checkable)

Sets whether it is checkable.

Note that it is only applied when isCheckmark() of Listbox is true.

Default: true.

Since:

3.0.4

getMaxlength

public int getMaxlength()

Returns the maximal length of each item's label. It is a shortcut of getParent().getMaxlength(); Thus, it works only if the listbox's mold is "select".

getValue

public <T> T getValue()

Returns the value.

Default: null.

Note: the value is application dependent, you can place whatever value you want.

If you are using listitem with HTML Form (and with the name attribute), it is better to specify a String-typed value.

setValue

public <T> void setValue(T value)

Sets the value.

Parameters:

value - the value.

Note: the value is application dependent, you can place whatever value you want.

If you are using listitem with HTML Form (and with the name attribute), it is better to specify a String-typed value.

setStubonly

public void setStubonly(java.lang.String stubonly)

Deprecated. as of release 7.0.3.

Please use Listcell or Listbox instead.

Specified by:

setStubonly in interface Component

Overrides:

setStubonly in class AbstractComponent

Parameters:

stubonly - whether it is stub-only. The allowed values include "true", "false" and "inherit".

setStubonly

public void setStubonly(boolean stubonly)

Deprecated. as of release 7.0.3.

Please use Listcell or Listbox instead.

Specified by:

setStubonly in interface Component

Overrides:

setStubonly in class AbstractComponent

isDisabled

public boolean isDisabled()

Returns whether it is disabled.

Default: false.

setDisabled

public void setDisabled(boolean disabled)

Sets whether it is disabled.

isSelected

public boolean isSelected()

Returns whether it is selected.

Default: false.

setSelected

public void setSelected(boolean selected)

Sets whether it is selected.

getLabel

public java.lang.String getLabel()

Returns the label of the Listcell it contains, or null if no such cell.

setLabel

public void setLabel(java.lang.String label)

Sets the label of the Listcell it contains.

If it is not created, we automatically create it.

getSrc

public java.lang.String getSrc()

Deprecated. As of release 3.5.0, it is redundant since it is the same getImage().

setSrc

public void setSrc(java.lang.String src)

Deprecated. As of release 3.5.0, it is redundant since it is the same getSrc().

getImage

public java.lang.String getImage()

Returns the image of the Listcell it contains.

setImage

public void setImage(java.lang.String image)

Sets the image of the Listcell it contains.

If it is not created, we automatically create it.

getIndex

public int getIndex()

Returns the index of this item (a.k.a., the order in the listbox).

isLoaded

public boolean isLoaded()

Returns whether the content of this item is loaded. It is meaningful only if getListbox() is live data, i.e., Listbox.getModel() is not null.

Since:

2.4.0

setIndex

protected void setIndex(int index)

setVisible

public boolean setVisible(boolean visible)

Description copied from interface: Component

Sets whether this component is visible.

Specified by:

setVisible in interface Component

Overrides:

setVisible in class AbstractComponent

Returns:

the previous visibility

smartUpdate

protected void smartUpdate(java.lang.String name,
                           java.lang.Object value)

Description copied from class: AbstractComponent

Smart-updates a property of the peer widget associated with the component, running at the client, with the given value.

The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution. If you prefer to send both updates to the client, use AbstractComponent.smartUpdate(String, Object, boolean) instead.

This method has no effect if AbstractComponent.invalidate() is ever invoked (in the same execution), since AbstractComponent.invalidate() assumes the whole content shall be redrawn and all smart updates to this components can be ignored,

Once AbstractComponent.invalidate() is called, all invocations to AbstractComponent.smartUpdate(String, Object) will then be ignored, and AbstractComponent.redraw(java.io.Writer) will be invoked later.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate(), and the other is AbstractComponent.smartUpdate(String, Object). While Component.invalidate() causes the whole content to redraw, AbstractComponent.smartUpdate(String, Object) let component developer control which part to redraw.

Overrides:

smartUpdate in class AbstractComponent

value - the new value. If it is DeferredValue, the value will be retrieved (by calling DeferredValue.getValue()) in the rendering phase. It is useful if the value can not be determined now.

For some old application servers (example, Websphere 5.1), Execution.encodeURL(java.lang.String) cannot be called in the event processing thread. So, the developers have to use DeferredValue or disable the use of the event processing thread (by use of disable-event-thread in zk.xml).

If you want to generate the JavaScript code directly (i.e., the value is a valid JavaScript snippet), you can use JavaScriptValue. Notice that the JavaScript code will be evaluated before assigning it to the widget.

If the value is a Date object, a special pattern will be generated (a.k.a., marshaling) to ensure it can be unmarshalled back correctly at the client. Notice that it is marshalled to a string based on TimeZones.getCurrent(), and then unmarshalled back at the client. In other words, if the client is in different time-zone, the value returned by getTime() might be different. However, the value will remain the same if the client marshalled the Date object back. In other words, it assumes the browser's time zone from enduser's perspective (not really browser's setting) shall be the same as TimeZones.getCurrent().

If the value is a component, a special pattern will be generated to ensure it can be unmarshalled back correctly at the client.

In addition, the value can be any kind of objects that the client accepts (marshaled by JSON) (see also JSONAware).

See Also:

AbstractComponent.updateByClient(java.lang.String, java.lang.Object), AbstractComponent.smartUpdate(String, Object, boolean)

smartUpdate

protected void smartUpdate(java.lang.String name,
                           boolean value)

Description copied from class: AbstractComponent

A special smart update to update a value in boolean.

It is the same as AbstractComponent.smartUpdate(String, Object).

Overrides:

smartUpdate in class AbstractComponent

smartUpdate

protected void smartUpdate(java.lang.String name,
                           int value)

Description copied from class: AbstractComponent

A special smart update to update a value in int.

It is the same as AbstractComponent.smartUpdate(String, Object).

Overrides:

smartUpdate in class AbstractComponent

getMold

public java.lang.String getMold()

Description copied from interface: Component

Returns the mold used to render this component.

Default: "default"

Since 5.0, the default can be overridden by specify a library property. For example, if the component's class name is org.zkoss.zul.Button, then you can override the default mold by specifying the property called "org.zkoss.zul.Button.mold" with the mold you want in zk.xml. For example,

<library-property>
  <name>org.zkoss.zul.Button.mold</name>
  <value>trendy</value>
</library-property>

Notice that it doesn't affect the deriving classes. If you want to change the deriving class's default mold, you have to specify them explicitly, too.

Specified by:

getMold in interface Component

Overrides:

getMold in class AbstractComponent

See Also:

ComponentDefinition

setWidth

public void setWidth(java.lang.String width)

Deprecated. as of release 6.0.0. To control the size of Listbox related components, please refer to Listbox and Listheader instead.

Description copied from class: HtmlBasedComponent

Sets the width. If null, the best fit is used.

Overrides:

setWidth in class HtmlBasedComponent

See Also:

HtmlBasedComponent.setWidthDirectly(java.lang.String), AbstractComponent.disableClientUpdate(boolean)

setHflex

public void setHflex(java.lang.String flex)

Deprecated. as of release 6.0.0. To control the size of Listbox related components, please refer to Listbox and Listheader instead.

Description copied from class: HtmlBasedComponent

Sets horizontal flex hint of this component.

Number flex indicates how this component's container distributes remaining empty space among its children horizontally. 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:

setHflex in class HtmlBasedComponent

Parameters:

flex - horizontal flex hint of this component.

See Also:

HtmlBasedComponent.setVflex(java.lang.String), HtmlBasedComponent.getHflex()

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 XulElement

Throws:

java.io.IOException

addMoved

protected void addMoved(Component oldparent,
                        Page oldpg,
                        Page newpg)

Description copied from class: AbstractComponent

Called when this component is moved from the specified parent and/or page to the new page.

Default: it notifies UiEngine to update the component at the client (usually remove-and-add).

It is designed to let derived classes overriding this method to disable this update. However, you rarely need to override it. One possible but rare case: the component's visual part at the client updates the visual representation at the client and then notify the component at the server to update its children accordingly. In this case, it is redundant if we ask UI Engine to send the updates to client.

Overrides:

addMoved in class AbstractComponent

Parameters:

oldparent - the parent before moved. The new parent can be found by calling AbstractComponent.getParent().

oldpg - the parent before moved.

newpg - the new page. AbstractComponent.getPage() might return the old page.

beforeParentChanged

public void beforeParentChanged(Component parent)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

beforeParentChanged in interface ComponentCtrl

Overrides:

beforeParentChanged in class AbstractComponent

Parameters:

parent - the new parent. If null, it means detachment.

See Also:

ComponentCtrl.beforeParentChanged(org.zkoss.zk.ui.Component)

beforeChildAdded

public void beforeChildAdded(Component child,
                             Component refChild)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

beforeChildAdded in interface ComponentCtrl

Overrides:

beforeChildAdded in class AbstractComponent

Parameters:

child - the child to be added (never null).

refChild - another child component that the new child will be inserted before it. If null, the new child will be the last child.

See Also:

ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

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.

getExtraCtrl

public java.lang.Object getExtraCtrl()

Description copied from class: HtmlBasedComponent

Returns the client control for this component. It is used only by component developers.

Default: creates an instance of HtmlBasedComponent.ExtraCtrl.

Specified by:

getExtraCtrl in interface ComponentCtrl

Overrides:

getExtraCtrl in class HtmlBasedComponent

Returns:

null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, Cropper.

See Also:

ComponentCtrl.getExtraCtrl()