Package 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`, `Component`, `Disable`, `Readonly`, `Scope`, `ComponentCtrl`, `Constrainted`

      public class Bandbox
      extends Textbox

  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.zk.ui.HtmlBasedComponent

      `HtmlBasedComponent.ExtraCtrl`

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

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ICON_SCLASS` |

    - ### Fields inherited from class org.zkoss.zul.impl.InputElement

      `_cols, _value`

    - ### 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_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Bandbox()` |
    `Bandbox​(java.lang.String value)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `beforeChildAdded​(Component newChild, Component refChild)` | Default: does nothing.
    `void` | `close()` | Closes the child if it was dropped down.
    `Bandpopup` | `getDropdown()` | Returns the dropdown window belonging to this band box.
    `java.lang.String` | `getIconSclass()` | Returns the iconSclass name of this Bandbox.
    `java.lang.String` | `getPopupWidth()` |
    `java.lang.String` | `getZclass()` | Returns the ZK Cascading Style class for this component.
    `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` | `isOpen()` | Returns whether this bandbox is open.
    `void` | `open()` | Drops down the child.
    `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` | `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` | `setIconSclass​(java.lang.String iconSclass)` | Sets the iconSclass name of this Bandbox.
    `void` | `setMultiline​(boolean multiline)` | Bandbox can't be enabled the multiline functionality.
    `void` | `setOpen​(boolean open)` | Sets to display dropdown or close the child.
    `void` | `setPopupWidth​(java.lang.String popupWidth)` | Sets the width of the popup of this component.
    `void` | `setRows​(int rows)` | Bandbox can't be enabled the rows functionality.

    - ### Methods inherited from class org.zkoss.zul.Textbox

      `checkBeforeSetRows, clone, coerceFromString, coerceToString, getPropertyAccess, getRows, getType, getValue, isMultiline, isSubmitByEnter, isTabbable, setHeight, setSubmitByEnter, setTabbable, setType, setValue, setVflex`

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

      `checkUserError, clearErrorMessage, clearErrorMessage, getCols, getConstraint, getConstraintString, 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`

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

      `getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes`

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

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, 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`

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

      `addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, 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, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, 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`

- - ### Field Detail

    - #### ICON_SCLASS

          public static final java.lang.String ICON_SCLASS

      See Also:
        Constant Field Values

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

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

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

    - #### isOpen

          public boolean isOpen()

      Returns whether this bandbox is open.

      Default: false.

      Since:
        6.0.0

    - #### setOpen

          public void setOpen​(boolean open)

      Sets to display dropdown or close the child. Only works while visible.
      Since:
        3.0.1

    - #### open

          public void open()

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

    - #### close

          public void close()

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

    - #### setMultiline

          public void setMultiline​(boolean multiline)

      Bandbox can't be enabled the multiline functionality.
      Overrides:
        `setMultiline` in class `Textbox`

    - #### setRows

          public void setRows​(int rows)

      Bandbox can't be enabled the rows functionality.
      Overrides:
        `setRows` in class `Textbox`

    - #### setIconSclass

          public void setIconSclass​(java.lang.String iconSclass)

      Sets the iconSclass name of this Bandbox.
      Parameters:
        `iconSclass` - String
      Since:
        8.6.2

    - #### getIconSclass

          public java.lang.String getIconSclass()

      Returns the iconSclass name of this Bandbox.
      Returns:
        the iconSclass name
      Since:
        8.6.2

    - #### getZclass

          public java.lang.String getZclass()

      Description copied from class: `HtmlBasedComponent`
      Returns the ZK Cascading Style class 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 `Textbox`
      See Also:
        `HtmlBasedComponent.getSclass()`

    - #### 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 `Textbox`
      Throws:
        `java.io.IOException`

    - #### service

          public void service​(AuRequest request,
                              boolean everError)

      Processes an AU request.

      Default: in addition to what are handled by `InputElement.service(AuRequest, boolean)` service}, it also handles onOpen and onSelect.

      Specified by:
        `service` in interface `ComponentCtrl`
      Overrides:
        `service` in class `InputElement`
        `everError` - whether any error ever occurred before processing this request.
      Since:
        5.0.0
      See Also:
        `AbstractComponent.setAuService(org.zkoss.zk.au.AuService)`

    - #### 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)`

    - #### isChildable

          protected boolean isChildable()

      Childable.
      Overrides:
        `isChildable` in class `InputElement`

    - #### getPopupWidth

          public java.lang.String getPopupWidth()

      Returns:
        the width of the popup of this component
      Since:
        8.0.3

    - #### setPopupWidth

          public void setPopupWidth​(java.lang.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