Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

Signature

Methods6
Methods - Class
captureclearhidesetVectorCallbackshowtakeFullScreen
Properties11
Class Properties
bgColorbordercompressionFormatfileNameheightleftoutputFormatpenColorpenWidthtopwidth
Examples3
Capture signature to file (fullscreen) and display it in a viewSet signature capture propertiesCapture as DataURI
Remarks4
Fullscreen and In-lineParameters which clear the signaturePage NavigationPersistent Behavior

creates a rectangular box within which the user can draw by using a finger or the device’s stylus to record handwritten data. Common usages for this tag include the capture of client/customer signatures and the input of handwritten text/notations. It is recommended to not to rotate the device when Signature window is shown.

Enabling the API

In order to use this API you must include the following extension in your build.yml

extensions: ["signature"]

The signature extension is also included automatically if you specify the following in your build.yml

app_type: "rhoelements"

Note: If you are building a Windows Mobile or Windows CE app with this API, you must set your app_type as “rhoelements” in your build.yml as shown here.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Persistence

With the old PocketBrowser / RhoElements 1 APIs, any events, such as signatureCaptureEvent were canceled when a full navigate was performed. The original reason for this was a limitation of the IE engine on WM5 devices. When moving to the common API this was changed so that callbacks are not canceled.

Methods

capture
(CallBackHandler callback)

Captures the in-line signature area as an image. This function works with a non-modal signature capture area shown inside browser window. All in-line signature capture functions (like this) do not has affect the capture area shown in takeFullScreen (modal full screen capture area).

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • status : STRING

      Whether a signature was captured or the signature capture area was dismissed (Fullscreen version only). Possible values:‘ok’ or ‘cancel’

    • imageUri : STRING

      If the outputFormat is “image”, this will be the URI of the captured signature image. If the outputFormat is “dataUri”, this will be the DataURI representation of the captured signature image.

    • signature_uri : STRING

      If the outputFormat is “image”, this will be the URI of the captured signature image. If the outputFormat is “dataUri”, this will be the DataURI representation of the captured signature image.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.capture(CallBackHandler callback)
    • Ruby: Rho::Signature.capture(CallBackHandler callback)
clear
()

Clears an in-line capture area. This function works with a non-modal signature capture area shown inside browser window. All in-line signature capture functions (like this) do not has affect to capture area shown in takeFullScreen (modal full screen capture area)

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.clear()
    • Ruby: Rho::Signature.clear()
hide
()

Hides an in-line capture area from view. It clears the inputed signature for in-line signature areas. In a hidden state, a user cannot interact with the signature capture area. This function work with non-modal signature capture area showed inside browser window. All in-line signature capture functions (like this) do not has affect to capture area showed in takeFullScreen (modal full screen capture area)

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.hide()
    • Ruby: Rho::Signature.hide()
setVectorCallback
(CallBackHandler callback)

Signature data is formatted into a series of vectors and returned to the application via this callback function. The received data may not represent the entire signature as the vectors will be sent in batches if the signature is large. A single vector (array entry) contains an X, Y coordinate and the beginning / end of the signature is defined by (65535, 65535). This callback is independent of the callback of the capture method, when specified the callback will be called whenever a ‘pen up’ occurs in the signature box.

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • vectorArray : ARRAY

      JavaScript array of vectors which represent the signature.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.setVectorCallback(CallBackHandler callback)
    • Ruby: Rho::Signature.setVectorCallback(CallBackHandler callback)
show
(HASH propertyMap)

Show in-line signature window. This function works with a non-modal signature capture area shown inside browser window. All in-line signature capture functions (like this) do not has affect the capture area shown in takeFullScreen (modal full screen capture area).

Parameters

  • propertyMap : HASH Optional

    Map of signature properties to be set.

    Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

    Use existing properties from this API.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.show(HASH propertyMap)
    • Ruby: Rho::Signature.show(HASH propertyMap)
takeFullScreen
(HASH propertyMap, CallBackHandler callback)

Shows a modal window with signature capture area and UI (toolbar with buttons) for cancel / capture and return to main application window. The callback is fired when the signature window is closed (when in full-screen) or when capture is called. On WM/CE, the signature area has visible buttons for ‘clear’, ‘capture’ and ‘cancel’. In Android / iOS, the signature area has images which will behave as buttons for ‘clear’, ‘capture’ and ‘cancel’. This function open modal full screen window therefore, other functions related to in-line signature capture (work with inside browser window area) do not affect the capture window shown by this function.

Parameters

  • propertyMap : HASH Optional

    Map of signature properties to be set

    Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

    Use already set properties

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • status : STRING

      Whether a signature was captured or the signature capture area was dismissed (Fullscreen version only). Possible values:‘ok’ or ‘cancel’

    • imageUri : STRING

      If the outputFormat is “image”, this will be the URI of the captured signature image. If the outputFormat is “dataUri”, this will be the DataURI representation of the captured signature image.

    • signature_uri : STRING

      If the outputFormat is “image”, this will be the URI of the captured signature image. If the outputFormat is “dataUri”, this will be the DataURI representation of the captured signature image.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Signature.takeFullScreen(HASH propertyMap, CallBackHandler callback)
    • Ruby: Rho::Signature.takeFullScreen(HASH propertyMap, CallBackHandler callback)

Properties

bgColor
: STRING

RGB or ARGB value that sets the background color of the signature capture area.

Default: #FFFFFFFF

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.bgColor
border
: BOOLEAN

Shows or hides a border for the rectangular capture area. Not applicable to full-screen signature capture area.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.border
compressionFormat
: STRING
Replaces:imageFormat

Compression format of the image file for the captured signature. On WM/CE, irrespective of setting any format, the output format will be of bitmap type. On WM/CE, when compressionFormat is queried, it will be of bitmap type always.

Possible Values (STRING):

Constant: Rho.Signature.COMPRESSION_FORMAT_JPG (For Ruby use "::" for all "." when referencing constants)
String: jpg

JPEG file format (Not available on WM/CE).

Constant: Rho.Signature.COMPRESSION_FORMAT_PNG (For Ruby use "::" for all "." when referencing constants)
String: png

Portable Network Graphics file (Not available on WM/CE).

Constant: Rho.Signature.COMPRESSION_FORMAT_BMP (For Ruby use "::" for all "." when referencing constants)
String: bmp

Bitmap image file (Not available on iOS).

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.compressionFormat
fileName
: STRING
Replaces:name

The filename in which to store the signature image, if “image” is used as the outputFormat. The file extension is determined by the compressionFormat used.

Default: signature

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.fileName
height
: INTEGER

The height of the signature capture area in pixels. Not applicable to full-screen signature capture area.

Default: 150

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.height
left
: INTEGER

The coordinates in pixels of the left side of the signature capture area. Not applicable to full-screen signature capture area.

Default: 15

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.left
outputFormat
: STRING

The return type of the saved signature capture image.

Default: image

Possible Values (STRING):

Constant: Rho.Signature.OUTPUT_FORMAT_IMAGE (For Ruby use "::" for all "." when referencing constants)
String: image

Outputs the signature capture image into an image file. The compression method and extension of the image file can be specified in compressionFormat.

Constant: Rho.Signature.OUTPUT_FORMAT_DATAURI (For Ruby use "::" for all "." when referencing constants)
String: dataUri

Outputs the signature capture image as a DataURI string. (Not available on iOS).

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.outputFormat
penColor
: STRING

RGB or ARGB value that sets the color of the stylus pen ink using HTML web colors.

Default: #FF000000

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.penColor
penWidth
: INTEGER

Sets the width of the pen line in pixels when using the device’s stylus. On Android this setting will also be applied to any previously drawn signature currently displayed. It is advised that you keep this at 5 or less.

Default: 3

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.penWidth
top
: INTEGER

The coordinates in pixels of the top side of the signature capture area. Not applicable to full-screen signature capture area.

Default: 60

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.top
width
: INTEGER

The width of the signature capture area in pixels. Not applicable to full-screen signature capture area.

Default: 200

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.width

Examples

Capture signature to file (fullscreen) and display it in a view

In order to capture a signature in full-screen mode you need to

  def capture_fullscreen
    # Invoke signature capture screen and assign callback
    Rho::Signature.takeFullScreen({}, url_for(:action => :signature_callback))

    render :action => :show_signature
  end

  def signature_callback
    # If status is not 'ok', the capture was canceled
    if @params['status'] == 'ok'

      # By default, the output format is "image", so the imageUri parameter will contain the relative filename of an image
      # We must convert that relative filename to an absolute path in order to access the file
      signature = Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])

      # In our example, we will display the signature as soon as it is captured.
      # We have a JavaScript function in our page to set the src attribute of an img element and we will call it now
      #
      WebView.executeJavascript("updateSignature('#{signature}')")
    else
      # if we did not really capture a signature, there is nothing else to do here
      WebView.navigate(url_for(:action => :index ))
    end
  end

In the view, we have an img element to display the captured signature and a JavaScript function to update it

<div data-role="page">


  <div data-role="header" data-position="in-line">
    <h1>Captured signature</h1>
  </div>

  <div data-role="content">
    <img id="signature-image" src="<%= @signature %>">
  </div>

  <script type="text/javascript">
    function updateSignature(signature) {
      $("#signature-image").attr('src',signature);
    }
  </script>

</div>
Set signature capture properties

Several properties affect the appearance of the signature capture functionality. You can set their values before showing the capture interface:

// Change full-screen from true (default) to false
// Change background color from white (default) to black
// Change pen color from blue (default) to white
Rho.Signature.show ({"fullScreen" : false, "bgColor" : "#000000", "penColor" : "#FFFFFF"});
                   
                 
# Change full-screen from true (default) to false
# Change background color from white (default) to black
# Change pen color from blue (default) to white
Rho::Signature.show { :fullScreen => false, :bgColor => "#000000", :penColor => "#FFFFFF" }
Capture as DataURI

By default, the Signature API returns the capture as an image. If you prefer a DataURI representation of the signature, use the “outputFormat” property

Rho.Signature.takeFullScreen({"outputFormat" : "dataUri"}, signature_callback)
                   
                 
Rho::Signature.takeFullScreen({ :outputFormat => "dataUri" }, url_for(:action => :signature_callback))

Remarks

Fullscreen and In-line

The signature capture feature can work in two visual modes, Full-screen and In-line. The full-screen variant has buttons to capture, clear and cancel the signature capture box, so the methods: “clear”, “hide”, “capture” don’t need to be used. Whereas with the in-line signature capture, there are no such buttons so these will have to be designed into the app itself.

Parameters which clear the signature

The signature capture area is designed to be set up prior to capturing the signature, as such the following parameters will clear any current signature: “width”, “height”, “penColor”, “bgColor”.

Page Navigation

In Android, the state of the signature will not be cleared on page navigation whereas in Windows, the state of the signature is cleared.

Persistent Behavior

While using “takeFullScreen” method, if we press Home button and re-launch the application the state won’t be persisted in Android platform.