Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Signature

Methods 6  
Properties 11
Examples 3
Remarks 4
Licensing

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.

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"

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.

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 1.0.0

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 1.0.0

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 4.0.0

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 "::" instead of ".")
String: jpg

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

Constant: Rho.Signature.COMPRESSION_FORMAT_PNG (For Ruby use "::" instead of ".")
String: png

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

Constant: Rho.Signature.COMPRESSION_FORMAT_BMP (For Ruby use "::" instead of ".")
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 1.0.0

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 1.0.0

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 1.0.0

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 4.0.0

The return type of the saved signature capture image.

Default: image

Possible Values (STRING):

Constant: Rho.Signature.OUTPUT_FORMAT_IMAGE (For Ruby use "::" instead of ".")
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 "::" instead of ".")
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 1.0.0

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 1.0.0

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 1.0.0

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 1.0.0

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.

Licensing

You can fully use all features of this API during evaluation, development or testing without obtaining a license. A message will be displayed on application startup and will also display a nag screen periodically. Before deploying an application to a production environment, you must obtain a license key. Read more about licensing.