Package org.zkoss.stateless.sul

## Interface IHtmlBasedComponent<I extends IHtmlBasedComponent>

- All Superinterfaces:
    `IComponent<I>`
  All Known Subinterfaces:
    `IA<I>`, `IAbsolutechildren<I>`, `IAbsolutelayout`, `IAnchornav<I>`, `IAudio`, `IAuxhead`, `IAuxheader<I>`, `IBandbox`, `IBandpopup<I>`, `IBarcode`, `IBarcodescanner`, `IBiglistbox`, `IBorderlayout`, `IButton`, `IButtonBase<I>`, `ICalendar`, `ICamera`, `ICaption<I>`, `ICardlayout<I>`, `ICascader`, `ICell<I>`, `ICenter<I>`, `ICheckbox`, `ICheckboxBase<I>`, `IChosenbox`, `ICoachmark<I>`, `IColorbox`, `IColumn<I>`, `IColumnchildren<I>`, `IColumnlayout`, `IColumns`, `ICombobox`, `ICombobutton`, `IComboitem`, `ICropper`, `IDatebox`, `IDateTimeFormatInputElement<I>`, `IDecimalbox`, `IDetail<I>`, `IDetailChild<I>`, `IDiv<I>`, `IDoublebox`, `IDoublespinner`, `IDrawer<I>`, `IDropupload`, `IEast<I>`, `IFileupload`, `IFisheye`, `IFisheyebar`, `IFoot`, `IFooter<I>`, `IFooterElement<I>`, `IFormatInputElement<I,​ValueTypeT>`, `IFrozen<I>`, `IGoldenLayout`, `IGoldenPanel<I>`, `IGrid`, `IGroup<I>`, `IGroupbox<I>`, `IGroupChild<I>`, `IGroupfoot<I>`, `IGroupfootChild<I>`, `IHeaderElement<I>`, `IHeadersElement<I>`, `IHlayout<I>`, `IHtml`, `IIframe`, `IImage`, `IImageBase<I>`, `IImagemap`, `IInputElement<I,​ValueTypeT>`, `IInputgroup`, `IIntbox`, `ILabel`, `ILabelElement<I>`, `ILabelImageElement<I>`, `ILayout<I>`, `ILayoutRegion<I>`, `ILineitem<I>`, `ILinelayout`, `IListbox`, `IListcell<I>`, `IListfoot`, `IListfooter<I>`, `IListgroup`, `IListgroupChild<I>`, `IListgroupfoot`, `IListgroupfootChild<I>`, `IListhead`, `IListheader<I>`, `IListitem`, `IListitemBase<I>`, `ILongbox`, `IMenu`, `IMenubar`, `IMenuitem`, `IMenupopup`, `IMenuseparator`, `IMeshElement<I>`, `IMultislider`, `INav`, `INavbar`, `INavitem`, `INavseparator`, `INorth<I>`, `INumberInputElement<I,​ValueTypeT>`, `IOrganigram`, `IOrgchildren`, `IOrgitem`, `IOrgnode<I>`, `IPaging`, `IPanel`, `IPanelchildren<I>`, `IPdfviewer`, `IPopup<I>`, `IPopupBase<I>`, `IPortalchildren`, `IPortallayout`, `IProgressmeter`, `IRadio`, `IRadiogroup<I>`, `IRangeslider`, `IRangesliderBase<I>`, `IRating`, `IRow<I>`, `IRowBase<I>`, `IRowchildren<I>`, `IRowlayout`, `IRows`, `IScrollview<I>`, `ISearchbox`, `ISelectbox`, `ISeparator`, `ISeparatorBase<I>`, `ISignature`, `ISlider`, `ISliderbuttons`, `ISouth<I>`, `ISpace`, `ISpan<I>`, `ISpinner`, `ISplitlayout<I>`, `IStep`, `IStepbar`, `ITab`, `ITabbox`, `ITablechildren<I>`, `ITablelayout`, `ITabpanel<I>`, `ITabpanels`, `ITabs`, `ITbeditor`, `ITextbox`, `ITextboxBase<I>`, `ITimebox`, `ITimepicker`, `ITimer`, `IToolbar<I>`, `IToolbarbutton`, `ITrack`, `ITree`, `ITreecell<I>`, `ITreechildren`, `ITreecol<I>`, `ITreecols`, `ITreefoot`, `ITreefooter<I>`, `ITreeitem`, `ITreerow`, `IVideo`, `IVlayout<I>`, `IWest<I>`, `IWindow<I>`, `IXulElement<I>`

      public interface IHtmlBasedComponent<I extends IHtmlBasedComponent>
      extends IComponent<I>

  Immutable `HtmlBasedComponent` interface. Provides a skeleton for HTML based immutable components.

  ### Support @Action

  Name | Action Type
  --- | ---
  onClick | ActionData: `MouseData` Represents an action triggered by the user clicks on a component.
  onDoubleClick | ActionData: `MouseData` Represents an action triggered by the user double-clicks on a component.
  onRightClick | ActionData: `MouseData` Represents an action triggered by the user right-clicks on a component.
  onMouseOver | ActionData: `MouseData` Represents an action triggered by the user moves the mouse pointer onto a component.
  onMouseOut | ActionData: `MouseData` Represents an action triggered by the user moves the mouse pointer out a component.
  onOK | ActionData: `KeyData` Represents an action triggered by the user presses the `ENTER` key on a component.
  onCancel | ActionData: `KeyData` Represents an action triggered by the user presses the `ESC` key on a component.
  onDrop | ActionData: `DropData` Represents an action triggered by user’s dragging and dropping a component.
  onSwipe | ActionData: `SwipeData` Represents an action that indicates swipe on a component and provides information about the swipe displacement, duration and direction. (Tablet only)
  onAfterSize | ActionData: `AfterSizeData` Represents an action that resizes a component and provides the new size of the component

  Author:
    jumperchen

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getClientAction()` | Returns the client-side action (CSA).
    `default java.lang.String` | `getDraggable()` | Returns the identifier of a draggable type of objects, or `"false"` if not draggable (never null nor empty).
    `default java.lang.String` | `getDroppable()` | Returns the identifier, or a list of identifiers (split by a comma `","`) of a droppable type of objects, or `"false"` if not droppable (never null nor empty).
    `java.lang.String` | `getHeight()` | Returns the height of the component.
    `java.lang.String` | `getHflex()` | Return horizontal flex hint of this component.
    `java.lang.String` | `getLeft()` | Returns the left position of the `positioned` component.
    `default int` | `getRenderdefer()` | Returns the number of milliseconds before rendering this component at the client.
    `java.lang.String` | `getSclass()` | Returns the CSS class(es).
    `java.lang.String` | `getStyle()` | Returns the CSS style.
    `java.lang.Integer` | `getTabindex()` | Returns the tab order of this component.
    `java.lang.String` | `getTooltiptext()` | Returns the text of the tooltip which belongs to this component.
    `java.lang.String` | `getTop()` | Returns the top position of the `positioned` component.
    `java.lang.String` | `getVflex()` | Return vertical flex hint of this component.
    `java.lang.String` | `getWidth()` | Returns the width of the component.
    `java.lang.String` | `getZclass()` | Returns the ZK Cascading Style class for this component.
    `default int` | `getZIndex()` | Returns the stack order of a positioned component.
    `default boolean` | `isFocus()` | Returns the focus set by `withFocus(boolean)`.
    `I` | `withClientAction​(java.lang.String clientAction)` | Returns a copy of `this` immutable component with the specified `clientAction`.
    `I` | `withDraggable​(java.lang.String draggable)` | Returns a copy of `this` immutable component with the specified `draggable`.
    `I` | `withDroppable​(java.lang.String droppable)` | Returns a copy of `this` immutable component with the specified `droppable`.
    `I` | `withFocus​(boolean focus)` | Returns a copy of `this` immutable component with the specified `focus`.
    `I` | `withHeight​(java.lang.String height)` | Returns a copy of `this` immutable component with the specified `height`.
    `I` | `withHflex​(java.lang.String hflex)` | Returns a copy of `this` immutable component with the specified `hflex`.
    `I` | `withLeft​(java.lang.String left)` | Returns a copy of `this` immutable component with the specified `left`.
    `I` | `withRenderdefer​(int renderdefer)` | Returns a copy of `this` immutable component with the specified `renderdefer`.
    `I` | `withSclass​(java.lang.String sclass)` | Returns a copy of `this` immutable component with the specified `sclass`.
    `I` | `withStyle​(java.lang.String style)` | Returns a copy of `this` immutable component with the specified `style`.
    `default I` | `withTabindex​(int tabindex)` | Returns a copy of `this` immutable component with the specified `tabindex`.
    `I` | `withTabindex​(java.lang.Integer tabindex)` | Returns a copy of `this` immutable component with the specified `tabindex`.
    `I` | `withTooltiptext​(java.lang.String tooltiptext)` | Returns a copy of `this` immutable component with the specified `tooltiptext`.
    `I` | `withTop​(java.lang.String top)` | Returns a copy of `this` immutable component with the specified `top`.
    `I` | `withVflex​(java.lang.String vflex)` | Returns a copy of `this` immutable component with the specified `vflex`.
    `I` | `withWidth​(java.lang.String width)` | Returns a copy of `this` immutable component with the specified `width`.
    `I` | `withZclass​(java.lang.String zclass)` | Returns a copy of `this` immutable component with the specified `zclass`.
    `I` | `withZIndex​(int zIndex)` | Returns a copy of `this` immutable component with the specified `zIndex`.

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

      `getAction, getActions, getClientAttributes, getId, getMold, getWidgetClass, 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`

- - ### Method Detail

    - #### getLeft

          @Nullable
          java.lang.String getLeft()

      Returns the left position of the `positioned` component. If not specified, `null` is assumed.

      Default: `null`

    - #### withLeft

          I withLeft​(@Nullable
                     java.lang.String left)

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

      This attribute specifies the left position of the component at client HTML element including `padding`, `scrollbar`, `border` and `margin`.

      Tip: A positioned component is a HTML element with the `position` attribute set to: `relative`, `absolute`, or `fixed` in `withStyle(String)`.
      Tip: To set the `right` position of a positioned component, use the `withStyle(String)` instead.
      Parameters:
        `left` - The left position of the component to set.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getTop

          @Nullable
          java.lang.String getTop()

      Returns the top position of the `positioned` component. If not specified, `null` is assumed.

      Default: `null`

    - #### withTop

          I withTop​(@Nullable
                    java.lang.String top)

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

      This attribute specifies the top position of the component at client HTML element including `padding`, `scrollbar`, `border` and `margin`.

      Tip: A positioned component is a HTML element with the `position` attribute set to: `relative`, `absolute`, or `fixed` in `withStyle(String)`.
      Tip: To set the `bottom` position of a positioned component, use the `withStyle(String)` instead.
      Parameters:
        `top` - The top position of the component to set.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getZIndex

          default int getZIndex()

      Returns the stack order of a positioned component.

      Default: `-1`

    - #### withZIndex

          I withZIndex​(int zIndex)

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

      A component with greater stack order (`1`) is always in front of another component with lower stack order (`0`).

      Tip: A positioned component is a HTML element with the `position` attribute set to: `relative`, `absolute`, or `fixed` in `withStyle(String)`.

      Parameters:
        `zIndex` - The stack order of a positioned component.

        Default: `-1`

      Returns:
        A modified copy of the `this` object

    - #### getHeight

          @Nullable
          java.lang.String getHeight()

      Returns the height of the component. If not specified, `null` is assumed.

      Default: `null`

    - #### withHeight

          I withHeight​(@Nullable
                       java.lang.String height)

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

      The `height` attribute includes `padding` and `borders`, but not `margins`, and the value can be set to a numeric value (like pixels, (r)em, percentages). (Same as CSS Height property)

      Parameters:
        `height` - The height of the component.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getWidth

          @Nullable
          java.lang.String getWidth()

      Returns the width of the component. If not specified, `null` is assumed.

      Default: `null`

    - #### withWidth

          I withWidth​(@Nullable
                      java.lang.String width)

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

      The `width` attribute includes `padding` and `borders`, but not `margins`, and the value can be set to a numeric value (like pixels, (r)em, percentages). (Same as CSS Width property)

      Parameters:
        `width` - The width of the component.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getTooltiptext

          @Nullable
          java.lang.String getTooltiptext()

      Returns the text of the tooltip which belongs to this component.

      Default: `null`

    - #### withTooltiptext

          I withTooltiptext​(@Nullable
                            java.lang.String tooltiptext)

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

      Sets the text as the tooltip to the component. (Same as HTML Title property)

      Parameters:
        `tooltiptext` - A text to set as tooltip on the component.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getZclass

          @Nullable
          java.lang.String getZclass()

      Returns the ZK Cascading Style class for this component. It usually depends on the implementation of the mold (`IComponent.getMold()`).
      See Also:
        `getSclass()`

    - #### withZclass

          I withZclass​(@Nullable
                       java.lang.String zclass)

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

      Sets the ZK Cascading Style class for this component. It usually depends on the implementation of the `mold`.
      Note:The `zclass` attribute 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 `getZclass()`. Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use `withSclass(String)` instead.

      Parameters:
        `zclass` - The ZK Cascading Style class for this component.

        Note: The value is better to use a single Cascading Style class; multiple values may cause some unwanted behavior, because the `zclass` value will be used to plus other postfix as its descendant elements at client.
        For example,
        `"z-window-embedded"` or `"z-window-content"` for the `zclass` value (`"z-window"`) on `IWindow`.

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

      Returns:
        A modified copy of the `this` object

    - #### getSclass

          @Nullable
          java.lang.String getSclass()

      Returns the CSS class(es).

      Default: `null`.

      See Also:
        `getZclass()`

    - #### withSclass

          I withSclass​(@Nullable
                       java.lang.String sclass)

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

      The default styles of ZK components doesn't depend on the value of `getSclass()`. Rather, `withSclass(String)` is provided to perform small adjustment, e.g., only changing the font size. In other words, the default style is still applied if you change the value of `getSclass()`. To replace the default style completely, use `withZclass(String)` instead.

      Parameters:
        `sclass` - The CSS class(es) to apply to this component. With multiple values, please use a space `" "` to separate them. aka `"class1 class2 class3"`.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getStyle

          @Nullable
          java.lang.String getStyle()

      Returns the CSS style.

      Default: `null`.

    - #### withStyle

          I withStyle​(@Nullable
                      java.lang.String style)

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

      Sets the CSS style to this component.

      Parameters:
        `style` - The CSS style.
      Returns:
        A modified copy of the `this` object

    - #### getDraggable

          default java.lang.String getDraggable()

      Returns the identifier of a draggable type of objects, or `"false"` if not draggable (never null nor empty).

      Default: `"false"`

    - #### withDraggable

          I withDraggable​(java.lang.String draggable)

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

      Sets `"true"` or `"false"` to denote whether a component is draggable, or an identifier of a draggable type of objects.

      The simplest way to make a component draggable is to set this attribute to `"true"`. To disable it, set this to `"false"`.

      If there are several types of draggable objects, you could assign an identifier for each type of draggable object. The identifier could be anything but empty.

      Parameters:
        `draggable` - The value of `"false"` and `""` to denote non-draggable; `"true"` for draggable with anonymous identifier; others for an identifier of draggable.
      Returns:
        A modified copy of the `this` object

    - #### isFocus

          default boolean isFocus()

      Returns the focus set by `withFocus(boolean)`.

      Note: it simply returns what is passed to `withFocus(boolean)`.

      Default: `false`

    - #### withFocus

          I withFocus​(boolean focus)

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

      Sets the focus onto this component.

      Parameters:
        `focus` - True to focus on this component.
      Returns:
        A modified copy of the `this` object

    - #### getDroppable

          default java.lang.String getDroppable()

      Returns the identifier, or a list of identifiers (split by a comma `","`) of a droppable type of objects, or `"false"` if not droppable (never null nor empty).

      Default: `"false"`

    - #### withDroppable

          I withDroppable​(java.lang.String droppable)

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

      Sets `"true"` or `"false"` to denote whether a component is droppable, or a list of identifiers of draggable types of objects that could be dropped to this component. (split by a comma `","`)

      The simplest way to make a component droppable is to set this attribute to `"true"`. To disable it, set this to `"false"`.

      If there are several types of draggable objects and this component accepts only some of them, you could assign a list of identifiers that this component accepts, separated by comma. For example, if this component accepts `dg1` and `dg2`, then assign `"dg1, dg2"` to this attribute.

      Parameters:
        `droppable` - The value of `"false"` or `""` to denote not-droppable; `"true"` for accepting any draggable types; a list of identifiers, separated by comma for identifiers of `draggables` this component accept (to be dropped in).
      Returns:
        A modified copy of the `this` object

    - #### getVflex

          @Nullable
          java.lang.String getVflex()

      Return vertical flex hint of this component.

      Default: `null`

    - #### withVflex

          I withVflex​(@Nullable
                      java.lang.String vflex)

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

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

      Note: in Stateless, it uses CSS Flex implementation at all, except the `min` value, which calculates the size of the element by JavaScript.

      Parameters:
        `vflex` - The vertical flex hint.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getHflex

          @Nullable
          java.lang.String getHflex()

      Return horizontal flex hint of this component.

      Default: `null`

    - #### withHflex

          I withHflex​(@Nullable
                      java.lang.String hflex)

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

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

      Note: in Stateless, it uses CSS Flex implementation at all, except the `min` value, which calculates the size of the element by JavaScript.

      Parameters:
        `hflex` - The horizontal flex hint.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### getRenderdefer

          default int getRenderdefer()

      Returns the number of milliseconds before rendering this component at the client.

      Default: `-1` (don't wait).

    - #### withRenderdefer

          I withRenderdefer​(int renderdefer)

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

      Sets the number of milliseconds before rendering this component at the client.

      Default: `-1` (don't wait).

      This method is useful if you have a sophisticated page that takes long to render at a slow client. You can specify a non-negative value as the render-defer delay such that the other part of the UI can appear earlier. The styling of the render-deferred widget is controlled by a CSS class called `z-renderdefer`.

      Note: Be aware of that too many components use this `renderdefer` at client will reduce the browser rendering performance.

      Parameters:
        `renderdefer` - The time to wait in milliseconds before rendering. Notice: `0` also implies deferring the rendering (just right after all others are rendered).
      Returns:
        A modified copy of the `this` object

    - #### getClientAction

          @Nullable
          java.lang.String getClientAction()

      Returns the client-side action (CSA).

      Default: `null` (no CSA at all)

    - #### withClientAction

          I withClientAction​(@Nullable
                             java.lang.String clientAction)

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

      Sets the client-side action (CSA).
      Default: `null` (no CSA at all)

      The format:
      `action1: action-effect1; action2: action-effect2`

      Currently, only two actions are `show` and `hide`. They are called when the widget is becoming visible (show) and invisible (hide).

      The action effect (`action-effect1`) is the name of a method defined in zk.eff.Actions, such as `show: slideDown; hide: slideUp`

      You could specify the effects as follows:
      `show: slideDown({duration:1000})`

      Security Tips: the `client action` is not encoded, it is OK to embed JavaScript, so, if you want to allow users to specify the action, you have to encode it.

      Parameters:
        `clientAction` - The client-side action to set.
      Returns:
        A modified copy of the `this` object

    - #### getTabindex

          @Nullable
          java.lang.Integer getTabindex()

      Returns the tab order of this component. (when the `"tab"` button is used for navigating)

      Default: `null`

    - #### withTabindex

          I withTabindex​(@Nullable
                         java.lang.Integer tabindex)

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

      Specifies the `tab` order of this component. (when the `"TAB"` button is used for navigating)

      Parameters:
        `tabindex` - The order of this component to set.

        Default: `null`

      Returns:
        A modified copy of the `this` object

    - #### withTabindex

          default I withTabindex​(int tabindex)

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

      Specifies the `tab` order of this component. (when the `"TAB"` button is used for navigating)

      Parameters:
        `tabindex` - The order of this component to set.

        Default: `null`

      Returns:
        A modified copy of the `this` object
      See Also:
        `withTabindex(Integer)`