Interface Implementations

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

File and Module Conventions

All Wintab functionality is implemented and referenced through the file "WINTAB32.DLL". This file is provided by the tablet driver and should not be included with the application. All functions should be dynamically referenced.

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 contains these and other files necessary for Wintab programming, plus several example programs with C-language source files. The Wintab Programmer's Kit is available from the author.

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 system 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 implementation-dependent. However, the manager functions should be present in all implementations, returning 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 manager interface may relieve the implementation of a considerable amount of user interface 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.

Function Reference

All tablet function names have the prefix "WT" and have attributes equivalent to WINAPI. Applications 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.

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.

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.

WTInfo

Syntax

UINT WTInfo(wCategory, nIndex, lpOutput)

This function returns global information about the interface in an application-supplied buffer. Different types of information are specified by different index arguments. Applications use this function to receive information about tablet coordinates, physical dimensions, capabilities, and cursor types.

Parameter	Type	Description
wCategory	UINT	Identifies the category from which information is being requested.
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 information is not supported, the function returns zero. If a tablet is not physically present, 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. Second, 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 function may provide any other implementation- or vendor-specific information categories necessary.

• The information returned by this function is subject to change during a Windows session. Applications cannot change the information returned here, but tablet manager 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, and the WT_INFOCHANGE message.

WTOpen

Syntax

HCTX WTOpen(hWnd, lpLogCtx, fEnable)

This function establishes an active context on the tablet. On successful completion of this function, the application may begin receiving tablet events via messages (if they were requested), and may use the handle returned to poll the context, or to perform other context-related functions.

Parameter	Type	Description
hWnd	HWND	Identifies the window that owns the tablet context, and receives messages from the context.
lpLogCtx	PLOGCONTEXT	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 order.

• Invalid or out-of-range attribute values in the logical context structure will either 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, the LOGCONTEXT data structure, and the context and information change messages.

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 window (and all manager windows) will receive a WT_CTXCLOSE message when the context has been closed.

See Also

The WTOpen function.

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 information 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 lpPktargument.

See Also
The WTPacketsPeek function, and the descriptions of the LOGCONTEXT and PACKET data structures.

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.
lpPkts	LPVOID	Points to a buffer to receive the event packets.

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 information that was requested when the context was opened.
• The buffer pointed to by lpPkts must be at least sizeof(PACKET) bytes long to prevent overflow.
• Applications may flush packets from the queue by calling this function with a NULL lpPktsargument.

See Also
The descriptions of the LOGCONTEXT and PACKET data structures.

Visibility Functions

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

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	UINT	Serial number of the tablet event to return.
lpPkts	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, and the LOGCONTEXT structure.

WTOverlap

Syntax

BOOL WTOverlap(hCtx, fToTop)

This function sends a tablet context to the top or bottom of the order of overlapping tablet contexts.

Parameter	Type	Description
hCtx	HCTX	Identifies the context to move within the overlap order.
lpPkts	BOOL	Specifies sending the context to the top of the overlap order 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 maintains an overlap order that helps determine 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,WTDataGet will process the event.
• This function is useful for getting access to input events when the application's context is overlapped by other contexts.
• The function will fail only if the context argument is invalid.

Context Editing Functions

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

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	BOOL	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. Otherwise, it returns zero.

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 specified as locked when the context was opened. Context lock values can only be changed by the context’s owner.
• 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.

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. Otherwise, it returns zero.

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 specified 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.

WTExtSet

Syntax

BOOL WTExtSet(hCtx, wExt, lpData)

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. Otherwise, it returns zero.

Comments

• Extensions may forbid their context-specific data to be changed during the lifetime 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 LOGCONTEXT data structure and the context locking values.

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 determine the packet size (by interrogating the context, if necessary), and to allocate a large enough buffer. Applications may flush packets from the queue by passing a NULL buffer pointer.

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.
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. Otherwise, it returns zero.

Comments

• Extensions may forbid their context-specific data to be changed during the lifetime 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 LOGCONTEXT data structure and the context locking values.

WTDataGet

Syntax

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

This function copies all packets with serial numbers between wBegin and wEnd inclusive 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 actually 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, and the WTQueuePacketsEx function.

WTDataPeek

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

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

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 actually 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, and the WTQueuePacketsEx function.

WTQueuePacketsEx

Syntax

BOOL WTQueuePacketsEx(hCtx, lpOld, lpNew)

This function returns the serial numbers of the oldest and newest packets currently 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.

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 returned.

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

See Also
The WTQueueSizeSet function.

WTQueueSizeSet

Syntax

BOOL WTQueueSizeSet(hCtx, 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. Otherwise, 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.

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.

WTMgrOpen

Syntax

HMGR WTMgrOpen(hWnd, wMsgBase)

This function opens a tablet manager handle for use by tablet manager and configuration applications. This handle is required to call the tablet management functions.

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 messages 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, the WTMgrClose function, the description of message base numbers, and the context and informational change messages.

WTMgrClose

Syntax

BOOL WTMgrClose(hMgr)

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.

Manager Context Functions

These functions provide access to open contexts and their owners, and allow changing context defaults. Only tablet managers are allowed to manipulate tablet contexts belonging to other applications.

Syntax

HCTX WTMgrDefContext(hMgr, fSystem)

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 WTInfofunction 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 the WTMgrDefContextEx function, and the category and index definitions.

WTMgrDefContextEx

Syntax

HCTX WTMgrDefContextEx(hMgr, wDevice, fSystem)

This function retrieves a context handle that allows setting values for the default digitizing 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 contexts 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, and the category and index definitions.

Manager Preference Data Functions

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

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.

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 logical 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 appropriate limitations are applied to the logical button map and that the system buttons are not left disabled.

See Also
The cursor information categories, and the system button assignment codes.

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 pressure buttons when they are used as conventional buttons.
• The pressure ranges are defined such that the minimum value of the range indicates 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 button is logically 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 generate.
• The marks are valid if and only if the button press mark is greater than the button release mark. Setting the marks to invalid combinations will turn off button-event generation for the button.

See Also
The cursor information categories.

WTMgrCsrPressureResponse

Syntax

BOOL WTMgrCsrPressureResponse(hMgr, wCsr, lpNResp, lpTResp)

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 pressure values to logical pressure values (applications see only logical pressure values). Each array element contains a logical pressure value corresponding to some pressure value. The array indices are "stretched" evenly over the input range.
• The number of entries in the arrays depends upon the range of pressure values. The number will be 256. When there is an entry for each possible value, the value is used as an index 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.

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, or via the wMsgBase argument of the WTMgrOpen function. Applications may choose different ranges for each context and manager handle, 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 message base is the global constant value WT_DEFBASE, defined as 0x7FF0. Although this default value will be reasonably safe for many applications, it is the responsibility of application programmers to prevent message number conflicts.

Although most message arguments' types are wider for 32-bit Wintab, no message 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 32-bit use.

Event Messages

Wintab applications that receive device events via Windows messages will receive the WT_PACKET message.

WT_PACKET

Description
The WT_PACKET message is posted to the context-owning windows that have requested messaging for their context.

Parameter	Description
wParam	Contains the serial number of the packet that generated the message.
lParam	Contains the handle of the context that processed the packet.

Comments
Applications should call the WTPacket function or other packet retrieval functions upon receiving this message.

See Also
The WTPacket function, and the advanced packet and queue functions.

WT_CSRCHANGE

Description
The WT_CSRCHANGE message is posted to the owning window when a new cursor enters the context.

Parameter	Description
wParam	Contains the serial number of the packet that generated the message.
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.

Context Messages

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

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 note that the context is being closed and take appropriate action.

WT_CTXCLOSE

Description
The WT_CTXCLOSE message is sent to the owning window 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.

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.

WT_CTXOVERLAP

Description
The WT_CTXOVERLAP message is sent to the owning window and to any manager 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 requests by applications.
• Applications can handle this message to find out when their context is obscured by another context.

WT_PROXIMITY

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

Parameter	Description
wParam	Contains the handle of the context that the cursor is entering or leaving.
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 hardware proximity.

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

Information Change Messages

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

WT_INFOCHANGE

Description
The WT_INFOCHANGE message is sent to all manager and context-owning windows 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 hardware.
lParam	Contains category and index numbers for the changed information. 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 applications that use the default context should not need to take any action.

Data Reference

The data types in the following list are keywords that define the size and meaning of parameters and return values associated with tablet interface functions and messages. This list contains fixed-point arithmetic 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 various 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 functions. Handles provide access to resources managed internally by the tablet interface. The tablet interface data types are defined in the following list.

Common Data Types

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 context tables.

LPLOGCONTEXT

Long pointer to a LOGCONTEXT data structure.

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);

WTPKT

Bit field that specifies the various optional data items available in event packets. 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 below, as well as any defined for extension data items.

PK_CONTEXT – Specifies the handle of the reporting context. PK_STATUS – Specifies status information. PK_TIMS – 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, respectively. PK_NORMAL_PRESSURE, PK_TANGENT_PRESSURE – Specify tip-button or normal-to-surface pressure data, and barrel-button or tangent-to-surface pressure data, respectively. PK_ORIENTATION – Specifies cursor orientation information. PK_ROTATION: Specifies cursor rotation information.

Information Data Structures

This section describes the data formats returned by the WTInfo function and the category and index values used when calling the function. Some of the common data return formats are described first, followed by a complete listing of all the category and index values.

AXIS

Range and Resolution Descriptor

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;

Field	Description
axMin	Specifies the minimum value of the data item in the tablet's native coordinates.
axMax	Specifies the maximum value of the data item in the tablet's native 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 increments per physical unit.

Comments
This structure is used to construct return data for the WTInfo function. In particular, it is used within the WTI_DEVICES category for returning the capabilities of the device with respect to each axis or packet data item.

See Also
The WTInfo function and the values used for specifying units.

Physical Unit Specifiers

Field	Description
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 centimetres.
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.

Information Categories and Indices

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 sy­tem contexts, respectively. The WTI_DEVICES, WTI_CURSORS and WTI_EXTENSIONS categories are multiplexed; the category names actually refer to the first of several consecutive categories.

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	Each contains the current default digitizing logical context for the corresponding device.
WTI_DSCTXS	Each contains the current default system logical context for the corresponding device.

WTI_INTERFACE Index Definitions

Index	Type	Description
IFC_WINTABID	TCHAR[]	Returns a copy of the null-terminated tablet hardware identification string in the user buffer. This string should include make, model, and revision 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.
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.

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 received by any context, in Hertz.
STA_PKTDATA	WTPKT	Returns a mask indicating which packet data items are requested 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 assigned a system button function by the current cursor's system button map.

WTI_DEFCONTEXT, WTI_DEFSYSCTX, WTI_DDCTXS, and WTI_DSCTXS 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.
CTX_STATUS	UINT	Returns zero.
CTX_LOCKS	UINT	Returns which attributes of the default context are locked.
CTX_MSGBASE	UINT	Returns the value WT_DEFBASE.
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 absolute 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 processed 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 processed in the context.
CTX_INORGX, CTX_INORGY, CTX_INORGZ	LONG	Each returns the origin of the context's input area in the tablet's native 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 native 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 directions, respectively.
CTX_SYSSENSX, CTX_SYSSENSY	FIX32	Each returns the system cursor relative-mode sensitivity factor, in the x and y directions, respectively.

WTI_DEVICES Index Definitions

Index	Type	Description
DVC_NAME	TCHAR[]	Returns a displayable null- terminated string describing the device, manufacturer, and revision level.
DVC_HARDWARE	UINT	Returns flags indicating hardware and driver capabilities, as defined below:
		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: Indicates that device can uniquely identify 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 always 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 coordinates, 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	AXIS[]	Returns a 3-element array describing the tablet's rotation range and resolution capabilities.
DVC_PNPID	TCHAR[]	Returns a null-terminated string containing the device’s Plug and Play ID.

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 supported 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 separated 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 controlled 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 controlled 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	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 functions to specific physical cursors, even if category numbers change and multiple, otherwise identical, physical cursors are present.
CSR_MODE	UINT	Returns the cursor mode number of this cursor type, if this cursor type has the CRC_MULTIMODE capability.
CSR_MINPKTDATA	UINT	Returns the minimum set of data available from a physical cursor in this cursor type, if this cursor type has the CRC_AGGREGATE capability.
CSR_MINBUTTONS	UINT	Returns the minimum number of buttons of physical cursors in the cursor type, if this cursor type has the CRC_AGGREGATE capability.
CSR_CAPABILITIES	UINT	Returns flags indicating cursor capabilities, as defined by the values and their meanings, below:
		CRC_MULTIMODE: Indicates this cursor type describes one of several modes of a single physical cursor. Consecutive cursor type categories describe the modes; the CSR_MODE data item gives the mode number of each cursor type.
		CRC_AGGREGATE: Indicates this cursor type describes several physical cursors that cannot be distinguished by software.
		CRC_INVERT: Indicates this cursor type describes the physical cursor in its inverted orientation; the previous consecutive cursor type category describes the normal orientation.

WTI_EXTENSIONS Index Definitions

Index	Type	Description
EXT_NAME	TCHAR[]	Returns a unique, null-terminated string describing the extension.
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 variables 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 extension.
EXT_DEFAULT	BYTE[]	Returns the current global default data, as needed for the extension. 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 system-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 needed for the extension. This data is modified via the WTMgrCsrExt function.

System Button Assignment Values

The values defined below indicate emulations of mouse button actions. Three different types of actions are defined for each mouse button: clicking, double-clicking, and dragging. Clicking means the button behaves 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 toggles 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 tablet 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), respectively.
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.

Context Data Structures

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.

LOGCONTEXT

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

Field	Description
lcName	Contains a zero-terminated context name string.
lcOptions	Specifies options for the context. These options can be combined by using the bitwise OR operator. The lcOptions field can be any combination of the values defined. Specifying options that are unsupported in a particular implementation will cause WTOpen to fail.
lcStatus	Specifies current status conditions for the context. These conditions can be combined by using the bitwise OR operator. The lcStatus field can be any combination of the values defined.
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 operator. The lcLocks field can be any combination of the values defined. 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 reporting the activity of the context.
lcDevice	Specifies the device whose input the context processes.
lcPktRate	Specifies the desired packet report rate in Hertz. Once the context is opened, this field will contain the actual report rate.
lcPktData	Specifies which optional data items will be in packets returned from the context. Requesting unsupported data items will cause WTOpen to fail.
lcPktMode	Specifies whether the packet data items will be returned in absolute 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 definition in the lcPktData field will be ignored. The bits for buttons, time stamp, and the serial number will also be ignored. In the case of overlapping contexts, movement events for data items not selected in this field may be processed by underlying contexts.
lcBtnDnMask	Specifies the buttons for which button press events will be processed 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 release events are selected for a button (see the lcBtnDnMask field above), then the interface will cause the context to implicitly 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 button 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 tablet's native coordinates, along the x, y, and z axes, respectively. 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 tablet's native coordinates, along the x, y, and z axes, respectively. 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 context output coordinates, along the x, y, and z axes, respectively. Each is used in coordinate scaling for absolute mode only.
lcOutExtX, lcOutExtY, lcOutExtZ	Each specifies the extent of the context's output area in context output coordinates, along the x, y, and z axes, respectively. 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 absolute; non-zero means relative.
lcSysOrgX, lcSysOrgY	Together specify the origin of the screen mapping area for system cursor tracking, in screen coordinates.
lcSysExtX, lcSysExtY	Together specify the extent of the screen mapping area for system 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 Windows itself.

• Tablet contexts reflect the tension between application control of input data and user control of workstation ergonomics. Some attributes of contexts are controlled by the user, others by the application. The notion of locks allows applications 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 workstations in a comfortable, efficient manner.

• 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 coordinates, 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 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, the Context Status Values, and the Context Lock Condition Values tables below.

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 installed. 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 input 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	Specifies that the context returns WT_CSRCHANGE messages to its owner.

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 context that is higher in the context overlap order.
CXS_ONTOP	Specifies that the context is the topmost context in the context overlap order.

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 possible.
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 system pointing control variables of the context cannot be changed.

Event Data Structures

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

PACKET

Event Packet Data Structure

Description
The PACKET data structure is a flexible structure that contains tablet event information. Each of its fields is optional. The structure consists of a concatenation of the data items selected in the lcPktData field of the context that generated the packet. The order of the data items is the same as the order of the corresponding 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 lcPktDatafield are set and the lcPktMode field is clear (all items are in absolute mode).

Field	Description
pkContext	Specifies the context that generated the event.
pkStatus	Specifies various status and error conditions. These conditions can be combined by using the bitwise OR operator. The pkStatus field can be any combination of the status values.
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 (displayed with Value and 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, respectively. In relative mode, each is a LONG containing 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 details, see the description of the ORIENTATION data structure.
pkRotation	Contains updated cursor rotation information. For details, see the description of the ROTATION data structure.

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, the ORIENTATION structure, the ROTATION structure, the WTOpen function, LOGCONTEXT data structure, and the WTI_EXTENSIONS group of information categories.

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	Specifies that the cursor is in its inverted state.

ORIENTATION

Cursor Orientation Descriptor

Description
The ORIENTATION data structure specifies the orientation of the cursor with respect to the tablet.

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, semicircular 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.

ROTATION

Cursor Rotation Descriptor

Description
The ROTATION data structure specifies the Rotation of the cursor with respect to the tablet.

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.