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 |
|
2.1.0.3 |
n/c |
Remove
refs to standalone Windows installers |
11/10/2014 |
R. Cohn |
Contents
1.1.1 Supported
Browsers and Operating Systems
1.3.1 WacomTabletPlugin.plugin
(for Firefox)
2.1 Supported
Tablets and Webplugin versions
2.4 Webplugin
Pen API (WebPAPI) Properties
2.6 Updating
Web Apps from 1.0.x.x to the 2.0.x.x Webplugin
3.5 Webplugin
Touch API (WebTAPI) Properties
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.
Webplugin
components are automatically installed on the user system when a Wacom tablet
driver software is installed.
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.
There 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 (both 32bit and 64bit versions) 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.
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"
OS X plugins for all supported Netscape-compatible
browsers. To install:
cp -r WacomTabletPlugin.plugin "/Library/Internet Plug-Ins"
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
· 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.
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
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,...)
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 |
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
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>
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
· 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.
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
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,...)
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
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. |
|
Returns latest raw finger touch data to the user from the first touch device found.
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.
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.
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...
}
Returns the capabilities for the specified touch device.
deviceID Int
For now, the only device ID accepted will be -1. See TouchRawFingerData for details.
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.
var
touchDeviceCaps = plugin.TouchAPI.TouchDeviceCapabilities(0);
var
maxNumFingers = touchDeviceCaps. MaxFingers;
var
maxXTouchPoints = touchDeviceCaps.ReportedSizeX;
var
maxYTouchPoints = touchDeviceCaps.ReportedSizeY;
etc...
Returns status of whether any touch devices are physically attached to the system.
None
bool True -> at least one touch device was found
var isTDAttached
= plugin.IsTouchDeviceAttached();
Returns list of attached touch device IDs.
None
FB::VariantList of attached touch device IDs. If no touch device IDs are attached, the array is of zero size.
_touchDeviceIDList =
plugin().touchAPI.TouchDeviceIDList;
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.
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
0 on success; non-zero if error.
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
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.
deviceID Int // -1 -> close all touch devices; else
close deviceID
passed
from TouchDeviceCapabilities
0 on success; non-zero if error.
Either of these will work:
var status =
plugin.TouchAPI.Close (-1); //
close all devices
var status = plugin.TouchAPI.Close (caps.DeviceID); // close specified device
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.
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.
0 on success; non-zero if error.
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
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).
"onTouchDataEvent"
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
}
Fires when any supported touch device is attached to the system.
"onTouchDeviceAttachEvent"
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);
}
Fires when any supported touch device is detached from the system.
"onTouchDeviceDetachEvent"
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);
}