SigCtl

SigCtl

Summary

Method
AboutBox
Capture
GetProperty
SetProperty

Property
AppData
BackColor
BackStyle
BorderColor
BorderStyle
BorderVisible
BorderWidth
Caption
CtlPadding
DisplayMode
Enabled
Font
ForeColor
InkColor
InkWidth
InputData
InputSignature
InputWho
InputWhy
Licence
Rotation
ShowWhen
ShowWho
ShowWhy
Signature
TabStop
WhenFormat
Zoom

Event
Click
DblClick
KeyDown
KeyPress
KeyUp
MouseDown
MouseMove
MouseUp
PostCapture
PreCapture
Remove

Note
SigCtlXHTML extends this class and includes common methods and properties.

Methods

AboutBox

Displays an About Box for the control. The dialog box will display version, licensing and contact information:

Void AboutBox()
Parameters
None
Return Value
None

Capture

This method is deprecated; the DynamicCapture object should instead be used.

Displays a Signature Capture Window in which a user may sign their name using a digitizing tablet. The window contains three buttons:

• Clear: Clears the currently rendered signature.
• Cancel: Dismisses the window without capturing a signature.
• OK: Dismisses the window and captures the currently rendered signature.

CaptureResult Capture(Who, Why, What, Key)
Parameters
Who	String specifying the signatory name. Optional if InputWho property is set.
Why	String specifying the reason for signing. Optional if InputWhy property is set.
What	Hash object derived from the data set with which the captured signature is to be bound. Typically, the data set is the content of the document or form signed by the user. SigCtlXHTML: The hash is generated automatically from the contents of the XHTML document and cannot be supplied here. (Optional)
Key	Key object supplied to detect malicious or accidental tampering with the signature object or the signature data it contains. SigCtlXHTML: Key type SHA256 is supplied automatically, but an alternative can be specified. (Optional)
Return Value
CaptureResult
CaptureOK	Signature captured successfully.
CaptureCancel	Signature not captured because the user cancelled the Signature Capture Window.
CapturePadError	No capture service available; typically, no functioning digitizing tablet or other device for capturing signatures was found.
CaptureNotLicensed	The component has not been licensed to perform capture. This may be due to an unsuitable license or unmet licensing conditions (e.g., no suitable hardware was found).
CaptureError	System error or another unusual error condition.
CaptureAbort	Signature not captured because the handler for the PreCapture event returned False. SigCtlXHTML: This can indicate a failure to parse document contents.

---

GetProperty

Returns the current value of a property.

void GetProperty(Name)
Parameters
Name	The name of the property to retrieve.
Return Value
Variant
Current value of the named property. Empty if no value has been set.

---

SetProperty

Sets the value of a named additional property, overriding a value set in the registry.

void SetProperty(Name, Value)
Parameters
Name	String. Name of the property.
Value	Value to assign to the property.
Return Value
Boolean
True: Name exists and value is valid. False: Failed to set property.

Properties

Property	Type	SigCtl Property Description
AppData(Key)	Variant	Application data identified by Key Parameterised property supporting key/value pairs for the storage of any application specific data. For example, may be used to store a signatory name and reason for signing in the control prior to the signature being captured. The Key may be an integer or string e.g. two separate keys: sig.AppData(0)="a" sig.AppData("0")="b" AppData may be initialised in XHTML using the AppData param name, e.g. <param name="AppData" value="key1=value1;key2=value2;etc=etc"/>
BackColor	OLE_COLOR	Colour of control (Signature Area) background. Default = background colour of container if available, or colour of system window.
BackStyle	Int	Used to determine whether the control is transparent or opaque. 0 = Opaque 1 = Transparent Default: Opaque
BorderColor	OLE_COLOR	Colour of control (Signature Area) border if BorderStyle is 'flat'. Ignored for other values of BorderStyle. Default = colour of system window frame.
BorderStyle	Int	Style of control (Signature Area) border. While any long value can be set, the BorderStyle enumerator includes the most useful values. Default = 0 (BdrFlat)
BorderVisible	Boolean	Shows or hides the control (Signature Area) border: True is visible, False is not visible. Default = True
BorderWidth	Int	Width in pixels of control (Signature Area) border if BorderStyle is 'flat'. Ignored for other values of BorderStyle. Default = 1
Caption	String	Text centrally displayed in the control (Signature Area) when no signature has been captured as an alternative to the default signature guideline. Default = Empty string
CtlPadding	Short	Size, in pixels, of space between the border of the control (Signature Area) and the bounding rectangle of the rendered signature if DisplayMode is 'DspForceFit'. Ignored if DisplayMode is 'DspUseZoom'. Default = 2
DisplayMode	DisplayMode (Enum)	Specifies scaling mode of rendered signature, with possible values: DspForceFit scale signature to exactly fit the control (Signature Area). DspUseZoom scale signature (relative to its actual size) according to the Zoom property. DspBestFit reduce signature to fit in box if too big, otherwise show at true size. In each case, the image is centred in the control. If scaling is chosen and the value of the Zoom property results in an image larger than the control area, it will be clipped. Default = DspForceFit
Font	IFontDisp	Font used to display the Caption property (if set) and the When/Who text (see ShowWhen & ShowWho properties). Default = container font, if available, or 8 point MS Sans Serif.
ForeColor	OLE_COLOR	Colour of the default signature guideline or (if set) the Caption property text, and the colour of any When/Who text displayed in the Signature Area (see ShowWhen & ShowWho properties). Default = foreground colour of container, if available, or system window text colour. Note: the colour of the rendered signature is controlled independently by the InkColor property.
InkColor	OLE_COLOR	Colour of 'ink' used to render signature image. Default = system window text colour
InkWidth	Float	Width, in mm, of 'ink' used to render signature image. Default = 0.7mm Note: min = 0.1mm max = 2.0 mm scales with signature varies with pressure (if pressure data is available)
InputData	String	Allows supplementary data to be stored in the signature. The data is defined in the form of "key=value" pairs separated by ';' e.g. "Account=12345;Branch=AB12" When the signature is captured the InputData values are transferred and become available as the ExtraData in the ISigObjXHTML interface. Key values can be changed by re-setting the parameter, and can be cleared by setting the value to a blank string.
InputSignature	String	Binary Signature SigObj data, base-64 encoded or as a string of hexadecimal digits. On Read the format is determined by the get_SigText registry setting.
InputWho	String	Used to pre-set the name of the person who is to sign. This value is then used if the Who parameter in the Capture method is not defined.
InputWhy	String	Used to pre-set the reason for signing text. This value is then used if the Why parameter in the Capture method is not defined.
Licence	Variant	Licence object or string
Rotation	Short	Drawing angle. Note: Signature rotation is not currently supported. Setting any value other than 0 will cause an error.
ShowWhen	ShowText (Enum)	Specifies whether and how to display time of signing within the Signature Area. See Enumerator Types for possible values. Default = TxtDontShow Note: the entire area of the control is used to render the signature image, thus it is possible for the When text to be overwritten.
ShowWho	ShowText (Enum)	Specifies whether and how to display signatory name within the Signature Area. See Enumerator Types for possible values. Default = TxtDontShow Note: the entire area of the control is used to render the signature image, thus it is possible for the Who text to be overwritten.
ShowWhy	ShowText (Enum)	Specifies whether and how to display the reason for signing text within the Signature Area. See Enumerator Types for possible values. Default = TxtDontShow Note: the entire area of the control is used to render the signature image, thus it is possible for the Why text to be overwritten.
Signature	SigObj	Signature object created by the Signature control. The SigCtl owns the SigObj – both are generally created and destroyed together. However, the SigCtl may be outlived by the SigObj if the client application retains an outstanding object reference. Property put is by value, rather than by reference, so that an assignment in Visual Basic takes the form: SigCtl.Signature = SigObj rather than: Set SigCtl.Signature = SigObj However, the converse assignment takes the form: Set SigObj = SigCtl.Signature
WhenFormat	String	Format used to display time of signing (a Win32-style date/time format string). Default = HH':'mm dd MMM yyyy
Zoom	Short	Scaling factor (expressed as a percentage of actual size) for rendering the signature image when DisplayMode is 'DspUseZoom'. Ignored if DisplayMode is 'DspForceFit'. Default = 100

Properties Supported by GetProperty/SetProperty

Name	Get/Set	Type	Description
Licence	Get/Set	String	String containing the license used for signature capture
Component_FileVersion	Get	String	Component version e.g., "4.5.2.210"
DisablePropertyChange PostCapture	Get/Set	Boolean	Disables changing control properties after a signature has been captured
ShowWhere	Get/Set	ShowText	Specifies whether and how to display the location of signing within the Signature Area. See Enumerator Types for possible values.
UILanguage	Get/Set	String	Selects the language used in the signature capture dialog.
hWnd	Get/Set	Variant	Windows handle used to display the control

---

Events

Click

Occurs when the user clicks (presses and then releases) a mouse button over a SigCtl.

Private Sub object_Click()
Parameters
None
Return Value
None

DblClick

Occurs when the user double-clicks a mouse button over a SigCtl.

Private Sub object_DblClick()
Parameters
None
Return Value
None

---

KeyDown

Occurs when the user presses a key while a SigCtl has the focus.

Private Sub object_KeyDown( KeyCode, Shift )
Parameters
KeyCode	Short integer code for the key pressed. Passed by reference; changing it sends a different code to the control (however, the control does not process key presses).
Shift	Short integer bit field indicating the state of the SHIFT (bit 0), CTRL (bit 1), and ALT (bit 2) keys at the time of the event. These bits correspond to values 1, 2, and 4 respectively.
Return Value
None

---

KeyPress

Occurs when the user presses and releases an ANSI key while a SigCtl has the focus.

Private Sub object_KeyPress( KeyAscii )
Parameters
KeyAscii	A short integer that returns a standard numeric ANSI keycode. Passed by reference; changing it sends a different character to the control (however, the control does not process key presses).
Return Value
None

---

KeyUp

Occurs when the user releases a key while a SigCtl has the focus.

Private Sub object_KeyUp( KeyCode, Shift )
Parameters
KeyCode	Short integer code for the key released. Passed by reference; changing it sends a different code to the control (however, the control does not process key presses).
Shift	Short integer bit field indicating the state of the SHIFT (bit 0), CTRL (bit 1), and ALT (bit 2) keys at the time of the event. These bits correspond to values 1, 2, and 4 respectively.
Return Value
None

---

MouseDown

Occurs when the user presses a mouse button over a SigCtl.

Private Sub object_MouseDown( Button, Shift, X, Y )
Parameters
Button	Short integer identifying the button pressed. This is a bit field where bits correspond to the left button (bit 0, value = 1), right button (bit 1, value = 2), and middle button (bit 2, value = 4).
Shift	Short integer bit field indicating the state of the SHIFT, CTRL, and ALT keys at the time of the event.
X, Y	Current coordinates of the mouse pointer.
Return Value
None

MouseMove

Occurs when the user moves the mouse over a SigCtl.

Private Sub object_MouseMove( Button, Shift, X, Y )
Parameters
Button	Short integer that corresponds to the state of the mouse buttons in which a bit is set if the button is down. The button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). It indicates the complete state of the mouse buttons; some, all, or none of these three bits can be set, indicating that some, all, or none of the buttons are pressed.
Shift	Short integer bit field indicating the state of the SHIFT (bit 0), CTRL (bit 1), and ALT (bit 2) keys at the time of the event. These bits correspond to the values 1, 2, and 4 respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are down.
X, Y	Current coordinates of the mouse pointer.
Return Value
None

---

MouseUp

Occurs when the user releases a mouse button over a SigCtl.

Private Sub object_MouseUp( Button, Shift, X, Y )
Parameters
Button	Short integer that identifies the button that was released. The button argument is a bit field with bits corresponding to the left button (bit 0, value = 1), right button (bit 1, value = 2), and middle button (bit 2, value = 4). Only one of the bits is set, indicating the button that caused the event.
Shift	Short integer bit field indicating the state of the SHIFT (bit 0), CTRL (bit 1), and ALT (bit 2) keys at the time of the event. These bits correspond to the values 1, 2, and 4 respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are down.
X, Y	Current coordinates of the mouse pointer.
Return Value
None