Package org.zkoss.stateless.sul

## Interface ISignature

- All Superinterfaces:
    `IAnyGroup<ISignature>`, `IComponent<ISignature>`, `IHtmlBasedComponent<ISignature>`, `IXulElement<ISignature>`

      public interface ISignature
      extends IXulElement<ISignature>, IAnyGroup<ISignature>

  Immutable `Signature` component.

  A signature pad for user to sign a signature on it with save, undo, clear method.

  ### Support @Action

  Name | Action Type
  --- | ---
  onSave | ActionData: `FileData` When user invoke the save method, the action would be triggered.
  onClear | When user invoke the clear method, the action would be triggered.

  ## Example

  #### Buttons

  There are 3 buttons when you hover on this component: (from left to right)

  1. undo: to remove the last step that was drawn on the signature pad.
  2. save: to save the signature image to the server, a user can get the image by listening onSave event.
  3. clear: to clear signature pad.

  #### Toolbar Visible

  The toolbar contain three buttons: undo button, clear button and save button, it is enabled by default. If you don't want to show the toolbar, please use the following API to hide it.

      .withToolbarVisible(false)

  The toolbar button only contains icon by default. If you want to show message after icons on the button, we provide three attributes: `undoLabel`, `clearLabel`, and `saveLabel`.

  Default:

  Customized:

       ISignature.DEFAULT.withUndoLabel("Undo").withClearLabel("Clear").withSaveLabel("Save");

  #### Upload

  After calling save method, the signature will be uploaded to server. You can listen `onSave` action to get the uploaded image and integrate with `IImage`.
  For example:

       @RichletMapping("/example/upload")
       public IComponent uploadExample() {
           return IVlayout.of(
               ISignature.ofSize("600px", "300px").withAction(this::doUpload), IImage.ofId("image"));
       }

       @Action(type= Events.ON_SAVE)
       public void doUpload(UiAgent uiAgent, FileData data) {
           uiAgent.smartUpdate(Locator.ofId("image"), new IImage.Updater().content((AImage) data.getMedia()));
       }

  Author:
    katherine
  See Also:
    `Signature`

- - ### Nested Class Summary

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

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static ISignature` | `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` | `getBackgroundColor()` | Returns the background color of the signature pad.
    `java.lang.String` | `getBackgroundImage()` | Returns the background image URI of signature pad.
    `java.lang.String` | `getClearLabel()` | Returns the label on clear button.
    `default java.lang.String` | `getPenColor()` | Returns the pen color of the signature pad.
    `default int` | `getPenSize()` | Returns the pen size of the signature pad.
    `java.lang.String` | `getSaveLabel()` | Returns the label on save button.
    `default java.lang.String` | `getSaveType()` | Returns the type for saving signature image.
    `java.lang.String` | `getUndoLabel()` | Returns the label on undo button.
    `default java.lang.String` | `getWidgetClass()` | Returns the client widget class.
    `default boolean` | `isBackgroundIncluded()` | Returns whether the background color and image are included while saved.
    `default boolean` | `isToolbarVisible()` | Returns the visibility of the toolbar for signature pad.
    `static ISignature` | `ofId​(java.lang.String id)` | Returns the instance with the given id.
    `static ISignature` | `ofSize​(java.lang.String width, java.lang.String height)` | Returns the instance with the given size, width and height.
    `ISignature` | `withBackgroundColor​(java.lang.String backgroundColor)` | Returns a copy of `this` immutable component with the specified `backgroundColor`.
    `ISignature` | `withBackgroundImage​(java.lang.String backgroundImage)` | Returns a copy of `this` immutable component with the specified `backgroundImage`.
    `ISignature` | `withBackgroundIncluded​(boolean backgroundIncluded)` | Returns a copy of `this` immutable component with the specified `backgroundIncluded`.
    `ISignature` | `withClearLabel​(java.lang.String clearLabel)` | Returns a copy of `this` immutable component with the specified `clearLabel`.
    `ISignature` | `withPenColor​(java.lang.String penColor)` | Returns a copy of `this` immutable component with the specified `penColor`.
    `ISignature` | `withPenSize​(int penSize)` | Returns a copy of `this` immutable component with the specified `penSize`.
    `ISignature` | `withSaveLabel​(java.lang.String saveLabel)` | Returns a copy of `this` immutable component with the specified `saveLabel`.
    `ISignature` | `withSaveType​(java.lang.String saveType)` | Returns a copy of `this` immutable component with the specified `saveType`.
    `ISignature` | `withToolbarVisible​(boolean toolbarVisible)` | Returns a copy of `this` immutable component with the specified `toolbarVisible`.
    `ISignature` | `withUndoLabel​(java.lang.String undoLabel)` | Returns a copy of `this` immutable component with the specified `undoLabel`.

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

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

- - ### Field Detail

    - #### DEFAULT

          static final ISignature DEFAULT

      Constant for default attributes of this immutable component.

  - ### Method Detail

    - #### getWidgetClass

          default java.lang.String getWidgetClass()

      Returns the client widget class.

      Default: `"zkmax.signature.Signature"`

      Specified by:
        `getWidgetClass` in interface `IComponent<ISignature>`
      Returns:

    - #### getBackgroundImage

          @Nullable
          java.lang.String getBackgroundImage()

      Returns the background image URI of signature pad.

      Default: `null`.

    - #### withBackgroundImage

          ISignature withBackgroundImage​(@Nullable
                                         java.lang.String backgroundImage)

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

      Sets the background image URI of signature pad.

      Parameters:
        `backgroundImage` - The background image URI of signature pad

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getUndoLabel

          @Nullable
          java.lang.String getUndoLabel()

      Returns the label on undo button.

      Default: `null`.

    - #### withUndoLabel

          ISignature withUndoLabel​(@Nullable
                                   java.lang.String undoLabel)

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

      Sets the label on undo button.

      Parameters:
        `undoLabel` - The label on undo button.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getSaveLabel

          @Nullable
          java.lang.String getSaveLabel()

      Returns the label on save button.

      Default: `null`.

    - #### withSaveLabel

          ISignature withSaveLabel​(@Nullable
                                   java.lang.String saveLabel)

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

      Sets the label on save button.

      Parameters:
        `saveLabel` - The label on save button.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getClearLabel

          @Nullable
          java.lang.String getClearLabel()

      Returns the label on clear button.

      Default: `null`.

    - #### withClearLabel

          ISignature withClearLabel​(@Nullable
                                    java.lang.String clearLabel)

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

      Sets the label on clear button.

      Parameters:
        `clearLabel` - The label on save button.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getPenSize

          default int getPenSize()

      Returns the pen size of the signature pad.

      Default: `1`.

    - #### withPenSize

          ISignature withPenSize​(int penSize)

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

      Sets the pen size of the signature pad.

      Parameters:
        `penSize` - The pen size of the signature pad.

        Default: `1`.

      Returns:
        A modified copy of the `this` object

    - #### getPenColor

          default java.lang.String getPenColor()

      Returns the pen color of the signature pad.

      Default: `"black"`.

    - #### withPenColor

          ISignature withPenColor​(java.lang.String penColor)

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

      Sets the pen color of the signature pad.

      Parameters:
        `penColor` - The pen color of the signature pad.

        Default: `"black"`.

      Returns:
        A modified copy of the `this` object

    - #### getBackgroundColor

          default java.lang.String getBackgroundColor()

      Returns the background color of the signature pad.

      Default: `"white"`.

    - #### withBackgroundColor

          ISignature withBackgroundColor​(java.lang.String backgroundColor)

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

      Sets the background color of the signature pad.

      Parameters:
        `backgroundColor` - The background color of the signature pad.

        Default: `"white"`.

      Returns:
        A modified copy of the `this` object

    - #### getSaveType

          default java.lang.String getSaveType()

      Returns the type for saving signature image. The supported type is MIME type, e.g., `"image/png"`, `"image/jpeg"`. If the requested type is invalid or unspecified, it will use `"image/png"`. Default: `"image/png"`.

    - #### withSaveType

          ISignature withSaveType​(java.lang.String saveType)

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

      Sets the type for saving signature image. The supported type is MIME type, e.g., `"image/png"`, `"image/jpeg"`. If the requested type is invalid or unspecified, it will use `"image/png"`.

      Parameters:
        `saveType` - The type for saving signature image.

        Default: `"image/png"`.

      Returns:
        A modified copy of the `this` object

    - #### isBackgroundIncluded

          default boolean isBackgroundIncluded()

      Returns whether the background color and image are included while saved.

      Default: `true`.

    - #### withBackgroundIncluded

          ISignature withBackgroundIncluded​(boolean backgroundIncluded)

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

      Sets whether the background color and image are included while saved.

      Parameters:
        `backgroundIncluded` - Whether the background color and image are included while saved

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### isToolbarVisible

          default boolean isToolbarVisible()

      Returns the visibility of the toolbar for signature pad.

      Default: `true`.

    - #### withToolbarVisible

          ISignature withToolbarVisible​(boolean toolbarVisible)

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

      Sets the visibility of the toolbar for signature pad.

      Parameters:
        `toolbarVisible` - The visibility of the toolbar for signature pad.

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### ofSize

          static ISignature ofSize​(java.lang.String width,
                                   java.lang.String height)

      Returns the instance with the given size, width and height.
      Parameters:
        `width` - The width of the component
        `height` - The height of the component

    - #### ofId

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

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