4.15. wintab — Wrapper around the Wintab Developer Kit
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.
-
cgkit.wintab.available()
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.
-
cgkit.wintab.info(category)
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 |
... |
4.15.1. Context class
The Context class provides the interface to the tablet driver.
-
class cgkit.wintab.Context
- 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
- Context name.
-
Context.options
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 |
-
Context.status
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 |
-
Context.locks
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 |
-
Context.msgbase
- Base number for the message IDs.
-
Context.device
- Specifies the device whose input the context processes.
-
Context.pktrate
- Specifies the desired packet report rate in Hertz. Once the context is open,
this field will contain the actual report rate.
-
Context.pktdata
- Specifies which optional data items will be in packets returned from the
context.
-
Context.pktmode
- 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.
-
Context.movemask
- Specifies which packet data items can generate move events in the context.
-
Context.btndnmask
- Specifies the buttons for which button press events will be processed in the
context.
-
Context.btnupmask
- Specifies the buttons for which button release events will be processed in the
context.
-
Context.inorgx
- Specifies the origin of the context’s input area in the tablet’s native
coordinates along the x axis.
-
Context.inorgy
- Specifies the origin of the context’s input area in the tablet’s native
coordinates along the y axis.
-
Context.inorgz
- Specifies the origin of the context’s input area in the tablet’s native
coordinates along the z axis.
-
Context.inextx
- Specifies the extent of the context’s input area in the tablet’s native
coordinates along the x axis.
-
Context.inexty
- Specifies the extent of the context’s input area in the tablet’s native
coordinates along the y axis.
-
Context.inextz
- Specifies the extent of the context’s input area in the tablet’s native
coordinates along the z axis.
-
Context.outorgx
- Specifies the extent of the context’s output area in context output coordinates
along the x axis.
-
Context.outorgy
- Specifies the extent of the context’s output area in context output coordinates
along the y axis.
-
Context.outorgz
- Specifies the extent of the context’s output area in context output coordinates
along the z axis.
-
Context.outextx
- Specifies the extent of the context’s output area in context output coordinates
along the x axis.
-
Context.outexty
- Specifies the extent of the context’s output area in context output coordinates
along the y axis.
-
Context.outextz
- Specifies the extent of the context’s output area in context output coordinates
along the z axis.
-
Context.sensx
- Specifies the relative-mode sensitivity factor for the x axis.
-
Context.sensy
- Specifies the relative-mode sensitivity factor for the y axis.
-
Context.sensz
- Specifies the relative-mode sensitivity factor for the z axis.
-
Context.sysmode
- Specifies the system cursor tracking mode. True specifies absolute,
False means relative.
-
Context.sysorgx
- Specifies the origin in screen coordinates of the screen mapping area for system
cursor tracking.
-
Context.sysorgy
- Specifies the origin in screen coordinates of the screen mapping area for system
cursor tracking.
-
Context.sysextx
- Specifies the extent in screen coordinates of the screen mapping area for system
cursor tracking.
-
Context.sysexty
- Specifies the extent in screen coordinates of the screen mapping area for system
cursor tracking.
-
Context.syssensx
- Specifies the system-cursor relative-mode sensitivity factor for the x axis.
-
Context.syssensy
- Specifies the system-cursor relative-mode sensitivity factor for the y axis.
Other attributes:
-
Context.queuesize
- 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.
-
Context.id_packet
- The final id of the WT_PACKET message.
-
Context.id_csrchange
- The final id of the WT_CSRCHANGE message.
-
Context.id_ctxopen
- The final id of the WT_CTXOPEN message.
-
Context.id_ctxclose
- The final id of the WT_CTXCLOSE message.
-
Context.id_ctxupdate
- The final id of the WT_CTXUPDATE message.
-
Context.id_ctxoverlap
- The final id of the WT_CTXOVERLAP message.
-
Context.id_proximity
- The final id of the WT_PROXIMITY message.
-
Context.id_infochange
- The final id of the WT_INFOCHANGE message.
Methods:
-
Context.open(hwnd, enable)
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.
-
Context.restore(hwnd, saveinfo, enable)
- 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.
-
Context.close()
- Closes the context if it was open (or do nothing if it was already closed or if
it was not open at all).
-
Context.save()
- Returns a binary saveinfo string containing the current context state. This
string can be used as argument to the restore() method.
-
Context.packet(serial)
- Returns the packet with the specified serial number.
-
Context.enable(flag)
- If flag is True the context is enabled, otherwise it is disabled. Returns
True if the operation was successful.
-
Context.overlap(totop)
- 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.
-
Context.config(hwnd=0)
- 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.
-
Context.get()
- Update the local context attributes.
-
Context.set()
- Update the tablet context with the settings stored in the local context
attributes.
-
Context.packetsGet(maxpkts)
- Return the next maxpkts packets and remove them from the queue.
-
Context.packetsPeek(maxpkts)
- Return the next maxpkts packets without removing them from the queue.
-
Context.dataGet(begin, end, maxpkts)
- 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.
-
Context.dataPeek(begin, end, maxpkts)
- This is the same as dataGet() but it doesn’t remove the packets from the
queue.
-
Context.queuePacketsEx()
- Returns the serial numbers of the oldest and newest packets currently in the
queue.
4.15.2. Packet class
-
class cgkit.wintab.Packet
-
Packet.pktdata
- 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.
-
Packet.context
- Specifies the context that generated the event.
-
Packet.status
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 |
-
Packet.time
- 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.
-
Packet.changed
- Specifies which of the included packet data items have changed since the
previously posted event.
-
Packet.serial
- Contains a serial number assigned to the packet by the context.
-
Packet.cursor
- Specifies which cursor type generated the packet.
-
Packet.buttons
- 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.
-
Packet.x
- In absolute mode, contains the scaled cursor location along the x axis. In
relative mode, contains the scaled change in cursor position.
-
Packet.y
- In absolute mode, contains the scaled cursor location along the y axis. In
relative mode, contains the scaled change in cursor position.
-
Packet.z
- In absolute mode, contains the scaled cursor location along the z axis. In
relative mode, contains the scaled change in cursor position.
-
Packet.normalpressure
- In absolute mode, contains the adjusted state of the normal pressure. In
relative mode, contains the change in adjusted pressure state.
-
Packet.tangentpressure
- In absolute mode, contains the adjusted state of the tangential pressure. In
relative mode, contains the change in adjusted pressure state.
-
Packet.orient_azimuth
- Specifies the clockwise rotation of the cursor about the z axis through a full
circular range.
-
Packet.orient_altitude
- Specifies the angle with the x-y plane through a signed, semicircular range.
-
Packet.orient_twist
- Specifies the clockwise rotation of the cursor about its own major axis.
-
Packet.rot_pitch
- Specifies the pitch of the cursor.
-
Packet.rot_roll
- Specifies the roll of the cursor.
-
Packet.rot_yaw
- Specifies the yaw of the cursor.