8/12/2019 WINPEN

1/12

CONTENTS___________________________________________________________________________

Introduction . . . . . . . . . . . 1 WM_HEDITCTL and HE_CHAROFFSET . 6Hardware requirements and basic WM_SKB message . . . . . . . . 7limitations . . . . . . . . . . . 1 SKN_TERMINATED . . . . . . . . 7Installation notes and REC_DEBUG . . . . . . . . . . . 7procedures . . . . . . . . . . . . 2 clErrorLevel . . . . . . . . . 8 Installing the pen components-- Dictionary searches . . . . . . 8 minimum . . . . . . . . . . . . 2 rc.RectBound . . . . . . . . . 8 SYSTEM.INI changes . . . . . . 2 DRV_SetSamplingDist . . . . . . 9 Installing the pen COMPONENTS-- RecognizeData and ink . . . . . 9 complete . . . . . . . . . . . . 2 List of characters effected by SYSTEM.INI changes . . . . . . 3 ALC_PUNC . . . . . . . . . . . 9 PENWIN.INI changes . . . . . . 4 DLLs that use hedit and bedit

Shipping PENWIN.DLL with your controls . . . . . . . . . . . 9application . . . . . . . . . . . 4 Dictionary and recognizer ISVs:Release notes . . . . . . . . . . 5 When Windows ends . . . . . . . 9 Hedits--delayed recogntion SetAlcBitGesture, mode . . . . . . . . . . . . . . 5 ResetAlcBitGesture, and PostVirtualMouseEvent . . . . . 6 IsAlcBitGesture removed . . . . 10 ALC_USEBITMAP . . . . . . . . . 6 REC_ error values from Recognize ProcessWriting . . . . . . . . . 6 . . . . . . . . . . . . . . . 10 Microsoft user dictionary DLL . 6 DIRQ_SUGGEST not implemented . 10

i

8/12/2019 WINPEN

2/12

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

Borland C++ contains sufficient components from Windows for Pen Computing to let you to 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) shipped with Borland C++ 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.

8/12/2019 WINPEN

3/12

===========================================================================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 yourSYSTEM.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:\BORLANDC\REDIST\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 APIs.

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 -

8/12/2019 WINPEN

4/12

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 yourSYSTEM.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 C++. For example:

display.drv=C:\BORLANDC\REDIST\VGAP.DRV

Only the VGA display device is supported by the pen components in Borland C++.

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:\BORLANDC\REDIST\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:\BORLANDC\REDIST\MSMOUSE.DRV

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

penwindows=C:\BORLANDC\REDIST\PENWIN.DLL

- 3 -

8/12/2019 WINPEN

5/12

------------------ The PENWIN.INI file contains a number of initializationPENWIN.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. INSTALL will add the correct paths to PENWIN.INI but if you move any files, open PENWIN.INI with any generic text editor (like Windows Notepad) and change the path to MARS.DLL and MARS.MOB so that it correctly identifies points to the correct location.

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 BWCC.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.

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 later one, Windows will have to be restarted. As an

- 4 -

8/12/2019 WINPEN

6/12

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.

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, Microsoft cannot completely 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 -

8/12/2019 WINPEN

7/12

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."

- 6 -

8/12/2019 WINPEN

8/12

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.

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

This should be corrected in two places: 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 0xffff) if the keyboard has been closed.

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

WM_SKB sends SKN_TERMINATED in HIWORD(lParam) when terminating SKN_TERMINATED (0xffff) 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."

- 7 -

8/12/2019 WINPEN

9/12

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

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

#define CL_MINIMUM 1

The correct minimum for clErrorLevel is 1

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.

- 8 -

8/12/2019 WINPEN

10/12

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 pendata, as no inking has taken place during this recognition context.

List of characters ======================================================= effected 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.

- 9 -

8/12/2019 WINPEN

11/12

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 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 -

8/12/2019 WINPEN

12/12