Example code

Example code

Warning: This API is deprecated, please consider using the new version located here: http://scriptel.com/developers/proscript/net-library/

STSeries.dll is a .NET assembly used to interface the ScripTouch Series of digitizers to applications. C# is a natural choice of languages for a new .NET application. For this reason, the C# example is the most complete of the example set. Example applications are provided within Visual Studio 12 projects, found in examples.zip. With a ScripTouch device attached, open one of the projects with Visual Studio 12, build and run the application. Experiment with the applications as a user, and modify the code to gain a better understanding of the API.

This topic contains the following sections:

Finding ScripTouch Devices
Addressing the Device
Events
The Signature Class

Finding ScripTouch Devices

To find all of the devices attached to the system, instantiate an STSeriesDevicesManager object. The number of devices attached is returned by GetNumberOfSTSeriesDevices and GetSTSeriesDevice(Int32) will return a the device requested.

C++

Copy

 1// get all of the digitizers plugged into the system
 2ISTSeriesDevice selectedDevice;
 3
 4ISTSeriesDevicesManager devManager = new STSeriesDevicesManager();
 5
 6if (devManager.GetNumberOfSTSeriesDevices() > 0)
 7{
 8    // Use the first device in the list
 9    selectedDevice = devManager.GetSTSeriesDevice(0);
10
11    // Open the device to prepare it for use
12    try
13    {
14        selectedDevice.Open();
15    }
16    catch (STDeviceNotOpenedException dno)
17    {
18        System.Diagnostics.Debug.Assert(false,
19            "Can't open the first device found...this shouldn't happen " +
20            dno.Message));
21    }
22}
23else
24{
25    System.Diagnostics.Debug.Assert(false, "No devices found");
26}

 1'get all of the digitizers plugged into the system
 2
 3Dim selectedDevice As ISTSeriesDevice = Nothing
 4
 5Dim numOfDevices As Integer = devices.GetNumberOfSTSeriesDevices()
 6
 7'Use the first device in the list
 8If numOfDevices > 0 Then
 9    selected Device = devices.GetSTSeriesDevice(0)
10
11    'Open the device to prepare for using it 
12    Try
13        selectedDevice.Open()
14    Catch dno As STDeviceNotOpenedException 
15        System.Diagnostics.Debug.Assert(false, "Can't open the first device found...this shouldn't happen. " + dno.Message)
16    End Try
17Else
18    Console.Writeln("No Scriptel STSeries devices were found on the system")
19End If

 1// C++ example is using managed code: ref class
 2
 3// get all of the digitizers plugged into the system
 4ISTSeriesDevice^ selectedDevice;
 5
 6ISTSeriesDevicesManager^ devices = gcnew STSeriesDevicesManager();
 7
 8if (devices->GetNumberOfSTSeriesDevices() > 0)
 9{
10    // Use the first device in the list
11    selectedDevice = devices->GetSTSeriesDevice(0);
12
13    // Open the device to prepare for using it
14    try {
15        selectedDevice->Open();
16    }
17    catch (STDeviceNotOpenedException dno)
18    {
19        System::Diagnostics::Debug::Assert(false,
20            "Can't open the first device found...this shouldn't happen. " + dno->Message);
21    }
22}
23else
24{
25    wprintf(L"No Scriptel STSeries devices were found on the system\n.");
26}

Addressing the Device

Once a device object is obtained, you must decide how you want to address it. You can address it through the generic interface ISTSeriesDevice or the specific device's interface, such as IST1500U. The advantage to the former is that your code can use this interface for any ScripTouch device. In most cases this is sufficient. If the device does not support paticular feature, calls to that feature are ignored. For example, clearing the display on an ST1400 does nothing because the screen is always clear. Some devices may have special features only available through its class/interface.

Events

Events are used to notify the program that an action has occurred on the device. Events can be setup to indicate pen-up or pen-down on the screen or on a button; when the device is unplugged; and when the firmware is downloaded.

The example below shows the pertinent part of a class that registers for a button event. RegisterButton causes any event on any button to call OnButtonSelected(). At some point the button should be unregistered as seen in UnregisterButton().

C++

Copy

 1namespace Scriptel.STSeries.Examples.Csharp
 2{
 3    using System;
 4    using Scriptel.STSeries;
 5
 6    public class STSeriesExample
 7    {
 8        private ISTSeriesDevice selectedDevice;
 9        private STSeriesDevice.ButtonSelectedEventHandler buttonTarget;
10        private STSignature sig = new STSignature();
11
12        ...
13
14        public void RegisterButton()
15        {
16            // this will register the buttons on the screen to fire an event to
17            // the OnButtonSelected() method whenever the pen goes down on a button or
18            // is lifted off the button
19            // this assumes that selectedDevice is assigned and opened prior to reaching this point
20
21            buttonTarget = new STSeriesDevice.ButtonSelectedEventHandler(OnButtonSelected);
22            selectedDevice.RegisterForButtonSelectedEvent(this, buttonTarget); 
23        }
24
25        public void UnregisterButton()
26        {
27            // Unregisters for the ButtonSelectedEvent.  This will stop you from receiving information when a button region is selected.
28            selectedDevice.UnregisterForButtonSelectedEvent(this, buttonTarget);
29        }
30
31        private void OnButtonSelected(Object sender, STSeriesDevice.RegionSelectedEventArgs e)
32        {
33            // e.SigPoint will tell whether the pen was down or lifted. If down, it will
34            //     tell the XY coordinates.
35            // e.RegionNumber will tell us which button was selected
36
37            // Add the new signature point to the signature
38            // because this is in the button event handler, this is only going
39            // to happen when the stroke starts in a button...this maybe a 
40            // silly thing to do, but it is for example only.
41            sig.AddPoint(e.SigPoint);    // see below
42        }
43    }
44}

 1Imports Scriptel.STSeries
 2
 3Module VB
 4    Public Class STExample
 5        Private selectedDevice As STSeriesDevice
 6        Private buttonTarget As STSeriesDevice.ButtonSelectedEventHandler
 7        Private sig As STSignature
 8
 9        ...
10
11        Sub RegisterButton
12            'This will register the buttons on the screen to fire an event to
13            'the OnButtonSelected() method whenever the pen goes down on a button or
14            'is lifted off the button
15            'this assumes that selectedDevice is assigned and opened prior to reaching this point
16            buttonTarget = New STSeriesDevice.ButtonSelectedEventHandler(AddressOf OnButtonEvent)
17            selectedDevice.RegisterForButtonSelectedEvent(Me, buttonTarget)
18        End Sub
19
20        Sub UnregisterButton
21            'Unregisters for the ButtonSelectedEvent.  This will stop you from receiving information when a button region is selected.
22            selectedDevice.UnregisterForButtonSelectedEvent(Me, buttonTarget)
23        End Sub
24
25        Sub OnButtonEvent(sender As Object, e As STSeriesDevice.RegionSelectedEventArgs)
26            'e.SigPoint will tell whether the pen was down or lifted. If down, it will
27            'tell the XY coordinates.
28            'e.RegionNumber will tell us which button was selected
29
30            'Add the new signature point to the signature
31            'because this is in the button event handler, this is only going
32            'to happen when the stroke starts in a button...this maybe a
33            'silly thing to do, but it is for example only.
34            sig.AddPoint(e.SigPoint)
35        End Sub
36
37    End Class
38End Module

 1using namespace System; 
 2using namespace std;
 3using namespace msclr::interop;
 4
 5namespace CppExample
 6{
 7    extern "C"
 8    {
 9        public ref class STExample
10        {
11            public:
12                STExample()
13                {
14                    sig = gcnew STSignature()
15                }
16                void RegisterButton();
17                void UnregisterButton();
18                void OnButtonSelected(Object^ sender, STSeriesDevice::RegionSelectedEventArgs^ event);
19
20            private:
21                ISTSeriesDevice^ selectedDevice;
22                STSeriesDevice::ButtonSelectedEventHandler^ buttonTarget;
23                STSignature^ sig;
24        };
25
26        ...
27
28        void STExample::RegisterButton()
29        {
30            // this will register the buttons on the screen to fire an event to
31            // the OnButtonSelected() method whenever the pen goes down on a button or
32            // is lifted off the button
33            // this assumes that selectedDevice is assigned and opened prior to reaching this point
34
35            buttonTarget = gcnew STSeriesDevice::ButtonSelectedEventHandler(this, &STExample::OnButtonSelected);
36            device->RegisterForButtonSelectedEvent(this, buttonTarget);
37        }
38
39        void STExample::UnregisterButton()
40        {
41            // Unregisters for the ButtonSelectedEvent.  This will stop you from receiving information when a button region is selected.
42            device->UnregisterForButtonSelectedEvent(this, buttonTarget);
43        }
44
45        void STExample::OnButtonSelected(Object^ sender, STSeriesDevice::RegionSelectedEventArgs^ event)
46        {
47            // e.SigPoint will tell whether the pen was down or lifted. If down, it will
48            //     tell the XY coordinates.
49            // e.RegionNumber will tell us which button was selected
50
51            // Add the new signature point to the signature
52            // because this is in the button event handler, this is only going
53            // to happen when the stroke starts in a button...this maybe a 
54            // silly thing to do, but it is for example only.
55            sig->AddPoint(event->SigPoint);
56        }
57    }
58}

The Signature Class

The STSignature class is a convenient way to store and process signatures captured from the device as individual points. In the example above, the last line of code added a point to an STSignature object. This class can be used to do very useful things such as Save the signature to a raster file, to save to the clipboard, to crop, and other useful things.