Webplugin Release Notes

Update History

Windows Versions

Mac

Versions

Changes

Date

Author

 2.0.0.1

2.0.0.1

Updated to Firebreath platform; combined PenAPI and TouchAPI info

05/23/2010

R. Cohn

D. Ralley

2.0.0.3

2.0.0.3

TouchAPI fixes; updated version

10/27/2010

R. Cohn

2.1.0.1

2.1.0.1

Updated to Firebreath 1.6

05/09/2012

R. Cohn

2.1.0.2

2.1.0.2

Bug fixes

various

R. Cohn

D. Ralley

2.1.0.3

n/c

Bug fixes

01/02/2013

R. Cohn

 

Contents

1      Overview... 2

1.1         Supported Browsers. 2

1.1.1      Supported Browsers and Operating Systems. 2

1.2         Plugin Files. 3

1.2.1      Windows Plugin Files. 3

1.2.2      Standalone Webplugin Installers. 3

1.3        Mac OSX Plugin Files. 4

1.3.1      WacomTabletPlugin.plugin  (for Firefox). 4

2      Webplugin Pen API. 4

2.1         Supported Tablets and Webplugin versions. 4

2.2         Development Resources. 4

2.3         Programming Model 6

2.4         Webplugin Pen API (WebPAPI) Properties. 7

2.5        Sample Javascript Usage. 8

2.6        Updating Web Apps from 1.0.x.x to the 2.0.x.x Webplugin.. 8

3      Webplugin Touch API. 9

3.1         Supported Tablets. 9

3.2         Development Resources. 9

3.3         Programming Model 9

3.4        Sample Javascript Usage. 11

3.5         Webplugin Touch API (WebTAPI) Properties. 11

3.5.1      TouchRawFingerData. 12

3.5.2      TouchDeviceCapabilities. 13

3.5.3      TouchDeviceAttached. 14

3.5.4      TouchDeviceIDList 14

3.5.5      Open. 14

3.5.6      Close. 15

3.5.7      Modes. 15

3.6         Webplugin Touch API Events. 16

3.6.1      TouchDataEvent 16

3.6.2      TouchDeviceAttachEvent 16

3.6.3      TouchDeviceDetachEvent 17

 

1                   Overview

This document describes changes to an updated Webplugin that includes the same pen properties supported in the older 1.0.x.x version of the Webplugin.  Applications may continue to use those plugins for the present, but it is strongly encouraged that applications update to the Webplugin described in this document.  See section 2.6  for details.  At some point, support for the older 1.0.x.x plugins will be discontinued.

The Wacom Tablet Plugin (Webplugin) is a browser extension that provides supports for obtaining certain tablet properties, which can be used in web applications.  The plugin works in conjunction with an installed Wacom tablet driver service to provide pen data such as pressure and pen position (see section 2) and touch data such as number of fingers touching tablet and finger data (see section 3).

For example, a web drawing application (such as the one provided in the 'Scribble' example) can be created that uses tablet pen pressure and position properties to allow the user to do free-form drawing on a web page.

This document provides a summary of the plugin API, with an explanation of how the plugin can be installed and used on either Windows or Mac OSX systems.

Examples showing how to use the Webplugin pen and touch APIs can be found at Wacom Software Development Support: http://www.wacomeng.com/web/index.html.

Although plugin components are automatically installed on the user system when a Wacom tablet driver software is installed, standalone plugin installers can be found at: http://www.wacom.com/productsupport/plugin.php, for those systems that have not updated their tablet driver software.

1.1            Supported Browsers

1.1.1       Supported Browsers and Operating Systems

Note that Firefox, Safari, Chrome and Opera are what’s known as “Netscape” browsers.  Use of the Webplugin for these browsers requires a different API than for Internet Explorer, which uses the “ActiveX” API.  The Webplugin described in this document supports both API types in the same plugin component.

The Webplugin is supported on these browsers and operating systems:

 

Windows 7, Vista, XP

Mac OSX 10.6, 10.7, 10.8

Firefox

yes

yes

Safari

yes

yes

Chrome

Yes

yes

Internet Explorer

Yes

n/a

In general, unless specified otherwise, the webplugin will support the current and previous versions of each browser.

1.1            Plugin Files

1.1.1       Windows Plugin Files

There are is one plugin module that supports plugin operation for both Internet Explorer (IE) and Netscape-plugin (NP) browsers. 

When a user installs the Wacom tablet driver software, all of the necessary Webplugin components are installed on the system, and the user can immediately create javascript applications that can use Webplugin properties to get pen and touch data (on supported tablets).    See programming examples at http://wacomeng.com/web/index.html.

In addition to the plugin components installed by the Wacom tablet driver installation, there are standalone Webplugin installers (Windows only).  Normally, the standalone Webplugin installers would not be needed as the Webplugin components are installed automatically with the Wacom tablet driver software.  However, if the Webplugin is not installed (because the user has inadvertently uninstalled it, or the user has an older version of the tablet driver software installed), then there is another option to get the Webplugin.  See section 1.2.2 for details.

The Webplugin can be identified in an HTML web app by its mime-type.  Here are the mime-types for the older and newer Webplugins:
Version 1.0.x.x Webplugin uses type="application/x-wacom-tablet"
Version 2.0.0.x Webplugin uses type="application/x-wacomtabletplugin"
 
The IE browser uses the ActiveX API and identifies the Webplugin by a CLASSID (GUID).  Here are the older and newer Webplugin GUIDs:
Version 1.0.x.x Webplugin uses classid="449E4080-7C69-4767-A1AE-6AAE25B0B906"
Version 2.0.0.x Webplugin uses classid="092dfa86-5807-5a94-bf3b-5a53ba9e5308"

 

1.1.2       Standalone Webplugin Installers

·         FBWTPInstall.exe:

This standalone Webplugin installer, which supports both IE and NP browsers, is available from:  http://www.wacom.com/productsupport/plugin.php .  This is the installer that is automatically installed when the Wacom tablet driver is installed.

·         FBWacomTabletPlugin.cab:

This standalone Webplugin installer, which supports IE browsers only, is available from: http://www.wacom.com/U/plugins/Windows
 

·         FBWacomTabletPlugin.xpi:

This standalone Webplugin installer, which supports Firefox browsers only, is available from: http://www.wacom.com/U/plugins/Windows

 

 

1.2            Mac OSX Plugin Files

1.2.1       WacomTabletPlugin.plugin  (for Firefox)

OS X plugins for all supported Netscape-compatible browsers. To install:

                       cp -r WacomTabletPlugin.plugin "/Library/Internet Plug-Ins"

2                   Webplugin Pen API

The Wacom Webplugin pen API (WebPAPI) is a browser plugin interface for pen data access from all Wacom consumer and professional tablets. The WebPAPI is included in the Webplugin component that also includes the Wacom Webplugin touch API (WebTAPI). 

WebPAPI can be used by web developers who want access to Wacom tablet pen data for development of applications that use pen data.  Highlights of WebPAPI include data reports of:

·         Pen location

·         Pen pressure data

·         Pen rotation data

·         Pen tilt data

·         Pen eraser or tip indication

2.1            Supported Tablets and Webplugin versions

·         WebPAPI properties are supported on all versions of the Webplugin prior to 2.0.0.1

·         WebPAPI is currently supported on all Wacom professional and consumer tablets.

2.2            Development Resources

The necessary developer components to use WebPAPI are installed with the tablet driver (see Error! Reference source not found.Error! Reference source not found. for supported driver versions and tablets); there are no additional "SDKs"  or modules to add to immediately begin programming web applications to WebPAPI.

WebTAPI examples can be found at http://www.wacomeng.com/web/index.html

 


 

2.3            Programming Model

The diagram in Figure 1 shows an overview of where the WebPAPI fits into the system architecture.  For simplicity, the plugin is shown as being within the process space of the browser.  In actuality, most browsers have gone to an "out-of-process" model , in which the plugin instance is launched in its own process.  

The WebPAPI is accessed from the Webplugin component, which is installed on the user's system with the tablet driver installation.  The Webplugin caches pen data as it is produced by the user drawing the pen across the tablet.  When a javascript app wants to read the latest pen data, it simply makes one of the WebPAPI property calls (see Properties list below).  A standard way to sync up the user’s pen movement with pen data is for the javascript app to read pen data on system mouse events (see examples below).

Figure 1 - Webplugin Pen API Architecture Overview

Components installed with the tablet driver.

javascript web application

WebPAPI

(in Webplugin)

Pen data

 

Raw pen data

Wacom tablet

pen driver

Wacom pen tablet

Wintab32

Operating system

Pen data

 

Browser (IE, Firefox,...)

 


 


2.4            Webplugin Pen API (WebPAPI) Properties

All versions of the plugin expose the same properties.  Note, however, that only the professional Wacom tablets (Intuos, Cintiq) support all properties.  Unsupported properties return a zero value.  The following table describes the supported properties:

Property

Type

Default Value

Description

Supported Tablets

 Read/Write

isEraser

BYTE

0

TRUE if the last-seen packet came from an eraser, FALSE otherwise.

Consumer, Professional

 Read-only

isWacom

BYTE

1 (connected)

0 (not connected)

TRUE if the object is attached to a Wacom Wintab, FALSE otherwise.

Consumer, Professional

Read-only

pointerType

LONG

0

0 = Out of Proximity

1 = Pen

2 = Mouse (also known as 'puck')

3 = Eraser

Consumer, Professional

Read-only

posX

LONG

0

 The last-seen packet's X position in pixel coordinates.

Consumer, Professional

Read-only

posY

LONG

0

The last-seen packet's Y position in pixel coordinates.

Consumer, Professional

Read-only

pressure

FLOAT

0.0 (connected)

1.0 (not connected)

The last-seen packet's pressure, in the range [0.0,1.0].

Consumer, Professional

Read-only

rotationDeg

FLOAT

0.0

The last-seen packet's rotation value in degrees.

Professional

Read-only

rotationRad

FLOAT

0.0

The last-seen packet's rotation value in radians.

Professional

Read-only

sysX

FLOAT

0.0

The last-seen packet's X position in pixel coordinates (to sub-pixel resolution).

Consumer, Professional

Read-only

sysX

FLOAT

0.0

The last-seen packet's Y position in pixel coordinates (to sub-pixel resolution).

Consumer, Professional

Read-only

tabX

LONG

0

 The last-seen packet's X position in tablet coordinates.

Consumer, Professional

Read-only

tabY

LONG

0

The last-seen packet's Y position in tablet coordinates.

Consumer, Professional

Read-only

SetFocus

BOOL

n/a

True: forces browser page containing plugin to get focus for tablet data events.

False: allows another page to get focus for tablet data events.

Consumer, Professional

Write-only

TabletModel

STRING

"" (empty string)

Returns model name of last touched tablet.

(Eg: "Intuos4 Medium")

Consumer, Professional

Read-only

TabletModelID

STRING

"" (empty string)

Returns tablet ID of last touched tablet.

(Eg: "PTK-640")

Consumer, Professional

Read-only

tangentialPressure

FLOAT

0.0

The last-seen packet's tangential pressure value, in the range [0.0,1.0]

Professional

Read-only

tiltX

FLOAT

0.0

The last-seen packet's X tilt value, in the range [-1.0, 1.0].

Professional

Read-only

tiltY

FLOAT

0.0

The last-seen packet's Y tilt value, in the range [-1.0, 1.0].

Professional

Read-only

version

LONG

<plugin version>

The version of the plugin in decimal form (eg: 1.1.0.1 is reported as 1101).

Consumer, Professional

Read-only

 

2.5            Sample Javascript Usage

A javascript application using the WebPAPI should adopt a mouse event-driven model, in which the app would query for pen properties upon mouse down, mouse drag and mouse up events.  For example, to get pressure and pen X and Y position, the following javascript can be used:

   function mousedrag(evt)

   {

var plugin = document.getElementById('wtPlugin');

var pressure = plugin.penAPI.pressure;

var plugin.penAPI.posX;

var plugin.penAPI.posY;

}

 

Complete examples can be found on http://wacomeng.com/web/index.html

2.6            Updating Web Apps from 1.0.x.x to the 2.0.x.x Webplugin

 

In updating a web app from Webplugin 1.0.x.x  to 2.0.0.x, the following should be done:

·         Change the plugin mime-type from type="application/x-wacom-tablet" to type="application/x-wacomtabletplugin

·         Change access to the properties from plugin.<property> to plugin.penAPI.<property>


 

3                   Webplugin Touch API

The Wacom Webplugin touch API (WebTAPI) is a browser plugin interface for touch data access from certain Wacom tablets. The WebTAPI is included in the Webplugin component that also includes the Wacom Webplugin pen API (WebPAPI). 

WebTAPI can be used by web developers who want access to Wacom raw touch tablet data for development of touch applications.  Note that WebTAPI gives the developer freedom to use finger data to control web applications or to define custom gestures for his application.  Highlights of WebTAPI include reports of:

·         Number and type of supported touch tablets attached to the system

·         Capabilities of attached supported touch tablets

·         Number of fingers touching the tablets

·         Raw finger data for each touching finger

·         Touch tablet raw finger data arrivals

·         Touch tablet attach events

·         Touch tablet detach events

3.1            Supported Tablets

·         WebTAPI is not supported on Webplugin versions prior to 2.0.0.1

·         WebTAPI is not supported on Wacom tablet drivers prior to 5.2.5 (Bamboo tablet driver)

·         WebTAPI is currently supported on these Bamboo tablets: CTT-470, CTH-470, CTH-670.

3.2            Development Resources

The necessary developer components to use WebTAPI are installed with the tablet driver (see Error! Reference source not found.Error! Reference source not found. for supported driver versions and tablets); there are no additional "SDKs"  or modules to add to immediately begin programming web applications to WebTAPI.

WebTAPI examples can be found at http://www.wacomeng.com/web/index.html

3.3            Programming Model

The diagram in Figure 2 shows an overview of where the WebTAPI fits into the system architecture.  For simplicity, the plugin is shown as being within the process space of the browser.  In actuality, most browsers have gone to an "out-of-process" model , in which the plugin instance is launched in its own process.  

The WebTAPI is accessed from the Webplugin component, which is installed on the user's system with the tablet driver installation.  The Webplugin app registers to receive notification when touch devices are attached and detached from the system, as well as notifications of when data becomes available (when the user touches the tablet).   When the app receives attach and detach events, it can query for the current list of devices, select one, and query for that device's touch device capabilities (eg: how many fingers supported, tablet dimensions, etc.).   Upon receipt of a touch data notification, the app can query WebTAPI for touch data.

Note that the web app, through use of the Open.PassThru argument   (see section 3.5.5), can decide whether to consume the data or just observe it and allow it be passed to other processes on the system.   For example, the web app could implement a "scribble" app to draw touch data, and allow the data to be passed on to the system to move the system cursor.

 

Components installed with the tablet driver.

Raw finger data Event

Attach Event

Detach Event

 

javascript web application

WebTAPI

(in Webplugin)

Raw finger data

Touch device capabilities

 

Raw finger data

Events,

Touch device Capabilities

Raw finger data

 

Wacom tablet touch driver

Wacom touch tablet

Wacom tablet touch driver  I/F

Operating system

Browser (IE, Firefox,...)

Figure 2 – Webplugin Touch API architecture overview

3.4            Sample Javascript Usage

A javascript application using the WebTAPI should adopt an event-driven model, waiting for notification from the Webplugin on touch device attach, detach and data events.  In pseudo-code, such an application would be structured similar to the following:

      Register for attach events

      Register for detach events

      On Attach event:

            Read the current list of attached touch devices

            Open a device to receive touch data from

            Register to receive touch data from that device

 

      On Raw Finger Data event:

            Read the touch data

            Use the data in the app

 

      On Detach event:

            Get current list of attached touch devices

            If device in use has gone away, close that device

 

See the examples in the properties below for actual javascript examples.  Complete examples can be found on http://wacomeng.com/web/index.html

 

3.5            Webplugin Touch API (WebTAPI) Properties

Here is an overview of the WebTAPI properties.  They are described in detail in the following sections.

Property or Event Name

Param

Return Type

Description

Read/Write

TouchRawFingerData

deviceID

FB::VariantMap

Returns latest raw finger touch data to the user from the first touch device found.

 

Read-only

TouchDeviceCapabilities

deviceID

FB::VariantMap

Returns the capabilities for the specified touch device.

Read-only

TouchDeviceAttached

None

Bool

Returns status of whether any touch devices are physically attached to the system.

Read-only

 

TouchDeviceIDList

None

FB::VariantList

Returns list of attached touch device IDs.

Read-only

Open

deviceID

passThru

0 on success; else non-0

Attach to specified device.

Write-only

Close

deviceID

0 on success; else non-0

Detach from the specified device.

Write-only

TouchDataEvent

n/a

n/a

Fires when touch data is received when any touch data is received. 

 

TouchDeviceAttachEvent

n/a

n/a

Fires when any supported touch device is attached to the system.

 

 

TouchDeviceDetachEvent

n/a

n/a

Fires when any supported touch device is detached from the system.

 

 

 

 

3.5.1       TouchRawFingerData

Returns latest raw finger touch data to the user from the first touch device found.

3.5.1.1       Params:

deviceID   Int

For now, the only deviceID accepted will be -1 or a deviceID returned from TouchDeviceCapabilities, which will mean to return data from the first touch device found, or the data for that specified device respectively.  If a deviceID other than a valid ID is used, then the Status flag in the returned FB::VariantMap will indicate an error.

3.5.1.2       Returns:

FB::VariantMap consisting of the following members:

NumFingers    Int                        // #fingers in this data packet

DeviceID      Int                        // device from which data is sent

Status        Int                        // indicates if data is valid (see below)

FingerList    FB::VariantList            // list of finger data

              FingerList[0]

                     FB::VariantMap       // Data for Finger1

                     FingerID      Int    // as specified in data packet

                     PosX          float  // X coord passed back from API (see below)

                     PosY          float  // Y coord passed back from API (see below)

                     Width         float  // logical width of finger contact area

                     Height        float  // logical height of finger contact area

                     Orientation   float  // finger contact ellipse angle from vertical

                     Confidence    Int    // 1 if driver believe this is valid touch

                     Sensitivity   Short  // reserved (unused in Ironwood)

                     FingerState   Int    // latest activity for this finger (see below)

              FingerList[1]

                     FB::VariantMap       // Data for Finger2

                     FingerID      Int

                     PosX          float

                     PosY          float

                     Width         float

                     Height        float

                     Orientation   float

                     Confidence    Int

                     Sensitivity   Short

                     FingerState   Int

              ...

 

If it is supported in Firebreath, the size of the returned FB::VariantMap will depend on the number of fingers in the most recent touch data packet.  If dynamic FB::VariantMap is not supported, then the plugin will pre-allocate a map for 10 fingers, and fill in the number of fingers of data from the latest touch API data packet.

Status indicates whether the FB::Variant returned contains valid data.  If data is valid then, Status will be zero.  If data is not valid, then Status will be the value -1.

PosX and PosY will be logical units in the range of 0 to 1.0 for opaque tablets. 

PosX and PosY will be pixel screen coordinates in the virtual desktop range for integrated tablets.

FingerState =  0 (FingerStateNone),   finger's state is unknown

                            1 (FingerStateDown),    finger's state is touching the tablet

                            2 (FingerStateHold),    finger's state is remaining on tablet (after Down)

                            3 (FingerStateUp)           finger's state has left tablet (after Hold)

Note that there is no Move state.  The Hold state can be interpreted as a move if the finger position changes.

3.5.1.3       Sample Javascript Usage:

var fingerdata  = plugin.TouchAPI.TouchRawFingerData(0);

var numFingers = fingerdata.NumFingers;

var status = fingerdata.Status;

if ( status == 0 )

{

var finger1= FingerData.FingerList[0];

var finger1ID = finger1.FingerID;

if (finger1.Confidence == 1 && finger1.FingerState != 0)

{

var finger1PosX = finger1.PosX;

var finger1PosY = finger1.PosY;

...

}

var finger2 = FingerData.FingerList[1];

etc...

}

3.5.2       TouchDeviceCapabilities

Returns the capabilities for the specified touch device.

3.5.2.1       Params:

deviceID   Int

For now, the only device ID accepted will be -1.  See TouchRawFingerData for details.

3.5.2.2       Returns:

FB::VariantMap consisting of the following members:

Version            Int      // data structure version (1 for Ironwood release)

DeviceID           Int      // identifier of this device

DeviceType         Int      // this value is currently always set to zero         

MaxFingers         Int      // max number of fingers supported by device

ReportedSizeX      Int      // Number of touch points in X direction

ReportedSizeY      Int      // Number of touch points in Y direction

PhysicalSizeX      float    // Width of the device active touch surface in mm

PhysicalSizeY      float    // Height of the device active touch surface in mm

LogicalOriginX    float    // Device MinX. Relative to 0,0 point on current display

LogicalOriginY    float    // Device MinY. Relative to 0,0 point on current display

LogicalWidth       float  // Device logical width. MaxX = LogicalOriginX+LogicalWidth

LogicalHeight      float  // Device logical height. MaxY = LogicalOriginY+LogicalHeight     

 

If the call fails, then the returned FB::VariantMap will have Version == -1.

3.5.2.3       Sample Javascript Usage:

var touchDeviceCaps = plugin.TouchAPI.TouchDeviceCapabilities(0);

var maxNumFingers = touchDeviceCaps. MaxFingers;

var maxXTouchPoints = touchDeviceCaps.ReportedSizeX;

var maxYTouchPoints = touchDeviceCaps.ReportedSizeY;

etc...

3.5.3       TouchDeviceAttached

Returns status of whether any touch devices are physically attached to the system.

3.5.3.1       Params:

None

3.5.3.2       Returns:

bool    True -> at least one touch device was found

3.5.3.3       Sample Javascript Usage:

var  isTDAttached = plugin.IsTouchDeviceAttached();

3.5.4       TouchDeviceIDList

Returns list of attached touch device IDs.

3.5.4.1       Params:

None

3.5.4.2       Returns:

FB::VariantList of attached touch device IDs.  If no touch device IDs are attached, the array is of zero size.

3.5.4.3       Sample Javascript Usage:

_touchDeviceIDList = plugin().touchAPI.TouchDeviceIDList;

3.5.5       Open

This is a method that will attach to the specified device and initialize the touch API for the client so that data from that device will be sent to the client. The client can elect to connect so that touch data is NOT passed to the system, or can connect so that touch data is passed to him (the client) as well as being sent to the system.

3.5.5.1       Params:

deviceID   Int  // -1 -> open first touch device found; else open specified deviceID

                                                                passed from TouchDeviceCapabilities

passThru   Int  // 1: data is passed to system; 0: data is not passed to system

3.5.5.2       Returns:

0 on success; non-zero if error.

3.5.5.3       Sample Javascript Usage:

var caps = plugin.TouchAPI.TouchDeviceCapabilities(-1);// get caps of first touch device

 

Either of these will work:

var status = plugin.TouchAPI.Open(-1, 0);              // open 1st device; do NOT pass data to system

var status = plugin.TouchAPI.Open(caps.DeviceID, 0);   // open specified device

 

3.5.6       Close

This method detaches client from the specified device, so that no further data from that device nor all touch devices will be sent to the client.

3.5.6.1       Params:

deviceID   Int  // -1 -> close all touch devices; else close deviceID

                                                                passed from TouchDeviceCapabilities

3.5.6.2       Returns:

0 on success; non-zero if error.

3.5.6.3       Sample Javascript Usage:

Either of these will work:

var status = plugin.TouchAPI.Close (-1);        // close all devices

var status = plugin.TouchAPI.Close (caps.DeviceID);    // close specified device

3.5.7       Modes

This method allows the plugin to be set for different conditions. The conditions supported at this time are:

1.       CHILD_BIT: Telling the API that the plugin will be run in a browser child process or in the browser main thread. Using this setting, the API is told that the plugin is configured to work in a browser that launches plugins either in a child process, or launches plugins in the main thread. Currently, most browsers (Internet Explorer, Firefox, Chrome, etc.) launch plugins in a separate process. This guards against a failing plugin crashing the whole browser. Although the plugin API assumes that it will be run in a child process by default, there is a way to switch off that behavior and have the plugin API assume the webplugin will be run in the main thread.

2.       OBSERVER_BIT: Setting the plugin to run as a touch consumer or touch observer. Using this setting, the plugin is configured to run in observer or consumer mode. In observer mode, the plugin processes touch data, and then passes the touch data on to the system, where it can be used by other applications or by the system to execute gestures or cursor navigation. In consumer mode, the plugin processes touch data, but does not let it be passed to the system.

3.5.7.1       Params:

mode Int  // A bitwise-OR of conditions:

           // CHILD_BIT:    0x00000001 -> plugin assumed to be in a child browser process

           // OBSERVER_BIT: 0x00000010 -> plugin passes data to the system (Observer)

           // By default, the plugin executes in a child browser process as a Consumer.

3.5.7.2       Returns:

0 on success; non-zero if error.

3.5.7.3       Sample Javascript Usage:

var status = plugin.TouchAPI.Modes (0);         // tells API that plugin runs in browser main thread, and is a consumer

var status = plugin.TouchAPI.Modes (1);         // tells API that plugin runs in a child process, and is a consumer

var status = plugin.TouchAPI.Modes (3);         // tells API that plugin runs in a child process, and is an observer

 

3.6            Webplugin Touch API Events

3.6.1       TouchDataEvent

Fires when touch data is received when any touch data is received from a supported touch device.  The client's handler, upon receiving this event, can query for data (see below).

3.6.1.1       Plugin Event Name

      "onTouchDataEvent"

3.6.1.2       Example Javascript Usage

Registering for the event:

if (window.addEventListener)

{

    obj.addEventListener("TouchDataEvent", touchDataHandler, false);

}

else

{

    obj.attachEvent("onTouchDataEvent", touchDataHandler);

}

 

Function handler for the event:

function touchDataHandler()

{

    // Use TouchRawFingerData to query for cached data

    // process/render finger data in client display area

}

 

3.6.2       TouchDeviceAttachEvent

Fires when any supported touch device is attached to the system.

3.6.2.1       Plugin Event Name

      "onTouchDeviceAttachEvent"

3.6.2.2       Example Javascript Usage

Registering for the event:

if (window.addEventListener)

{

    obj.addEventListener("TouchDeviceAttachEvent", touchDeviceAttachHandler, false);

}

else

{

    obj.attachEvent("onTouchDeviceAttachEvent ", touchDeviceAttachHandler);

}

 

Function handler for the event:

function touchDeviceAttachHandler ()

{

    // Get current list of touch devices and open first device.

    _touchDeviceIDList = plugin().touchAPI.TouchDeviceIDList;

    _touchDeviceID = _touchDeviceIDList[0];

    plugin().touchAPI.Open(_touchDeviceID, 0);

}

 

3.6.3       TouchDeviceDetachEvent

Fires when any supported touch device is detached from the system.

3.6.3.1       Plugin Event Name

      "onTouchDeviceDetachEvent"

3.6.3.2       Example Javascript Usage

Registering for the event:

if (window.addEventListener)

{

    obj.addEventListener("TouchDeviceDetachEvent",touchDeviceDetachHandler,false);

}

else

{

    obj.attachEvent("onTouchDeviceDetachEvent", touchDeviceDetachHandler);

}

 

Function handler for the event:

function touchDeviceDetachHandler ()

{

    // close connection to the current touch device

    plugin().touchAPI.Close(_touchDeviceID);

}