org.zkoss.zul
Class Bandbox

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, HtmlBasedComponent, Component, Scope, ComponentCtrl, Bandbox, Textbox, Constrainted, InputElement, XulElement

public class Bandbox
extends Textbox
implements Bandbox

A band box. A bank box consists of an input box (Textbox and a popup window Bandpopup. It is similar to Combobox except the popup window could have any kind of children. For example, you could place a textbox in the popup to let user search particular items.

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

Events: onOpen
Developers can listen to the onOpen event and initializes it when OpenEvent.isOpen() is true, and/or clean up if false.

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

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zul.impl.InputElement

InputElement.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, RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

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

_visible

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

Bandbox()

Bandbox(java.lang.String value)

Method Summary

void	beforeChildAdded(Component newChild, Component refChild) Default: does nothing.
java.lang.Object	clone() Clones the component.
void	close() Closes the child if it was dropped down.
void	closeDropdown() Deprecated. As of release 3.6.1, use close() instead.
Bandpopup	getDropdown() Returns the dropdown window belonging to this band box.
Bandpopup	getDropdownApi() Returns the dropdown window belonging to this band box.
java.lang.String	getImage() Deprecated. As of release 3.5.0
java.lang.String	getInnerAttrs() Generates the Client-Side-Action attributes to the interior tag.
java.lang.String	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
protected int	getRealStyleFlags() Returns RS_NO_WIDTH|RS_NO_HEIGHT.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	insertBefore(Component newChild, Component refChild) Inserts a child before the reference child.
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.
boolean	isChildable() Childable.
void	onChildRemoved(Component child) Default: does nothing.
void	open() Drops down the child.
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	setImage(java.lang.String img) Deprecated. As of release 3.5.0
void	setMultiline(boolean multiline) Bandbox can't be enabled the multiline functionality.
void	setOpen(boolean open) Drops down or closes the child.
void	setRows(int rows) Bandbox can't be enabled the rows functionality.

Methods inherited from class org.zkoss.zul.Textbox

coerceFromString, coerceToString, getRows, getType, getValue, isMultiline, isTabbable, setTabbable, setType, setValue

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

checkUserError, clearErrorMessage, clearErrorMessage, getAreaText, getCols, getConstraint, getErrorMessage, getMaxlength, getName, getRawText, getRawValue, getTabindex, getTargetValue, getText, isDisabled, isReadonly, isValid, newExtraCtrl, onWrongValue, select, setCols, setConstraint, setConstraint, setDisabled, setMaxlength, setName, setRawValue, setReadonly, setSelectedText, setSelectionRange, setTabindex, setText, setValueDirectly, shallServerFormat, showCustomError, validate

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

getAction, getActionAttrs, getAllOnClickAttrs, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

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

focus, getAllOnClickAttrs, getDraggable, getDroppable, getHeight, getLeft, getMoldSclass, getRealSclass, getRealStyle, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, redraw, setClass, setDraggable, setDroppable, setFocus, setHeight, setLeft, setMoldSclass, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

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

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, containsVariable, detach, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, invalidate, isAsapRequired, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onDrawNewChild, onPageAttached, onPageDetached, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.zkoss.zul.api.Textbox

getRows, getValue, setType, setValue

Methods inherited from interface org.zkoss.zul.impl.api.InputElement

clearErrorMessage, clearErrorMessage, getAreaText, getCols, getErrorMessage, getMaxlength, getName, getRawText, getRawValue, getTabindex, getText, getType, isDisabled, isMultiline, isReadonly, isValid, select, setCols, setConstraint, setDisabled, setMaxlength, setName, setRawValue, setReadonly, setSelectedText, setSelectionRange, setTabindex, setText

Methods inherited from interface org.zkoss.zul.impl.api.XulElement

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

Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent

focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from interface org.zkoss.zk.ui.Component

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, invalidate, isInvalidated, isListenerAvailable, isVisible, redraw, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Methods inherited from interface org.zkoss.zul.ext.Constrainted

getConstraint, setConstraint

Constructor Detail

Bandbox

public Bandbox()

Bandbox

public Bandbox(java.lang.String value)
        throws WrongValueException

Throws:

WrongValueException

Method Detail

getDropdown

public Bandpopup getDropdown()

Returns the dropdown window belonging to this band box.

getDropdownApi

public Bandpopup getDropdownApi()

Returns the dropdown window belonging to this band box.

Specified by:

getDropdownApi in interface Bandbox

Since:

3.5.2

closeDropdown

public void closeDropdown()

Deprecated. As of release 3.6.1, use close() instead.

Description copied from interface: Bandbox

Closes the popup (Bandbox.getDropdownApi()).

Specified by:

closeDropdown in interface Bandbox

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.

Specified by:

setAutodrop in interface Bandbox

isButtonVisible

public boolean isButtonVisible()

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

Default: true.

Specified by:

isButtonVisible in interface Bandbox

setButtonVisible

public void setButtonVisible(boolean visible)

Sets whether the button (on the right of the textbox) is visible.

Specified by:

setButtonVisible in interface Bandbox

getImage

public java.lang.String getImage()

Deprecated. As of release 3.5.0

Returns the image URI that is displayed as the button to open Bandpopup. Default: null. (since 3.5.0)

setImage

public void setImage(java.lang.String img)

Deprecated. As of release 3.5.0

Sets the image URI that is displayed as the button to open Bandpopup.

Parameters:

img - the image URI.

setOpen

public void setOpen(boolean open)

Drops down or closes the child.

Specified by:

setOpen in interface Bandbox

Since:

3.0.1

See Also:

open(), close()

open

public void open()

Drops down the child. The same as setOpen(true).

Specified by:

open in interface Bandbox

Since:

3.0.1

close

public void close()

Closes the child if it was dropped down. The same as setOpen(false).

Specified by:

close in interface Bandbox

Since:

3.0.1

setMultiline

public void setMultiline(boolean multiline)

Bandbox can't be enabled the multiline functionality.

Specified by:

setMultiline in interface Textbox

Overrides:

setMultiline in class Textbox

setRows

public void setRows(int rows)

Bandbox can't be enabled the rows functionality.

Specified by:

setRows in interface Textbox

Overrides:

setRows in class Textbox

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 (@{link #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.

Specified by:

getZclass in interface HtmlBasedComponent

Overrides:

getZclass in class Textbox

See Also:

HtmlBasedComponent.getSclass(), HtmlBasedComponent.getRealSclass()

getOuterAttrs

public java.lang.String getOuterAttrs()

Description copied from class: HtmlBasedComponent

Returns the exterior attributes for generating the enclosing HTML tag; never return null.

Used only by component developers.

Default: Generates the tooltip text, style, sclass, draggable and droppable attribute if necessary. In other words, the corresponding attribute is generated if HtmlBasedComponent.getTooltiptext(), HtmlBasedComponent.getRealStyle(), HtmlBasedComponent.getSclass(), HtmlBasedComponent.getDraggable(), HtmlBasedComponent.getDroppable() are defined.

You have to call both HtmlBasedComponent.getOuterAttrs() and HtmlBasedComponent.getInnerAttrs() to generate complete attributes.

For simple components that all attributes are put on the outest HTML element, all you need is as follows.

<xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}>

If you want to put attributes in a nested HTML element, you shall use the following pattern. Notice: if HtmlBasedComponent.getInnerAttrs() in a different tag, the tag must be named with "${self.uuid}!real".

<xx id="${self.uuid}"${self.outerAttrs}>
 <yy id="${self.uuid}!real"${self.innerAttrs}>...

Note: This class handles non-deferrable event listeners automatically. However, you have to invoke AbstractComponent.appendAsapAttr(java.lang.StringBuffer, java.lang.String) for each event the component handles in HtmlBasedComponent.getOuterAttrs() as follows.

        appendAsapAttr(sb, Events.ON_OPEN);
  appendAsapAttr(sb, Events.ON_CHANGE);

Theorectically, you could put any attributes in either HtmlBasedComponent.getInnerAttrs() or HtmlBasedComponent.getOuterAttrs(). However, zkau.js assumes all attributes are put at the outer one. If you want something different, you have to provide your own setAttr (refer to how checkbox is implemented).

Overrides:

getOuterAttrs in class Textbox

getInnerAttrs

public java.lang.String getInnerAttrs()

Description copied from class: XulElement

Generates the Client-Side-Action attributes to the interior tag. Reason: onfocus is the main use.

Overrides:

getInnerAttrs in class Textbox

getRealStyleFlags

protected int getRealStyleFlags()

Returns RS_NO_WIDTH|RS_NO_HEIGHT.

Overrides:

getRealStyleFlags in class HtmlBasedComponent

beforeChildAdded

public void beforeChildAdded(Component newChild,
                             Component refChild)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

beforeChildAdded in interface ComponentCtrl

Overrides:

beforeChildAdded in class AbstractComponent

Parameters:

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

insertBefore

public boolean insertBefore(Component newChild,
                            Component refChild)

Description copied from interface: Component

Inserts a child before the reference child.

You could use Component.setParent(org.zkoss.zk.ui.Component) or Component.appendChild(org.zkoss.zk.ui.Component) instead of this method, unless you want to control where to put the child.

Note: Component.setParent(org.zkoss.zk.ui.Component) always calls back Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and/or Component.removeChild(org.zkoss.zk.ui.Component), while Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.removeChild(org.zkoss.zk.ui.Component) always calls back Component.setParent(org.zkoss.zk.ui.Component), if the parent is changed. Thus, you don't need to override both Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.setParent(org.zkoss.zk.ui.Component), if you want to customize the behavior.

Specified by:

insertBefore in interface Component

Overrides:

insertBefore in class AbstractComponent

Parameters:

newChild - the new child to be inserted.

refChild - the child before which you want the new child being inserted. If null, the new child is append to the end.

Returns:

true if newChild is added successfully or moved; false if it already has the specified child and the order doesn't change.

isChildable

public boolean isChildable()

Childable.

Specified by:

isChildable in interface Component

Overrides:

isChildable in class InputElement

onChildRemoved

public void onChildRemoved(Component child)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

onChildRemoved in interface ComponentCtrl

Overrides:

onChildRemoved in class AbstractComponent

See Also:

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

clone

public java.lang.Object clone()

Description copied from interface: Component

Clones the component. All of its children is cloned. Notice that the cloned component doesn't belong to any page, nor desktop. It doesn't have parent, either.

Specified by:

clone in interface Component

Overrides:

clone in class AbstractComponent