Package org.zkoss.stateless.sul

## Interface IButtonBase<I extends IButtonBase>

- All Superinterfaces:
    `IChildrenOfInputgroup<I>`, `IComponent<I>`, `IHtmlBasedComponent<I>`, `ILabelElement<I>`, `ILabelImageElement<I>`, `IXulElement<I>`
  All Known Subinterfaces:
    `IButton`, `ICombobutton`, `IFileupload`, `IToolbarbutton`

      public interface IButtonBase<I extends IButtonBase>
      extends ILabelImageElement<I>

  Immutable `Button` base component
  Author:
    katherine

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `IButtonBase.Direction` | Specifies the direction to layout image with `withDir(Direction)`
    `static class` | `IButtonBase.Orient` | Specifies the orient with `withOrient(Orient)`
    `static class` | `IButtonBase.Type` | Specifies the type with `withType(Type)`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default void` | `checkOrient()` |
    `default java.lang.String` | `getAutodisable()` | Returns a list of component IDs that shall be disabled when the user clicks this button.
    `default java.lang.String` | `getDir()` | Returns the direction.
    `default java.lang.String` | `getHref()` | Returns the href that the browser shall jump to, if a user clicks this button.
    `default java.lang.String` | `getOrient()` | Returns the orient.
    `default java.lang.String` | `getTarget()` | Returns the target frame or window.
    `default java.lang.String` | `getType()` | Returns the button type.
    `default java.lang.String` | `getUpload()` | Returns non-null if this component is used for file upload, or null otherwise.
    `default boolean` | `isDisabled()` | Returns whether it is disabled.
    `I` | `withAutodisable​(java.lang.String autodisable)` | Returns a copy of `this` immutable component with the specified `autodisable`.
    `I` | `withDir​(java.lang.String dir)` | Returns a copy of `this` immutable component with the specified `dir`.
    `default I` | `withDir​(IButtonBase.Direction dir)` | Returns a copy of `this` immutable component with the specified `dir`.
    `I` | `withDisabled​(boolean disabled)` | Returns a copy of `this` immutable component with the specified `disabled`.
    `I` | `withHref​(java.lang.String href)` | Returns a copy of `this` immutable component with the specified `href`.
    `I` | `withOrient​(java.lang.String orient)` | Returns a copy of `this` immutable component with the specified `orient`.
    `default I` | `withOrient​(IButtonBase.Orient orient)` | Returns a copy of `this` immutable component with the specified `orient`.
    `I` | `withTarget​(java.lang.String target)` | Returns a copy of `this` immutable component with the specified `target`.
    `I` | `withType​(java.lang.String type)` | Returns a copy of `this` immutable component with the specified `orient`.
    `default I` | `withType​(IButtonBase.Type type)` | Returns a copy of `this` immutable component with the specified `orient`.
    `I` | `withUpload​(java.lang.String upload)` | Returns a copy of `this` immutable component with the specified `upload`.

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

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

      `getLabel, withLabel`

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

      `getHoverImage, getIconSclass, getIconSclasses, getIconTooltip, getIconTooltips, getImage, isPreloadImage, withHoverImage, withIconSclass, withIconSclasses, withIconTooltip, withIconTooltips, withImage, withPreloadImage`

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

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

- - ### Method Detail

    - #### checkOrient

          @Check
          default void checkOrient()

    - #### getDir

          default java.lang.String getDir()

      Returns the direction.

      Default: `"normal"`.

    - #### withDir

          I withDir​(java.lang.String dir)

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

      Sets the direction to layout image.

      Parameters:
        `dir` - The direction to layout image, either `"normal"` or `"reverse"`

        Default: `"normal"`.

      Returns:
        A modified copy of the `this` object

    - #### withDir

          default I withDir​(IButtonBase.Direction dir)

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

      Sets the direction to layout image.

      Parameters:
        `dir` - The direction to layout image, either `"normal"` or `"reverse"`

        Default: `"normal"`.

      Returns:
        A modified copy of the `this` object

    - #### getOrient

          default java.lang.String getOrient()

      Returns the orient.

      Default: `"horizontal"`.

    - #### withOrient

          I withOrient​(java.lang.String orient)

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

      Sets the orient to layout image.

      Parameters:
        `orient` - the orient to layout image., either `"horizontal"` or `"vertical"`

        Default: `"horizontal"`.

      Returns:
        A modified copy of the `this` object

    - #### withOrient

          default I withOrient​(IButtonBase.Orient orient)

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

      Sets the orient to layout image.

      Parameters:
        `orient` - the orient to layout image., either `"horizontal"` or `"vertical"`

        Default: `"horizontal"`.

      Returns:
        A modified copy of the `this` object

    - #### getType

          default java.lang.String getType()

      Returns the button type.

      Default: `"button"`.

    - #### withType

          I withType​(java.lang.String type)

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

      Sets the button type. It is meaningful only if it is used with a HTML form. Refer to HTML Button Type for details.

      Parameters:
        `type` - Either `"button"`, `"submit"` or `"reset"`.

        Default: `"button"`.

      Returns:
        A modified copy of the `this` object

    - #### withType

          default I withType​(IButtonBase.Type type)

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

      Sets the button type. It is meaningful only if it is used with a HTML form. Refer to HTML Button Type for details.

      Parameters:
        `type` - Either `"button"`, `"submit"` or `"reset"`.

        Default: `"button"`.

      Returns:
        A modified copy of the `this` object

    - #### isDisabled

          default boolean isDisabled()

      Returns whether it is disabled.

      Default: `false`.

    - #### withDisabled

          I withDisabled​(boolean disabled)

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

      Sets whether it is disabled.

      Parameters:
        `disabled` - Whether it is disabled.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### getAutodisable

          @Nullable
          default java.lang.String getAutodisable()

      Returns a list of component IDs that shall be disabled when the user clicks this button.

    - #### withAutodisable

          I withAutodisable​(@Nullable
                            java.lang.String autodisable)

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

      Sets a list of component IDs that shall be disabled when the user clicks this button.

      To represent the button itself, the developer can specify `self`. For example, `.withAutodisable("self,cancel");` is the same as `IButton.ofId("ok").withAutodisable("ok,cancel");` that will disable both the ok and cancel buttons when a user clicks it.

      The button being disabled will be enabled automatically once the client receives a response from the server. In other words, the server doesn't notice if a button is disabled with this method.

      However, if you prefer to enable them later manually, you can prefix with '+'. For example, `IButton.ofId("ok").withAutodisable("+self,+cancel");`

      Then, you have to enable them manually such as

          if (something_happened){
            uiAgent.smartUpdate(Locator.ofId("ok"), new IButton.Updater().disabled(false));
            uiAgent.smartUpdate(Locator.ofId("cancel"), new IButton.Updater().disabled(false));

      Parameters:
        `autodisable` - Whether it is auto-disable.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getTarget

          @Nullable
          default java.lang.String getTarget()

      Returns the target frame or window.

      Note: it is useful only if href (`withHref(java.lang.String)`) is specified (i.e., use the onClick listener).

      Default: `null`.

    - #### withTarget

          I withTarget​(@Nullable
                       java.lang.String target)

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

      Sets the target frame or window

      Parameters:
        `target` - The name of the frame or window to hyperlink.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getUpload

          @Nullable
          default java.lang.String getUpload()

      Returns non-null if this component is used for file upload, or null otherwise. Refer to `withUpload(java.lang.String)` for more details.

      Default: `null`

    - #### withUpload

          I withUpload​(@Nullable
                       java.lang.String upload)

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

      Sets the JavaScript class at the client to handle the upload if this component is used for file upload.

      For example, the following example declares a button for file upload:

          IButton.of("Upload").withUpload("true").withAction(onUpload(this::doHandle));

      As shown above, after the file is uploaded, an instance of `FileData` is sent this handler.

      If you want to customize the handling of the file upload at the client, you can specify a JavaScript class when calling this method: `withUpload("foo.Upload");`

      Another options for the upload can be specified as follows:

          .withUpload("true,maxsize=-1,multiple=true,accept=audio/*|video/*|image/*,native");

      - maxsize: the maximal allowed upload size of the component, in kilobytes, or a negative value if no limit, if the maxsize is not specified, it will use `Configuration.getMaxUploadSize()`
      - native: treating the uploaded file(s) as binary, i.e., not to convert it to image, audio or text files.
      - multiple: treating the file chooser allows multiple files to upload, the setting only works with HTML5 supported browsers.
      - accept: specifies the types of files that the server accepts, the setting only works with HTML5 supported browsers.
      - suppressedErrors: specifies the suppressed uploading errors, separated by `|` (e.g. missing-required-component|illegal-upload) (since ZK 9.5.1).

      Note: if the options of the `false` or the customized handler (like `foo.Upload`) are not specified, the option of `true` is implicit by default.

      Parameters:
        `upload` - a JavaScript class to handle the file upload at the client, or "true" if the default class is used, or null or "false" to disable the file download (and then this button behaves like a normal button).

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getHref

          @Nullable
          default java.lang.String getHref()

      Returns the href that the browser shall jump to, if a user clicks this button.

      Default: `null`. If null, the button has no function unless you specify the onClick event listener.

      If it is not null, the onClick event won't be sent.

    - #### withHref

          I withHref​(@Nullable
                     java.lang.String href)

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

      Sets he href that the browser shall jump to, if a user clicks this button.

      Parameters:
        `href` - The href that the browser shall jump to, if a user clicks this button.

        Default: `null`.

      Returns:
        A modified copy of the `this` object