Function Name

Ordinal

Function Name

Ordinal

WTInfo

20, 1020

WTMgrOpen

100

WTOpen

21, 1021

WTMgrClose

101

WTClose

22

WTMgrContextEnum

120

WTPacketsGet

23

WTMgrContextOwner

121

WTPacket

24

WTMgrDefContext

122

WTEnable

40

WTMgrDefContextEx (1.1)

206

WTOverlap

41

WTMgrDeviceConfig

140

WTConfig

60

WTMgrConfigReplace

141

WTGet

61, 1061

WTMgrConfigReplaceEx

202, 1202

WTSet

62, 1062

WTMgrPacketHook

160

WTExtGet

63

WTMgrPacketHookEx

203, 1203

WTExtSet

64

WTMgrPacketUnhook

204

WTSave

65

WTMgrPacketHookDefProc

161

WTRestore

66

WTMgrPacketHookNext

205

WTPacketsPeek

80

WTMgrExt

180

WTDataGet

81

WTMgrCsrEnable

181

WTDataPeek

82

WTMgrCsrButtonMap

182

WTQueuePackets

83

WTMgrCsrPressureBtnMarks

183

WTQueuePacketsEx

200

WTMgrCsrPressureBtnMarksEx

201

WTQueueSizeGet

84

WTMgrCsrPressureResponse

184

WTQueueSizeSet

85

WTMgrCsrExt

185

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 in tables 7.3 through 7.9, and the WT_INFOCHANGE message in section 6.3.1.

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

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 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 in section 5.2.1, the LOGCONTEXT data structure in section 7.3.1, and the context and information change messages in sections 6.2 and 6.3.

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 in section 5.1.2.

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

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 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 lpPkts argument.

See Also

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

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 satisfied, zero otherwise.

Comments

Calls to this function to enable an already enabled context, or to disable an already 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 structure.

See Also

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

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.

fToTop

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

Syntax

BOOL WTConfig(hCtx, hWnd)

This function prompts the user for changes to the passed context via a dialog box.

Parameter

Type/Description

hCtx

HCTX Identifies the context that the user will modify via the dialog box.

hWnd

HWND Identifies the window that will be the parent window of the dialog box.

Return Value

The function returns a non-zero value if the tablet context was changed, zero otherwise.

Comments

Tablet applications can use this function to let the user choose context attributes that the application doesn't need to control. Applications can control the editing of context attributes via the lcLocks logical context structure member.

Applications should consider providing access to this function through a menu item or command.

See Also

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

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

See Also

The LOGCONTEXT structure in section 7.3.1.

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

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.

See Also

The extension definitions in Appendix B.

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. 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 extension definitions in Appendix B, the LOGCONTEXT data structure in section 7.3.1 and the context locking values in table 7.13.

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. Otherwise, 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 extension data bound to contexts.

See Also

The WTRestore function in section 5.3.7.

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 information for input instead of a logical context. In particular, it will generate a WT_CTXOPEN message 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.

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.

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 in section 5.4.3, and the WTQueuePacketsEx function in section 5.4.5.

Syntax

int WTDataPeek(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 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 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 in section 5.4.2, and the WTQueuePacketsEx function in section 5.4.5.

Syntax

DWORD WTQueuePackets(hCtx)

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.

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.

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.

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 in section 5.4.7.

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. 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 in section 5.4.6.

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 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 information change messages in sections 6.2 and 6.3.

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.

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

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 callback function. See the following "Comments" section for details.

lParam

LPARAM Specifies the value to be passed to the callback function for the application's use.

Return Value

The return value specifies the outcome of the function. It is non-zero if all contexts 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 application's module-definition file.

Parameter

Description

hCtx

Identifies the context.

lParam

Specifies the 32-bit argument of the WTMgrContextEnum function.

Return Value

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

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 management with the states of the context-owning windows.

Syntax

HCTX WTMgrDefContext(hMgr, fSystem)

This function retrieves a context handle that allows setting values for the current default digitizing or system context.

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.

Editing operations on the retrieved handles will fail if the new default contexts do not meet certain requirements. The digitizing context must include at least buttons, x, and y in its packet data, and must return absolute coordinates.

1.1: Editing the current default digitizing context will also update the device-specific default context for the device listed in the lcDevice field of the default context’s LOGCONTEXT structure.

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.

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.

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.

Editing operations on the retrieved handles will fail if the new default contexts do not meet certain requirements. The digitizing context must include at least buttons, x, and y in its packet data, and must return absolute coordinates.

See Also

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

Syntax

UINT WTMgrDeviceConfig(hMgr, wDevice, hWnd)

This function displays a custom modal tablet-hardware configuration dialog box, if one is supported.

Parameter

Type/Description

hMgr

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

wDevice

UINT Identifies the device that the user will configure via the dialog box.

hWnd

HWND Identifies the window that will be the parent window of the dialog box. If this argument is NULL, the function will return non-zero if the dialog is supported, or zero otherwise.

Return Value

The return value is zero if the dialog box is not supported. Otherwise, it is one of the following non-zero values.

Value

Meaning

WTDC_CANCEL

The user canceled the dialog without making any changes.

WTDC_OK

The user made and confirmed changes.

WTDC_RESTART

The user made and confirmed changes that require a system restart in order to take effect. The calling program should query the user to determine whether to restart. Restart Windows using the function call ExitWindows(EW_RESTARTWINDOWS, 0);.

Syntax

BOOL WTMgrConfigReplace(hMgr, fInstall, lpConfigProc)

This function allows a manager application to replace the default behavior of the WTConfig function.

Parameter

Type/Description

hMgr

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

fInstall

BOOL Specifies installation of a replacement function if non-zero, or removal of the current replacement if zero.

lpConfigProc

WTCONFIGPROC Is the procedure-instance address of the new configuration function. This argument is ignored during a removal request.

Return Value

The function return non-zero if the installation or removal request succeeded. Otherwise, it returns zero.

Comments

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

See Also

The WTConfig function in section 5.3.1, and for a description of the configuration callback function, see the WTMgrConfigReplaceEx function in section 5.7.3.

Syntax

BOOL WTMgrConfigReplaceEx(hMgr, fInstall, lpszModule, lpszCfgProc)

This function allows a manager application to replace the default behavior of the WTConfig function.

Parameter

Type/Description

hMgr

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

fInstall

BOOL Specifies installation of a replacement function if non-zero, or removal of the current replacement if zero.

lpszModule

LPCTSTR Points to a null-terminated string that names a DLL module containing the new configuration function. This argument is ignored during a removal request

lpszCfgProc

LPCSTR Points to a null-terminated string that names the new configuration function. This argument is ignored during a removal request.

Return Value

The function return non-zero if the installation or removal request succeeded. Otherwise, it returns zero.

Comments

The configuration callback function must have attributes equivalent to WINAPI.

Only one callback function may be installed at a time. The manager handle passed with the removal request must match the handle passed with the corresponding installation request.

Tablet managers that install a replacement context configuration function must remove it before exiting.

Callback

BOOL WINAPI ConfigProc(hWnd, hCtx)
HWND hWnd;
HCTX hCtx;

ConfigProc 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 application's module-definition file.

Parameter

Description

hWnd

Identifies the window that will be the parent window of the dialog box.

hCtx

Identifies the context that the user will modify via the dialog box.

Return Value

The function returns a non-zero value if the tablet context was changed, zero otherwise.

Comments

The configuration function and resulting dialog box should analyze the lcLocks context structure member, and only allow editing of unlocked context attributes.

See Also

The WTConfig function in section 5.3.1.

Syntax

WTHOOKPROC WTMgrPacketHook(hMgr, fInstall, nType, lpFunc)

This function installs or removes a packet hook function.

Parameter

Type/Description

hMgr

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

fInstall

BOOL Specifies installation of a hook function if non-zero, or removal of the specified hook if zero.

nType

int Specifies the packet hook to be installed. It can be any one of the following values:

Value

Meaning

WTH_PLAYBACK

Installs a packet playback hook.

WTH_RECORD

Installs a packet record hook.

lpFunc

WTHOOKPROC Is the procedure-instance address of the hook function to be installed. See the "Comments" section under WTMgrPacketHookEx for details.

Return Value

When installing a hook, the return value points to the procedure-instance address of the previously installed hook (if any). It is NULL if there is no previous hook; it is negative one if the hook cannot be installed. The application or library that calls this function should save this return value in the library's data segment. The fourth argument of the WTPacketHookDefProc function points to the location in memory where the library saves this return value.

When removing a hook, the return value is the passed lpFunc if successful, NULL otherwise.

Comments

This function is non-portable and is superseded by WTMgrPacketHookEx and WTMgrPacketUnhook.

See Also

the WTMgrPacketHookEx function in section 5.8.2, and the WTMgrPacketUnhook function in section 5.8.3.

Syntax

HWTHOOK WTMgrPacketHookEx(hMgr, nType, lpszModule, lpszHookProc)

This function installs a packet hook function.

Parameter

Type/Description

hMgr

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

nType

int Specifies the packet hook to be installed. It can be any one of the following values:

Value

Meaning

WTH_PLAYBACK

Installs a packet playback hook.

WTH_RECORD

Installs a packet record hook.

lpszModule

LPCTSTR Points to a null-terminated string that names a DLL module containing the new hook function. See the following "Comments" section for details.

lpszHookProc

LPCSTR Points to a null-terminated string that names the new hook function. See the following "Comments" section for details.

Return Value

If the function succeeds, the return value is the handle of the installed hook function. Otherwise, the return value is NULL.

Comments

Packet hooks are a shared resource. Installing a hook affects all applications using the interface.

All Wintab hook functions must be exported functions residing in a DLL module.

The following section describes how to support the individual hook functions.

WTH_PLAYBACK

Wintab calls the WTH_PLAYBACK hook whenever a request for an event packet is made. The function is intended to be used to supply a previously recorded event packet for a compatible context.

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

Hook Function

LRESULT WINAPI HookFunc(nCode, wParam, lParam);
int nCode;
WPARAM wParam;
LPARAM lParam;

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

Parameter

Description

nCode

Specifies whether the hook function should process the message or call the WTMgrPacketHookDefProc (if installed by WTMgrPacketHook)or WTMgrPacketHookNext (if installed by WTMgrPacketHookEx) function. If the nCode parameter is less than zero, the hook function should pass the message to the appropriate function without further processing.

wParam

Specifies the context handle whose event is being requested.

lParam

Points to the packet being processed by the hook function.

Comments

The WTH_PLAYBACK function should copy an event packet to the buffer pointed to by the lParam parameter. The packet must have been previously recorded by using the WTH_RECORD hook. It should not modify the packet. The return value should be the amount of time (in milliseconds) Wintab should wait before processing the message. This time can be computed by calculation the difference between the time stamps of the current and previous packets. If the function returns zero, the message is processed immediately. Once it returns control to Wintab, the packet continues to be processed. If the nCode parameter is WTHC_SKIP, the hook function should prepare to return the next recorded event message on its next call.

The packet pointed to by lParam will have the same structure as packets retrieved from the context normally. Wintab will validate the following packet items to ensure consistency: context handle, time stamp, and serial number. The remaining fields will be valid if the context used for playback is equivalent to the context from which the events were recorded.

The WTH_PLAYBACK hook will not be called to notify it of the display or removal of system modal dialog boxes. It is expected that applications playing back packets will also be playing back window event messages using Windows' own hook functions.

While the WTH_PLAYBACK function is in effect, Wintab ignores all hardware input.

WTH_RECORD

The interface calls the WTH_RECORD hook whenever it processes a packet from a context event queue. The hook can be used to record the packet for later playback.

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

Hook Function

LRESULT WINAPI HookFunc(nCode, wParam, lParam);
int nCode;
WPARAM wParam;
LPARAM lParam;

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

Parameter

Description

nCode

Specifies whether the hook function should process the message or call the WTMgrPacketHookDefProc (if installed by WTMgrPacketHook)or WTMgrPacketHookNext (if installed by WTMgrPacketHookEx) function. If the nCode parameter is less than zero, the hook function should pass the message to the appropriate function without further processing.

wParam

Specifies the context handle whose event is being processed.

lParam

Points to the packet being processed by the hook function.

Comments

The WTH_RECORD function should save a copy of the packet for later playback. It should not modify the packet. Once it returns control to Wintab, the message continues to be processed. The filter function does not require a return value.

The packet pointed to by lParam will have the same structure as packets retrieved from the context normally.

The WTH_RECORD hook will not be called to notify it of the display or removal of system modal dialog boxes. It is expected that applications recording packets will also be recording window event messages using Windows' own hook functions.

Syntax

BOOL WTMgrPacketUnhook(hHook)

This function removes a hook function installed by the WTMgrPacketHookEx function.

Parameter

Type/Description

hHook

HWTHOOK Identifies the hook function to be removed.

Return Value

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

See Also

The WTMgrPacketHookEx function in section 5.8.2, and the WTMgrPacketHookNext function in section 5.8.5.

Syntax

LRESULT WTMgrPacketHookDefProc(nCode, wParam, lParam, lplpFunc)

This function calls the next function in a chain of packet hook functions. A packet hook function is a function that processes packets before they are retrieved from a context's queue. When applications define more than one hook function by using the WTMgrPacketHook function, Wintab places functions of the same type in a chain.

Parameter

Type/Description

nCode

int Specifies a code used by the hook function to determine how to process the message.

wParam

WPARAM Specifies the word parameter of the message that the hook function is processing.

lParam

LPARAM Specifies the long parameter of the message that the hook function is processing.

lplpFunc

WTHOOKPROC FAR * Points to a memory location that contains the WTHOOKPROC returned by the WTMgrPacketHook function. Wintab changes the value at this location after an application unhooks the hook using the WTMgrPacketHook function.

Return Value

The return value specifies a value that is directly related to the nCode parameter.

Comments

This function is non-portable and is superseded by the WTMgrPacketHookNext function.

See Also

The WTMgrPacketHookNext function in section 5.8.5.

Syntax

LRESULT WTMgrPacketHookNext(hHook, nCode, wParam, lParam)

This function passes the hook information to the next hook function in the current hook chain.

Parameter

Type/Description

hHook

HWTHOOK Identifies the current hook.

nCode

int Specifies the hook code passed to the current hook function.

wParam

WPARAM Specifies the wParam value passed to the current hook function.

lParam

LPARAM Specifies the lParam value passed to the current hook function.

Return Value

If the function succeeds, the return value is the value returned by the next hook function in the chain. The current hook procedure must also return this value. The meaning of the return value depends on the hook type. For more information, see the descriptions of the individual hook functions.

Comments

Hook functions are installed in chains for particular hook types. WTMgrPacketHookNext calls the next hook in the chain.

Calling WTMgrPacketHookNext is optional. A hook procedure can call this function either before or after processing the hook information. If a hook function does not call WTMgrPacketHookNext, Wintab does no call the hook functions installed before the current hook function was installed.

See Also

The WTMgrPacketHookEx function in section 5.8.2, and the WTMgrPacketUnhook function in section 5.8.3.

Syntax

BOOL WTMgrExt(hMgr, wExt, lpData)

This function allows tablet managers to control ergonomic or preference settings for tablet extension data items.

Parameter

Type/Description

hMgr

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

wExt

UINT Identifies the extension whose settings are being changed.

lpData

LPVOID Points to data for the new settings. If the value WTP_LPDEFAULT is specified, the function resets the default value for the settings.

Return Value

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

Comments

The data passed to this function is defined in the extension definition. This data (or equivalent) should be available in the EXT_DEFAULT item of the information category for the extension.

See Also

The extension information categories in table 7.9, and the extension definitions in Appendix B.

Syntax

BOOL WTMgrCsrEnable(hMgr, wCursor, fEnable)

This function changes the active cursor type.

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 that will be activated.

fEnable

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

Return Value

The return value is non-zero if the request succeeded; otherwise it is zero.

Comments

This function is useful with tablets that cannot indicate to software which cursor type is active. For tablets that can indicate the active cursor types, the function will return non-zero if the specified cursor is in the state requested by the fEnable parameter.

For devices that support multiple active cursors, the function can be called repeatedly to enable multiple cursor types, up to the number supported by the device.

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 assigns physical 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 button map.

lpSysBtns

LPBYTE Points to a 32 byte array of button action codes, one for each logical button. If the value WTP_LPDEFAULT is specified, 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 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 in table 7.8, and the system button assignment codes in table 7.10.

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 button. 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 button. 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 WTMgrCsrPressureBtnMarksEx function in section 5.9.5.

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 in table 7.8.

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 pressure values to logical pressure values (applications see only logical pressure values). Each array element contains a logical pressure value corresponding to some physical 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 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 in table 7.8.

Syntax

BOOL WTMgrCsrExt(hMgr, wCsr, wExt, lpData)

This function allows tablet managers to set extension data for extensions that are bound to cursor types.

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 extension settings are being changed.

wExt

UINT Identifies the extension whose settings are being changed.

lpData

LPVOID Points to data for the new settings. If the value WTP_LPDEFAULT is specified, the function resets the default value for the settings.

Return Value

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

Comments

The extension definition will determine the effect of this function and the data types used. This data (or equivalent) should be available via the EXT_CURSORS index in the extension's information category.

See Also

The extension information categories in table 7.9.

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 in section 6.1.1, and the advanced packet and queue functions in section 5.4.

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.