The Wintab specification is an open industry standard interface that provides access to pointing devices such as a pen tablet, for example. The API was developed by LCS/Telegraphics.
The wintab module is a wrapper around the Wintab Developer Kit and can be used to add tablet support to your Python application. Before you can get any data from the tablet you have to create an instance of the Context class, set the desired parameters and open the context. Once the context is open you will either receive messages from the tablet driver or you can poll the current tablet state. Either way, you will receive the tablet data via Packet objects that contain all the data that was generated by the tablet. See also the Wintab Interface Specification at http://www.wacomeng.com/devsupport/index.html for more detailed usage information.
The constants used in this module are either available in the wintab module or in the wintab.constants module. The latter can be used if you want to import only the constants into your namespace.
Returns True if the Wintab functionality is available. As the Wintab Developer Kit is only available on Windows, this function will always return False on other operating systems.
On Windows, this function can still return False if either the Wintab drivers are not installed or cgkit was compiled without Wintab support.
If this function returns False, an exception will be raised whenever you try to call another function or instantiate a class from this module.
This function returns a dictionary with global information about the interface. category specifies the category from which information is being requested. It can be one of the values in the following table:
| Category | Description |
|---|---|
| WTI_INTERFACE | Global interface identification and capability information |
| WTI_STATUS | Current interface resource usage statistics |
| WTI_DEFCONTEXT | ... |
| WTI_DEFSYSCTX | ... |
| WTI_DEVICES+n | Capability and status information for a device |
| WTI_CURSORS+n | Capability and status information for a cursor |
| WTI_EXTENSIONS+n | Descriptive information and defaults for an extension |
| WTI_DDCTXS | ... |
| WTI_DSCTXS | ... |
Note
The module uses the Wintab Programmer’s Kit which can be found at http://www.wacomeng.com/devsupport/index.html.
The Wintab Programmer’s Kit is copyright 1991-1998 by LCS/Telegraphics.
The Context class provides the interface to the tablet driver.
The class takes no parameters. All the context attributes will be initialized with the default values as provided by the driver.
Context attributes:
Context name.
Specifies options for the context and must be a combination of the following flags:
| Option | Description |
|---|---|
| CXO_SYSTEM | The context is a system cursor context |
| CXO_PEN | The context is a Pen Windows (and system cursor) context |
| CXO_MESSAGES | The context sends WT_PACKET messages to its owner |
| CXO_MARGIN | The input context will have a margin |
| CXO_MGNINSIDE | The margin will be inside the specified context |
| CXO_CSRMESSAGES | The context sends WT_CSRCHANGE messages to its owner |
Specifies current status conditions for the context. The status value is a combination of the following bits:
| Status bit | Description |
|---|---|
| CXS_DISABLED | The context has been disabled |
| CXS_OBSCURED | The context is at least partially obscured by another context |
| CXS_ONTOP | The context is the topmost context |
Specifies which attributes of the context the application wishes to be locked. The value can be a combination of the following bits:
| Lock | Description |
|---|---|
| CXL_INSIZE | The input size cannot be changed |
| CXL_INASPECT | The input aspect ration cannot be changed |
| CXL_MARGIN | The margin options cannot be changed |
| CXL_SENSITIVITY | The sensitivity settings for x, y and z cannot be changed |
| CXL_SYSOUT | The system pointing control variables cannot be changed |
Base number for the message IDs.
Specifies the device whose input the context processes.
Specifies the desired packet report rate in Hertz. Once the context is open, this field will contain the actual report rate.
Specifies which optional data items will be in packets returned from the context.
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.
Specifies which packet data items can generate move events in the context.
Specifies the buttons for which button press events will be processed in the context.
Specifies the buttons for which button release events will be processed in the context.
Specifies the origin of the context’s input area in the tablet’s native coordinates along the x axis.
Specifies the origin of the context’s input area in the tablet’s native coordinates along the y axis.
Specifies the origin of the context’s input area in the tablet’s native coordinates along the z axis.
Specifies the extent of the context’s input area in the tablet’s native coordinates along the x axis.
Specifies the extent of the context’s input area in the tablet’s native coordinates along the y axis.
Specifies the extent of the context’s input area in the tablet’s native coordinates along the z axis.
Specifies the extent of the context’s output area in context output coordinates along the x axis.
Specifies the extent of the context’s output area in context output coordinates along the y axis.
Specifies the extent of the context’s output area in context output coordinates along the z axis.
Specifies the extent of the context’s output area in context output coordinates along the x axis.
Specifies the extent of the context’s output area in context output coordinates along the y axis.
Specifies the extent of the context’s output area in context output coordinates along the z axis.
Specifies the relative-mode sensitivity factor for the x axis.
Specifies the relative-mode sensitivity factor for the y axis.
Specifies the relative-mode sensitivity factor for the z axis.
Specifies the system cursor tracking mode. True specifies absolute, False means relative.
Specifies the origin in screen coordinates of the screen mapping area for system cursor tracking.
Specifies the origin in screen coordinates of the screen mapping area for system cursor tracking.
Specifies the extent in screen coordinates of the screen mapping area for system cursor tracking.
Specifies the extent in screen coordinates of the screen mapping area for system cursor tracking.
Specifies the system-cursor relative-mode sensitivity factor for the x axis.
Specifies the system-cursor relative-mode sensitivity factor for the y axis.
Other attributes:
The number of packets the context’s queue can hole. Setting this attribute may result in an exception if the queue size could not be set. In such a case, you must try again with a smaller value.
The final id of the WT_PACKET message.
The final id of the WT_CSRCHANGE message.
The final id of the WT_CTXOPEN message.
The final id of the WT_CTXCLOSE message.
The final id of the WT_CTXUPDATE message.
The final id of the WT_CTXOVERLAP message.
The final id of the WT_PROXIMITY message.
The final id of the WT_INFOCHANGE message.
Methods:
Opens the context. hwnd is the window handle (as integer) of the window that owns the context and that receives messages from the context. enable is a boolean that specifies whether the context will immediately begin processing input data.
Set the context attributes to the desired values before calling this method. Modifying context attributes after the context was opened is possible with the set() method.
This method is equivalent to the open() method with the only difference that it takes the context attributes via the binary saveinfo string which was returned by the save() method in a previous session.
Closes the context if it was open (or do nothing if it was already closed or if it was not open at all).
Returns a binary saveinfo string containing the current context state. This string can be used as argument to the restore() method.
Returns the packet with the specified serial number.
If flag is True the context is enabled, otherwise it is disabled. Returns True if the operation was successful.
If totop is True the context will become the topmost context, otherwise it will be send to the bottom. Returns True if the operation was successful.
Prompts the user for changes to the context via a dialog box. hwnd is the window handle of the window that will be parent of the dialog. If it is 0, the context owning window will be used. The return value is True if the context was changed.
Update the local context attributes.
Update the tablet context with the settings stored in the local context attributes.
Return the next maxpkts packets and remove them from the queue.
Return the next maxpkts packets without removing them from the queue.
Return all packets with serial numbers between begin and end inclusive and remove them from the queue. However, no more than maxpkts packets are returned. The return value is a 2-tuple (numpackets, packet list) where numpackets is the total number of packets found in the queue between begin and end.
This is the same as dataGet() but it doesn’t remove the packets from the queue.
Returns the serial numbers of the oldest and newest packets currently in the queue.
This is a copy of the pktdata attribute of the corresponding context, i.e. this attribute determines which of the following attributes are actually valid.
Specifies the context that generated the event.
Contains a combination of the following status and error conditions:
| Status bit | Description |
|---|---|
| TPS_PROXIMITY | The cursor is out of the context |
| TPS_QUEUE_ERR | The event queue for the context has overflowed |
| TPS_MARGIN | The cursor is in the margin of the context |
| TPS_GRAB | The cursor is out of the context, but the context has grabbed input |
| TPS_INVERT | The cursor is in its inverted state |
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.
Specifies which of the included packet data items have changed since the previously posted event.
Contains a serial number assigned to the packet by the context.
Specifies which cursor type generated the packet.
In absolute, contains the current button state. In relative mode, the low word contains a button number and the high word contains one of the following codes: TBN_NONE if there was no change in button state, TBN_UP if the button was released or TBN_DOWN if the button was pressed.
In absolute mode, contains the scaled cursor location along the x axis. In relative mode, contains the scaled change in cursor position.
In absolute mode, contains the scaled cursor location along the y axis. In relative mode, contains the scaled change in cursor position.
In absolute mode, contains the scaled cursor location along the z axis. In relative mode, contains the scaled change in cursor position.
In absolute mode, contains the adjusted state of the normal pressure. In relative mode, contains the change in adjusted pressure state.
In absolute mode, contains the adjusted state of the tangential pressure. In relative mode, contains the change in adjusted pressure state.
Specifies the clockwise rotation of the cursor about the z axis through a full circular range.
Specifies the angle with the x-y plane through a signed, semicircular range.
Specifies the clockwise rotation of the cursor about its own major axis.
Specifies the pitch of the cursor.
Specifies the roll of the cursor.
Specifies the yaw of the cursor.