WizCtl

WizCtl

Summary

Method
AddObject
AddPrimitive
Display
FireClick
GetObjectState
GetProperty
PadConnect
PadDisconnect
Reset
SetEventHandler
SetProperty

Property
BackColor
BorderColor
BorderStyle
BorderVisible
BorderWidth
EnableWizardDisplay
Font
InkingPad
Licence
PadHeight
PadWidth
Zoom

Event
PadEvent

Methods

AddObject

Adds an item to the pad control list.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectType enum value.
Id	String. Specifies an identifier for the object.
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	VARIANT. Value dependent on object type.
Options	VARIANT. Value dependent on object type.
Return Value
None

AddObject(ObjectText)

Displays a text string on the pad using the current font.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectText
Id	The following values have special meanings when used with a signature object: "who" - Text in Data will also be used as name of signatory. "why" - Text in Data will also be used as reason for signing. "when" - Reserved for future use. (Can be null or an empty string)
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	Text to display.
Options	A value from the TextOptions Enumerator (Optional).
Return Value
None

AddObject(ObjectButton)

Creates a button – text surrounded by a rectangle which generates a click event when tapped with the pen. Text is displayed in the current font.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectButton
Id	The following values have special meanings when used with signature or input objects: "OK" - Accepts current input.     • With a signature, stores the captured signature in the signature object and terminates input.     • Until a signature has been captured, the button is disabled by the Wizard Control.     • With an Input object, the button is disabled until the required minimum number of characters has been entered. "Clear" - Clears current input allowing user to start again.     • With a signature, clears any captured 'ink' from the display.     • With an Input object, clears all entered input. "Cancel" - With a signature, clears any captured 'ink' and terminates input. "Delete" - With an input object, deletes the last character.
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	Text to display.
Options	Either an integer specifying button width in pixels or an ObjectOptions object. If the given width is less than the width of the text (in the current font), it is ignored. (Optional)
Return Value
None

AddObject(ObjectCheckbox)

Creates a checkbox – a small rectangle followed by text which toggles its state and generates an event when tapped with the pen. Text is displayed in the current font.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectCheckbox
Id	The following values have special meanings when used with a signature object. Cannot be any of the values reserved for text or button objects: "who", "why", "OK", "Clear", "Cancel".
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	Text to display.
Options	A combination of values from the CheckboxOptions enum. (Optional)
Return Value
None

AddObject(ObjectRadioButton)

Creates a radio button – a small circle followed by text. Radio buttons are used in groups where tapping on one with the pen selects it and deselects the currently selected button in the group. Tapping with the pen also generates an event. Text is displayed in the current font.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectCheckbox
Id	The following values have special meanings when used with a signature object. Cannot be any of the values reserved for text or button objects: "who", "why", "OK", "Clear", "Cancel".
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	Text to display.
Options	ObjectOptions object specifying the name of the group to which this radio button belongs and, optionally, whether this option is initially selected.
Return Value
None

AddObject(ObjectSignature)

Puts the pad into signature capture mode and specifies a signature object or control in which a captured signature is saved. It is an error to add more than one ObjectSignature to the current control list.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectSignature
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	A signature object or control. Note: Cannot be a SigCtlXHTML if an ObjectHash has been added.
Options	A Key object to use for setting integrity of captured signature. (Optional)
Return Value
None

AddObject(ObjectInput)

Provides an input mechanism for PIN code entry.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectInput
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	InputObj to be used for handling pin pad input.
Options	Not used, should be omitted.
Return Value
None

AddObject(ObjectInputEcho)

Specifies location of and character to use for ObjectInput 'echo'.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectInputEcho
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	Character to be used for each button press.
Options	Either, a combination of values from the InputEchoOptions enum or an ObjectOptions object. (Optional)
Return Value
None

AddObject(ObjectHash)

Supplies a Hash object representing data to be bound to a captured signature. It is an error to add more than one ObjectHash to the current control list. Cannot be used in conjunction with a SigCtlXHTML control (ie in a web page) as the latter automatically binds to the host document.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectHash
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	Hash object representing data to be bound to a captured signature.
Options	Not used, should be omitted.
Return Value
None

AddObject(ObjectImage)

Displays an image on the pad. The image can optionally be made clickable in which case click events are generated when the image is tapped with the pen.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectImage
Id	Supports the same reserved Ids as button objects. To make the image clickable, supply a named Id (e.g. "myimage"). To prevent the image from being clickable, supply a blank Id ("").
X, Y	Position of the top left corner of the object on the pad display. Value can either be absolute position in pixels, or one of the strings: X: "left", "right", "centre" Y: "top", "middle", "bottom"
Data	Image to display. Can be any one of the following: String: containing "://" is assumed to be the URL of an image file; containing a character '.' or '\' is assumed to be the name of an image file on the local file system; otherwise assumed to be base64-encoded image data. Picture: OLE picture object (IPicture or IPictDisp interface). Array of bytes: Binary image data as an array of bytes.
Options	Not used, should be omitted.
Return Value
None

AddObject(ObjectDisplayAtShutdown)

Causes the current control set to remain displayed on the pad following disconnection.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectDisplayAtShutdown
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	Not used, should be omitted.
Options	Not used, should be omitted.
Return Value
None

AddObject(ObjectInking)

Provides a mechanism for capturing pad 'ink' as an image.

void AddObject( Type, Id, X, Y, Data, Options )
Parameters
Type	ObjectInking
Id	Cannot be any of the values reserved for text or button objects: who, why, Ok, Clear, Cancel; can be null or an empty string.
X, Y	Values ignored.
Data	Not used, should be omitted.
Options	Not used, should be omitted.
Return Value
None

A snapshot of current ink is retrieved, in PNG format as a base-64 encoded string, using the WizCtl GetProperty method as follows:

var pngAsText = wizctl.GetProperty("ObjectInking_Bitmap");

Alternatively, the image can be written to a file using SetProperty. The format of the image is determined by the file name extension (bmp, jpg, png or tif):

wizctl.SetProperty("ObjectInking_Bitmap", "c:\\file.png");

In both cases, the size of the image is the size of the LCD screen.

AddPrimitive

Adds a graphics primitive item to the internal list.

void AddPrimitive( Type, X1, Y1, X2, Y2, Data, Options )
Parameters
Type	PrimitiveType enum value.
X1, Y1	If Type is PrimitiveLine, start position of line, otherwise position of top-left corner of bounding rectangle of item. Value can be the absolute position in pixels, or one of the strings: X1: "left", "right", "centre" Y1: "top", "middle", "bottom".
X2, Y2	If Type is PrimitiveLine, end position of line, otherwise position of bottom-right corner of bounding rectangle of item. Value can be the absolute position in pixels, one of the strings: X2: "left", "right", "centre" Y2: "top", "middle", "bottom" Or a string in the format "+V" or "V" (where V is an integer) for a value relative to X1 or Y1.
Data	Line width in pixels (Optional, default value 1).
Options	VARIANT. Combination of PrimitiveOptions values (Optional, default value PrimitiveLineSolid + PrimitiveOutline).
Return Value
None

Display

Clears current display contents, turns on backlight (if not already on), updates display with all buffered objects and primitives, and enables event handling.

void Display()
Parameters
None
Return Value
None

---

FireClick

Simulates 'click' on an object (button, checkbox, image, etc). Allows, for example, a signature to be accepted by clicking a button on the PC screen rather than tapping the OK button on the pad.

void FireClick(Id)
Parameters
Id	Id of pad control for which to simulate click.
Return Value
None

---

GetObjectState

Returns state information of a given object or an empty Variant if the specified object does not exist.

Variant GetObjectState( Id )
Parameters
Id	Identifier of object.
Return Value
Variant
ObjectCheckbox	1 = Checked; 0 = Unchecked
ObjectInput	Number of characters currently in input buffer
Other Object types	Integer, value undefined
Id not recognised	Empty variant

---

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.

---

PadConnect

Connects to the signature tablet/pad.

Boolean PadConnect()
Parameters
None
Return Value
Boolean	True if the connection was successful, False if it failed to connect.

PadDisconnect

Disconnects the signature tablet/pad.

void PadDisconnect()
Parameters
None
Return Value
None

---

Reset

Disables events, removes all internal controls, and prepares for setting the display. Does not change the current display.

void Reset()
Parameters
None
Return Value
None

---

SetEventHandler

Sets the script function to be called to handle tablet control events.

void SetEventHandler(EventHandler)
Parameters
EventHandler	Dispatch interface with a default method. See Notes below for method parameters.
Return Value
None

---

SetProperty

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

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

Properties

Property	Type	WizCtl Property Description
BackColor	OLE_COLOR	Background colour.
BorderColor	OLE_COLOR	Colour of 'Flat' border.
BorderStyle	long	Type of border displayed if BorderVisible is True. See BorderStyle enumeration type.
BorderVisible	Boolean	True to draw a border around the wizard display; False to draw without a border.
BorderWidth	long	Width in pixels of 'Flat' border.
EnableWizardDisplay	Boolean	Enables or disables mouse interaction with objects (buttons, etc.) on the wizard display. Note: Mouse interaction is not currently implemented.
Font	IFontDisp	Font used to display text of all subsequently added objects.
InkingPad	Boolean	True if the pad has a display (Read-only).
Licence	Variant	Licence object or string.
PadHeight	short	Height of the pad display in pixels. Read-only if inking pad.
PadWidth	short	Width of the pad display in pixels. Read-only if inking pad.
Zoom	float	Sets the scaling of the wizard display relative to the physical pad display as a percentage. (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".
DynamicSignatureCapture_RetryCount	Get/Set	String	The number of times the Clear button can be used during signature capture.
ForceMonochrome	Get/Set	Boolean	When true, the Wizard sends text displays as monochrome images. This reduces the time to update the display on colour STU tablets.
ObjectInking_Bitmap	Get	String	Snapshot of captured 'ink' in PNG image format, as a base-64 encoded string. (See AddObject(ObjectInking)).
InputValue	Set	-	Sets the value for an ObjectInput.
ObjectOptions.*	Get	Boolean	True if specified option is supported. Possible values are: ObjectOptions.Button.Width ObjectOptions.Button.Height ObjectOptions.Button.Invert ObjectOptions.Echo.Char ObjectOptions.Echo.Spacing ObjectOptions.Echo.Underline ObjectOptions.Echo.Length
CaptureInkWidth	Get/Set	String	Decimal width (in mm) of 'ink' used to render the signature image.Default: 0.7mmNote:min = 0.1mm, max = 2.0mm, scales with signature, varies with pressure (if pressure data is available).
CaptureInkColor	Get/Set	String	Color of 'ink' used to render the signature image as a comma-separated decimal RGB value. Example for Blue:setProperty("CaptureInkColor", "0,0,1")Individual color values are in the decimal range 0.0 to 1.0, factoring the RGB maximum of 255. Examples: 0.0 for 0 0.5 for 127 1.0 for 255
ObjectForegroundColor	Get/Set	String	Foreground color to use for objects added subsequently, as a comma-separated decimal RGB value.
ObjectBackgroundColor	Get/Set	String	Background color to use for objects added subsequently, as a comma-separated decimal RGB value.