Back to Windows Developer Support page

Notes for Tablet Aware Application Developers

 

Contents

Audience. 1

Overview... 1

Change History. 2

General Programming Notes. 3

Initialization.. 3

Message Handling.. 3

Notes About Contexts. 5

Features Updates. 5

Features You Should Already Have Implemented.. 5

New Features to Implement. 6

New  Extensions Support. 6

 

Audience

This document is mainly intended to assist developers who already have tablet aware applications and want to add new capabilities to their applications. You should already be able to access the tablet data and capabilities. Developers who are adding tablet features for the first time should start with the Overview section, and examine the sample code.

Any questions concerning this document or any aspects of using Wintab with Wacom products can be directed to: developer@wacom.com

Overview

Applications receive tablet-specific data by using the Wintab Application Programmers Interface (see the Wintab Specification Level 1.4 document, which can be downloaded from the Windows Tablet Developer Site: http://us.wacom.com/en/developerrelations/windows). Wintab is an industry standard for interfacing with pointing devices. Not all features of the original Wintab 1.0 interface are supported and some pointing devices support features while others do not.

Information on Wintab, including a developersí SDK can be obtained from the Windows download sample code at: http://us.wacom.com/en/developerrelations/windows. The TiltTest program which is included with this implementers guide is a good example of how to use Wintab to get tablet data.

In addition to the Wintab specification, there is a useful FAQ document, Wacom Windows Developer FAQ, on the same website. This contains a large number of programming examples.

Change History

With some exceptions the Wacom driver implements the Wintab specification version 1.1 as published by LCS/Telegraphics. The specification version returned by the Wacom driver is 1.4. A copy of this specification, Wintab Specification Level 1.4, is included on the Windows Tablet Developer site at: http://us.wacom.com/en/developerrelations/windows.

// Check the Wintab version in this manner

WORD thisVersion;

WTInfo(WTI_INTERFACE, IFC_SPECVERSION, &thisVersion);

Version 1.2 added CSR_TYPE which is needed to carry information for Unique ID.

Version 1.3 add a now depricated incomplete extension for express keys. (WTX_EXPKEYS is not supported and has been replaced by WTX_EXPKEYS2)

Version 1.4 adds an updated extension for express keys and also adds extensions for touch strips and touch rings. (WTX_EXPKEYS2, WTX_TOUCHSTRIP, WTX_TOUCHRING)

You should not have to change any code to support the features you currently support, you simply add code to support new features. The depricated express key implementation of 1.3 will not return unsupported.

The latest header files, WINTAB.H and PKTDEF.H are included with the Windows download sample code at: http://us.wacom.com/en/developerrelations/windows These files bring the data structures up to specification 1.4, and add the 1.2 feature (CSR_TYPE).

General Programming Notes

There are two main points in an application where modifications may be made to support tablets:

Initialization

During initialization you need to:

    1. Determine if a tablet is attached by looking for the Wintab interface. Call the Wintab function WTInfo(0, 0, NULL) to see if Wintab is present.
    2. Use WTInfo() to get static information about the tablet, such as tablet dimensions, coordinate resolution, the presence of tilt, pressure range, tangential pressure range, and other features.
    3. Create at least one Wintab context for your application. Get a default context using WTInfo() and use it as a template to create your own tablet context. Set up the context as appropriate for your application. Applications can open two kinds of contexts: system contexts and digitizing contexts. Wintab moves the system cursor on behalf of the application for system contexts, while applications must move the system cursor themselves for digitizing contexts. Most applications use system contexts. The user can change the area of a system context to make navigation easier. Digitizer contexts usually cover the entire tablet. Digitizer contexts are used for digitizing or to define tablet menus. Setting up the context includes determining what data items will be included in the packets. Although the documentation says you can not include items in the packet that are not supported by the tablet, it appears that this is incorrect. Unsupported items may be included and will be set to zero. Then call WTOpen() to create your context so you can begin processing packet data.
    4. Wintab passes data for a tablet point, such as coordinates, pressure and tilt, to an application as a Wintab packet. By default, the packet queue for a context is very small and can easily overflow. Applications should guard against overflowing their queues by increasing their contextís queue sizes using WTQueueSizeSet().

Message Handling

During device operation, you will get data from the tablet. This data is used for line rendering or navigation. You may need to find additional information about the tablet device currently in use. This device information can be used to change tools or screen cursors, for example, when a stylus eraser is placed in use or when tools are changed based on device ID.

The following Windows messages should be handled.

    1. WM_LBUTTONDOWN / WM_LBUTTONUP message (for stylus buttons)

On WM_LBUTTONDOWN the packets in the tablet queue should be flushed using, for example, WTPacketsGet() (since they are old). If you are very particular, you may want to flush all packets up to the one with the button pressed and use the rest for drawing. Set a flag indicating packet events should now be processed and drawn. On WM_LBUTTONUP clear the flag and stop processing packets. Again, if you are particular, on the WM_LBUTTONUP event process the packets in the queue that correspond to the button press state.

    1. WT_PACKET message (usually during a button down)

In the draw loop (usually continuously done between WM_LBUTTONDOWN and WM_LBUTTONUP), tablet data is read from packets and used to modify the rendering of the line being drawn. Data such as current pressure, tilt angles, and fingerwheel values are used to change rendering parameters like opacity, brush direction, line thickness, and so forth. Wintab stores packets in a context-unique packet queue until the application that opened the context requests packet data using a Wintab function such as WTPacket().

When applications open a context they pass Wintab a window handle. If the application sets the contextís CXO_MESSAGES option, the window receives notification that a packet has been added to the queue via the WT_PACKET message. This event contains the serial number for the packet that generated the event. Upon receiving the event, call WTPacket() with the serial number provided in the message.

CAUTION! If the queue overflows, Wintab stops informing the application that packets have been queued, and it discards the subsequently received packets until the queue is no longer full. Be sure to avoid overflow by draining the queue during WT_PACKET messages.

    1. WT_CSRCHANGE (and/or WT_PROXIMITY) message

When a pointing device enters or leaves a context, the application that opened the context is notified through the WT_PROXIMITY message. When a different pointing device enters proximity of the context, the application is informed through a WT_CSRCHANGE message, if the application requested this message when the context was created. When an application receives a WT_PROXIMITY and/or WT_CSRCHANGE message, it can call WTInfo() to get information about the pointing device, such as number of buttons on the device, which end of the stylus is in use, or the deviceís physical ID. This message is very useful for changing drawing tools. The selected tool (and/or screen cursor) should change when the pointing device is first brought into use, not when drawing starts. Therefore, you will want to check for tip vs. eraser, and check the Unique ID at this point.

    1. WT_PACKET message (without a button down)

You may want to look at device information for navigational purposes, such as rotating an object with the stylus tilt. You can do this by always reading tablet packets in response to WT_PACKET events, even when a button is not down. For example, if you are using a 4D Mouse for navigation, current device information can be used to modify an objectís position or to modify your own viewpoint.

Notes About Contexts

Wintab holds all open contexts for all applications in a single overlapping container for each tablet. It uses the overlap order to decide which context should process each tablet packet. Each packet is put in only one contextís packet queue. In general, if context A is above context B in the overlap order, context A will receive tablet packets and context B will not. Applications bring their contexts to the top or bottom of the overlap order by calling WTOverlap(). Many applications fail to properly handle their context ordering. This causes simultaneously executing Wintab applications to stop working or to behave unpredictably. When applications receive the WM_ACTIVATE message, they should push their contexts to the bottom of the overlap order if their application is being deactivated, and should bring their context to the top if they are being activated. Applications should also disable their contexts when they are minimized.

The Wacom implementation of Wintab will manage the context order for the application. This means that the application will only get data when that application has keyboard focus. We did this because too many applications do not correctly handle their own contexts. Please help us out by correctly managing your contexts so some day we can remove this code.

It is best to have at least two undo buffers, or one more than the desired number. Donít flush the undo buffer on a button down when you are about to draw, it takes too long. Flush the buffer on a button up. This will improve the beginning of your strokes.

Features Updates

Features You Should Already Have Implemented

Eraser and Tilt are features that have been around for some time. A large installed base of tablets supports these capabilities and, if you have not already done so, you can increase the power and performance of your application by implementing these features.  See the Wintab Specification Level 1.4 for details.

New Features to Implement

New features introduced with the Intuos series tablets include:

         Unique ID - a feature that allows unique numbers to be assigned to stylus devices

         Airbrush Fingerwheel - a feature that allows fingerwheel data as tangential pressure to be reported

         4D Mouse Rotation - a feature that allows axial rotation data to be obtained from a puck-type stylus with a thumbwheel on its side

         4D Mouse Thumbwheel - a feature that allows an extra Z dimension of data to be obtained from the 4D mouse thumbwhee

If your application already supports Wintab then these features are VERY easy to add. An old feature which is now fully supported is Dual Track.  See the Wintab Specification Level 1.4 for details on these features.

New  Extensions Support

Extensions supported by Wintab 1.4 include:

         Out of Bounds Tracking Extensions - enables cursor tracking in areas not covered by any active tablet context

         Cursor Mask Extensions - allows contexts to select input based on the cursor type

         Extended Button Masks Extensions - allows contexts to fully select input of up to 256 buttons (supports locator devices with great numbers of buttons)

         Express Keys Extensions - allows an application to receive Express Key event notifications and override the normal system-wide behavior of Express Keys

         Touch Strip Extensions - on Intuos tablets that support Touch Strips, allows an application to receive Touch Strip event notifications and override the normal system-wide behavior of Touch Strips

         Touch Rings Extensions - on Intuos tablets that support Touch Rings, allows an application to receive Touch Ring event notifications and override the normal system-wide behavior of Touch Rings

See the Wintab Specification Level 1.4 for details on these extensions.