




CONTENTS
___________________________________________________________________________





Introduction . . . . . . . . . . . 1     WM_HEDITCTL and HE_CHAROFFSET .  6
Hardware requirements and basic          WM_SKB message  . . . . . . . .  6
limitations  . . . . . . . . . . . 1     SKN_TERMINATED  . . . . . . . .  7
Installation notes and                   REC_DEBUG . . . . . . . . . . .  7
procedures . . . . . . . . . . . . 2     clErrorLevel  . . . . . . . . .  7
  Installing the pen components--        Dictionary searches . . . . . .  8
  minimum  . . . . . . . . . . . . 2     rc.RectBound  . . . . . . . . .  8
    SYSTEM.INI changes . . . . . . 2     DRV_SetSamplingDist . . . . . .  8
  Installing the pen components--        RecognizeData and ink . . . . .  8
  complete . . . . . . . . . . . . 2     List of characters affected by
    SYSTEM.INI changes . . . . . . 3     ALC_PUNC  . . . . . . . . . . .  9
    PENWIN.INI changes . . . . . . 4     DLLs that use hedit and bedit
Shipping PENWIN.DLL with your            controls  . . . . . . . . . . .  9
application  . . . . . . . . . . . 4     Dictionary and recognizer ISVs:
Release notes  . . . . . . . . . . 5     When Windows ends . . . . . . .  9
  Hedits--delayed recogntion             SetAlcBitGesture,
  mode . . . . . . . . . . . . . . 5     ResetAlcBitGesture, and
  PostVirtualMouseEvent  . . . . . 6     IsAlcBitGesture removed . . . .  9
  ALC_USEBITMAP  . . . . . . . . . 6     REC_ error values from Recognize
  ProcessWriting . . . . . . . . . 6       . . . . . . . . . . . . . . .  9
  Microsoft user dictionary DLL  . 6     DIRQ_SUGGEST not implemented  . 10























                                     i






===========================================================================
Introduction
===========================================================================

                    Borland Pascal with Objects 7.0 contains the components
                    from Windows for Pen Computing to let you build and
                    test pen applications. A mouse can be used to get a
                    rough idea of how recognition and a pen will work.

                    However, we strongly recommended that you use Windows
                    for Pen Computing hardware (a pen, for example) during
                    the design and development process. This is critical
                    because a pen gives you an accurate feel for how an
                    application will work in real situations and because
                    the Microsoft Alphanumeric Recognition System (MARS)
                    has been optimized for a pen and won't work as well
                    with a mouse.



===========================================================================
Hardware requirements and basic limitations
===========================================================================

                    1. A driver for Microsoft-compatible mice has been
                       provided so you can do simple testing of pen
                       functionality. This pen driver is called
                       MSMOUSE.DRV.

                    2. At this time, only VGA displays can be used with the
                       pen extensions. The VGAP.DRV display driver is a
                       modified version of the VGA.DRV that supports
                       inking. It's required if you want to test pen
                       functionalities.

                    3. Handwriting recognition with a mouse will be much
                       less accurate than with digitizer hardware designed
                       specifically for Pen Computing. The recognizer has
                       been designed to work with pen computers and
                       peripherals with true digitizer input and its
                       associated high data rates and high data resolution.

                    4. The spell checking technology included in Windows
                       for Pens must be used exclusively for the purpose of
                       improving handwriting recognition. It is not to be
                       used by applications as a spell checker or spelling
                       corrector.






===========================================================================
Installation notes and procedures
===========================================================================



Installing the pen  =======================================================
components--minimum
                    This procedure will result in a system that will let
                    you build applications that contain hedit and bedit
                    controls - and call any Windows for Pen Computing API
                    functions. You will not be able to perform handwriting
                    recognition or see ink on the screen.

------------------  The following items must be added or changed in your
SYSTEM.INI changes  SYSTEM.INI file so that the pen extensions will work.
------------------  Note: Back up your old SYSTEM.INI file before
                    proceeding.

                    1. In the "[boot]" section:

                       a. Add "penwindows" to the list of drivers after the
                          "drivers=" key. For example:

                          drivers=mmsystem.dll penwindows

                    2. In the "[Drivers]" section:

                       a. Add a new item "penwindows" and set it equal to
                          the path to PENWIN.DLL. For example:

                          penwindows=C:\BP\PENWIN\PENWIN.DLL

                    When Windows is restarted PENWIN.DLL will be loaded as
                    an installed driver and you will be able to run
                    applications containing bedit and hedit controls and
                    call the Windows for Pen Computing functions in the
                    PenWin unit.


Installing the pen  =======================================================
components--complete
                    This procedure will result in a system that will run
                    pen applications and allow you to experiment with
                    handwriting recognition and inking functionalities in
                    your applications. Once again, interaction with the
                    mouse will prove inferior in every respect to
                    interaction with a true pen device--but this system of



                                   - 2 -






                    using the special mouse driver will allow you to
                    experiment and perform rudimentary testing of your pen
                    functionalities.


------------------  The following items must be added or changed in your
SYSTEM.INI changes  SYSTEM.INI file so that the pen extensions will work.
------------------  Note: Back up your old SYSTEM.INI file before
                    proceeding.

                    1. In the "[boot]" section:

                       a. Change the "display.drv=" line so that the
                          display driver is the pen capable VGAP.DRV
                          shipped with Borland Pascal with Objects 7.0.
                          For example:

                             display.drv=C:\BP\PENWIN\VGAP.DRV

                          Note: Only the VGA display device is supported by
                          the pen components.

                       b. Add "pen penwindows" to the list of drivers after
                          the "drivers=" key. For example:

                          drivers=mmsystem.dll pen penwindows

                       c. Change the "mouse.drv=" line so that it points to
                          YESMOUSE.DRV. For example:

                          mouse.drv=C:\BP\PENWIN\YESMOUSE.DRV

                    2. In the "[Drivers]" section:

                       a. Add a new item "pen" and set it equal to the path
                          to MSMOUSE.DRV. For example:

                          pen=C:\BP\PENWIN\MSMOUSE.DRV

                       b. Add a new item "penwindows" and set it equal to
                          the path to PENWIN.DLL. For example:

                          penwindows=C:\BP\PENWIN\PENWIN.DLL








                                   - 3 -






------------------  The PENWIN.INI file contains a number of initialization
PENWIN.INI changes  settings for Windows for Pen Computing.
------------------
                    There are also two explicit paths that must correctly
                    identify the locations of MARS.DLL and MARS.MOB. To
                    verify these paths, open PENWIN.INI with any generic
                    text editor (like the BPW IDE) and make sure the path
                    to MARS.DLL points to the current MARS.DLL location. Do
                    the same for MARS.MOB.

                    Once the paths are correct, the file should be copied
                    to the Windows 3.1 root - that is, the directory
                    containing the Windows 3.1 WIN.COM.



===========================================================================
Shipping PENWIN.DLL with your application
===========================================================================

                    PENWIN.DLL is a fully redistributable component of
                    Windows for Pen Computing. Because applications will
                    seek to leverage the Pen API - hedit and bedit controls
                    in particular - PENWIN.DLL can be shipped with your
                    application. There are some considerations to keep in
                    mind in shipping PENWIN.DLL with your application:

                    1. PENWIN.DLL functions ONLY under Windows 3.1. It WILL
                       NOT WORK with Windows 3.0 because it functions only
                       as an installable device driver - a feature not
                       present in Windows 3.0.

                    2. As with other redistributable components such as
                       COMMDLG.DLL and the OLE libraries, it is the
                       responsibility of the application vendor to
                       determine whether PENWIN.DLL has already been
                       installed (there is a GetSystemMetrics call for
                       this) and to ensure that the version of PENWIN.DLL
                       with the latest version stamping is the one that is
                       running. These issues are the same for all
                       redistributable components, and further information
                       is in the README file.

                    3. Unlike some of the other redistributable components,
                       if your application installs PENWIN.DLL for the
                       first time, or replaces the current version with a





                                   - 4 -






                       later one, Windows will have to be restarted. As an
                       installable driver PENWIN.DLL can be loaded only at
                       Windows boot time. Restarting Windows can be
                       accomplished via an ExitWindows call or by simply
                       prompting the user to do so.

                       Note: To install PENWIN.DLL on a Windows 3.1 system
                       follow the "Minimum" procedure listed above.

                    4. PENWIN.DLL may be in either the \WINDOWS or the
                       \WINDOWS\SYSTEM directory. The default will be
                       \WINDOWS but since Windows for Pen Computing is an
                       OEM product, you cannot control where PENWIN.DLL is
                       located on a particular machine.



===========================================================================
Release notes
===========================================================================

                    Release Notes for the Microsoft(R) Windows for Pen
                    Computing Programmer's Reference, version 1.00 (C)
                    Copyright 1992 Microsoft Corporation.

                    This section contains release notes for version 1.00 of
                    the Microsoft(R) Windows for Pen Computing Programmer's
                    Reference. The information in this section is more
                    current than the information in the manual. Where this
                    file conflicts with printed documentation, you should
                    assume that this file is correct.

                    Microsoft revises its documentation at the time of
                    reprinting; the manuals and online help files may
                    already include some of this information.

   Hedits--delayed  =======================================================
   recogntion mode
                    Setting focus in hedit causes any text in the control
                    to appear even if the control is in "ink" mode. If this
                    is undesireable the control should never be allowed to
                    get the focus.

                    Sending an hedit the WM_HEDITCTL message with the
                    HE_SETINKMODE parameter will clear the hedit's text
                    buffer. The same message to a bedit will preserve the
                    control's text contents.




                                   - 5 -






PostVirtualMouseEvent======================================================

                    Values greater than the maximum resolution in X
                    direction (usually 640) and max resoultion Y direction
                    (usually 480) will overflow.

     ALC_USEBITMAP  =======================================================

                    The Microsoft recognizer does not implement
                    ALC_USEBITMAP in the alcPriority field for version 1.0.
                    Note that alcPriority is implemented for the alc field.

    ProcessWriting  =======================================================

                    In the description of ProcessWriting, it says "The
                    window specified by the hwnd parameter receives a
                    WM_PARENTNOTIFY message when ProcessWriting destroys
                    its inking window."

                    The window never gets the WM_PARENTNOTIFY message since
                    it is not
                    guaranteed that an inking window is created.

    Microsoft user  =======================================================
    dictionary DLL
                    The documentation incorrectly states that up to 16
                    dictionaries can be loaded.

                    MSSPELL.DLL actually allows only six wordlists to be
                    loaded. Consequently, version 1.00 of the Microsoft
                    User Dictionary DLL allows only six wordlists to be
                    loaded at a time.

   WM_HEDITCTL and  =======================================================
     HE_CHAROFFSET
                    Under the documentation for WM_HEDITCTL messages, under
                    HE_CHAROFFSET, it says "See the related HE_CHAROFFSET."
                    It should say "See the related HE_CHARPOSITION."

    WM_SKB message  =======================================================

                    When the state of the SKB changes, a WM_SKB message is
                    posted. The documentation says that the LOWORD of the
                    lParam contains information on what changed and that
                    the HIWORD contains the window handle of the SKB.






                                   - 6 -






                    Actually, the LOWORD contains the hWnd and the HIWORD
                    contains the information on what changed.

                    This should be corrected in two places: in the
                    ShowKeyboard function and in the WM_SKB message
                    documentation.

                    Also, one more value should be mentioned: the HIWORD of
                    lParam contains SKN_TERMINATED (value $FFFF) if the
                    keyboard has been closed.

    SKN_TERMINATED  =======================================================

                    WM_SKB sends SKN_TERMINATED in HIWORD(lParam) when
                    terminating SKN_TERMINATED ($FFFF) is sent in the
                    HIWORD(lParam) when the WM_SKB is sent to notify top-
                    level windows that the On-Screen Keyboard is being
                    terminated. This needs to be added to the documentation
                    for the WM_SKB message and for the ShowKeyboard
                    function.

         REC_DEBUG  =======================================================

                    In the Guide to Pen Programming, Chapter 11 "Pen
                    Messages and
                    Constants," under REC_ Values, under Debugging Values,
                    it says:

                    "REC_DEBUG All debugging return values are less than
                    this."

                    It should say:

                    "REC_DEBUG All debugging return values are less than or
                    equal
                    to this."

      clErrorLevel  =======================================================

                    The documentation for the RC field clErrorLevel says
                    that this value can range from 0 to 100. In the
                    PENWIN.PAS file, the minimum CL value is defined as

                     const
                       cl_Minimum = 1;

                    The correct minimum for clErrorLevel is 1




                                   - 7 -






        Dictionary  =======================================================
          searches
                    The documentation is somewhat confusing on the point of
                    dictionary enumeration procedures in Chapter 7, page
                    103. To expound:

                    If there are ten dictionaries in the dictionary path,
                    and the ninth finds a match for a particular
                    enumeration in a symbol graph, the remaining symbol
                    graph elements will still be enumerated - checking for
                    a match in a higher-order dictionary. In other words,
                    the other eight dictionaries before the ninth
                    dictionary in the list will get a shot at finding a
                    "better" match. Enumeration of dictionaries therefore
                    can be said to stop only when the symbol graph is
                    exausted, or the first dictionary in the list responds
                    affirmatively to a query.


      rc.RectBound  =======================================================

                    Here is additional detail on the rectBound element of
                    the RC structure.

                    rc.rectBound will be ignored if PCM_RECTBOUND is not
                    set. The documentation suggests on page 237 that
                    rc.lPcm = PCM_RECTBOUND only determines how the
                    recognition context will end.

DRV_SetSamplingDist =======================================================

                    Page 226 of Chapter 10 - PENINFO structure:

                    In the notes after nSamplingRate and nSamplingDist, the
                    driver messages that manipulate these fields are
                    misnamed. In the printed documentation, they are named
                    DRV_SetSamplingDist and DRV_SetSamplingRate; they are
                    actually DRV_SetPenSamplingDist and
                    DRV_SetPenSamplingRate.

 RecognizeData and  =======================================================
               ink
                    Calls to RecognizeData may return an rcresult that
                    references pendata different than that used as a
                    Parameter to the call. For example, Strokes may be
                    removed and the rgbInk and nInkWidth fields of the
                    PENDATAHEADER may not match the values in the original




                                   - 8 -






                    pendata, as no inking has taken place during this
                    recognition context.

List of characters  =======================================================
       affected by
          ALC_PUNC  On page 253 of the documentation, the list of chars in
                    ALC_PUNC has two semicolons; one of these should be a
                    colon.

     DLLs that use  =======================================================
   hedit and bedit
          controls  Any DLL that creates an hedit or bedit control must
                    have a nonzero heap size. This is because those
                    controls allocate buffers out of this heap.

    Dictionary and  =======================================================
  recognizer ISVs:
 When Windows ends  When a Windows session is about to end, PENWIN.DLL
                    takes the following actions:

                    o Calls all the dictionaries in the global recognition
                      context with a DIRQ_CLEANUP message and then frees
                      the corresponding DLLs.

                    o Calls the CloseRecognizer function for the current
                      recognizer and frees the corresponding DLL.

                    Dictionaries and recognizers can take the appropriate
                    cleanup action at this time. The limitations on things
                    that can be done are the same as those when an
                    application receives a WM_ENDSESSION message.

 SetAlcBitGesture,  =======================================================
ResetAlcBitGesture,
               and  The Windows for Pen Computing Programmer's Reference
   IsAlcBitGesture  refers to the above macros. They have been removed
           removed  because the ability to set alc bits for gestures was
                    not implemented.

 REC_ error values  =======================================================
   from Recognize
                    In the documentation for Recognize API and REC_ values
                    in Chapter 11, there is a Debugging values section.
                    There is a sentence that reads: "All of the values
                    listed in the following table are in debug version
                    only." That sentence should be replaced with the
                    following: "All of the values below are providing for
                    debugging information. A well-behaved application



                                   - 9 -






                    should not specify an RC that causes any of these
                    values to be returned."

  DIRQ_SUGGEST not  =======================================================
       implemented
                    In version 1.0 of Windows for Pens, the dictionary
                    shipped with the system does not support DIRQ_SUGGEST.












































                                  - 10 -

