EZTWAIN\README.TXT
rev 1.02  10/26/94 spike
rev 1.03  02/06/95 spike
rev 1.04  05/03/95 spike

New in Rev 1.04:
* FoxPro sample program, courtesy of Kevin Moreland!  See README.TXT
  in the foxpro subdirectory for more details.

* Added TWAIN_WriteNativeToFile and TWAIN_WriteNativeToFilename
  These routines make writing images to BMP files much easier,
  especially for those using higher-level languages like VB and FoxPro
 
* Added TWAIN_FreeNative, to provide a way to delete images without
  having to call the Windows GlobalFree directly.

* Added TWAIN_SetHideUI and TWAIN_GetHideUI to control display
  of the source user interface during acquisition.

* Added several TWAIN_SetCurrentXXX functions, to provide some control
  over scanning, especially when the source user interface is hidden.

* Removed call to TWAIN_NegotiateXferCount in TWAIN_AcquireNative.
  Some old sources can't handle this, and it isn't critical anyway.

* Enhanced error diagnosis in TWAIN_AcquireNative and in
  TWAIN_NegotiatePixelTypes.

* Revised TWERP (1.2) to use TWAIN_WriteNativeToFilename.

* Rearranged TWERP menus, added control of pixel type negotiation,
  and source U/I visibility.

New in Rev 1.03:
* Fixed bugs in TWAIN_WriteDibToFile - I don't know if that code
  would have worked for any source in the world!  Was I asleep or what?

* TWERP 1.1 now includes a Save As command in the file menu, to test
  and demonstrate TWAIN_WriteDibToFile.

* New MFC subdirectory, with an EZTWAIN-like C++ class for use with
  App Wizard & MFC.

New in Rev 1.02:
* Bug fix to TWAIN_ModalEventLoop, courtesy of Bill DeVoe of HP.
  This was a coding error where a local variable masked a global,
  causing EZTWAIN to fail when working with some HP datasources.
  This problem was also reported by David at LENTEC.

* Added to EZTWAIN.H:  A TWAIN_State() inquiry that returns the
  current TWAIN Protocol State.  Internally, EZTWAIN now tracks the
  state instead of keeping a bevy of booleans.

--------------- EZTWAIN.DLL for Windows 3.1 - Usage Notes

EZTWAIN.DLL is a Windows DLL that provides, as its name implies, an easy
interface to the TWAIN image acquisition protocol.

EZTWAIN functions are provided at several levels of abstraction:  At the
highest level, a single call will acquire an image and either return a
handle to it (as a DIB - Device Independent Bitmap) or place it in the
Windows clipboard.  There is also a single function that does all the work
of the 'Select Source' File menu item.

At the lowest level, there are functions to send individual triplets to the
Source Manager or to the currently open Data Source.  The full source code
of EZTWAIN.DLL is provided.


EZTWAIN is specifically designed to simplify the use of TWAIN in three cases:

** When the development language is not a mainstream C/C++ compiler - for
   example, Visual Basic, Application Basic, database programming languages,
   interpreted languages, Pascal, LISP, etc.

   With these languages, using the standard TWAIN.DLL entry point directly
   may be difficult or even impossible.  We hope that EZTWAIN.DLL will bridge
   this gap.

** When the image acquisition requirements are very simple.  Many developers
   just want to 'grab an image' without spending days or weeks understanding
   TWAIN (and its subtleties.)  For these developers, the full TWAIN protocol
   is expensive overkill - EZTWAIN.DLL may meet their needs with a much
   smaller learning and programming effort.

** Even skilled C programmers with weeks or months to spend on a full
   TWAIN implementation can still become frustrated trying to get their code
   to the point where it actually 'does something'.  Calling the high-level
   EZTWAIN functions should produce results in an hour or two, and then the
   high-level calls can be refined into calls to functions at lower and
   lower levels as needed to achieve more exotic effects.


------------------------------------
What is in the EZTWAIN subdirectory?
------------------------------------

There are two subdirectories - VB and WIN31.
The VB subdirectory contains a sample program in Microsoft Visual Basic 1.0
that calls EZTWAIN.DLL, with an accompanying README.TXT file.

Everything else is currently in the WIN31 subdirectory:

A binary EZTWAIN.DLL and EZTWAIN.LIB, ready to link & run

An include file EZTWAIN.H that declares and documents the EZTWAIN interface

A sample application, TWERP.EXE

Full C source, EZTWAIN.C and TWERP.C

Supporting files (.DEF, .RC, .ICO)

EZTWAIN.MAK and TWERP.MAK, Microsoft Visual C++ 1.0/1.5 project files

EZTWAIN.PRJ and TWERP.PRJ, Borland C++ 3.1 project files


--------------------------
How is EZTWAIN.DLL called?
--------------------------

The EZTWAIN interface was designed to have easy-to-remember names, to require
very few parameters to functions, and to not require the use of any data
structures (except the DIB image format.)  For the high-level functions,
passing 0 for all parameters is a good way to start.  

If you are programming in C or C++, examine EZTWAIN.H and TWERP.C to see
how the EZTWAIN functions are declared and called.  You may have to configure
your system to find the EZTWAIN.H file during compilation, the EZTWAIN.LIB
file during linking, and the EZTWAIN.DLL during execution.  For Microsoft
Visual C++ 1.0 and Borland C++ 3.1, these issues are taken care of if you
open the project files mentioned above - all the necessary files are in the
one subdirectory, so they are found automatically.

For other development platforms, you will have to study your documentation
to learn three things:

1. How to declare DLL functions to be called.

If your platform can do this, it will be covered in the documentation, and
almost any programming language for Windows has a way to do this.
There is sample code for Microsoft Visual Basic in another subdirectory.

2. How to link to the DLL.

For static languages like C, C++, Pascal, and so on, this is usually done
during linking and uses the EZTWAIN.LIB library.  Your documentation should
have a section on 'Linking to DLLs' or something of that sort.  For dynamic
languages like Basic, you may not have to do anything - there is no linking
process.

3. How to access the DLL at run-time.

Typically, for static languages that produce .EXE files, EZTWAIN.DLL will
have to be in either the same directory as the .EXE file, or somewhere in
the PATH.  For dynamic languages, I'm not sure in general - Visual Basic
seems to do no searching, so you have to tell it for every function exactly
where to find the DLL that contains that function.


--------------------------------------------------
How should I design TWAIN support into my program?
--------------------------------------------------

Start out by calling TWAIN_SelectImageSource - this call is simple, and
should be the easiest to debug.  Alternatively, you could put in code to
call TWAIN_IsAvailable.  Use the result of this call to disable, gray or
hide, or to enable your TWAIN facilities.

Then add the calls to TWAIN_AcquireNative or TWAIN_AcquireToClipboard.
Don't worry about passing proper Window handles at first.  Notice also
that TWAIN_AcquireNative will disable and re-enable your app window, once
you decide to pass it in.

Once you have Select Source and Acquire working in your program, then it's
just a matter of deciding how much more you want.  The simple behavior of
AcquireNative is attractive but limiting.  AcquireNative treats every
Data Source as modal - disabling & closing the source after a single image
is acquired.  To allow acquisition of multiple images, and to allow
modeless Data Sources to function properly, you will have to dig into
the source code for EZTWAIN and break it apart for use in your app.


---------------------------------------------------
What to do with problems, questions and suggestions
---------------------------------------------------

If your problem, question or suggestion would benefit or benefit from a wide
audience, send e-mail to twain@caere.com.  This mailing list goes out to a
large community of TWAIN developers.  Keep in mind that EZTWAIN.DLL has been
available since about July '94 - if this is August '94, not many people will
have it or even know about it.

If you have a specific problem to report, or a question or suggestion for the
developers of EZTWAIN, send an e-mail to twain-wg@caere.com.  This is
guaranteed to reach people who are responsible, to bother as few people as
possible, and it keeps EZTWAIN support independent of any single individual
or company.

If you use EZTWAIN, we would like to hear about your experience whether good
or bad - please send us a report at twain-wg@caere.com



Spike for the Working Group, Vashon WA, 10/26/94
