Package org.zkoss.stateless.sul

## Interface IBandbox

- All Superinterfaces:
    `IAnyGroup<IBandbox>`, `IChildrenOfInputgroup<IBandbox>`, `IComponent<IBandbox>`, `IHtmlBasedComponent<IBandbox>`, `IInputElement<IBandbox,​java.lang.String>`, `IReadonly<IBandbox>`, `ISingleChildable<IBandbox,​IBandpopup>`, `ITextboxBase<IBandbox>`, `IXulElement<IBandbox>`

      public interface IBandbox
      extends ITextboxBase<IBandbox>, ISingleChildable<IBandbox,​IBandpopup>, IAnyGroup<IBandbox>

  Immutable `Bandbox` component.

  A bandbox is a special text box that embeds a customizable popup window (aka., a dropdown window). Like comboboxes, a bandbox consists of an input box and a popup window. The popup window is opened automatically, when a user presses `Alt+DOWN` or clicks the magnifier button.

  Unlike comboboxes, the popup window of a bandbox could be anything. It is designed to give developers the maximal flexibility. A typical use is to represent the popup window as a search dialog.

  ### Support @Action

  Name | Action Type
  --- | ---
  onOpen | ActionData: `OpenData` Denotes user has opened or closed a component. Note: unlike `onClose`, this action is only a notification. The client sends this action after opening or closing the component.

  ## Mouseless Entry

  - `Alt+DOWN` to pop up the list.
  - `Alt+UP` or `ESC` to close the list.

  ## Constraint

  You could specify what value to accept for input controls by use of the `constraint` attribute. It could be `no empty`, and/or a regular expression.

  To specify two or more constraints, use comma to separate them as follows.

      IBandbox.ofConstraint("no empty,/^A/");

  To specify a regular expression, you may have to use the character `/` to enclose the regular expression as follows.

      IBandbox.ofConstraint("/^A/");

  If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.

      IBandbox.ofConstraint("/^A/: only allowed the item start with A");

  Author:
    katherine
  See Also:
    `Bandbox`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `IBandbox.Builder` | Builds instances of type `IBandbox`.
    `static class` | `IBandbox.Updater` | Builds an updater of type `IBandbox` for `UiAgent.smartUpdate(Locator, SmartUpdater)`.

    - ### Nested classes/interfaces inherited from interface org.zkoss.stateless.sul.ITextboxBase

      `ITextboxBase.Type`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static IBandbox` | `DEFAULT` | Constant for default attributes of this immutable component.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default java.lang.String` | `getIconSclass()` | Returns the iconSclass name of this Bandbox.
    `java.lang.String` | `getPopupWidth()` | Returns the width of the popup of this component
    `default java.lang.String` | `getWidgetClass()` | Returns the client widget class.
    `default boolean` | `isAutodrop()` | Returns whether to automatically drop the list if users is changing this text box.
    `default boolean` | `isButtonVisible()` | Returns whether the button (on the right of the timebox) is visible.
    `default boolean` | `isOpen()` | Returns whether this bandbox is open.
    `static IBandbox` | `of​(java.lang.String value)` | Return the instance of the given value.
    `static IBandbox` | `of​(java.lang.String value, IBandpopup bandpopup)` | Return the instance of the given value and bandpopup child.
    `static IBandbox` | `of​(IBandpopup bandpopup)` | Return the instance of the given bandpopup child.
    `static IBandbox` | `ofCols​(int cols)` | Returns the instance with the given cols.
    `static IBandbox` | `ofConstraint​(java.lang.String constraint)` | Returns the instance with the given constraint.
    `static IBandbox` | `ofId​(java.lang.String id)` | Returns the instance with the given id.
    `IBandbox` | `withAutodrop​(boolean autodrop)` | Returns a copy of `this` immutable component with the specified `autodrop`.
    `IBandbox` | `withButtonVisible​(boolean buttonVisible)` | Returns a copy of `this` immutable component with the specified `buttonVisible`.
    `IBandbox` | `withIconSclass​(java.lang.String iconSclass)` | Returns a copy of `this` immutable component with the specified `iconSclass`.
    `IBandbox` | `withOpen​(boolean open)` | Returns a copy of `this` immutable component with the specified `sclass`.
    `IBandbox` | `withPopupWidth​(java.lang.String popupWidth)` | Returns a copy of `this` immutable component with the specified `popupWidth`.

    - ### Methods inherited from interface org.zkoss.stateless.sul.IComponent

      `getAction, getActions, getClientAttributes, getId, getMold, getWidgetListeners, getWidgetOverrides, isVisible, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withActions, withActions, withClientAttribute, withClientAttributes, withId, withMold, withVisible, withWidgetClass, withWidgetListener, withWidgetListeners, withWidgetOverride, withWidgetOverrides`

    - ### Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent

      `getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZIndex, isFocus, withClientAction, withDraggable, withDroppable, withFocus, withHeight, withHflex, withLeft, withRenderdefer, withSclass, withStyle, withTabindex, withTabindex, withTooltiptext, withTop, withVflex, withWidth, withZclass, withZIndex`

    - ### Methods inherited from interface org.zkoss.stateless.sul.IInputElement

      `getCols, getConstraint, getErrorboxIconSclass, getErrorboxSclass, getErrorMessage, getInputAttributes, getInstant, getMaxlength, getName, getPlaceholder, getValue, isDisabled, isInplace, withCols, withConstraint, withDisabled, withErrorboxIconSclass, withErrorboxSclass, withErrorMessage, withInplace, withInputAttributes, withInstant, withMaxlength, withName, withPlaceholder`

    - ### Methods inherited from interface org.zkoss.stateless.sul.IReadonly

      `isReadonly, withReadonly`

    - ### Methods inherited from interface org.zkoss.stateless.sul.ISingleChildable

      `getChild, withChild`

    - ### Methods inherited from interface org.zkoss.stateless.sul.ITextboxBase

      `getRows, getType, isMultiline, isSubmitByEnter, isTabbable, withMultiline, withRows, withSubmitByEnter, withTabbable, withType, withType, withValue`

    - ### Methods inherited from interface org.zkoss.stateless.sul.IXulElement

      `getContext, getCtrlKeys, getPopup, getTooltip, withContext, withCtrlKeys, withPopup, withTooltip`

- - ### Field Detail

    - #### DEFAULT

          static final IBandbox DEFAULT

      Constant for default attributes of this immutable component.

  - ### Method Detail

    - #### getWidgetClass

          default java.lang.String getWidgetClass()

      Returns the client widget class.

      Default: `"zul.inp.Bandbox"`

      Specified by:
        `getWidgetClass` in interface `IComponent<IBandbox>`

    - #### getPopupWidth

          @Nullable
          java.lang.String getPopupWidth()

      Returns the width of the popup of this component

      Default: `null`

    - #### withPopupWidth

          IBandbox withPopupWidth​(@Nullable
                                  java.lang.String popupWidth)

      Returns a copy of `this` immutable component with the specified `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.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### isAutodrop

          default boolean isAutodrop()

      Returns whether to automatically drop the list if users is changing this text box.

      Default: `false`.

    - #### withAutodrop

          IBandbox withAutodrop​(boolean autodrop)

      Returns a copy of `this` immutable component with the specified `autodrop`.

      Sets whether to automatically drop the list if users is changing this text box.

      Parameters:
        `autodrop` - `true` to enable the auto-drop facility.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### isButtonVisible

          default boolean isButtonVisible()

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

      Default: `true`.

    - #### withButtonVisible

          IBandbox withButtonVisible​(boolean buttonVisible)

      Returns a copy of `this` immutable component with the specified `buttonVisible`.

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

      Parameters:
        `buttonVisible` - `false` to disable the button visibility.

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### getIconSclass

          default java.lang.String getIconSclass()

      Returns the iconSclass name of this Bandbox.

      Default: `Bandbox.ICON_SCLASS`

    - #### withIconSclass

          IBandbox withIconSclass​(java.lang.String iconSclass)

      Returns a copy of `this` immutable component with the specified `iconSclass`.

      Sets the iconSclass name of this Bandbox.

      Parameters:
        `iconSclass` - The iconSclass name of this Bandbox.

        Default: `Bandbox.ICON_SCLASS`

      Returns:
        A modified copy of the `this` object

    - #### isOpen

          default boolean isOpen()

      Returns whether this bandbox is open.

      Default: `false`.

    - #### withOpen

          IBandbox withOpen​(boolean open)

      Returns a copy of `this` immutable component with the specified `sclass`.

      Sets whether this bandbox is open or not.

      Parameters:
        `open` - `true` to open the dropdown.

        Default: `false`

      Returns:
        A modified copy of the `this` object

    - #### of

          static IBandbox of​(java.lang.String value)

      Return the instance of the given value.
      Parameters:
        `value` - The value of the text box.

    - #### of

          static IBandbox of​(java.lang.String value,
                             IBandpopup bandpopup)

      Return the instance of the given value and bandpopup child.
      Parameters:
        `value` - The value of the text box.
        `bandpopup` - The popup child of the bandbox

    - #### of

          static IBandbox of​(IBandpopup bandpopup)

      Return the instance of the given bandpopup child.
      Parameters:
        `bandpopup` - The popup child of the bandbox

    - #### ofCols

          static IBandbox ofCols​(int cols)

      Returns the instance with the given cols.
      Parameters:
        `cols` - The cols which determines the visible width

    - #### ofConstraint

          static IBandbox ofConstraint​(java.lang.String constraint)

      Returns the instance with the given constraint.
      Parameters:
        `constraint` - The bandbox constraint

    - #### ofId

          static IBandbox ofId​(java.lang.String id)

      Returns the instance with the given id.
      Parameters:
        `id` - The id to identify this component