Wintab Interface Specification 1.4:

16-bit and 32-bit API Reference

Revised October, 2010


This specification was developed in response to a perceived need for a standardized programming inter­face to digitizing tablets, three dimensional position sensors, and other pointing devices by a group of lead­ing digitizer manufacturers and applications developers. The availability of drivers that support the features of the specification will simplify the process of developing Windows appli­cation programs that in­corporate absolute coordinate input, and enhance the acceptance of ad­vanced pointing de­vices among users.

This specification is intended to be an open standard, and as such the text and information contained herein may be freely used, copied, or distributed without compensation or licensing restrictions.

Original copyright  © 1991 by LCS/Telegraphics.*

Update:  copyright © 2014 by Wacom Technology Corp.

Address questions and comments to:

Wacom Technology Corporation
1311 SE Cardinal Court
Vancouver, WA 98683
USA Tel:  ++1-360-896-9833

Ø  For Wintab programming developer support questions, send email to: developer@wacom.com

Ø  For Wintab samples and documentation, visit: http://us.wacom.com/en/developerrelations/windows

Ø  For general questions regarding Wacom tablet usage, visit: http://www.wacom.com and search for "Product Support".

 


Contents

1.      Background Information.. 6

1.1.        Features of Digitizers. 6

1.2.        The Windows Environment. 6

2.      Design Goals. 6

2.1.        User Control. 7

2.2.        Ease of Programming.. 7

2.3.        Tablet Sharing.. 7

2.4.        Tablet Feature Support. 8

3.      Design Concepts. 8

3.1.        Device Conventions. 8

3.2.        Device Information.. 9

3.3.        Tablet Contexts. 9

3.4.        Event Packets. 9

3.5.        Extensions. 10

3.6.        Persistent Binding of Interface Features (1.1) 10

4.      Interface Implementations. 11

4.1.        File and Module Conventions. 11

4.2.        Feature Support Options. 11

5.      Function Reference. 12

5.1.        Basic Functions. 13

5.1.1.          WTInfo. 13

5.1.2.          WTOpen. 14

5.1.3.          WTClose. 15

5.1.4.          WTPacketsGet 16

5.1.5.          WTPacket 16

5.2.        Visibility Functions. 17

5.2.1.          WTEnable. 17

5.2.2.          WTOverlap. 17

5.3.        Context Editing Functions. 18

5.3.1.          WTGet 18

5.3.2.          WTSet (1.1 modified) 18

5.3.3.          WTExtGet 19

5.3.4.          WTExtSet 19

5.3.5.          WTSave. 20

5.3.6.          WTRestore. 21

5.4.        Advanced Packet and Queue Functions. 21

5.4.1.          WTPacketsPeek. 21

5.4.2.          WTDataGet 22

5.4.3.          WTDataPeek. 22

5.4.4.          WTQueuePackets (16-bit only) 23

5.4.5.          WTQueuePacketsEx. 23

5.4.6.          WTQueueSizeGet 24

5.4.7.          WTQueueSizeSet 24

5.5.        Manager Handle Functions. 25

5.5.1.          WTMgrOpen. 25

5.5.2.          WTMgrClose. 25

5.6.        Manager Context Functions. 26

5.6.1.          WTMgrContextEnum.. 26

5.6.2.          WTMgrContextOwner 27

5.6.3.          WTMgrDefContext 27

5.6.4.          WTMgrDefContextEx (1.1 modified, 1.4 modified) 28

5.7.        Manager Preference Data Functions (1.4 modified) 28

5.7.1.          WTMgrCsrButtonMap. 28

5.7.2.          WTMgrCsrPressureBtnMarks (16-bit only) 29

5.7.3.          WTMgrCsrPressureBtnMarksEx. 30

5.7.4.          WTMgrCsrPressureResponse. 31

6.      Message Reference. 32

6.1.        Event Messages. 33

6.1.1.          WT_PACKET. 33

6.1.2.          WT_CSRCHANGE (1.1) 33

6.2.        Context Messages. 33

6.2.1.          WT_CTXOPEN.. 33

6.2.2.          WT_CTXCLOSE. 34

6.2.3.          WT_CTXUPDATE. 34

6.2.4.          WT_CTXOVERLAP. 34

6.2.5.          WT_PROXIMITY. 35

6.3.        Information Change Messages. 35

6.3.1.          WT_INFOCHANGE (1.4 modified) 35

7.      Data Reference. 36

7.1.        Common Data Types (1.1 modified, 1.4 modified) 36

7.2.        Information Data Structures. 37

7.2.1.          AXIS. 37

7.2.2.          Information Categories and Indices (1.1 modified) 38

7.3.        Context Data Structures. 47

7.3.1.          LOGCONTEXT (1.1 modified) 47

7.4.        Event Data Structures. 52

7.4.1.          PACKET (1.1 modified) 52

7.4.2.          ORIENTATION.. 54

7.4.3.          ROTATION (1.1) 55

Appendix A.  Using PKTDEF.H.. 55

Appendix B.  Extension Definitions (1.4 modified) 57

B.1.        Extensions Programming.. 57

Extensions Programming Notes. 58

B.2.        Out of Bounds Tracking.. 58

OBT Programming. 59

Information Category. 59

Turning OBT On and Off 59

B.5.        Cursor Mask. 59

CSRMASK Programming. 59

Information Category. 60

B.6.        Extended Button Masks. 60

XBTNMASK Programming. 60

Information Category. 61

B.7.        Express Keys Extension (1.4 modified) 61

B.8.        Touch Strips and Touch Rings Extensions (1.4 modified) 64

B.9.        Extension Structures (1.4 modified) 67

EXPKEYSDATA structure. 67

SLIDERDATA structure. 67

EXTPROPERTY structure. 67

Appendix C.  Additional Features (1.4 modified) 68

C.1.        Eraser. 68

C.2.        Tilt. 68

C.3.        Dual Track. 69

C.4.        Unique ID.. 70

C.5.        Airbrush Fingerwheel. 71

C.6.        4D Mouse Rotation.. 71

C.7.        4D Mouse Thumbwheel. 71

 

 

 

 

 


1.      Background Information

This document describes a programming interface for using digitizing tablets and other advanced pointing de­vices with Microsoft Windows Version 3.0 and above. The design presented here is based on the input of numerous professionals from the pointing device manufacturing and Windows soft­ware development industries.

In this document, the words "tablet" and "digitizer" are used interchange­ably to mean all absolute point­ing or digitizing devices that can be made to work with this interface. The definition is not lim­ited to de­vices that use a physical tablet.  In fact, this specification can support de­vices that combine rela­tive and absolute pointing as well as purely relative devices.

The following sections describe features of tablets and of the Windows environment that helped mo­tivate the design.

1.1.   Features of Digitizers

Digitizing tablets present several problems to device interface authors.

        ·      Many tablets have a very high report rate.

        ·      Many tablets have many configurable features and types of input information.

        ·      Tablets often control the system cursor, provide additional digitizing input, and provide template or macro functions.

1.2.   The Windows Environment

Programming for tablets in the Windows environment presents additional problems.

        ·      Multitasking means multiple applications may have to share the tablet.

        ·      The tablet must also be able to control the system cursor and/or the pen (in Pen Windows).

        ·      The tablet must work with legacy applications, and with applications written to take advan­tage of tablet services.

        ·      The tablet driver must add minimal speed and memory overhead, so as many applications as possible can run as efficiently as possible.

        ·      The user should be able to control how applications use the tablet. The user interface must be ef­ficient, consistent, and customizable.

2.      Design Goals

While the tablet interface design must address the technical problems stated above, it must also be useful to the programmers who will write tablet programs, and ultimately, to the tablet users. Four design goals will help clarify these needs, and provide some criteria for evaluating the interface speci­fication. The goals are user control, ease of programming, tablet sharing, and tablet feature support.

2.1.   User Control

The user should be able to use and control the tablet in as natural and easy a manner as possible. The user's preferences should take precedence over application requests, where possible.

Here are questions to ask when thinking about user control as a design goal:

        ·      Can the user understand how applications use the tablet?

        ·      Is the interface for controlling tablet functions natural and unobtrusive?

        ·      Is the user allowed to change things that help to customize the work environment, but pre­vented from changing things over which applications must have control?

2.2.   Ease of Programming

Programming is easiest when the amount of knowledge and effort required matches the task at hand. Writing simple programs should require only a few lines of code and a minimal understanding of the en­vironment. On the other hand, more advanced features and functions should be available to those who need them. The interface should accommodate three kinds of programmers: those who wish to write sim­ple tablet programs, programmers who wish to write complex applications that take full ad­vantage of tab­let capabilities, and programmers who wish to provide tablet device control features. In addition, the inter­face should accommodate programmers in as many different programming lan­guages, situations, and en­vironments as possible.

Questions to ask when thinking about ease of programming include:

        ·      How hard is it to learn the interface and write a simple program that uses tablet input?

        ·      Can programmers of complex applications control the features they need?

        ·      Are more powerful tablet device control features available?

        ·      Can the interface be used in different programming environments?

        ·      Is the interface logical, consistent, and robust?

2.3.   Tablet Sharing

In the Windows environment, multiple applications that use the tablet may be running at once. Each ap­plication will require different services. Applications must be able to get the services they need without getting in each others' way.

Questions to ask when thinking about tablet sharing include:

    ·          Can tablet applications use the tablet features they need, independent of other applications?

    ·          Does the interface prevent a rogue application from "hijacking" the tablet, or causing dead­locks?

    ·          Does the sharing architecture promote efficiency?

2.4.   Tablet Feature Support

The interface gives standard access to as many features as possible, while leaving room for future ex­ten­sions and vendor-specific customizations. Applications should be able to get the tablet informa­tion and services they want, just the way they want them. Users should be able to use the tablet to set up an effi­cient, comfortable work environment.

Questions to ask when thinking about tablet feature support include:

        ·      Does the interface provide the features applications need? Are any commonly available fea­tures not supported?

        ·      Does the interface provide what users need? Is anything missing?

        ·      Are future extensions possible and fairly easy?

        ·      Are vendor-specific extensions possible?

3.      Design Concepts

The proposed interface design depends on several fundamental concepts. Devices and cursor types de­scribe physical hardware configurations. The interface publishes read-only information through a single information interface. Applications interact with the interface by setting up tablet contexts and consuming event packets. Applications may assume interface and hardware control functions by be­coming tablet managers. The interface provides explicit support for future extensions.

3.1.   Device Conventions

The interface provides access to one or more devices that produce pointing input. Devices sup­ported by this interface have some common characteristics. The device must define an absolute or relative coordi­nate space in at least two dimensions for which it can return position data. The device must have a point­ing ap­para­tus or method (such as a stylus, or a finger touching a touch pad), called the cursor, that de­fines the current position. The cursor must be able to return at least one bit of additional state (via a but­ton, touching a digitizing surface, etc.).

Devices may have multiple cursor types that have different physical configurations, or that have differ­ent numbers of buttons, or return auxiliary information, such as pressure information. Cursor types may also describe different optional hardware configurations.

The interface defines a standard orientation for reporting device native coordinates. When the user is viewing the device in its normal position, the coordinate origin will be at the lower left of the device. The coordinate system will be right-handed, that is, the positive x axis points from left to right, and the posi­tive y axis points either upward or away from the user. The z axis, if supported, points either to­ward the user or upward. For devices that lay flat on a table top, the x-y plane will be horizontal and the z axis will point upward. For devices that are oriented vertically (for example, a touch screen on a conventional dis­play), the x-y plane will be vertical, and the z axis will point toward the user.

 

 

1.    

2.    

3.    

3.1.    

3.2.   Device Information

Any program can get descriptive information about the tablet via the WTInfo function. The interface specifies certain information that must be available, but allows new implementations to add new types of information. The basic information includes device identifiers, version numbers, and overall ca­pabilities.

The information items are organized by category and index numbers. The combination of a category and index specifies a single information data item, which may be a scalar value, string, structure, or array. Applica­tions may retrieve single items or whole categories at once.

Some categories are multiplexed. A single category code represents the first of a group of identically in­dexed categories, one for each of a set of similar objects. Multiplexed categories in­clude those for devices and cur­sor types. One constructs the category number by adding the defined cate­gory code to a zero-based device or cursor identification number.

The information is read-only for normal tablet applications. Some information items may change during the course of a Windows session; tablet applications receive messages notifying them of changes in tablet information.

1.    

2.    

3.    

3.1.    

3.2.    

3.3.   Tablet Contexts

Tablet contexts play a central role in the interface; they are the objects that applications use to specify their use of the tablet. Con­texts include not only the physical area of the tablet that the application will use, but also information about the type, con­tents, and delivery method for tablet events, as well as other information. Tablet contexts are somewhat analo­gous to display contexts in the GDI interface model; they contain context information about a spe­cific application's use of the tablet.

An application can open more than one context, but most only need one. Applications can customize their contexts, or they can open a context using a default context specification that is always available. The WTInfo function provides access to the default context specification.

Opening a context requires a window handle. The window handle becomes the context's owner and will receive any window messages associated with the context.

Contexts are remotely similar to screen windows in that they can physically overlap. The tablet inter­face uses a combination of context overlap order and context attributes to decide which context will process a given event. The topmost context in the overlap order whose input context encompasses the event, and whose event masks select the event, will process the event. (Note that the notion of overlap order is sepa­rate from the notion of the physical z dimension.) Tablet managers (described below) provide a way to modify and overlap contexts.

1.    

2.    

3.    

3.1.    

3.2.    

3.3.    

3.4.   Event Packets

Tablet contexts generate and report tablet activity via event packets. Applications can control how they receive events, which events they receive, and what information they contain.

Applications may receive events either by polling, or via Windows messages.

        ·      Polling: Any application that has opened a context can call the WTPacketsGet function to get the next state of the tablet for that context.

        ·      Window Messages: Applications that request messages will receive the WT_PACKET mes­sage (described below), which indicates that something happened in the context and provides a refer­ence to more information.

Applications can control which events they receive by using event masks. For example, some appli­ca­tions may only need to know when a button is pressed, while others may need to receive an event every time the cursor moves. Tablet context event masks implement this type of control.

Applications can control the contents of the event packets they receive. Some tablets can return data that many applications will not need, like button pressure and three dimensional position and orien­tation in­formation. The context object provides a way of specifying which data items the appli­cation needs. This allows the driver to improve the efficiency of packet delivery to applications that only need a few items per packet.

Packets are stored in context-specific packet queues and retrieved by explicit function calls. The interface provides ways to peek at and get packets, to query the size and contents of the queue, and to re-size the queue.Tablet Managers

The interface provides functions for tablet management. An application can become a tablet manager by opening a tablet manager handle. This handle allows the manager access to spe­cial functions. These man­agement functions allow the application to arrange, overlap, and modify tablet contexts. Man­agers may also perform other functions, such as changing default values used by applica­tions, chang­ing ergo­nomic, preference, and configuration settings, controlling tablet behavior with non-tablet aware applica­tions, modi­fy­ing user dialogs, and recording and playing back tablet packets. Opening a manager handle re­quires a window handle. The window becomes a manager window and receives window messages about interface and con­text activity.

1.    

2.    

3.    

3.1.    

3.2.    

3.3.    

3.4.    

3.5.   Extensions

The interface allows implementations to define additional features called extensions. Extensions can be made available to new applications without the need to modify ex­isting applications. Extensions are sup­ported through the information categories, through the flexible definition of packets, and through special context and manager functions.

Designing an extension involves defining the meaning and behavior of the extension packet and/or prefer­ence data, filling in the information category, defining the extension's interface with the special functions, and possibly defining additional functions to support the extension. Each extension will be assigned a unique tag for identification. Not all implementations will support all extensions.

A multiplexed information category contains descriptive data about extensions. Note that applica­tions must find their extensions by iterating through the categories and matching tags. While tags are fixed across all implementations, category numbers may vary among implementations.

1.    

2.    

3.    

3.1.    

3.2.    

3.3.    

3.4.    

3.5.    

3.6.   Persistent Binding of Interface Features (1.1)

The interface provides access to many of its features using consecutive numeric indices whose value is not guaranteed from session to session. However, sufficient information is provided to create unique identifi­ers for devices, cursors, and interface extensions. Devices should be uniquely identified by the contents of their name strings. If multiple identical devices are present, implementation providers should provide unique, persistent id strings to the extent possible. Identical devices that return unique serial numbers are ideal. If supported by the hardware, cursors also may have a physical cursor id that uniquely identifies the cursor in a persistent and stable manner. Interface extensions are uniquely identified by their tag.

1. 

2. 

3. 


4.      Interface Implementations

Implementations of this interface usually support one specific device, a class of similar devices, or a com­mon combination of devices. The following sections discuss guidelines for implementations.

1.    

2.    

3.    

4.    

4.1.   File and Module Conventions

For 16-bit implementations, the interface functions, and any additional vendor- or device-specific func­tions, reside in a dynamic link library with the file name "WINTAB.DLL" and module name "WINTAB"; 32-bit implementations use the file name "WINTAB32.DLL" and module name "WINTAB32." Any other file or module con­ventions are implementation specific. Implementations may include other library mod­ules or data files as necessary. Installation processes are likewise implementa­tion-specific.

Wintab programs written in the C language require two header files. WINTAB.H contains definitions of all of the functions, constants, and fixed data types. PKTDEF.H contains a parameterized definition of the PACKET data structure, that can be tailored to fit the application. The Wintab Programmer's Kit con­tains these and other files necessary for Wintab programming, plus several example programs with C-lan­guage source files. The Wintab Programmer's Kit is available from the author.

1.    

2.    

3.    

4.    

4.1.    

4.2.   Feature Support Options

Some features of the interface are optional and may be left out by some implementations.

Support of defined data items other than x, y, and buttons is optional. Many devices only report x, y, and button information.

Support of system-cursor contexts is optional. This option relieves implementations of replacing the sys­tem mouse driver in Windows versions before 3.1.

Support of Pen Windows contexts is optional. Not all systems will have the Pen Windows hardware and software necessary.

Support of external tablet manager applications is optional, and the number of manager handles is imple­mentation-dependent. However, the manager functions should be present in all implementa­tions, return­ing appropriate failure codes if not fully implemented. An implementation may provide context- and hardware-management support internally only, if desired. On the other hand, providing the external man­ager interface may relieve the implementation of a considerable amount of user in­terface code, and make improvements to the manager interface easier to implement and distribute later.

Support of extension data items is optional. Most extensions will be geared to unusual hardware features.

1. 

2. 

3. 

4. 


5.      Function Reference

All tablet function names have the prefix "WT" and have attributes equivalent to WINAPI. Applica­tions gain access to the tablet interface functions through a dynamic-link library with standard file and module names, as defined in the previous section. Applications may link to the functions by using the Windows functions LoadLibrary, FreeLibrary, and GetProcAddress, or use an import library.

Specific to 32-bit Wintab:  The functions WTInfo, WTOpen,  WTGet, and WTSet have both ANSI and Unicode versions, using the same ANSI/Unicode porting conventions used in the Win32 API. Two non-portable functions, WTQueuePackets, WTMgrCsrPressureBtnMarks, are replaced by new portable functions WTQueuePacketsEx, WTMgrCsrPressureBtnMarksEx.

Table 5.1. Ordinal Function Numbers for Dynamic Linking

Ordinal numbers for dynamic linking are defined in the table below. Where two ordinal entries appear, the first entry identifies the 16-bit and 32-bit ANSI versions of the function. The second entry identifies the 32-bit Unicode version.

Function Name

Ordinal

Function Name

Ordinal

WTInfo

20, 1020

WTQueueSizeGet

84

WTOpen

21, 1021

WTQueueSizeSet

85

WTClose

22

WTMgrOpen

100

WTPacketsGet

23

WTMgrClose

101

WTPacket

24

WTMgrContextEnum

120

WTEnable

40

WTMgrContextOwner

121

WTOverlap

41

WTMgrDefContext

122

WTConfig

60

WTMgrDeviceConfig

140

WTGet

61, 1061

WTMgrExt

180

WTSet

62, 1062

WTMgrCsrEnable

181

WTExtGet

63

WTMgrCsrButtonMap

182

WTExtSet

64

WTMgrCsrPressureBtnMarks

183

WTSave

65

WTMgrCsrPressureResponse

184

WTRestore

66

WTMgrCsrExt

185

WTPacketsPeek

80

WTQueuePacketsEx

200

WTDataGet

81

WTMgrCsrPressureBtnMarksEx

201

WTDataPeek

82

WTMgrDefContextEx (1.1)

206

WTQueuePackets

83

 

 

1.    

2.    

3.    

4.    

5.    

5.1.   Basic Functions

The functions in the following section will be used by most tablet-aware applications. They include getting interface and device information, opening and closing contexts, and retrieving packets by polling or via Windows messages.

1.    

2.    

3.    

4.    

5.    

5.1.    

1.    

2.    

3.    

4.    

5.    

5.1.    

5.1.1.   WTInfo

Syntax

UINT WTInfo(wCategory, nIndex, lpOutput)

 

This function returns global information about the interface in an application-sup­plied buffer. Different types of information are specified by different index argu­ments. Applications use this function to receive information about tablet coordi­nates, physical dimensions, capabilities, and cursor types.

 

Parameter

Type/Description

 

wCategory

UINT  Identifies the category from which information is being re­quested.

 

nIndex

UINT  Identifies which information is being requested from within the category.

 

lpOutput

LPVOID  Points to a buffer to hold the requested information.

Return Value

The return value specifies the size of the returned information in bytes. If the infor­mation is not supported, the function returns zero. If a tablet is not physi­cally pres­ent, this function always returns zero.

Comments

Several important categories of information are available through this function. First, the function provides identification information, including specification and software version numbers, and tablet vendor and model information. Sec­ond, the function provides general capability information, including dimensions, resolutions, optional features, and cursor types. Third, the function provides categories that give defaults for all tablet context attributes. Finally, the func­tion may provide any other implementation- or vendor-specific information cat­egories necessary.

 

The information returned by this function is subject to change during a Win­dows session. Applications cannot change the information returned here, but tablet man­ager applications or hardware changes or errors can. Applications can respond to information changes by fielding the WT_INFOCHANGE message. The parameters of the message indicate which information has changed.

 

If the wCategory argument is zero, the function copies no data to the output buffer, but returns the size in bytes of the buffer necessary to hold the largest complete category. If the nIndex argument is zero, the function returns all of the information entries in the category in a single data structure.

 

If the lpOutput argument is NULL, the function just returns the required buffer size.

See Also

Category and index definitions in tables 7.3 through 7.9, and the WT_INFOCHANGE message in section 6.3.1.

5.1.2.   WTOpen

Syntax

HCTX WTOpen(hWnd, lpLogCtx, fEnable)

 

This function establishes an active context on the tablet. On successful comple­tion of this function, the application may begin receiving tablet events via mes­sages (if they were requested), and may use the handle returned to poll the con­text, or to per­form other context-related functions.

 

Parameter

Type/Description

 

hWnd

HWND  Identifies the window that owns the tablet context, and receives messages from the context.

 

lpLogCtx

LPLOGCONTEXT  Points to an application-provided LOGCONTEXT data structure describing the context to be opened.

 

fEnable

BOOL  Specifies whether the new context will immediately begin processing input data.

Return Value

The return value identifies the new context. It is NULL if the context is not opened.

Comments

Opening a new context allows the application to receive tablet input or creates a context that controls the system cursor or Pen Windows pen. The owning window (and all manager windows) will immediately receive a WT_CTXOPEN message when the context has been opened.

 

If the fEnable argument is zero, the context will be created, but will not process input. The context can be enabled using the WTEnable function.

 

If tablet event messages were requested in the context specification, the owning window will receive them. The application can control the message numbers used the lcMsgBase field of the LOGCONTEXT structure.

 

The window that owns the new context will receive context and information change messages even if event messages were not requested. It is not necessary to handle these in many cases, but some applications may wish to do so.

 

The newly opened tablet context will be placed on the top of the context overlap or­der.

 

Invalid or out-of-range attribute values in the logical context structure will ei­ther be validated, or cause the open to fail, depending on the attributes involved. Upon a successful return from the function, the context specification pointed to by lpLogCtx will contain the validated values.

See Also

The WTEnable function in section 5.2.1, the LOGCONTEXT data structure in section 7.3.1, and the context and infor­mation change messages in sections 6.2 and 6.3.

5.1.3.   WTClose

Syntax

BOOL WTClose(hCtx)

 

This function closes and destroys the tablet context object.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context to be closed.

Return Value

The function returns a non-zero value if the context was valid and was destroyed. Otherwise, it returns zero.

Comments

After a call to this function, the passed handle is no longer valid. The owning win­dow (and all manager windows) will receive a WT_CTXCLOSE message when the context has been closed.

See Also

The WTOpen function in section 5.1.2.

 


5.1.4.   WTPacketsGet

Syntax

int WTPacketsGet(hCtx, cMaxPkts, lpPkts)

 

This function copies the next cMaxPkts events from the packet queue of context hCtx to the passed lpPkts buffer and removes them from the queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose packets are being returned.

 

cMaxPkts

int  Specifies the maximum number of packets to return.

 

lpPkts

LPVOID  Points to a buffer to receive the event packets.

Return Value

The return value is the number of packets copied in the buffer.

Comments

The exact structure of the returned packet is determined by the packet infor­mation  that was requested when the context was opened.

 

The buffer pointed to by lpPkts must be at least cMaxPkts * sizeof(PACKET) bytes long to prevent overflow.

 

Applications may flush packets from the queue by calling this function with a NULL lpPkt argument.

See Also

The WTPacketsPeek function in section 5.4.1, and the descriptions of the LOGCONTEXT (section 7.3.1) and PACKET (section 7.4.1) data structures.

5.1.5.   WTPacket

Syntax

BOOL WTPacket(hCtx, wSerial, lpPkt)

 

This function fills in the passed lpPkt buffer with the context event packet having the specified serial number. The returned packet and any older packets are removed from the context's internal queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose packets are being returned.

 

wSerial

UINT  Serial number of the tablet event to return.

 

lpPkt

LPVOID  Points to a buffer to receive the event packet.

Return Value

The return value is non-zero if the specified packet was found and returned. It is zero if the specified packet was not found in the queue.

Comments

The exact structure of the returned packet is determined by the packet infor­mation that was requested when the context was opened.

 

The buffer pointed to by lpPkts must be at least sizeof(PACKET) bytes long to pre­vent overflow.

 

Applications may flush packets from the queue by calling this function with a NULL lpPkts argument.

See Also

The descriptions of the LOGCONTEXT (section 7.3.1) and PACKET (section 7.4.1) data structures.

 

1.    

2.    

3.    

4.    

5.    

5.1.    

5.2.   Visibility Functions

The functions in this section allow applications to control contexts' visibility, whether or not they are pro­cessing input, and their overlap order.

5.2.    

5.2.1.   WTEnable

Syntax

BOOL WTEnable(hCtx, fEnable)

 

This function enables or disables a tablet context, temporarily turning on or off the processing of packets.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context to be enabled or disabled.

 

fEnable

BOOL  Specifies enabling if non-zero, disabling if zero.

Return Value

The function returns a non-zero value if the enable or disable request was satis­fied, zero otherwise.

Comments

Calls to this function to enable an already enabled context, or to disable an al­ready disabled context will return a non-zero value, but otherwise do nothing.

 

The context’s packet queue is flushed on disable.

 

Applications can determine whether a context is currently enabled by using the WTGet function and examining the lcStatus field of the LOGCONTEXT struc­ture.

See Also

The WTGet function in section 5.3.2, and the LOGCONTEXT structure in sec­tion 7.3.1.

5.2.2.   WTOverlap

Syntax

BOOL WTOverlap(hCtx, fToTop)

 

This function sends a tablet context to the top or bottom of the order of over­lapping tablet contexts.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context to move within the overlap order.

 

fToTop

BOOL  Specifies sending the context to the top of the overlap or­der if non-zero, or to the bottom if zero.

Return Value

The function returns non-zero if successful, zero otherwise.

Comments

Tablet contexts' input areas are allowed to overlap. The tablet interface main­tains an overlap order that helps determine which context will process a given event. The topmost context in the overlap order whose input context encom­passes the event, and whose event masks select the event will process the event.

 

This function is useful for getting access to input events when the application's con­text is overlapped by other contexts.

 

The function will fail only if the context argument is invalid.

 

5.3.   Context Editing Functions

This group of functions allows applications to edit, save, and restore contexts.

5.3.    

5.3.1.   WTGet

Syntax

BOOL WTGet(hCtx, lpLogCtx)

 

This function fills the passed structure with the current context attributes for the passed handle.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose attributes are to be copied.

 

lpLogCtx

LPLOGCONTEXT  Points to a LOGCONTEXT data structure to which the context attributes are to be copied.

Return Value

The function returns a non-zero value if the data is retrieved successfully. Oth­er­wise, it returns zero.

See Also

The LOGCONTEXT structure in section 7.3.1.

5.3.2.   WTSet (1.1 modified)

Syntax

BOOL WTSet(hCtx, lpLogCtx)

 

This function allows some of the context's attributes to be changed on the fly.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose attributes are being changed.

 

lpLogCtx

LPLOGCONTEXT  Points to a LOGCONTEXT data structure containing the new context attributes.

Return Value

The function returns a non-zero value if the context was changed to match the passed context specification; it returns zero if any of the requested changes could not be made.

Comments

If this function is called by the task or process that owns the context, any context attribute may be changed. Otherwise, the function can change attributes that do not affect the format or meaning of the context's event packets and that were not speci­fied as locked when the context was opened. Context lock values can only be changed by the context’s owner.

 

1.1: If the hCtx argument is a default context handle returned from WTMgrDef­Context or WTMgrDefContextEx, and the lpLogCtx argument is WTP_LPDEFAULT, the default context will be reset to its initial factory default values.

See Also

The LOGCONTEXT structure in section 7.3.1 and the context lock values in table 7.13.

5.3.3.   WTExtGet

Syntax

BOOL WTExtGet(hCtx, wExt, lpData)

 

This function retrieves any context-specific data for an extension.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose extension attributes are being retrieved.

 

wExt

UINT  Identifies the extension tag for which context-specific data is being retrieved.

 

lpData

LPVOID  Points to a buffer to hold the retrieved data.

Return Value

The function returns a non-zero value if the data is retrieved successfully. Oth­er­wise, it returns zero.

See Also

The extension definitions in Appendix B.

5.3.4.   WTExtSet

Syntax

BOOL WTExtSet(hCtx, wExt, lpData)

 

This function sets any context-specific data for an extension.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose extension attributes are being modified.

 

wExt

UINT  Identifies the extension tag for which context-specific data is being modified.

 

lpData

LPVOID  Points to the new data.

Return Value

The function returns a non-zero value if the data is modified successfully. Oth­er­wise, it returns zero.

Comments

Extensions may forbid their context-specific data to be changed during the life­time of a context. For such extensions, calls to this function would always fail.

 

Extensions may also limit context data editing to the task of the owning window, as with the context locks.

See Also

The extension definitions in Appendix B, the LOGCONTEXT data structure in section 7.3.1 and the context locking values in table 7.13.

5.3.5.   WTSave

Syntax

BOOL WTSave(hCtx, lpSaveInfo)

 

This function fills the passed buffer with binary save information that can be used to restore the equivalent context in a subsequent Windows session.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context that is being saved.

 

lpSaveInfo

LPVOID  Points to a buffer to contain the save information.

Return Value

The function returns non-zero if the save information is successfully retrieved. Oth­erwise, it returns zero.

Comments

The size of the save information buffer can be determined by calling the WTInfo function with category WTI_INTERFACE, index IFC_CTXSAVESIZE.

 

The save information is returned in a private binary data format. Applications should store the information unmodified and recreate the context by passing the save information to the WTRestore function.

 

Using WTSave and WTRestore allows applications to easily save and restore ex­tension data bound to contexts.

See Also

The WTRestore function in section 5.3.7.

5.3.6.   WTRestore

Syntax

HCTX WTRestore(hWnd, lpSaveInfo, fEnable)

 

This function creates a tablet context from save information returned from the WTSave function.

 

Parameter

Type/Description

 

hWnd

HWND  Identifies the window that owns the tablet context, and receives messages from the context.

 

lpSaveInfo

LPVOID  Points to a buffer containing save information.

 

fEnable

BOOL  Specifies whether the new context will immediately begin processing input data.

Return Value

The function returns a valid context handle if successful. If a context equivalent to the save information could not be created, the function returns NULL.

Comments

The save information is in a private binary data format. Applications should only pass save information retrieved by the WTSave function.

 

This function is much like WTOpen, except that it uses save in­formation for input instead of a logical context.  In particular, it will generate a WT_CTXOPEN mes­sage for the new context.

See Also

The WTOpen function in section 5.1.2, the WTSave function in section 5.3.6, and the WT_CTXOPEN message in section 6.2.1.

 

5.4.   Advanced Packet and Queue Functions

These functions provide advanced packet retrieval and queue manipulation. The packet retrieval functions require the application to provide a packet output buffer. To prevent overflow, the buffer must be large enough to hold the requested number of packets from the specified context. It is up to the caller to deter­mine the packet size (by interrogating the context, if necessary), and to allocate a large enough buffer. Ap­plications may flush packets from the queue by passing a NULL buffer pointer.

5.4.    

5.4.1.   WTPacketsPeek

Syntax

int WTPacketsPeek(hCtx, cMaxPkts, lpPkts)

 

This function copies the next cMaxPkts events from the packet queue of context hCtx to the passed lpPkts buffer without removing them from the queue.

 

Parameter

Type/Description

 

hCtx

HCTX Identifies the context whose packets are being read.

 

cMaxPkts

int  Specifies the maximum number of packets to return.

 

lpPkts

LPVOID  Points to a buffer to receive the event packets.

Return Value

The return value is the number of packets copied in the buffer.

Comments

The buffer pointed to by lpPkts must be at least cMaxPkts * sizeof(PACKET) bytes long to prevent overflow.

See Also

the WTPacketsGet function in section 5.1.4.

5.4.2.   WTDataGet

Syntax

int WTDataGet(hCtx, wBegin, wEnd, cMaxPkts, lpPkts, lpNPkts)

 

This function copies all packets with serial numbers between wBegin and wEnd in­clusive from the context's queue to the passed buffer and removes them from the queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose packets are being returned.

 

wBegin

UINT  Serial number of the oldest tablet event to return.

 

wEnd

UINT  Serial number of the newest tablet event to return.

 

cMaxPkts

int  Specifies the maximum number of packets to return.

 

lpPkts

LPVOID  Points to a buffer to receive the event packets.

 

lpNPkts

LPINT  Points to an integer to receive the number of packets ac­tually copied.

Return Value

The return value is the total number of packets found in the queue between wBegin and wEnd.

Comments

The buffer pointed to by lpPkts must be at least cMaxPkts * sizeof(PACKET) bytes long to prevent overflow.

See Also

The WTDataPeek function in section 5.4.3, and the WTQueuePacketsEx function in section 5.4.5.

5.4.3.   WTDataPeek

Syntax

int WTDataPeek(hCtx, wBegin, wEnd, cMaxPkts, lpPkts, lpNPkts)

 

This function copies all packets with serial numbers between wBegin and wEnd in­clusive, from the context's queue to the passed buffer without removing them from the queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose packets are being read.

 

wBegin

UINT  Serial number of the oldest tablet event to return.

 

wEnd

UINT  Serial number of the newest tablet event to return.

 

cMaxPkts

int  Specifies the maximum number of packets to return.

 

lpPkts

LPVOID  Points to a buffer to receive the event packets.

 

lpNPkts

LPINT  Points to an integer to receive the number of packets ac­tually copied.

Return Value

The return value is the total number of packets found in the queue between wBegin and wEnd.

Comments

The buffer pointed to by lpPkts must be at least cMaxPkts * sizeof(PACKET) bytes long to prevent overflow.

See Also

The WTDataGet function in section 5.4.2, and the WTQueuePacketsEx function in section 5.4.5.

5.4.4.   WTQueuePackets (16-bit only)

Syntax

DWORD WTQueuePackets(hCtx)

 

This function returns the serial numbers of the oldest and newest packets cur­rently in the queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose queue is being queried.

Return Value

The high word of the return value contains the newest packet's serial number; the low word contains the oldest.

Comments

This function is non-portable and is superseded by WTQueuePacketsEx.

See Also

The WTQueuePacketsEx function in section 5.4.5.

5.4.5.   WTQueuePacketsEx

Syntax

BOOL WTQueuePacketsEx(hCtx, lpOld, lpNew)

 

This function returns the serial numbers of the oldest and newest packets cur­rently in the queue.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose queue is being queried.

 

lpOld

UINT FAR *  Points to an unsigned integer to receive the oldest packet's serial number.

 

lpNew

UINT FAR *  Points to an unsigned integer to receive the newest packet's serial number.

Return Value

The function returns non-zero if successful, zero otherwise.

5.4.6.   WTQueueSizeGet

Syntax

int WTQueueSizeGet(hCtx)

 

This function returns the number of packets the context's queue can hold.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose queue size is being re­turned.

Return Value

The return value is the number of packet the queue can hold.

See Also

The WTQueueSizeSet function in section 5.4.7.

5.4.7.   WTQueueSizeSet

Syntax

BOOL WTQueueSizeSet(hCtx, nPkts)

 

This function attempts to change the context's queue size to the value specified in nPkts.

 

Parameter

Type/Description

 

hCtx

HCTX  Identifies the context whose queue size is being set.

 

nPkts

int  Specifies the requested queue size.

Return Value

The return value is non-zero if the queue size was successfully changed.  Other­wise, it is zero.

Comments

If the return value is zero, the context has no queue because the function deletes the original queue before attempting to create a new one. The application must continue calling the function with a smaller queue size until the function returns a non-zero value.

See Also

The WTQueueSizeGet function in section 5.4.6.

 

5.5.   Manager Handle Functions

The functions described in this and subsequent sections are for use by tablet manager applications. The functions of this section create and destroy manager handles. These handles allow the interface code to limit the degree of simultaneous access to the powerful manager functions. Also, opening a manager handle lets the application receive messages about tablet interface activity.

5.5.    

5.5.1.   WTMgrOpen

Syntax

HMGR WTMgrOpen(hWnd, wMsgBase)

 

This function opens a tablet manager handle for use by tablet manager and con­figu­ration applications. This handle is required to call the tablet management func­tions.

 

Parameter

Type/Description

 

hWnd

HWND  Identifies the window which owns the manager handle.

 

wMsgBase

UINT  Specifies the message base number to use when notifying the manager window.

Return Value

The function returns a manager handle if successful, otherwise it returns NULL.

Comments

While the manager handle is open, the manager window will receive context mes­sages from all tablet contexts. Manager windows also receive information change messages.

 

The number of manager handles available is interface implementation-dependent, and can be determined by calling the WTInfo function with category WTI_INTERFACE and index IFC_NMANAGERS.

See Also

The WTInfo function in section 5.1.1, the WTMgrClose function in section 5.5.2, the description of message base numbers in section 6 and the context and in­for­ma­tion change messages in sections 6.2 and 6.3.

5.5.2.   WTMgrClose

Syntax

BOOL WTMgrClose(hMgr)

 

This function closes a tablet manager handle. After this function returns, the passed manager handle is no longer valid.

 

Parameter

Type/Description

 

hMgr

HMGR  Identifies the manager handle to close.

Return Value

The function returns non-zero if the handle was valid; otherwise, it returns zero.

 

5.6.   Manager Context Functions

These functions provide access to all open contexts and their owners, and allow changing context de­faults. Only tablet managers are allowed to manipulate tablet contexts belonging to other applica­tions.

5.6.    

5.6.1.   WTMgrContextEnum

Syntax

BOOL WTMgrContextEnum(hMgr, lpEnumFunc, lParam)

 

This function enumerates all tablet context handles by passing the handle of each context, in turn, to the callback function pointed to by the lpEnumFunc pa­rameter.

 

The enumeration terminates when the callback function returns zero.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

lpEnumFunc

WTENUMPROC  Is the procedure-instance address of the call­back function. See the following "Comments" section for details.

 

lParam

LPARAM  Specifies the value to be passed to the callback func­tion for the application's use.

Return Value

The return value specifies the outcome of the function. It is non-zero if all con­texts have been enumerated. Otherwise, it is zero.

Comments

The address passed as the lpEnumFunc parameter must be created by using the MakeProcInstance function.

 

The callback function must have attributes equivalent to WINAPI. The callback function must have the following form:

Callback

BOOL WINAPI EnumFunc(hCtx, lParam)
HCTX hCtx;
LPARAM lParam;

 

EnumFunc is a place holder for the application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the applica­tion's module-definition file.

 

Parameter

Description

 

hCtx

Identifies the context.

 

lParam

Specifies the 32-bit argument of the WTMgrContextEnum func­tion.

 

Return Value

The function must return a non-zero value to continue enumeration, or zero to stop it.

5.6.2.   WTMgrContextOwner

Syntax

HWND WTMgrContextOwner(hMgr, hCtx)

 

This function returns the handle of the window that owns a tablet context.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

hCtx

HCTX  Identifies the context whose owner is to be returned.

Return Value

The function returns the context owner's window handle if the passed arguments are valid. Otherwise, it returns NULL.

Comments

This function allows the tablet manager to coordinate tablet context manage­ment with the states of the context-owning windows.

5.6.3.   WTMgrDefContext

Syntax

HCTX WTMgrDefContext(hMgr, fSystem) (1.4 modified)

 

This function retrieves a context handle for either the default system context or the default digitizing context.  This context is read-only.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

fSystem

BOOL  Specifies retrieval of the default system context if non-zero, or the default digitizing context if zero.

Return Value

The return value is the context handle for the specified default context, or NULL if the arguments were invalid.

Comments

The default digitizing context is the context whose attributes are returned by the WTInfo function WTI_DEFCONTEXT category. The default system context is the context whose attributes are returned by the WTInfo function WTI_DEFSYSCTX category.

If any tablet is connected to the system, then the HCTX value returned by this function , when used with WTGet(), will return a LOGCONTEXT with lcDevice = (UINT)(-1), which represents the so-called "virtual device".  A virtual device (or "virtual tablet") accepts data from any connected tablet and sends it to the application.

See Also

The WTInfo function in section 5.1.1 the WTMgrDefContextEx function in section 5.6.4, and the category and index definitions in tables 7.3 through 7.9.

5.6.4.   WTMgrDefContextEx (1.1 modified, 1.4 modified)

Syntax

HCTX WTMgrDefContextEx(hMgr, wDevice, fSystem)

 

This function retrieves a context handle that allows setting values for the default digit­izing or system context for a specified device. This context is read-only.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

wDevice

UINT  Specifies the device for which a default context handle will be returned. 

 

fSystem

BOOL  Specifies retrieval of the default system context if non-zero, or the default digitizing context if zero.

Return Value

The return value is the context handle for the specified default context, or NULL if the arguments were invalid.

Comments

The default digitizing contexts are contexts whose attributes are returned by the WTInfo function WTI_DDCTXS multiplexed category. The default system con­texts are contexts whose attributes are returned by the WTInfo function WTI_DSCTXS multiplexed category.

If wDevice = (UINT)(-1), which represents the so-called "virtual device", then the HCTX value returned by this function , when used with WTGet(), will return a LOGCONTEXT with lcDevice = (UINT)(-1).  A virtual device (or "virtual tablet") accepts data from any connected tablet and sends it to the application.

See Also

The WTInfo function in section 5.1.1, and the category and index definitions in tables 7.3 through 7.9.

 

5.7.   Manager Preference Data Functions (1.4 modified)

The functions in this section manipulate global ergonomic or preference settings that are not bound to tablet contexts.

5.7.    

5.7.1.   WTMgrCsrButtonMap

Syntax

BOOL WTMgrCsrButtonMap(hMgr, wCursor, lpLogBtns, lpSysBtns)

 

This function allows tablet managers to change the button mappings for each cursor type. Each cursor type has two button maps. The logical button map as­signs physi­cal buttons to logical buttons (applications only use logical buttons). The system cursor button map binds system-button functions to logical buttons.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

wCursor

UINT  Specifies the zero-based cursor id of the cursor type whose button maps are being set.

 

lpLogBtns

LPBYTE  Points to a 32 byte array of logical button numbers, one for each physical button. If  the value WTP_LPDEFAULT is specified, the function resets the default value for the logical but­ton map.

 

lpSysBtns

LPBYTE  Points to a 32 byte array of button action codes, one for each logical button. If  the value WTP_LPDEFAULT is speci­fied, the function resets the default value for the system button map.

Return Value

The return value is non-zero if the new settings have taken effect. Otherwise, it is zero.

Comments

The function will allow two or more physical buttons to be assigned to one logi­cal button. Likewise, it does not ensure that left and right system button events can be properly generated. It is up to the tablet manager to make sure that ap­propriate limi­tations are applied to the logical button map and that the system buttons are not left disabled.

See Also

The cursor information categories in table 7.8, and the system button assign­ment codes in table 7.10.

5.7.2.   WTMgrCsrPressureBtnMarks (16-bit only)

Syntax

BOOL WTMgrCsrPressureBtnMarks(hMgr, wCsr, dwNMarks, dwTMarks)

 

This function allows tablet managers to change the pressure thresholds that control the mapping of pressure activity to button events.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

wCsr

UINT  Specifies the zero-based cursor id of the cursor type whose pressure button marks are being set.

 

dwNMarks

DWORD  Specifies the button marks for the normal pressure but­ton. The low order word contains the release mark; the high order word contains the press mark. If  the value WTP_DWDEFAULT is specified, the function resets the default value for the marks.

 

dwTMarks

DWORD  Specifies the button marks for the tangent pressure but­ton. The low order word contains the release mark; the high order word contains the press mark. If  the value WTP_DWDEFAULT is specified, the function resets the default value for the marks.

Return Value

The return value is non-zero if the new settings have taken effect. Otherwise, it is zero.

Comments

This function is non-portable and is superseded by WTMgrCsrPressureBtnMarksEx.

See Also

The cursor information categories in table 7.8, and the WTMgrCsrPres­sureBtnMarksEx function in section 5.9.5.

5.7.3.   WTMgrCsrPressureBtnMarksEx

Syntax

BOOL WTMgrCsrPressureBtnMarksEx(hMgr, wCsr, lpNMarks, lpTMarks)

 

This function allows tablet managers to change the pressure thresholds that control the mapping of pressure activity to button events.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

wCsr

UINT  Specifies the zero-based cursor id of the cursor type whose pressure button marks are being set.

 

lpNMarks

UINT FAR *  Points to a two-element array containing the button marks for the normal pressure button. The first unsigned integer contains the release mark; the second unsigned integer contains the press mark. If  the value WTP_LPDEFAULT is specified, the function resets the default value for the marks.

 

lpTMarks

UINT FAR *  Points to a two-element array containing the button marks for the tangent pressure button. The first unsigned integer contains the release mark; the second unsigned integer contains the press mark. If  the value WTP_LPDEFAULT is specified, the function resets the default value for the marks.

Return Value

The return value is non-zero if the new settings have taken effect. Otherwise, it is zero.

Comments

This function allows the tablet manager to let the user control the "feel" of the pres­sure buttons when they are used as conventional buttons.

 

The pressure ranges are defined such that the minimum value of the range indi­cates the resting, unpressed state, and the maximum value indicates the fully pressed state. The button marks determine the pressure at which button press and release events are generated. When the button is logically up and pressure rises above the press mark, a button press event is generated. Conversely, when the but­ton is logi­cally down and pressure drops below the release mark, a button release event is generated.

 

The marks should be set far enough apart so that the button does not "jitter," yet far enough from the ends of the range so that the button events are easy to gen­erate.

 

The marks are valid if and only if the button press mark is greater than the but­ton release mark. Setting the marks to invalid combinations will turn off button-event generation for the button.

See Also

The cursor information categories in table 7.8.

5.7.4.   WTMgrCsrPressureResponse

Syntax

BOOL WTMgrCsrPressureResponse(hMgr, wCsr, lpNResp, lpTResp)

 

This function allows tablet managers to tune the pressure response for each cursor type.

 

Parameter

Type/Description

 

hMgr

HMGR  Is the valid manager handle that identifies the caller as a manager application.

 

wCsr

UINT  Specifies the zero-based cursor id of the cursor whose pressure response curves are being set.

 

lpNResp

UINT FAR *  Points to an array of UINTs describing the pressure response curve for normal pressure. If  the value WTP_LPDEFAULT is specified, the function resets the default value for the response curve.

 

lpTResp

UINT FAR *  Points to an array of UINTs describing the pressure response curve for tangential pressure. If  the value WTP_LPDEFAULT is specified, the function resets the default value for the response curve.

Return Value

The return value is non-zero if the new settings have taken effect. Otherwise, it is zero.

Comments

The pressure response curves represent a transfer function mapping physical pres­sure values to logical pressure values (applications see only logical pressure values). Each array element contains a logical pressure value corresponding to some physi­cal pressure value. The array indices are "stretched" evenly over the input range.

 

The number of entries in the arrays depends upon the range of physical pressure values. The number will be the number of physical values or 256, whichever is smaller. When there is an entry for each possible value, the value is used as an in­dex to the array, and the corresponding array element is returned. When there are more values that array elements, the physical value is mapped to a 0-255 scale. The result is used as the index to look up the logical pressure value.

See Also

The cursor information categories in table 7.8.

 

6.      Message Reference

This section describes the messages sent to tablet-aware applications and to tablet managers. Since these messages are extensions to Windows, the message names below do not represent globally fixed message numbers. Applications choose a range of message numbers in the WM_USER range (WM_USER to 8000 hex), and publish their message base to the interface via the lcMsgBase field of the LOGCONTEXT structure (see section 7.3.1), or via the wMsgBase argument of the WTMgrOpen function (see section 5.5.1). Applications may choose different ranges for each context and manager han­dle, or use the same range for all.

The message names documented below actually represent fixed offsets from the application-selected base. The interface definition reserves sixteen offsets, to allow for future message definitions. The default mes­sage base is the global constant value WT_DEFBASE, defined as 7FF0 hex. Although this default value will be reasonably safe for many applications, it is the responsibility of application pro­grammers to pre­vent message number conflicts.

Specific to 32-bit Wintab:  Although most message arguments' types are wider for 32-bit Wintab, no mes­sage arguments have jumped from wParam to lParam or vice-versa. Most widened arguments now occupy previously unused or unavailable space. Please note that the category and index arguments of WT_INFOCHANGE have not been widened; they are still 16 bits. The header file WINTABX.H in the Wintab Programmer's Kit contains portable "message cracker" macros, suitable for both 16-bit and 32-bit use.

 


6.1.   Event Messages

Wintab applications that receive device events via Windows messages will receive the WT_PACKET mes­sage.

6.    

6.1.    

6.1.1.   WT_PACKET

Description

The WT_PACKET message is posted to the context-owning windows that have re­quested messag­ing for their context.

 

Parameter

Description

 

wParam

Contains the serial number of the packet that generated the mes­sage.

 

lParam

Contains the handle of the context that processed the packet.

Comments

Applications should call the WTPacket function or other packet retrieval func­tions upon receiving this message.

See Also

The WTPacket function in section 6.1.1, and the advanced packet and queue func­tions in section 5.4.

6.1.2.   WT_CSRCHANGE (1.1)

Description

The WT_CSRCHANGE message is posted to the owning window when a new cur­sor enters the context.

 

Parameter

Description

 

wParam

Contains the serial number of the packet that generated the mes­sage.

 

lParam

Contains the handle of the context that processed the packet.

Comments

Only contexts that have the CXO_CSRMESSAGES option selected will generate this message.

 

6.2.   Context Messages

The messages described in this section provide information about changes in contexts.

6.2.    

6.2.1.   WT_CTXOPEN

Description

The WT_CTXOPEN message is sent to the owning window and to any manager windows when a context is opened.

 

Parameter

Description

 

wParam

Contains the context handle of the opened context.

 

lParam

Contains the current context status flags.

Comments

Tablet manager applications should save the handle of the new context. Man­agers may want to query the user to configure the context further at this time.

6.2.2.   WT_CTXCLOSE

Description

The WT_CTXCLOSE message is sent to the owning win­dow and to any manager windows when a context is about to be closed.

 

Parameter

Description

 

wParam

Contains the context handle of the context to be closed.

 

lParam

Contains the current context status flags.

Comments

Tablet manager applications should note that the context is being closed and take appropriate action.

6.2.3.   WT_CTXUPDATE

Description

The WT_CTXUPDATE message is sent to the owning window and to any manager windows when a context is changed.

 

Parameter

Description

 

wParam

Contains the context handle of the changed context.

 

lParam

Contains the current context status flags.

Comments

Applications may want to call WTGet or WTExtGet on receiving this message to find out what context attributes were changed.

6.2.4.   WT_CTXOVERLAP

Description

The WT_CTXOVERLAP message is sent to the owning window and to any man­ager windows when a context is moved in the overlap order.

 

Parameter

Description

 

wParam

Contains the context handle of the re-overlapped context.

 

lParam

Contains the current context status flags.

Comments

Tablet managers can handle this message to keep track of context overlap re­quests by applications.

 

Applications can handle this message to find out when their context is obscured by another context.

6.2.5.   WT_PROXIMITY

Description

The WT_PROXIMITY message is posted to the owning window and any manager windows when the cursor enters or leaves context prox­imity.

 

Parameter

Description

 

wParam

Contains the handle of the context that the cursor is entering or leav­ing.

 

lParam

The low-order word is non-zero when the cursor is entering the context and zero when it is leaving the context. The high-order word is non-zero when the cursor is leaving or entering hard­ware proximity.

Comments

Proximity events are handled separately from regular tablet events. Applications will receive proximity messages even if they haven't requested event messages.

 

6.3.   Information Change Messages

The messages described in this section provide information about changes to information items.

6.3.    

6.3.1.   WT_INFOCHANGE (1.4 modified)

Description

The WT_INFOCHANGE message is sent to all man­ager and context-owning win­dows when the number of connected tablets has changed

 

 

Parameter

Description

 

wParam

Contains the manager handle of the tablet manager that changed the information, or zero if the change was reported through hard­ware.

 

lParam

Contains category and index numbers for the changed informa­tion. The low-order word contains the category number; the high-order word contains the index number.

Comments

Applications can respond to capability changes by handling this message. Simple applications may want to prompt the user to close and restart them. The most basic applica­tions that use the default context should not need to take any action.

 

Tablet managers should handle this message to react to hardware configuration changes or changes by other managers (in implementations that allow multiple tablet managers).

 

7.      Data Reference

The data types in the following list are keywords that define the size and meaning of parameters and re­turn values associated with tablet interface functions and messages. This list contains fixed-point arith­metic types, pointer types, bit field types, handles, and callback function prototypes. The fixed-point type names begin with the FIX prefix. The pointer-type names begin with either a P prefix ( for short pointers) or an LP prefix (for long pointers). Bit field types contain commonly used sets of bits used to specify vari­ous conditions. The callback function prototypes use the WT prefix and the PROC suffix; they define the attributes, arguments and return types of application-defined callback func­tions. Handles provide access to resources managed internally by the tablet interface. The tablet inter­face data types are defined in the fol­lowing list.

7.1.   Common Data Types (1.1 modified, 1.4 modified)

The data types in the following list are keywords that define the size and meaning of parameters and re­turn values associated with tablet interface functions and messages. This list contains fixed-point arith­metic types, pointer types, bit field types, handles, and callback function prototypes. The fixed-point type names begin with the FIX prefix. The pointer-type names begin with either a P prefix ( for short pointers) or an LP prefix (for long pointers). Bit field types contain commonly used sets of bits used to specify vari­ous conditions. The callback function prototypes use the WT prefix and the PROC suffix; they define the attributes, arguments and return types of application-defined callback func­tions. Handles provide access to resources managed internally by the tablet interface. The tablet inter­face data types are defined in the fol­lowing list.

Table 7.1. Common Data Types

Type

Definition

FIX32

A 32-bit fixed-point arithmetic type, with the radix point between the two words. Thus, the type contains 16 bits to the left of the radix point and 16 bits to the right of it.

HMGR

Handle for tablet manager. It is a value that allows applications to use tablet-management functions. When multiple manager applications are allowed, it also identifies the managers to the tablet interface.

HCTX

Handle to a tablet context. It is an index to the tablet interface's con­text ta­bles.

LPLOGCONTEXT

Long pointer to a LOGCONTEXT data structure.

WTPKT

Bit field that specifies the various optional data items available in event pack­ets. It is a 32-bit field. The event packet field flags can be combined using the bitwise OR operator. The WTPKT bit field can contain the values listed be­low, as well as any defined for extension data items.

 

Value

Meaning

 

PK_CONTEXT

Specifies the handle of the reporting con­text.

 

PK_STATUS

Specifies status information.

 

PK_TIME

Specifies the time at which the packet was generated.

 

PK_CHANGED

Specifies which packet data items have changed since the last packet.

 

PK_SERIAL_NUMBER

Specifies the packet serial number.

 

PK_CURSOR

Specifies the cursor that generated the packet.

 

PK_BUTTONS

Specifies packet button information.

 

PK_X, PK_Y, PK_Z

Specify packet x, y, and z axis data, re­spectively.

 

PK_NORMAL_PRESSURE, PK_TANGENT_PRESSURE

Specify tip-button or normal-to-surface pressure data, and barrel-button or tan­gent-to-surface pressure data, re­spec­tively.

 

PK_ORIENTATION

Specifies cursor orientation informa­tion.

 

PK_ROTATION  (1.1)

Specifies cursor rotation informa­tion.

WTENUMPROC

Specifies the prototype of a context enumeration callback:

BOOL (WINAPI * WTENUMPROC)(HCTX, LPARAM);

WTCONFIGPROC

Specifies the prototype of a context configuration callback:

BOOL (WINAPI * WTCONFIGPROC)(HCTX, HWND);

 

7.2.   Information Data Structures

This section describes the data formats returned by the WTInfo function and the cate­gory and index val­ues used when calling the function. Some of the common data return formats are de­scribed first, fol­lowed by a complete listing of all the category and index values.

7.    

7.1.    

7.2.    

7.2.1.   AXIS

Range and Resolution Descriptor

Description

The AXIS data structure defines the range and resolution for many of the packet data items.

 

typedef struct tagAXIS {

LONG    axMin;
LONG    axMax;
UINT      axUnits;
FIX32     axResolution;

} AXIS;

 

The AXIS data structure has the following fields:

 

Field

Description

 

axMin

Specifies the minimum value of the data item in the tablet's na­tive coordinates.

 

axMax

Specifies the maximum value of the data item in the tablet's na­tive coordinates.

 

axUnits

Indicates the units used in calculating the resolution for the data item.

 

axResolution

Is a fixed-point number giving the number of data item in­cre­ments per physical unit.

Comments

This structure is used to construct return data for the WTInfo function. In par­ticu­lar, it is used within the WTI_DEVICES category for returning the capabili­ties of the device with re­spect to each axis or packet data item.

See Also

The WTInfo function in section 5.1.1 and the values used for specifying units in table 7.2.

Table 7.2. Physical Unit Specifiers

TU_NONE

Specifies that no resolution in terms of physical units is given.

TU_INCHES

Specifies that resolution is given with respect to inches.

TU_CENTIMETERS

Specifies that resolution is given with respect to centimeters.

TU_CIRCLE

Specifies that resolution is given with respect to one full revolution of arc. For example, if a data item returns degrees, the resolution would be 360 and the units would be TU_CIRCLE. If the item were in radians, the resolution would be 6.28318 (to FIX32’s precision) and the units would be TU_CIRCLE.

7.2.2.   Information Categories and Indices (1.1 modified)

The categories, indices, and returned data formats are listed below. The WTI_DEFCONTEXT, WTI_DEFSYSCTX, WTI_DDCTXS, and WTI_DSCTXS categories share the same set of indices; they refer to the default digitizing and sys­tem contexts, respectively. The WTI_DEVICES, WTI_CURSORS and WTI_EXTENSIONS cate­gories are multiplexed; the category names ac­tu­ally refer to the first of sev­eral consecutive categories.

Table 7.3. Category Definitions

Category

Description

WTI_INTERFACE

Contains global interface identification and capability information.

WTI_STATUS

Contains current interface resource usage statistics.

WTI_DEFCONTEXT

Contains the current default digitizing logical context.

WTI_DEFSYSCTX

Contains the current default system logical context.

WTI_DEVICES

Each contains capability and status information for a device.

WTI_CURSORS

Each contains capability and status information for a cursor type.

WTI_EXTENSIONS

Each contains descriptive information and defaults for an extension.

WTI_DDCTXS (1.1)

Each contains the current default digitizing logical context for the corre­sponding device.

WTI_DSCTXS (1.1)

Each contains the current default system logical context for the correspond­ing device.

Table 7.4. WTI_INTERFACE Index Definitions

Index

Type/Description

IFC_WINTABID

TCHAR[]  Returns a copy of the null-terminated tablet hardware identifica­tion string in the user buffer. This string should include make, model, and revi­sion information in user-readable format.

IFC_SPECVERSION

WORD  Returns the specification version number. The high-order byte contains the major version number; the low-order byte contains the minor version number.

IFC_IMPLVERSION

WORD  Returns the implementation version number. The high-order byte contains the major version number; the low-order byte contains the minor version number.

IFC_NDEVICES

UINT  Returns the number of devices supported.

IFC_NCURSORS

UINT  Returns the total number of cursor types supported.

IFC_NCONTEXTS

UINT  Returns the number of contexts supported.

IFC_CTXOPTIONS

UINT  Returns flags indicating which context options are supported (see ta­ble 7.11).

IFC_CTXSAVESIZE

UINT  Returns the size of the save information returned from WTSave.

IFC_NEXTENSIONS

UINT  Returns the number of extension data items supported.

IFC_NMANAGERS

UINT  Returns the number of manager handles supported.

Table 7.5. WTI_STATUS Index Definitions

Index

Type/Description

STA_CONTEXTS

UINT  Returns the number of contexts currently open.

STA_SYSCTXS

UINT  Returns the number of system contexts currently open.

STA_PKTRATE

UINT  Returns the maximum packet report rate currently being re­ceived by any context, in Hertz.

STA_PKTDATA

WTPKT  Returns a mask indicating which packet data items are re­quested by at least one context.

STA_MANAGERS

UINT  Returns the number of manager handles currently open.

STA_SYSTEM

BOOL  Returns a non-zero value if system pointing is available to the whole screen; zero otherwise.

STA_BUTTONUSE

DWORD  Returns a button mask indicating the logical buttons whose events are requested by at least one context.

STA_SYSBTNUSE

DWORD  Returns a button mask indicating which logical buttons are as­signed a system button function by the current cursor's system button map.

Table 7.6. WTI_DEFCONTEXT, WTI_DEFSYSCTX, WTI_DDCTXS (1.1), and WTI_DSCTXS (1.1) Index Definitions

Index

Type/Description

CTX_NAME

TCHAR[]  Returns a 40 character array containing the default name. The name may occupy zero to 39 characters; the remainder of the array is padded with zeroes.

CTX_OPTIONS

UINT  Returns option flags. For the default digitizing context, CXO_MARGIN and CXO_MGNINSIDE are allowed. For the default system context, CXO_SYSTEM is required; CXO_PEN, CXO_MARGIN, and CXO_MGNINSIDE are allowed. See table 7.11 for more information.

CTX_STATUS

UINT  Returns zero.

CTX_LOCKS

UINT  Returns which attributes of the default context are locked. See table 7.13 for more information.

CTX_MSGBASE

UINT  Returns the value WT_DEFBASE. See the message descriptions in section 6.

CTX_DEVICE

UINT  Returns the default device.  If this value is -1, then it also known as a "virtual device".

CTX_PKTRATE

UINT  Returns the default context packet report rate, in Hertz.

CTX_PKTDATA

WTPKT  Returns which optional data items will be in packets returned from the context. For the default digitizing context, this field must at least indicate buttons, x, and y data.

CTX_PKTMODE

WTPKT  Returns whether the packet data items will be returned in abso­lute or relative mode.

CTX_MOVEMASK

WTPKT  Returns which packet data items can generate motion events in the context.

CTX_BTNDNMASK

DWORD  Returns the buttons for which button press events will be proc­essed in the context. The default context must at least select button press events for one button.

CTX_BTNUPMASK

DWORD  Returns the buttons for which button release events will be proc­essed in the context.

CTX_INORGX, CTX_INORGY, CTX_INORGZ

LONG  Each returns the origin of the context's input area in the tablet's na­tive coordinates, along the x, y, and z axes, respectively.

CTX_INEXTX, CTX_INEXTY, CTX_INEXTZ

LONG  Each returns the extent of the context's input area in the tablet's na­tive coordinates, along the x, y, and z axes, respectively.

CTX_OUTORGX, CTX_OUTORGY, CTX_OUTORGZ

LONG  Each returns the origin of the context's output coordinate space in context output coordinates, along the x, y, and z axes, respectively.

CTX_OUTEXTX, CTX_OUTEXTY, CTX_OUTEXTZ

LONG  Each returns the extent of the context's output coordinate space in context output coordinates, along the x, y, and z axes, respectively.

CTX_SENSX, CTX_SENSY, CTX_SENSZ

FIX32  Each returns the relative-mode sensitivity factor, along the x, y, and z axes, respectively.

CTX_SYSMODE

BOOL  Returns the default system cursor tracking mode.

CTX_SYSORGX, CTX_SYSORGY

int  Each returns 0.

CTX_SYSEXTX, CTX_SYSEXTY

int  Each returns the current screen display size in pixels, in the x and y di­rections, respectively.

CTX_SYSSENSX, CTX_SYSSENSY

FIX32  Each returns the system cursor relative-mode sensitivity factor, in the x and y directions, respectively.

Table 7.7. WTI_DEVICES Index Definitions

Index

Type/Description

DVC_NAME

TCHAR[]  Returns a displayable null- terminated string describing the de­vice, manufacturer, and revision level.

DVC_HARDWARE

UINT  Returns flags indicating hardware and driver capabilities, as de­fined below:

 

Value

Meaning

 

HWC_INTEGRATED

Indicates that the display and digitizer share the same surface.

 

HWC_TOUCH

Indicates that the cursor must be in physical contact with the device to report position.

 

HWC_HARDPROX

Indicates that device can generate events when the cursor is entering and leaving the physical detection range.

 

HWC_PHYSID_CURSORS (1.1)

Indicates that device can uniquely iden­tify the active cursor in hardware.

DVC_NCSRTYPES

UINT  Returns the number of supported cursor types.

DVC_FIRSTCSR

UINT  Returns the first cursor type number for the device.

DVC_PKTRATE

UINT  Returns the maximum packet report rate in Hertz.

DVC_PKTDATA

WTPKT  Returns a bit mask indicating which packet data items are al­ways available.

DVC_PKTMODE

WTPKT  Returns a bit mask indicating which packet data items are physically relative, i.e., items for which the hardware can only report change, not absolute measurement.

DVC_CSRDATA

WTPKT  Returns a bit mask indicating which packet data items are only available when certain cursors are connected. The individual cursor descriptions must be consulted to determine which cursors return which data.

DVC_XMARGIN, DVC_YMARGIN, DVC_ZMARGIN

int  Each returns the size of tablet context margins in tablet native co­ordinates, in the x, y, and z directions, respectively.

DVC_X, DVC_Y, DVC_Z

AXIS  Each returns the tablet's range and resolution capabilities, in the x, y, and z axes, respectively.

DVC_NPRESSURE, DVC_TPRESSURE

AXIS  Each returns the tablet's range and resolution capabilities, for the normal and tangential pressure inputs, respectively.

DVC_ORIENTATION

AXIS[]  Returns a 3-element array describing the tablet's orientation range and resolution capabilities.

DVC_ROTATION  (1.1)

AXIS[]  Returns a 3-element array describing the tablet's rotation range and resolution capabilities.

DVC_PNPID  (1.1)

TCHAR[]  Returns a null-terminated string containing the device’s Plug and Play ID.

Table 7.8. WTI_CURSORS Index Definitions

Index

Type/Description

CSR_NAME

TCHAR[]  Returns a displayable zero-terminated string containing the name of the cursor.

CSR_ACTIVE

BOOL  Returns whether the cursor is currently connected.

CSR_PKTDATA

WTPKT  Returns a bit mask indicating the packet data items sup­ported when this cursor is connected.

CSR_BUTTONS

BYTE  Returns the number of buttons on this cursor.

CSR_BUTTONBITS

BYTE  Returns the number of bits of raw button data returned by the hardware.

CSR_BTNNAMES

TCHAR[]  Returns a list of zero-terminated strings containing the names of the cursor's buttons. The number of names in the list is the same as the number of buttons on the cursor. The names are sepa­rated by a single zero character; the list is terminated by two zero characters.

CSR_BUTTONMAP

BYTE[]  Returns a 32 byte array of logical button numbers, one for each physical button.

CSR_SYSBTNMAP

BYTE[]  Returns a 32 byte array of button action codes, one for each logical button.

CSR_NPBUTTON

BYTE  Returns the physical button number of the button that is con­trolled by normal pressure.

CSR_NPBTNMARKS

UINT[]  Returns an array of two UINTs, specifying the button marks for the normal pressure button. The first UINT contains the release mark; the second contains the press mark.

CSR_NPRESPONSE

UINT[]  Returns an array of UINTs describing the pressure response curve for normal pressure.

CSR_TPBUTTON

BYTE  Returns the physical button number of the button that is con­trolled by tangential pressure.

CSR_TPBTNMARKS

UINT[]  Returns an array of two UINTs, specifying the button marks for the tangential pressure button. The first UINT contains the release mark; the second contains the press mark.

CSR_TPRESPONSE

UINT[]  Returns an array of UINTs describing the pressure response curve for tangential pressure.

CSR_PHYSID (1.1)

DWORD  Returns a manufacturer-specific physical identifier for the cursor. This value will distinguish the physical cursor from others on the same device. This physical identifier allows applications to bind func­tions to specific physical cursors, even if category numbers change and multiple, otherwise identical, physical cursors are present.

CSR_MODE (1.1)

UINT  Returns the cursor mode number of this cursor type, if this cursor type has the CRC_MULTIMODE capability.

CSR_MINPKTDATA (1.1)

UINT  Returns the minimum set of data available from a physical cursor in this cursor type, if this cursor type has the CRC_AGGREGATE ca­pability.

CSR_MINBUTTONS (1.1)

UINT  Returns the minimum number of buttons of physical cursors in the cursor type, if this cursor type has the CRC_AGGREGATE capabil­ity.         

CSR_CAPABILITIES  (1.1)

UINT  Returns flags indicating cursor capabilities, as defined below:

 

Value

Meaning

 

CRC_MULTIMODE

Indicates this cursor type describes one of several modes of a single physical cursor. Consecutive cursor type categories de­scribe the modes; the CSR_MODE data item gives the mode number of each cur­sor type.

 

CRC_AGGREGATE

Indicates this cursor type describes sev­eral physical cursors that cannot be dis­tinguished by software.

 

CRC_INVERT

Indicates this cursor type describes the physical cursor in its inverted orienta­tion; the previous consecutive cursor type category describes the normal orienta­tion.

Table 7.9. WTI_EXTENSIONS Index Definitions

Index

Type/Description

EXT_NAME

TCHAR[]  Returns a unique, null-terminated string describing the ex­tension.

EXT_TAG

UINT  Returns a unique identifier for the extension.

EXT_MASK

WTPKT  Returns a mask that can be bitwise OR'ed with WTPKT-type vari­ables to select the extension.

EXT_SIZE

UINT[]  Returns an array of two UINTs specifying the extension's size within a packet (in bytes). The first is for absolute mode; the second is for relative mode.

EXT_AXES

AXIS[]  Returns an array of axis descriptions, as needed for the exten­sion.

EXT_DEFAULT

BYTE[]  Returns the current global default data, as needed for the ex­tension. This data is modified via the WTMgrExt function.

EXT_DEFCONTEXT, EXT_DEFSYSCTX

BYTE[]  Each returns the current default context-specific data, as needed for the extension. The indices identify the digitizing- and sys­tem-context defaults, respectively.

EXT_CURSORS

BYTE[]  Is the first of one or more consecutive indices, one per cursor type. Each returns the current default cursor-specific data, as need for the extension. This data is modified via the WTMgrCsrExt function.

Table 7.10. System Button Assignment Values

The values defined below indicate emulations of mouse button actions. Three different types of ac­tions are defined for each mouse button: clicking, double-clicking, and dragging. Clicking means the button be­haves exactly like the corresponding mouse button. Double-clicking means the pressing the button once emulates a double-click of the mouse button. Dragging means that pressing the button tog­gles the state of the emulated mouse button: one click to press, one to release.

Value

Meaning

SBN_NONE

no system button actions.

SBN_LCLICK, SBN_LDBLCLICK, SBN_LDRAG

left button click, double-click, and drag, respectively.

SBN_RCLICK, SBN_RDBLCLICK, SBN_RDRAG

right button click, double-click, and drag, respectively.

SBN_MCLICK, SBN_MDBLCLICK, SBN_MDRAG

middle button click, double-click, and drag, respectively.

In implementations that support Pen Windows, the values defined below assign pen-button actions to tab­let cursor buttons. They may be used alone or may be combined (using the bitwise OR operator) with one of the values defined above.

Value

Meaning

SBN_PTCLICK, SBN_PTDBLCLICK, SBN_PTDRAG

pen tip click (tap), double-click (double-tap), and drag (stroke), respec­tively.

SBN_PNCLICK, SBN_PNDBLCLICK, SBN_PNDRAG

inverted pen tip click, double-click, and drag, respectively.

SBN_P1CLICK, SBN_P1DBLCLICK, SBN_P1DRAG

barrel button 1 click, double-click, and drag, respectively.

SBN_P2CLICK, SBN_P2DBLCLICK, SBN_P2DRAG

barrel button 2 click, double-click, and drag, respectively.

SBN_P3CLICK, SBN_P3DBLCLICK, SBN_P3DRAG

barrel button 3 click, double-click, and drag, respectively.

 


7.3.   Context Data Structures

7.3. 

This section describes the LOGCONTEXT data structure, which is used when opening and manipulating contexts. This structure contains everything applications and tablet managers need to know about a context. To simplify context manipulations, applications may want to take advantage of the default context specification available via the WTInfo function.

7.3.1.   LOGCONTEXT (1.1 modified)

The LOGCONTEXT data structure contains the attributes necessary to specify a tablet context.

#define LC_NAMELEN 40

typedef struct tagLOGCONTEXT {

TCHAR       lcName[LC_NAMELEN];

UINT        lcOptions;

UINT        lcStatus;

UINT        lcLocks;

UINT        lcMsgBase;

UINT        lcDevice;

UINT        lcPktRate;

WTPKT       lcPktData;

WTPKT       lcPktMode;

WTPKT       lcMoveMask;

DWORD       lcBtnDnMask;

DWORD       lcBtnUpMask;

LONG        lcInOrgX;

LONG        lcInOrgY;

LONG        lcInOrgZ;

LONG        lcInExtX;

LONG        lcInExtY;

LONG        lcInExtZ;

LONG        lcOutOrgX;

LONG        lcOutOrgY;

LONG        lcOutOrgZ;

LONG        lcOutExtX;

LONG        lcOutExtY;

LONG        lcOutExtZ;

FIX32       lcSensX;

FIX32       lcSensY;

FIX32       lcSensZ;

BOOL        lcSysMode;

int         lcSysOrgX;

int         lcSysOrgY;

int         lcSysExtX;

int         lcSysExtY;

FIX32       lcSysSensX;

FIX32       lcSysSensY;

} LOGCONTEXT;

 

Description

The LOGCONTEXT data structure has the following fields:

 

Field

Description

 

lcName

Contains a zero-terminated context name string.

 

lcOptions

Specifies options for the context. These options can be com­bined by using the bitwise OR operator. The lcOptions field can be any combination of the values defined in table 7.11. Specify­ing options that are unsupported in a particular im­plementation will cause WTOpen to fail.

 

lcStatus

Specifies current status conditions for the context. These condi­tions can be combined by using the bitwise OR opera­tor. The lcStatus field can be any combination of the values defined in table 7.12.

 

lcLocks

Specifies which attributes of the context the application wishes to be locked. Lock conditions specify attributes of the context that cannot be changed once the context has been opened (calls to WTConfig will have no effect on the locked attributes). The lock conditions can be combined by using the bitwise OR opera­tor. The lcLocks field can be any combina­tion of the values de­fined in table 7.13. Locks can only be changed by the task or process that owns the context.

 

lcMsgBase

Specifies the range of message numbers that will be used for re­porting the activity of the context. See the message descrip­tions in section 6.

 

lcDevice

Specifies the device whose input the context processes.

 

lcPktRate

Specifies the desired packet report rate in Hertz. Once the con­text is opened, this field will contain the actual report rate.

 

lcPktData

Specifies which optional data items will be in packets re­turned from the context. Requesting unsupported data items will cause WTOpen to fail.

 

lcPktMode

Specifies whether the packet data items will be returned in abso­lute or relative mode. If the item's bit is set in this field, the item will be returned in relative mode. Bits in this field for items not selected in the lcPktData field will be ignored. Bits for data items that only allow one mode (such as the serial number) will also be ignored.

 

lcMoveMask

Specifies which packet data items can generate move events in the context. Bits for items that are not part of the packet def­ini­tion in the lcPktData field will be ignored. The bits for but­tons, time stamp, and the serial number will also be ig­nored. In the case of overlapping contexts, movement events for data items not selected in this field may be processed by underlying con­texts.

 

lcBtnDnMask

Specifies the buttons for which button press events will be proc­essed in the context. In the case of overlapping contexts, button press events for buttons that are not selected in this field may be processed by underlying contexts.

 

lcBtnUpMask

Specifies the buttons for which button release events will be processed in the context. In the case of overlapping contexts, button release events for buttons that are not selected in this field may be processed by underlying contexts.

If both press and re­lease events are selected for a button (see the lcBtnDnMask field above), then the interface will cause the context to implic­itly capture all tablet events while the button is down. In this case, events occurring outside the context will be clipped to the context and processed as if they had occurred in the context. When the but­ton is released, the context will receive the button release event, and then event processing will return to normal.

 

lcInOrgX, lcInOrgY, lcInOrgZ

Each specifies the origin of the context's input area in the tab­let's native coordinates, along the x, y, and z axes, respec­tively. Each will be clipped to the tablet native coordinate space when the context is opened or modified.

 

lcInExtX, lcInExtY, lcInExtZ

Each specifies the extent of the context's input area in the tab­let's native coordinates, along the x, y, and z axes, respec­tively. Each will be clipped to the tablet native coordinate space when the context is opened or modified.

 

lcOutOrgX, lcOutOrgY, lcOutOrgZ

Each specifies the origin of the context's output area in con­text output coordinates, along the x, y, and z axes, respec­tively. Each is used in coordinate scaling for absolute mode only.

 

lcOutExtX, lcOutExtY, lcOutExtZ

Each specifies the extent of the context's output area in con­text output coordinates, along the x, y, and z axes, respec­tively. Each is used in coordinate scaling for absolute mode only.

 

lcSensX, lcSensY, lcSensZ

Each specifies the relative-mode sensitivity factor for the x, y, and z axes, respectively.

 

lcSysMode

Specifies the system cursor tracking mode. Zero specifies abso­lute; non-zero means relative.

 

lcSysOrgX, lcSysOrgY

Together specify the origin of the screen mapping area for sys­tem cursor tracking, in screen coordinates.

 

lcSysExtX, lcSysExtY

Together specify the extent of the screen mapping area for sys­tem cursor tracking, in screen coordinates.

 

lcSysSensX, lcSysSensY

Each specifies the system-cursor relative-mode sensitivity factor for the x and y axes, respectively.

Comments

The LOGCONTEXT structure determines what events an application will get, how they will be processed, and how they will be delivered to the application or to Win­dows it­self.

 

Tablet contexts reflect the tension between application control of input data and user control of workstation ergonomics. Some attributes of contexts are con­trolled by the user, others by the application. The notion of locks allows appli­cations to control some of the attributes that are normally controlled by the user. The user can always control the origin of a tablet context's input area (its physical location on the tablet). The lockable attributes are controlled by either the user or the application, at the application's discretion. Everything else is controlled by the application. This arrangement allows programmers to control the complexity of their applications, while allowing users to arrange their work­stations in a comfortable, efficient man­ner.

 

Tablet contexts control scaling of input points. The scaling works in a manner analogous to the scaling features provided in Windows' GDI interface. The tablet input area is mapped to the output coordinate space using transformation equations similar to the equations for the GDI's MM_ANISOTROPIC scaling mode. In other words, the entire input context is mapped to the entire output context. The scaling transformation can change the unit size, the origin or offset of the returned coordi­nates, and the direction of the axes, just as in GDI scaling.

 

System cursor scaling and tracking can be controlled independently from tablet packet scaling and tracking. Thus, system contexts may be use polling to receive auxiliary tablet data in any desired form. Absolute-mode system cursor contexts can be mapped to a sub-context of the screen, such as an application drawing window. This feature allows absolute mode data entry and scaling of drawings with existing, unmodified applications.

 

The exact scaling equations for each axis are as follows.

 

Let:

 

In = the input value for the axis.

Out = the output value for the axis

InOrg = the input origin (such as lcInOrgX) for the axis

InExt = the input extent (such as lcInExtX) for the axis

OutOrg = the output origin (such as lcOutOrgX or lcSysOrgX) for

       the axis

OutExt = the output extent (such as lcOutExtX or lcSysExtX) for

       the axis

sign() returns 1 if the input value is greater than or equal to

       0, -1 otherwise.

abs() returns the absolute value of its input.

 

if sign(OutExt) == sign(InExt)

       Out = ((In - InOrg) * abs(OutExt) / abs(InExt)) + OutOrg

else

       Out = ((abs(InExt) - (In - InOrg)) * abs(OutExt) /

              abs(InExt)) + OutOrg

 

The move mask and button masks together determine what kinds of events will be processed by the context.

See Also

The context option values in table 7.11, the context status values in table 7.12, and the context lock values in table 7.13.

Table 7.11. Context Option Values

Value

Meaning

CXO_SYSTEM

Specifies that the context is a system cursor context.

CXO_PEN

Specifies that the context is a Pen Windows context, if Pen Windows is in­stalled. The context is also a system cursor context; specifying CXO_PEN implies CXO_SYSTEM.

CXO_MESSAGES

Specifies that the context returns WT_PACKET messages to its owner.

CXO_MARGIN

Specifies that the input context on the tablet will have a margin. The margin is an area outside the specified input area where events will be mapped to the edge of the input area. This feature makes it easier to in­put points at the edge of the context.

CXO_MGNINSIDE

If the CXO_MARGIN bit is on, specifies that the margin will be inside the specified context. Thus, scaling will occur from a context slightly smaller than the specified input context to the output coordinate space.

CXO_CSRMESSAGES (1.1)

Specifies that the context returns WT_CSRCHANGE messages to it owner.

Table 7.12. Context Status Values

Value

Meaning

CXS_DISABLED

Specifies that the context has been disabled using the WTEnable function.

CXS_OBSCURED

Specifies that the context is at least partially obscured by an overlapping con­text that is higher in the context overlap order.

CXS_ONTOP

Specifies that the context is the topmost context in the context overlap order.

 

Table 7.13. Context Lock Condition Values

Value

Meaning

CXL_INSIZE

Specifies that the context's input size cannot be changed. When this value is not specified, the context's input extents in x, y, and z can be changed. NOTE: The context's origins in x, y, and z can always be changed.

CXL_INASPECT

Specifies that the context's input aspect ratio cannot be changed. When this value is specified, the context's size can be changed, but the ratios among x, y, and z extents will be kept as close to constant as pos­sible.

CXL_MARGIN

Specifies that the context's margin options cannot be changed. This value controls the locking of the CXO_MARGIN and CXO_MGNINSIDE option values.

CXL_SENSITIVITY

Specifies that the context's sensitivity settings for x, y, and z cannot be changed.

CXL_SYSOUT

If the context is a system cursor context, the value specifies that the sys­tem pointing control variables of the context cannot be changed.

 

 

7.4.   Event Data Structures

This section describes the data structures used to return events. The definitions include the family of vari­able data structures for packets, and related structures and constants.

7.4.    

7.4.1.   PACKET (1.1 modified)

Event Packet Data Structure

Description

The PACKET data structure is a flexible structure that contains tablet event infor­mation. Each of its fields is optional. The structure consists of a concatena­tion of the data items selected in the lcPktData field of the context that gener­ated the packet. The order of the data items is the same as the order of the cor­responding set bits in the field.

 

The pkButtons data item has different formats in absolute and relative modes, as determined by the PK_BUTTONS bit in the lcPktMode field of the context.

 

The example structure below illustrates the case where all of the defined bits in the lcPktData field are set and the lcPktMode field is clear (all items are in absolute mode).

 

typedef struct tagPACKET {

HCTX        pkContext;
UINT        pkStatus;
LONG        pkTime;
WTPKT       pkChanged;
UINT        pkSerialNumber;
UINT        pkCursor;
DWORD       pkButtons;
DWORD       pkX;
DWORD       pkY;
DWORD       pkZ;
UINT        pkNormalPressure;
UINT        pkTangentPressure;
ORIENTATION pkOrientation;

ROTATION    pkRotation;  /* 1.1 */

} PACKET;

 

The PACKET data structure has the following defined fields:

 

Field

Description

 

pkContext

Specifies the context that generated the event.

 

pkStatus

Specifies various status and error conditions. These con­ditions can be combined by using the bitwise OR opera­tor. The pkStatus field can be any combination of the values defined in table 7.14.

 

pkTime

In absolute mode, specifies the system time at which the event was posted. In relative mode, specifies the elapsed time in milliseconds since the last packet.

 

pkChanged

Specifies which of the included packet data items have changed since the previously posted event.

 

pkSerialNumber

Contains a serial number assigned to the packet by the context. Consecutive packets will have consecutive serial numbers.

 

pkCursor

Specifies which cursor type generated the packet.

 

pkButtons

In absolute mode, is a DWORD containing the current button state. In relative mode, is a DWORD whose low word contains a button number, and whose high word contains one of the following codes:

 

 

Value

Meaning

 

 

TBN_NONE

no change in button state.

 

 

TBN_UP

button was released.

 

 

TBN_DOWN

button was pressed.

 

pkX, pkY, pkZ

In absolute mode, each is a DWORD containing the scaled cursor location along the x, y, and z axes, re­spec­tively. In relative mode, each is a LONG contain­ing the scaled change in cursor position.

 

pkNormalPressure, pkTangentPressure

In absolute mode, each is a UINT containing the adjusted state of the normal and tangent pressures, respectively. In relative mode, each is an int containing the change in adjusted pressure state.

 

pkOrientation

Contains updated cursor orientation information. For de­tails, see the description of the ORIENTATION data structure in section 7.4.2.

 

pkRotation  (1.1)

Contains updated cursor rotation information. For de­tails, see the description of the ROTATION data struc­ture in section 7.4.3.

Comments

Extension data items are also concatenated onto PACKET data structures, when supported by the implementation, and selected by using the appropriate mask in the lcPktData context field. Extension items are concatenated after the standard data items, in increasing order of their unique tags (using unsigned comparison). Within an implementation, extension masks will be assigned in tag order. While the value of an extension's mask is not guaranteed to be the same across imple­mentations, the extension's tag (and thus the order of extensions within the PACKET structure) will always be the same.

See Also

The packet status values in table 7.14, the ORIENTATION structure in section 7.4.2, the ROTATION structure in section 7.4.3, the WTOpen function in section 5.1.2, LOGCONTEXT data structure in section 7.3.1, and the WTI_EXTENSIONS group of information categories in table 7.9.

 

Table 7.14. Packet Status Values

Value

Meaning

TPS_PROXIMITY

Specifies that the cursor is out of the context.

TPS_QUEUE_ERR

Specifies that the event queue for the context has overflowed.

TPS_MARGIN

Specifies that the cursor is in the margin of the context.

TPS_GRAB

Specifies that the cursor is out of the context, but that the context has grabbed input while waiting for a button release event.

TPS_INVERT (1.1)

Specifies that the cursor is in its inverted state.

 

7.4.2.   ORIENTATION

Cursor Orientation Descriptor

Description

The ORIENTATION data structure specifies the orientation of the cursor with re­spect to the tablet.

typedef struct tagORIENTATION {

int   orAzimuth;
int   orAltitude;
int   orTwist;

} ORIENTATION;

The ORIENTATION data structure has the following fields:

 

Field

Description

 

orAzimuth

Specifies the clockwise rotation of the cursor about the z axis through a full circular range.

 

orAltitude

Specifies the angle with the x-y plane through a signed, semicir­cular range.  Positive values specify an angle upward toward the positive z axis; negative values specify an angle downward toward the negative z axis.

 

orTwist

Specifies the clockwise rotation of the cursor about its own major axis.

Comments

Each cursor type will have a major axis and "normal orientation" defined for it, based on its physical characteristics.

See Also

The PACKET data structure definition in section 7.4.1.

 

7.4.3.   ROTATION (1.1)

Cursor Rotation Descriptor

Description

The ROTATION data structure specifies the Rotation of the cursor with re­spect to the tablet.

typedef struct tagROTATION {

int   roPitch;
int   roRoll;
int   roYaw;

} ROTATION;

The ROTATION data structure has the following fields:

 

Field

Description

 

roPitch

Specifies the pitch of the cursor.

 

roRoll

Specifies the roll of the cursor.

 

roYaw

Specifies the yaw of the cursor.

Comments

Each cursor type will have rotation semantics defined for it, based on its physical characteristics.

See Also

The PACKET data structure definition in section 7.4.1.

 

 

Appendix A.  Using PKTDEF.H

This appendix describes how to use the header file PKTDEF.H in C-language programs.

The program must first include WINTAB.H, since PKTDEF.H depends on definitions in WINTAB.H.

If the program will use just one packet format, the following steps are necessary before including PKTDEF.H. The program must define the PACKETDATA constant to indicate which packet data items to include, and the PACKETMODE constant to indicate which packet data items are in relative mode. Both constants should be combinations of WTPKT bits (the PK_* identifiers), combined with the bitwise OR operator. The generated structure typedef will be called PACKET. Use the PACKETDATA and PACKETMODE constants to fill in the lcPktData and lcPktMode fields of the LOGCONTEXT struc­ture. See example #1 below.

 

Example #1.-- single packet format

#include <wintab.h>

#define PACKETDATA   PK_X | PK_Y | PK_BUTTONS   /* x, y, buttons */

#define PACKETMODE   PK_BUTTONS                 /* buttons relative mode */

#include <pktdef.h>

...

       lc.lcPktData = PACKETDATA;

       lc.lcPktMode = PACKETMODE;

If the program uses multiple packet formats, PKTDEF.H can generate multiple packet structures with dif­ferent names, data items, and modes. The program will include PKTDEF.H once for each packet struc­ture. Before each PKTDEF.H inclusion, define a constant PACKETNAME. Its text value will be a prefix for this packet's parameters and names. Next define <name>PACKETDATA and <name>PACKETMODE, where <name> is the value of the PACKETNAME constant just defined. Fi­nally include PKTDEF.H to define a structure named <name>PACKET. See example #2 below.

 

Example #2. -- multiple formats

#include <wintab.h>

#define PACKETNAME         MOE

#define MOEPACKETDATA             PK_X | PK_Y | PK_BUTTONS   /* x, y, buttons */

#define MOEPACKETMODE             PK_BUTTONS                 /* buttons relative mode */

#include <pktdef.h>

#define PACKETNAME         LARRY

#define LARRYPACKETDATA    PK_Y | PK_Z | PK_BUTTONS   /* y, z, buttons */

#define LARRYPACKETMODE    PK_BUTTONS                 /* buttons relative mode */

#include <pktdef.h>

#define PACKETNAME         CURLY

#define CURLYPACKETDATA    PK_X | PK_Z | PK_BUTTONS   /* x, z, buttons */

#define CURLYPACKETMODE    PK_BUTTONS                 /* buttons relative mode */

#include <pktdef.h>

...

       lcMOE.lcPktData = MOEPACKETDATA;

       lcMOE.lcPktMode = MOEPACKETMODE;

...

       lcLARRY.lcPktData = LARRYPACKETDATA;

       lcLARRY.lcPktMode = LARRYPACKETMODE;

...

       lcCURLY.lcPktData = CURLYPACKETDATA;

       lcCURLY.lcPktMode = CURLYPACKETMODE;


 

Appendix B.  Extension Definitions (1.4 modified)

This appendix describes in more detail the programming interface for extensions. It also includes defini­tions of all currently defined extensions.

Table B.1. Current Defined Extensions (1.4 modified)

Name

Tag Constant Symbol

Tag Constant Value

Out of Bounds Tracking

WTX_OBT

0

Cursor Mask

WTX_CSRMASK

3

Extended Button Masks

WTX_XBTNMASK

4

Touch Strips

WTX_TOUCHSTRIP

6

Touch Rings

WTX_TOUCHRING

7

Express Keys

WTX_EXPKEYS2

8

 

Note (1.4 modified) - if a WTX_* value is not included in Table B.1, then it is not supported.

B.1.     Extensions Programming

Each extension has several parts to its interface. It has a unique identifying number called its tag. It has an information category, multiplexed under WTI_EXTENSIONS. Optionally, it may also define a packet data item, or respond to one or more of the functions WTExtGet, WTExtSet, WTMgrExt, or WTMgrCsrExt.

The header file WINTAB.H includes tag definitions for currently defined extensions. The tag identifiers have the prefix "WTX_".

Since not all Wintab implementations support all extensions, applications must detect extension support at run-time, using a function like the one shown below. The function takes an extension's tag, and returns its information category offset from WTI_EXTENSIONS.

 

UINT ScanExts(UINT wTag)

{

       UINT i;

       UINT wScanTag;

 

       /* scan for wTag's info category. */

       for (i = 0; WTInfo(WTI_EXTENSIONS + i, EXT_TAG, &wScanTag); i++) {

               if (wTag == wScanTag) {

                     /* return category offset from WTI_EXTENSIONS. */

                     return i;

              }

       }

       /* return error code. */

       return 0xFFFF;

}

Extensions that have a packet data item will not have the same WTPKT bit assigned across implementa­tions, so extension packet data items use a slightly different scheme for controlling PKTDEF.H. For each such extension, the application defines a constant PACKET<extension name> with a value of either PKEXT_ABSOLUTE or PKEXT_RELATIVE. In the following example, the application adds the packet data item for the extension "XFOO".

 

#include <wintab.h>

#define PACKETDATA   PK_X | PK_Y | PK_BUTTONS   /* x, y, buttons */

#define PACKETMODE   PK_BUTTONS                 /* buttons relative mode */

#define PACKETXFOO   PKEXT_ABSOLUTE                    /* XFOO absolute mode */

#include <pktdef.h>

The application should then detect if XFOO is supported at run-time, and retrieve its WTPKT bit mask from XFOO's EXT_MASK information item.

Extensions Programming Notes

NOTE: It is recommended that applications remove their overrides when the application's main window is no longer active (use WM_ACTIVATE). Extension overrides take effect across the entire system; if an application leaves its overrides in place, that control will not function correctly in other applications.

When an extension event occurs, an extension packet is created and queued to the context. If the application requested messages then a WT_PACKETEXT message is sent to the application. This message is identical to the WT_PACKET message except for the queue. The application should call the WTPacket function with the context provided and a PACKETEXT will be returned. This packet contains an EXTENSIONBASE data structure as well as any other structures the application requested at PKTDEF.h include time.

 

B.2.     Out of Bounds Tracking

The Wintab Out of Bounds Tracking (OBT) extension enables cursor tracking in areas not covered by any active tablet context. Normally, when the cursor moves outside all active contexts, Wintab event activity ceases, until the cursor again enters some context. Wintab simply discards such out of bounds events. With OBT enabled, Wintab delivers out of bounds events to some context, usually the one the cursor most recently left. The receiving context clips the event into its coordinate range. The user usually sees the cur­sor moving along the edge of the screen, or some window, as when a mouse user tries to roll the screen cursor off the edge of the screen.

The OBT logic routes unclaimed events by several rules. Only contexts that capture motion events (i.e., their logical context lcMoveMask field has the PK_X, PK_Y, or PK_Z bits set) are eligible to receive out-of-bounds events. Whenever an eligible context processes an event, it becomes the current OBT context. When an out-of-bounds event takes place, the current OBT context, if any, receives it. There is no current OBT context at system startup, or when the current OBT context is closed or disabled. In such situations, an out-of-bounds event goes to the first eligible context in the context stacking order.

OBT is very similar to the margin feature controlled by the CXO_MARGIN and CXO_MGNINSIDE con­text options. In fact, to applications, out-of-bounds events are indistinguishable from margin events; both will have the TPS_MARGIN flag set in their packet's pkStatus field.

OBT Programming

The OBT extension supports enabling or disabling OBT behavior on a per-device basis. Any Wintab aware program can detect OBT support and read its current state. Wintab manager programs can turn OBT on or off for any or all devices. OBT uses the extension tag value zero. Updated versions of WINTAB.H define the constant WTX_OBT as zero.

Information Category

The OBT Info category implements only the EXT_NAME, EXT_TAG, and EXT_DEFAULT indices. Using the other the indices in the category will cause WTInfo to return zero. The size of the EXT_DEFAULT data depends on the number of currently installed Wintab devices. Applications should use either the WTInfo function's return value for EXT_DEFAULT, or the number of devices indicated in the IFC_NDEVICES information item to determine the appropriate buffer size.

 

Index

Value

EXT_NAME

TCHAR[] the null-terminated string "Out of Bounds Tracking"

EXT_TAG

UINT the tag value zero

EXT_DEFAULT

BOOL[] an array of flags, one per device, that are non-zero if OBT is enabled for the corresponding device

Turning OBT On and Off

A Wintab manager program can turn OBT on and off using the WTMgrExt function. The passed data buffer has the same format as the EXT_DEFAULT information item.

B.5.     Cursor Mask

The Wintab Cursor Mask (CSRMASK) extension allows contexts to select input based on the cursor type. Such selection supports easy assignment of functionality to specific cursors, particularly on devices that support multiple active cursors.

CSRMASK Programming

There are three main steps to using CSRMASK: detecting CSRMASK support at run-time, creating a context, and modifying the context’s cursor mask using the functions WTExtGet and WTExtSet. Appli­cations supporting CSRMASK should use updated version of WINTAB.H with the tag constant WTX_CSRMASK (defined as 3). See also the example program CSRMASK in the Wintab Programmer's Kit.

Detect CSRMASK by scanning the WTI_EXTENSIONS information categories for one having the WTX_CSRMASK tag. If none is found, the CSRMASK extension is not supported and the application should not attempt to use CSRMASK. If CSRMASK is supported, the application should use the WTOpen function with the enable flag argument set to FALSE, set the desired CSRMASK value using the function WTExtSet, and finally enable the context with WTEnable.

The cursor mask data is 16-byte bitmap, in which each bit controls input selection for a corresponding cursor id. Bits 0 to 7 of byte 0 correspond to cursor ids 0 to 7, bits 0 to 7 of byte 1 correspond to cursor ids 8 to 15, and so on. A value of 1 in the bit means the context will process input from the cursor, a value of  0 means the context will ignore that cursor.

Note that in multiple-device configurations, the cursor ids of the device in question may not start at zero. The first cursor id of a given device is available from the DVC_FIRSTCSR item of the device information category.  Also, note that cursor ids are not guaranteed to remain the same from session to session, if other devices or cursor types are installed or removed. Persistent functional bindings on cursor types should use the device name (DVC_NAME) and physical cursor id (CSR_PHYSID) to guarantee binding stability between sessions.

Information Category

The CSRMASK information category implements only the items listed below.

Index

Value

EXT_NAME

TCHAR[]  the null-terminated string "Cursor Mask"

EXT_TAG

UINT the tag value three.

EXT_DEFCONTEXT

BYTE[16] the default cursor mask; all bits set to one.

EXT_DEFSYSCTX

BYTE[16] the default cursor mask; all bits set to one.

 

B.6.     Extended Button Masks

The Wintab Extended Button Masks (XBTNMASK) extension allows contexts to fully select input of up to 256 buttons. This supports locator devices with great numbers of buttons.

XBTNMASK Programming

There are three main steps to using XBTNMASK: detecting XBTNMASK support at run-time, creating a context, and modifying the context’s cursor mask using the functions WTExtGet and WTExtSet. Appli­cations supporting XBTNMASK should use updated version of WINTAB.H with the tag constant WTX_XBTNMASK (defined as 4).

Detect XBTNMASK by scanning the WTI_EXTENSIONS information categories for one having the WTX_XBTNMASK tag. If none is found, the XBTNMASK extension is not supported and the applica­tion should not attempt to use XBTNMASK. If XBTNMASK is supported, the application should use the WTOpen function with the enable flag argument set to FALSE, set the desired XBTNMASK value using the function WTExtSet, and finally enable the context with WTEnable.

The button mask data structure consists of two 32-byte bitmaps, in which each bit controls input selection for a corresponding button. Bits 0 to 7 of byte 0 correspond to buttons 0 to 7, bits 0 to 7 of byte 1 corre­spond to buttons 8 to 15, and so on. A value of 1 in the bit means the context will process input from the button, a value of  0 means the context will ignore that button. The first 32-byte map controls button down events; the second controls button up events. The button mask data structure definition follows.

 

typedef struct tagXBTNMASK {

       BYTE xBtnDnMask[32];

       BYTE xBtnUpMask[32];

} XBTNMASK;

These extended button masks extend the button masks in the logical context structure, but their behavior is otherwise identical to that described for lcBtnDnMask and lcBtnUpMask. Conflicts between the val­ues of  the logical context masks and the extension masks will be resolved by combining the low four bytes of the masks via a bitwise AND operation. Both the extension masks and the logical context masks re­turned by subsequent WTGet calls will be updated.

Information Category

The XBTNMASK information category implements only the items listed below.

Index

Value

EXT_NAME

TCHAR[]  the null-terminated string "Extended Button Mask"

EXT_TAG

UINT the tag value four.

EXT_DEFCONTEXT

XBTNMASK the default masks; all bits set to one.

EXT_DEFSYSCTX

XBTNMASK the default masks; all bits set to one.

EXT_CURSORS

BYTE[512] the system and logical button maps for each cursor type. The first 256 bytes comprise the system button map; the second 256 bytes contain the logical button map. 

B.7.     Express Keys Extension (1.4 modified)

Some tablets have physical key on the tablet surface. We have received requests to expose these keys to an application and allow the application to perform tasks when the key is pressed.

This extension allows an application to receive Express Key event notifications, and to override the normal system-wide behavior of Express Keys. For a working example, see the TabletControlsSample demo from the Windows download sample code at: http://us.wacom.com/en/developerrelations/windows

To make use of this extension, perform the following steps:

a.       Make sure you have versions of WINTAB.H and PKTDEF.H that support this extension (≥ 1.4).

The following information items are supported for this extension:

b.       Detect at run-time whether the Express Key extension is supported by the installed driver. This can be done by scanning the WTI_EXTENSIONS information categories for an extensions whose tag is equal to WTX_EXPKEYS2. If found, the extension is supported. (see PKTDEF.H for details)

// Iterate through Wintab extension indices
for ( UINT i=0, thisTag = 0;
      WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &thisTag);
      i++)
{
    // looking for the specified tag
    if (thisTag == WTX_EXPKEYS2)
    {
        // note the index of the found tag
        return i;
    }
}
return ERROR("EXPKEYS2 not supported by this Wintab");

c.        Add the Express Keys data to your extension packet definition by adding the following declaration before including PKTDEF.H:

#define PACKETEXPKEYS PKEXT_ABSOLUTE

This causes the EXPKEYSDATA structure to be included in the PACKETEXT structure definition. It is added as pkExpKeys.

Get the required mask for the extension and the mask with the lcPktData member of the context.

// get the extension mask for the express keys
WTInfo(WTI_EXTENSIONS + extIndex_ExpKeys, EXT_MASK, &lExpKeys_Mask);
 
...
 
lcContext.lcPktData = PACKETDATA | lExpKeys_Mask;

This tells the driver to fill in the EXPKEYSDATA structure.

d.       Determine the keys that are present by requesting extension data through the WTExtGet command:

// allocate a buffer
BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
// cast the buffer to the extension property data structure
EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
 
// fill in the data
prop->version = 0;
prop->tabletIndex = tablet_I;
prop->controlIndex = control_I;
prop->functionIndex = function_I;
prop->propertyID = TABLET_PROPERTY_AVAILABLE;
prop->reserved = 0;
prop->dataSize = sizeof(BOOL);
 
// send the command to Wintab
if (WTExtGet(ghCtx, ext_I, prop))
{
    // store the data requested
    return *((BOOL*)(&prop->data[0]));
}

WTExtGet uses the EXTPROPERTY structure to recieve data about the extension.

e.        Override ExpressKey behavior by calling WTExtSet.

// allocate a buffer
BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
// cast the buffer to the extension property data structure
EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
 
// fill in the data
prop->version = 0;
prop->tabletIndex = tablet_I;
prop->controlIndex = control_I;
prop->functionIndex = function_I;
prop->propertyID = TABLET_PROPERTY_OVERRIDE;
prop->reserved = 0;
prop->dataSize = sizeof(BOOL);
*((BOOL*)(&prop->data[0])) = TRUE;
 
// send the command to Wintab
return !WTExtSet(ghCtx, ext_I, prop);

With WTExtSet command, you can also override the name of the Express Key. (see the WINTAB.H for a complete list of properties)

Express Key Display Icons

Some tablets have display icons associated with the Express Keys.

// allocate a buffer

BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(UINT32)];

// cast the buffer to the extension property data structure

EXTPROPERTY *prop = (EXTPROPERTY*)buffer;

 

// fill in the data

prop->version = 0;

prop->tabletIndex = tablet_I;

prop->controlIndex = control_I;

prop->functionIndex = function_I;

prop->propertyID = TABLET_PROPERTY_ICON_FORMAT;

prop->reserved = 0;

prop->dataSize = sizeof(UINT32);

 

// send the command to Wintab

if (WTExtGet(ghCtx, ext_I, prop))

{

    // store the data requested

    return *((UINT32*)(&prop->data[0]));

}

If the return value is TABLET_ICON_FMT_NONE the express key has no display.

// allocate a buffer

BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + imageSize];

// cast the buffer to the extension property data structure

EXTPROPERTY *prop = (EXTPROPERTY*)buffer;

 

// fill in the data

prop->version = 0;

prop->tabletIndex = tablet_I;

prop->controlIndex = control_I;

prop->functionIndex = function_I;

prop->propertyID = TABLET_PROPERTY_OVERRIDE_ICON;

prop->reserved = 0;

prop->dataSize = imageSize;

for (int i = 0; i < imageSize; i++)

{

    prop->data[i] = imageData[i];

}

 

// send the command to Wintab

return !WTExtSet(ghCtx, ext_I, prop);

The image data should follow be in BMP or PNG format.

 

B.8.     Touch Strips and Touch Rings Extensions (1.4 modified)

These extensions allow an application to receive Touch Strip and Touch Ring event notifications, and to override the normal system-wide behavior of Touch Strip and Touch Ring. To make use of this extension, perform the following steps:

The following information items are supported for the touch strip extension:

c.        Detect at run-time whether the extension is supported by the installed driver. This can be done by scanning the WTI_EXTENSIONS information categories for an extensions whose tag is equal to WTX_TOUCHSTRIP and/or WTX_TOUCHRING respectfully. If found, the extension is supported. (see PKTDEF.H for details)

// Iterate through Wintab extension indices
for ( UINT i=0, thisTag = 0;
      WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &thisTag);
      i++)
{
    // looking for the specified tag
    if (thisTag == WTX_TOUCHSTRIP)
    {
        // note the index of the found tag
        return i;
    }
}
return ERROR("TOUCHSTRIP not supported by this Wintab");

d.       Add the Express Keys data to your extension packet definition by adding the following declaration before including PKTDEF.H:

#define PACKETTOUCHSTRIP PKEXT_ABSOLUTE

#define PACKETTOUCHRING PKEXT_ABSOLUTE

This causes the SLIDERDATA structure to be included in the PACKETEXT structure definition. The touchstrip extension adds pkTouchStrip; while the touchring extension adds pkTouchRing.

e.        Get the required mask for the extension and add the mask with the lcPktData member of the context.

// get the extension mask for the touch strip
WTInfo(WTI_EXTENSIONS + extIndex_TouchStrip, EXT_MASK, &lTouchStrip_Mask);
 
// get the extension mask for the touch ring
WTInfo(WTI_EXTENSIONS + extIndex_TouchRing, EXT_MASK, &lTouchRing_Mask);
 
...
 
lcContext.lcPktData = PACKETDATA | lTouchStrip_Mask | lTouchRing_Mask;

This tells the driver to fill in the correct SLIDERDATA structure.

f.        Determine the functions that are present by requesting extension data through the WTExtGet command:

// allocate a buffer
BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
// cast the buffer to the extension property data structure
EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
 
// fill in the data
prop->version = 0;
prop->tabletIndex = tablet_I;
prop->controlIndex = control_I;
prop->functionIndex = function_I;
prop->propertyID = TABLET_PROPERTY_AVAILABLE;
prop->reserved = 0;
prop->dataSize = sizeof(BOOL);
 
// send the command to Wintab
if (WTExtGet(ghCtx, ext_I, prop))
{
    // store the data requested
    return *((BOOL*)(&prop->data[0]));
}

WTExtGet uses the EXTPROPERTY structure to recieve data about the extension.

g.        Override the function behavior by calling WTExtSet.

// allocate a buffer
BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
// cast the buffer to the extension property data structure
EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
 
// fill in the data
prop->version = 0;
prop->tabletIndex = tablet_I;
prop->controlIndex = control_I;
prop->functionIndex = function_I;
prop->propertyID = TABLET_PROPERTY_OVERRIDE;
prop->reserved = 0;
prop->dataSize = sizeof(BOOL);
*((BOOL*)(&prop->data[0])) = TRUE;
 
// send the command to Wintab
return !WTExtSet(ghCtx, ext_I, prop);

With WTExtSet command, you can also override the name of the function. (see the WINTAB.H for a complete list of properties)

B.9.     Extension Structures (1.4 modified)

EXPKEYSDATA structure

typedef struct tagEXPKEYSDATA { /* 1.4 */

    BYTE    nTablet;    // index of the tablet

    BYTE    nControl;   // position index of the control

    BYTE    nLocation;  // location of the control

    BYTE    nReserved;  //

    DWORD   nState;     // state of the control (1 - pressed, 0 - released)

} EXPKEYSDATA;

This structure is returned as part of the PACKETEXT structure.

SLIDERDATA structure

typedef struct tagSLIDERDATA { /* 1.4 */

    BYTE    nTablet;    // index of the tablet

    BYTE    nControl;   // position index of the control

    BYTE    nFunction;  // control function index

    BYTE    nReserved;  //

    DWORD   nPosition;  // position of the finger on the control (zero for no touch)

} SLIDERDATA;

 

This structure is returned as part of the PACKETEXT structure.

EXTPROPERTY structure

typedef struct tagEXTPROPERTY { /* 1.4 */

    BYTE    version;        // Structure version, 0 for now

    BYTE    tabletIndex;    // 0-based index for tablet

    BYTE    controlIndex;   // 0-based index for control

    BYTE    functionIndex;  // 0-based index for control's sub-function

    WORD    propertyID;     // property ID

    WORD    reserved;       // DWORD-alignment filler

    DWORD   dataSize;       // number of bytes in data[] buffer

    BYTE    data[1];        // raw data

} EXTPROPERTY;

This structure is used for WTExtGet and WTExtSet.

Note that this stucture is of variable size. The total size of the structure is sizeof(EXTPROPERTY) + dataSize. Take care to allocate the correct amount of memory before using this structure.

Appendix C.  Additional Features (1.4 modified)

C.1.     Eraser

The obvious purpose of the eraser is to use it as an erasing tool. But you can change the function of the eraser to perform more advanced tasks. Using the stylus tip in conjunction with the eraser, you can easily perform two opposing functions such as dodge and burn, or ink and bleach. The eraser can also function independently as any tool selected in the application.

There are several ways to detect the use of the eraser.

One way is to look for a negative orAltitude value in the pkOrientation data of a packet. If you use this method please note that the tilt value is defined as unsigned (although it is stated to be signed in the Wintab specification) so you will have to cast the tilt value as signed to make this work.

Another way to detect the eraser is to look for cursor number 2, and with the advent of the Dual Track (explained later) also check for cursor number 5. The time to check the cusor number is once the device is brought into proximity. The WT_CSRCHANGE message is will allow you to detect when a new device enters proximity. For backwards compatibility you might also process the WT_PROXIMITY message. Be sure to include the cursor number (pkCursor field) in the data packet. If you wish to use this method you should ask Wintab for the number of cursors per device (WTInfo(WTI_INTERFACE, IFC_NCURSORS, &data) and modulus that result with the pkCursor field to do the test.

The third way an application can detect the eraser is by looking at the TPS_INVERT bit-field in the pkStatus data item of a packet. This field was added to the Wintab 1.1 specification.

C.2.     Tilt

Stylus tilt has several uses, but the most obvious is to change brush shape. Tilt can also be used for object rotation, or as a joystick.

During initialization you can check for the existence of tilt this way:

// Get info. about tilt

struct tagAXIS tiltOrient[3];

BOOL tiltSupport = FALSE;

tiltSupport = WTInfo(WTI_DEVICES, DVC_ORIENTATION, &tiltOrient);

if (tiltSupport )

{

    // Does the tablet support azimuth and altitude

    if (tiltOrient[0].axResolution && tiltOrient[1].axResolution)

    {

        // Get resolution

        azimuth = tiltOrient[0].axResolution;

        altitude = tiltOrient[1].axResolution;

    }

    else

    {

        tiltSupport = FALSE;

    }

}

Tilt data is in the pkOrientation packet.

C.3.     Dual Track

Dual Track, also referred to as multimode, allows two devices to be tracked at the same time. With the UDII series 12 x 12 and larger it is possible to simultaneously track a stylus and a puck. With certain supported Intuos tablets it is possible to track ANY two devices.

Note: Dual track was only supported for the following tablets. UDII 12x12, Intuos and Intuos II. Intuos III and IV do not support Dual track.

Working with two tools at once expands your capabilities in many unique ways. Stretch a line from both ends, or move a frisket with one hand while airbrushing around it with the other. Move a magnifying glass with one hand and draw on either the magnified, or the unmagnified image with the other. See the paper Bier, Eric A., Stone, Maureen C., Pier, Ken, Buxton, William. "Toolglass and Magic Lenses: The See-Through Interface" Computer Graphics, (1993), 73-80 or the video tape submission: A GUI Paradigm Using Tablets, Two Hands and Transparency, by George Fitzmaurice, Thomas Baudel, Gordon Kurtenbach and Bill Buxton, CHI 97 Video Program by ACM.

Here are some things to keep in mind when implementing dual track:

Pointing devices are indexed from 0 to 5. The application can tell which device generated a packet by looking at the packet’s pkCursor data item. The possible index values are:

Index 0 – Puck-like device #1

Index 1 – Stylus-like device #1

Index 2 – Inverted stylus-like device #1

Index 3 – Puck-like device #2

Index 4 – Stylus-like device #2

Index 5 – Inverted stylus-like device #2

The indexes are really placeholders for actual pointing devices. For example, the first time device index 2 enters the proximity of a context, it may be an inverted airbrush. As long as device index 2 is in proximity of the context, the device index of 2 uniquely identifies this physical device as the same inverted airbrush. However, after device 2 exits proximity, the next time the context sees a pointing device with an index of 2 enter proximity, index 2 may identify a different device, such as an inverted pen.

By default, tracking is turned on for the first device (pkCursor = 0, 1, or 2). This is the first device to enter proximity. Tracking is turned off (pkCursor = 3, 4, or 5) for the second device to enter proximity. So, an application that does not support dual tracking will virtually have the second device turned off. If they are both on, the screen cursor jumps back and forth between them. You may need to reverse this on the fly (on a WT_CSRCHANGE message) based on which device is in which hand.

Use the cursor number (pkCursor field) in the data packet to separate the packet stream into two streams (0-2 and 3-5) one steam for each device.

C.4.     Unique ID

There is another new feature to the Intuos series: Unique ID. A chip with a unique number is inside every stylus device so every device can be uniquely identified. With Unique ID you can assign a specific drawing tool to a specific pointing device or use it to "sign" a document. You can restrict access to document layers to particular devices and have settings follow a device to other machines.

The ID code from the device is in two sections. It is the combination of the two that is guaranteed unique. One section, the CSR_TYPE, is actually a code unique to each device type. The other section, the CSR_PHYSID, is a unique 32 bit number within a device type. CSR_PHYSID may be repeated between device types, but not within a type.

The CSR_TYPE is a coded bit field. Some bits have special meaning to the hardware, but are not of interest to a developer.

What is of interest is:

There are 12 bits total.

Bits 1,2,8,9,10,11 identify the device. The middle 4 bits (4,5,6,7) are used to differentiate between electrically similar, but physically different devices, such as a general stylus with a different color. So to figure out a specific device type you mask with 0x0F06. For example maybe 0x0812 is a stylus that is black, 0x0802 is the standard stylus included in the box, and 0x0832 may be a stylus with one side switch. Bits 0,3 are used internally and should be ignored.

The currently supported types are:

General stylus: (CSR_TYPE & 0x0F06) == 0x0802

Airbrush: (CSR_TYPE & 0x0F06) == 0x0902

Art Pen: (CSR_TYPE & 0x0F06) == 0x0804

4D Mouse: (CSR_TYPE & 0x0F06) == 0x0004

5 button puck: (CSR_TYPE & 0x0F06) == 0x0006

To create the unique ID just concatenate CSR_TYPE (without masking with 0x0F06) and CSR_PHYSID to make a 48 bit (you will probably use 64 bit) serial number.

C.5.     Airbrush Fingerwheel

The Intuos series tablets have a device that is similar to an airbrush. The device not only supports pressure on the tip, but also has a fingerwheel on the side to simultaneously vary a second value. For example, using the fingerwheel to vary ink density and, using pressure to vary line width.

The value of the fingerwheel on the side of the airbrush is reported in the pkTangentPressure (tangential pressure) field so be sure to include it in your packets. The value varies between 0 and 1023. But don’t hard code 1024! Use the function WTInfo(WTI_DEVICES, DVC_TPRESSURE) to query the tangent pressure range supported by the tablet.

C.6.     4D Mouse Rotation

The Intuos series tablets have a device that is similar to a puck. In addition to normal puck parameters, this puck supports axial rotation and a thumbwheel on the side. For example, with the 4D Mouse rotation, you can rotate the paper or an object, and zoom with the thumbwheel.

4D Mouse axial rotation is reported in the pkOrientation.orTwist field. Values in this field range from 0 to 3599.

During initialization you can check for the existence of rotation this way:

// Get info. about rotation

struct tagAXIS tiltOrient[3];

BOOL rotateSupport = FALSE;

rotateSupport = WTInfo(WTI_DEVICES, DVC_ORIENTATION, &tiltOrient);

if (rotateSupport)

{

    // Does the tablet support twist

    if (!tiltOrient[2].axResolution)

    {

        rotateSupport = FALSE;

    }

}

You would probably check for this at the same time you check for tilt, since it is in the same data structure.

C.7.     4D Mouse Thumbwheel

Uses for the 4D Mouse thumbwheel include zooming and 3D navigation. The thumbwheel value is reported in the pkZ field. The thumbwheel varies from pkZ = 1023 to pkZ = -1023 and snaps to the middle when released. The middle is 0, and the total range is from axMin to axMax. The value axResolution is 0 if the tablet does not support the 4D Mouse (such as legacy tablets). The thumbwheel may not have a broad enough range for all uses. It is left as an exercise to the reader to devise a way to extend the range.

During initialization you can check for the existence of the thumbwheel this way:

// Get info. about thumbwheel

struct tagAXIS thumbwheelAxis;

BOOL thumbwheelSupport = FALSE;

thumbwheelSupport = WTInfo(WTI_DEVICES, DVC_Z, &thumbwheelAxis);

if (thumbWheelSupport)

{

    // Does the tablet support thumbwheel?

    if (!thumbwheelAxis.axResolution)

    {

        thumbwheelSupport = FALSE;

    }

}

 

 

 

 

 



* Trademark holders: Wintab - LCS/Telegraphics, WindowsTM  and Pen WindowsTM - Microsoft Corp. Registered trademark holders: Microsoft® - Microsoft Corp.