244 lines
10 KiB
Plaintext
244 lines
10 KiB
Plaintext
------------------------------- readme.txt -------------------------------
|
|
|
|
Wintab(tm) Programmer's Kit V. 1.26 for 16- and 32-bit Windows APIs.
|
|
|
|
This file contains programmer's kit installation instructions and
|
|
programming notes.
|
|
|
|
Please direct your programming questions and comments to:
|
|
|
|
LCS/Telegraphics
|
|
150 Rogers St.
|
|
Cambridge, MA 02142
|
|
voice: (617) 225-7970
|
|
fax: (617) 225-7969
|
|
email: wintab@pointing.com
|
|
web site: http://www.pointing.com
|
|
ftp site: ftp://ftp.pointing.com/pointing/Wintab/
|
|
|
|
Questions or problems regarding specific devices or device drivers
|
|
should be directed to the device manufacturer.
|
|
|
|
--------------------------------------------------------------------------
|
|
Legal/Disclaimer
|
|
--------------------------------------------------------------------------
|
|
|
|
The Wintab specification is intended to be an open standard. The
|
|
Wintab Programmer's Kit is an aid to understanding the Wintab
|
|
standard and implementing Wintab-compliant applications. As such,
|
|
the text and information contained herein may be freely used, copied,
|
|
or distributed without compensation or licensing restrictions.
|
|
|
|
The Wintab Programmer's Kit is copyright 1991-1998 by
|
|
LCS/Telegraphics.
|
|
|
|
LCS/Telegraphics does not assume any liability for damages resulting
|
|
from the use of the information contained herein.
|
|
|
|
--------------------------------------------------------------------------
|
|
Installation
|
|
--------------------------------------------------------------------------
|
|
|
|
* Getting the latest Wintab driver files
|
|
|
|
To get the latest Wintab driver files, including WINTAB.DLL and
|
|
WINTAB32.DLL, contact your device manufacturer. Follow the
|
|
manufacturer's installation directions.
|
|
|
|
* Installing the development files
|
|
|
|
The files are in several subdirectories on this disk. To copy the
|
|
whole tree to your hard disk, use XCOPY with the /S flag.
|
|
|
|
Example:
|
|
xcopy a:\*.* c:\wintab\ /s
|
|
|
|
* Installing the sample programs and testing your configuration
|
|
|
|
To test your Wintab driver configuration, build and run the
|
|
sample programs. (Previous versions of this kit included executable
|
|
of all the samples, but as Windows platforms proliferate, these have
|
|
been dropped to control the size of the kit.) The source code for
|
|
the programs is in stored in subdirectories by program name.
|
|
|
|
* Project settings for WTKIT
|
|
All projects require that the LIB and INCLUDE variables point to
|
|
the appropriate Windows SDK directories. Also, the WINTAB variable
|
|
must point to a tree containing the LIB and INCLUDE subtrees from the
|
|
Wintab Programmer's Kit.
|
|
|
|
For example, in MSVC 5.0, under the Tools menu, Options setting,
|
|
the WINTAB\INCLUDE directory must be listed as a directory for
|
|
Include files, and the WINTAB\LIB\I386 must be listed as a directory
|
|
for library files. Also, please see the note about linker warnings
|
|
during the debug build under the WNTAB32X.LIB section of this document.
|
|
|
|
* Compiler notes
|
|
Makefiles compatible with Microsoft NMAKE are in the win16
|
|
subdirectories. Project files for Microsoft Visual C versions 4.2
|
|
and 5.0 are in the win32 subdirectories.
|
|
|
|
MSVC 5.0 will be able to compile all the projects.
|
|
|
|
MSVC 4.2 will not be able to compile MFC_DEMO and WTHOOK
|
|
projects.
|
|
|
|
* Cleaning intermediate files before switching targets
|
|
Please cleanup intermediate files between builds to different targets.
|
|
If you have built the programs from source for one target environment,
|
|
and wish to switch to another target, first run the command NMAKE
|
|
CLEANALL in the source subdirectories.
|
|
|
|
--------------------------------------------------------------------------
|
|
Using WINTABX.LIB and WNTAB32X.LIB
|
|
--------------------------------------------------------------------------
|
|
|
|
Two types of import libraries are provided. WINTAB.LIB and
|
|
WINTAB32.LIB are regular import libraries created with the SDK
|
|
utilities. Any module linked with WINTAB.LIB or WINTAB32.LIB will not
|
|
load unless Wintab API support is present. WINTABX.LIB and
|
|
WNTAB32X.LIB are more flexible. They link each function as it is
|
|
invoked, using the Windows functions LoadLibrary and GetProcAddress.
|
|
If the link fails, the user will see a message box saying "cannot
|
|
find WINTAB.DLL", and the function will return 0 (the failure code
|
|
for all WINTAB functions) to its caller. Thus, WINTABX and WNTAB32X
|
|
provide the flexibility of run-time linking, while reducing the code
|
|
burden.
|
|
|
|
WINTABX and WNTAB32X do add one new requirement, though. Since Wintab
|
|
was explicitly linked using LoadLibrary, it must be explicitly freed
|
|
using FreeLibrary when shutting down. WINTABX and WNTAB32X provide a
|
|
new function, _UnlinkWintab, that calls FreeLibrary and resets the
|
|
automatic function-linking mechanism. The C declaration is included
|
|
in the header file WINTABX.H.
|
|
|
|
If you want to avoid the "cannot find WINTAB.DLL" message when Wintab
|
|
is not present, you can use the Windows function SetErrorMode() to
|
|
suppress the error box while issuing a Wintab function call. For
|
|
example:
|
|
|
|
BOOL WintabHere(void)
|
|
{
|
|
/*-----
|
|
Call this function before any Wintab API
|
|
function when using WINTABX.LIB.
|
|
|
|
This function returns TRUE if Wintab is
|
|
present and functioning; FALSE otherwise.
|
|
No warning message will be displayed if
|
|
the WINTAB.DLL file is not found.
|
|
-----*/
|
|
|
|
WORD errmode;
|
|
BOOL fResult;
|
|
|
|
/* suppress error box */
|
|
errmode = SetErrorMode(SEM_NOOPENFILEERRORBOX
|
|
#ifdef WIN32
|
|
| SEM_FAILCRITICALERRORS
|
|
#endif
|
|
);
|
|
|
|
/* try wintab */
|
|
fResult = WTInfo(0,0,NULL);
|
|
|
|
/* restore previous error mode */
|
|
SetErrorMode(errmode);
|
|
|
|
/* return wintab result */
|
|
return fResult;
|
|
}
|
|
|
|
*Note on MSVC 5.0 projects using WNTAB32X.LIB
|
|
Note that the linker warning LNK4098 (to recompile with the
|
|
/Nodefaultlib:LIBC option) during the compilation of Debug projects
|
|
will not affect the operation of the resulting executable. This bug
|
|
will be fixed in the next version of the Wintab Programmer's Kit.
|
|
For example, the WTHOOK project will give this linker warning during
|
|
debug compilation, but the resulting executable is functional.
|
|
|
|
--------------------------------------------------------------------------
|
|
Determining whether 1.1 features are supported
|
|
--------------------------------------------------------------------------
|
|
|
|
To determine which version of the Wintab specification your device
|
|
supports, use the result of the following function call:
|
|
WTINFO(WTI_INTERFACE,IFC_SPECVERSION)
|
|
Please see MGRTEST for an example.
|
|
The specification version number (either 1.0 or 1.1) will be
|
|
returned. If you need 1.1 features for your application, and you want to
|
|
make sure they are supported in a tablet, please email us at
|
|
wintab@pointing.com
|
|
|
|
--------------------------------------------------------------------------
|
|
Using Non-Microsoft C Compilers
|
|
--------------------------------------------------------------------------
|
|
|
|
WINTAB.LIB and WINTAB32.LIB are implicit import libraries created and
|
|
tested with Microsoft C tools. Some linkers from other vendors may
|
|
not work with these versions of the libraries. This Programmer's Kit
|
|
now includes the corresponding WINTAB.DEF and WINTAB32.DEF files used
|
|
to create WINTAB.LIB and WINTAB32.LIB. Use the .DEF files with your
|
|
vendor's IMPLIB or librarian tools to create compatible import
|
|
libraries.
|
|
|
|
WINTABX.LIB and WNTAB32X.LIB have been tested with Microsoft C, but
|
|
not with other C or C++ compilers, or compilers for other languages.
|
|
Source code for these libraries are in the directories WINTABX and
|
|
WNTAB32X.
|
|
|
|
--------------------------------------------------------------------------
|
|
RULE and RULE2
|
|
--------------------------------------------------------------------------
|
|
|
|
Rule and Rule2 are versions of the same program. Rule demonstrates
|
|
the limitations of a polled input approach in Windows; Rule2
|
|
demonstrates a more robust, message-based approach, and adds a few
|
|
other enhancements.
|
|
|
|
To see what's bad about Rule, run it, click on it but don't start
|
|
measuring. Now turn off your Wintab device. Windows is now hung.
|
|
|
|
If you try the same experiment with Rule2, you can still use the
|
|
keyboard.
|
|
|
|
--------------------------------------------------------------------------
|
|
MGRTEST as a Debugging Aid
|
|
--------------------------------------------------------------------------
|
|
|
|
Besides demonstrating the WTMgr* APIs, MGRTEST is useful in itself.
|
|
You can use MGRTEST to see what contexts are active, their modes,
|
|
status, and active areas, as well as the current overlap order. It
|
|
can be very useful in understanding how various Wintab-aware programs
|
|
use contexts.
|
|
|
|
--------------------------------------------------------------------------
|
|
Keeping in Touch
|
|
--------------------------------------------------------------------------
|
|
|
|
Here are three ways to show your support for the Wintab standard, and
|
|
allow us to let people know that your product has Wintab support.
|
|
|
|
1. When you complete Wintab support in your product, let us know. Be
|
|
sure to include the product name, a description, and contact
|
|
information for your company.
|
|
|
|
2. If possible, send us an evaluation copy of your product, or the
|
|
portions of it that contain Wintab support. LCS/Telegraphics is
|
|
building a library of Wintab-compliant applications for ongoing
|
|
compatibility testing.
|
|
|
|
3. Join the Committee for Advanced Pointing Standards (CAPS). CAPS
|
|
formed in August of 1993 to promote and support future development of
|
|
the specification. The more than 40 corporate members of CAPS
|
|
include most major pointing device manufacturers, and many leading
|
|
CAD and graphics arts software developers. To join CAPS, contact:
|
|
|
|
LCS/Telegraphics
|
|
150 Rogers St.
|
|
Cambridge, MA 02142
|
|
voice: (617) 225-7970
|
|
fax: (617) 225-7969
|
|
email: caps@pointing.com
|
|
web site: http://www.pointing.com
|