Signature"

From Documentation
 
(52 intermediate revisions by 7 users not shown)
Line 2: Line 2:
  
 
= Signature =
 
= Signature =
 +
{{versionSince| 8.6.0}}
 +
{{ZK EE}}
  
−
*Demonstration: [http://www.zkoss.org/zkdemo/input/signature Signature]
 
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Signature</javadoc>
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Signature</javadoc>
−
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Slider</javadoc>
+
*JavaScript API: <javadoc directory="jsdoc">zkmax.wgt.Signature</javadoc>
−
*Style Guide: [[ZK_Style_Guide/XUL_Component_Specification/Signature | Signature]]
+
 
 +
= Browser Support =
 +
*This component supports IE10+ and modern browsers.
  
 
= Employment/Purpose =
 
= Employment/Purpose =
−
A Signature component represents a signature pad which can let user to take a signature on zk. It supports the desktop and touch-panel device. The Signature widget provides save, undo and clear API, you can save undo and clear the SignaturePad with this API. And Signature also provide a build-in tool bar to control the API.
+
Signature components support signature pad on the desktop and mobile browsers. User can customize pen size, pen color, background color etc., it also provides undo, save and clear methods.
  
 
= Example =
 
= Example =
−
[[Image:ZKComRef_Slider.png]]
+
[[File:Signature.png]]
  
 
<source lang="xml" >
 
<source lang="xml" >
−
  <slider id="slider" orient="vertical"/>
+
<signature width="600px" height="300px" penColor="white" backgroundColor="#AED6F1" penSize="6"/>
−
  <slider curpos="1" maxpos="20" />
 
 
</source>
 
</source>
  
−
= Minimal Position =
+
== Buttons ==
−
  [Since 7.0.1]
 
−
Slider supports minimal position, which can be changed by the minpos property as follows.
 
  
−
[[File:min_slider.png]]
+
There are 3 buttons when you hover on this component: (from left to right)
  
−
<source lang="xml" >
+
# '''undo''': to remove the last step that was drawn on the signature pad.
−
  <slider minpos="30"/>
+
# '''save''': to save the signature image to the server, a user can get the image by listening onSave event.
−
</source>
+
# '''clear''': to clear signature pad.
−
Slider also provides <tt>setRange(int, int)</tt> and <tt>setRange(double, double)</tt> methods to help user change the range from minimal position to maximum position.
 
  
−
= Decimal Mode =
+
= toolbarVisible =
−
  [Since 7.0.1]
 
−
Set the mode property to "decimal" will enable decimal slider. So the slider can represent decimal number.
 
  
−
[[File:dec_slider.png]]
+
The toolbar contains 3 buttons: undo button, clear button, and save button. They are visible by default. If you can hide them:
  
−
<source lang="xml" >
+
<source lang="xml">
−
  <slider mode="decimal" step="0.1"/>
+
<signature toolbarVisible="false"/>
 
</source>
 
</source>
  
−
= Page Increment =
+
The toolbar buttons only contain icons by default. If you want to show message after icons on the buttons, we provide three attributes: <code>undoLabel</code>, <code>clearLabel</code>, and <code>saveLabel</code>.
 +
 
 +
Default:
 +
 
 +
[[File:Signature toolbar.png]]
  
−
By default, the slider will move to the position of the try on which an user clicks. If you prefer to move in a fixed amount (like the scrollbar does), you could specify the amount of value to move by use of <javadoc method="setPageIncrement(int)">org.zkoss.zul.Slider</javadoc>.
+
Customized:
  
−
<source lang="xml" >
+
[[File:Signature toolbar2.png]]
−
  <slider pageIncrement="10"/>
+
<source lang="xml">
 +
<signature undoLabel="Undo" clearLabel="Clear" saveLabel="Save"/>
 
</source>
 
</source>
  
−
= Step =
+
= Style Attributes =
−
  [Since 7.0.1]
 
−
By default, the slider will scroll to the position continuously when an user drags it. If you prefer to scroll a discrete fixed amount on each step, you can set the amount of value of the <tt>step</tt> property. Step property is useful in decimal mode, slider's position value could be rounded to a fixed number by specifying step property. For example, if we want to retrieve the value from decimal slider in the range of 10.0 to 12.0. As the below picture shows, the default decimal show the value contains only one digit in fractional part.
 
  
−
[[File:dec_slider_no_step.png]]
+
There are some attributes to adjust the signature style:
  
−
If we want to retrieve the value which contains two digits in fractional part, we can set the step value to 0.01. Then the value will increase as 10.01, 10.02, 10.02 on each step when scrolling the slider. If step is 0.05, the value will increase as 10.05, 10.10, 10.15 on each step, as below.
+
== penSize==
 +
the width of a line on the signature, the default is 1.
  
−
[[File:dec_slider_step.png]]
+
== penColor ==
 +
Can be any color format accepted by context.fillStyle(canvas), defaults to black.
  
−
<source lang="xml" >
+
== backgroundColor==  
−
  <slider mode="decimal" minpos="10.0" maxpos="12.0" step="0.05"/>
+
Can be any color format accepted by context.fillStyle(canvas), defaults to white.
−
</source>
 
  
−
= Knob Mold =
+
== backgroundImage==  
−
  [Since 8.6.0]
+
{{versionSince| 9.6.0}}
−
Set the mold property to "knob" will enable knob slider. So the slider can act as a normal knob. The knob can controlled by wheel, drag, click and enter a value to the input element.
+
Can be any image format accepted by context.drawImage(canvas), defaults to null.
  
−
[[File:knob360.png]]
+
= BackgroundIncluded =
 +
{{versionSince |9.6.0}}
  
−
<source lang="xml" >
+
The background color and image will be saved by default.  If you don't want to save the background color and image, please use the following setting.
−
  <slider mold="knob" mold="knob" minpos="0.0" maxpos="100.0" curpos="40.0" step="1"/>
+
<source lang="xml">
 +
<signature backgroundIncluded="false"/>
 
</source>
 
</source>
  
 +
== Scanned Paper Form==
 +
You can load a scanned paper form as a background and save it with a signature.
 +
[[File:Paper-form.jpg|center]]
  
−
= AngelArc & strokeWidth=
+
= Saves Signature Image =
−
  [Since 8.6.0]
 
−
AngelArc & strokeWidth are properties only for knob mold. Set the angelArc property with a double for the angle of the knob slider. Set the strokeWidth property with a double for the stroke width of the knob.
 
  
−
[[File:knob270.png]]
+
After clicking "Save" button, the component will upload the signature to a server. You can listen <code>onSave</code> to get the uploaded signature and show it with [https://www.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Image Image]:
  
−
<source lang="xml" >
+
<source lang="xml">
−
  <slider mold="knob" mold="knob" minpos="0.0" maxpos="100.0" curpos="40.0" step="1" strokeWidth="20" angelArc="270"/>
+
<signature onSave="image.setContent(event.getMedia())"/>
 +
<image id="image"/>
 
</source>
 
</source>
 +
 +
== File Size Limit ==
 +
If you see <code>SizeLimitExceededException</code>, you can adjust max uploading file size by
 +
[[ZK_Configuration_Reference/zk.xml/The_system-config_Element/The_max-upload-size_Element | file-size-threshold]].
  
 
=Supported Events=
 
=Supported Events=
  
−
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
−
| <center>onScroll</center>
+
| <center>onSave</center>
−
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.ScrollEvent</javadoc>
+
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>
−
Denotes the content of a scrollable component has been scrolled by the user.  
+
When user invoke the save method, the event would be triggered.  
 
|-
 
|-
−
| <center>onScrolling</center>
+
| <center>onClear</center>
−
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.ScrollEvent</javadoc>
+
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
−
Denotes that the user is scrolling a scrollable component. Notice that the component's content (at the server) won't be changed until onScroll is received. Thus, you have to invoke the <tt>getPos</tt> method in the ScrollEvent class to retrieve the temporary position.
+
When user invoke the clear method, the event would be triggered.  
−
|}
 
−
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/XulElement#Supported_Events | XulElement]]
 
−
 
 
−
=Supported Molds=
 
−
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
−
{| border="1" | width="100%"
 
−
! <center>Name</center>
 
−
! <center>Snapshot</center>
 
−
|-
 
−
| <center>default</center>
 
−
|[[Image:slider_mold_default.png ]]
 
−
|-
 
−
| <center>sphere</center>
 
−
|[[Image:slider_mold_sphere.png ]]
 
−
|-
 
−
| <center>scale</center>
 
−
|[[Image:slider_mold_scale.png ]]
 
−
|-
 
−
| <center>knob</center>
 
−
|[[Image:knob360.png ]][[Image:knob270.png ]]
 
−
|}
 
−
 
 
−
[Since 7.0.0]  [mold knob Since 8.6.0]
 
−
 
 
−
the scale mold is deprecated because designs are changed.
 
−
 
 
−
=Supported Children=
 
−
 
 
−
*None
 
−
 
 
−
=Use Cases=
 
−
 
 
−
{| border='1px' | width="100%"
 
−
! Version !! Description !! Example Location
 
−
|-
 
−
| &nbsp;
 
−
| &nbsp;
 
−
| &nbsp;
 
 
|}
 
|}
  
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
−
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
−
| 5.0.4
+
| 8.6.0
−
| August 2010
+
| August 2018
−
| <javadoc method="setPageIncrement(int)">org.zkoss.zul.Slider</javadoc> is supported.
+
|
−
|-
 
−
| 5.0.4
 
−
| August 2010
 
−
| Slider support for clicking to increment or decrement
 
−
|-
 
−
| 7.0.1
 
−
| January 2014
 
−
| [http://tracker.zkoss.org/browse/ZK-2085 Slider support minimal position and decimal mode]
 
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 10:15, 19 September 2022


DocumentationZK Component ReferenceInputSignature
Signature

Signature

Since 8.6.0

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Browser Support

  • This component supports IE10+ and modern browsers.

Employment/Purpose

Signature components support signature pad on the desktop and mobile browsers. User can customize pen size, pen color, background color etc., it also provides undo, save and clear methods.

Example

Signature.png 

<signature width="600px" height="300px" penColor="white" backgroundColor="#AED6F1" penSize="6"/>

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.

toolbarVisible

The toolbar contains 3 buttons: undo button, clear button, and save button. They are visible by default. If you can hide them: 

<signature toolbarVisible="false"/>

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

Default:

Signature toolbar.png

Customized:

Signature toolbar2.png 

<signature undoLabel="Undo" clearLabel="Clear" saveLabel="Save"/>

Style Attributes

There are some attributes to adjust the signature style:

penSize

the width of a line on the signature, the default is 1.

penColor

Can be any color format accepted by context.fillStyle(canvas), defaults to black.

backgroundColor

Can be any color format accepted by context.fillStyle(canvas), defaults to white.

backgroundImage

Since 9.6.0 Can be any image format accepted by context.drawImage(canvas), defaults to null.

BackgroundIncluded

Since 9.6.0

The background color and image will be saved by default. If you don't want to save the background color and image, please use the following setting. 

<signature backgroundIncluded="false"/>

Scanned Paper Form

You can load a scanned paper form as a background and save it with a signature.

Paper-form.jpg

Saves Signature Image

After clicking "Save" button, the component will upload the signature to a server. You can listen onSave to get the uploaded signature and show it with Image: 

	<signature onSave="image.setContent(event.getMedia())"/>
	<image id="image"/>

File Size Limit

If you see SizeLimitExceededException, you can adjust max uploading file size by file-size-threshold.

Supported Events

Name
Event Type
onSave
 Event: UploadEvent

When user invoke the save method, the event would be triggered.

onClear
 Event: Event

When user invoke the clear method, the event would be triggered.

Version History

Last Update : 2022/09/19


Version Date Content
8.6.0 August 2018



Last Update : 2022/09/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Component_Reference/Input/Signature&oldid=55161"