Copyright © 1992, Dr. Dobb's Journal

Copyright © 1992, Dr. Dobb's Journal

Copyright © 1992, Dr. Dobb's Journal

Copyright © 1992, Dr. Dobb's Journal

This article contains the folowing executables: PENCKBK.ARC

Moshe Lichtman

You've undoubtedly noticed a number of recent DDJ articles on programming Windows applications using various flavors of Basic--Visual Basic, GFA Basic, and the like. In this article, I carry that discussion into the realm of pen-based application development by presenting an overview of the pen extensions to the Microsoft Windows 3.1 API. I then describe how custom controls make this new API accessible to Visual Basic applications, and how they can turn conventional Visual Basic programs into pencentric applications.

"Windows for Pens" is the name given to a set of extensions to Version 3.1 of Microsoft Windows. Windows for Pens adds about 70 new functions that support pen-based applications to the existing 600-plus functions in the Windows 3.1 API.

To create a standard Windows application using Visual Basic, you interactively design its interface by dragging and placing GUI elements, known as "controls," onto a layout form. You specify the behavior of your application by attaching Visual Basic code to these controls. Programmers can extend the default functionality in Visual Basic by means of custom controls. Custom controls are similar to Windows controls and are typically written in C, following the specifications in the Visual Basic Control Development Kit (CDK). Once created, custom controls are basically indistinguishable from controls included with the product.

The pen-oriented custom controls added to Visual Basic provide a high-level, interactive way of creating pencentric programs. Although some pencentric applications need to use the full Windows for Pens API (for example, a calligraphy program that relies on device-specific information such as stylus pressure and angle), the needs of most pencentric applications can be satisfied with less functions. These commonly used functions are found in the Windows for Pens custom controls and are contained in the file pencntrl.vbx. Currently, this file is available only as part of the Windows 3.1 Pen SDK, but future versions of Visual Basic will include these controls as an integral part of the development environment.

The BEdit and HEdit custom controls replace the standard Visual Basic text-input controls. HEdit is a pen-enhanced version of the text-box control. It supports most of the regular text-box properties and adds the handwriting and inking capabilities from the Windows for Pens API. When running, it accepts handwriting input and displays the corresponding recognized text. Many of the initial pen applications will be form based, so the HEdit has an additional BorderStyle setting, Underline, which applies only to single-line controls.

BEdit, or "boxed edit" control, is a superset of HEdit and provides the application with comb or box style guides that accept pen input. Each segment or box accepts only a single character of input. The BEdit control is used to work around the limitations of today's recognition algorithms. BEdit provides important baseline and segmentation information to the recognizer. By dividing up handwritten text into single characters placed one at a time into box or comb guides, users write more neatly, and recognition accuracy is significantly enhanced. BEdit properties control the size of the BEdit cells, their shape (box or comb), and the number of rows and columns in a certain control. BEdit is for fields which accept a predefined text length. For example, phone numbers will typically not exceed 15 characters.

Unlike typed text, the size of which is controlled by the application, handwriting size depends solely on user habits. Users tend to write larger because of the limited resolution and display quality found in today's pen computers. Pen applications address this problem by allowing inking in areas that extend beyond the displayed input box. This area is sometimes called the "gray area." Its size is controlled via the "Inflate" properties, of which there are four: InflateBottom, InflateLeft, InflateRight, and InflateTop. The gray area becomes active only when the associated control receives focus (which indicates that the user has started inking inside the visible boundary). In delayed-recognition mode, the gray area is not active: ink can then be drawn only inside the visible boundary.

It's no secret that present handwriting-recognition engines, even with accuracy levels as high as 95 percent, are far from perfect. Pencentric applications should be designed to minimize text entry and to utilize contextual information during the recognition process. One popular method for enhancing recognition accuracy is to constrain the character set for a particular field. For example, there is no point in allowing alphabetic characters in a social-security number field. By constraining the allowed character set in the social-security number field to numerical only, we avoid misrecognizing "Z" for "2" and "O" for "0" (zero).

In Visual Basic, you can use the CharSet property, which accepts the settings: ALC_DEFAULT, ALC_LCALPHA, ALC_UCALPHA, ALC_NUMERIC, ALC_PUNC, ALC_MATH, ALC_MONETARY, ALC_OTHER, and ALC_WHITE. These settings can be ORed together and are controlled either at design time via a custom dialog, or at run time.

Ink is an exciting feature unique to pen applications. The ability to capture, store, manipulate, and display ink opens up new application categories as well as adding a new dimension to existing "text-centric" applications. Visual Basic supports inking via the DelayedRecog property. When set to True, all writing in the control remains as ink until the property is set to False. When it is changed from True to False, the OnTap property is examined. If OnTap is True, recognition of the collected ink will take place when the user taps on the control with the pen. The pen custom controls incorporate two new events: the RcResult and the Update. The RcResult event occurs whenever the control receives recognition results from the recognizer. The returned result is a pointer to the RcResult structure (Recognition Context), which forms a central part of the Windows for Pens API. The RcResult structure contains a symbol graph that describes the possible results from the ink, a handle to the ink, and the best guess at the symbols. If DelayedRecog is True, the RcResult structure does not contain any information about recognized symbols.

The Update event occurs before the control redraws the data. This differs from the Change event, which redraws the data before it occurs. Update can be used to format data so that flashes do not appear.

Aside from allowing quick erasing of the ink via the EraseInk method, Visual Basic currently does not provide sophisticated ink-handling methods. To add advanced functions such as ink selection, resizing, and editing you must access the internal ink data structures and the underlying Windows for Pens API. You can do this with Visual Basic's facility for declaring external DLL calls and by using the handles to the ink and window structures provided by the hInk and hWnd methods. I'll discuss these later.

PenCheckbook is a program that started out as a regular Visual Basic application. I converted it into a pen application by replacing the standard controls with pen custom controls.

The background consists of a bitmap of a check. This bitmap was first drawn with Paintbrush, and cut-and-pasted into a picture field in the main program form. In the nonpen version of the program, the main form includes five Edit Controls to handle user input: PayToCtrl, AmountCtrl, AmountStrCtrl, RemarksCtrl, and SignatureCtrl. Three other fields are display-only: DateLabel, CheckNumLabel, and CurrencyLabel, which display, respectively, the current date, a revolving check number, and the relevant currency. These fields are controlled by the application but do not accept user input.

In modifying Checkbook to accept pen input, the standard edit controls were replaced with pen custom controls. Consequently, the PayToCtrl, AmountStrCtrl, and RemarksCtrl fields can process both handwriting and gestures. The original AmountCtrl field was replaced by a boxed edit field which recognizes numbers and gestures only. The BalanceCtrl field in the Balance form will be converted to a BEdit on-the-fly (when the user presses the Change button). This whole process requires adding less than ten lines of code. The new SignatureCtrl field accepts the user's signature and retains it as ink.

Replacing the standard controls with pen controls is a slightly tedious task, because there is no automated way to do it. You have to delete the old control, drag the new HEdit or BEdit control, and redefine various properties such as BorderStyle, BackColor, and CtlName. During this process you may notice a number of new properties. The CharSet property enables you to define the characters accepted by the input field; restricting the character set substantially improves recognition.

When adding the SignatureCtrl field, I set the DelayedRecog property to True. This results in an ink field which captures stylus input and can later recognize ink if the user taps on the field when the OnTap property is set to True. The program uses the signature to "lock" a certain check so that users cannot change the amount on the check once it has been signed.

Modifying the AmountCtrl and BalanceCtrl fields (located on the second form) requires more changes. The single edit control is replaced by two BEdit controls for Dollars and Cents. You will need to adjust the Cell and Comb properties to achieve the best space utilization without compromising usability. The names of the controls now become CentCtrl, DollarBalanceCtrl, and CentBalanceCtrl. I used the CharSet property to restrict input to numerical values (and gestures).

At this stage in its evolution, the Checkbook program is ready for pen input. Users can write and sign checks on screen similar to the way they would in a paper checkbook. Standard gestures can be invoked to edit and manipulate the various fields.

After using the application for a while, you'll realize that certain layout changes make life easier. As mentioned before, handwriting is typically larger than printed text. The controls built for keyboard input may be too small and result in loss of ink when the pen exits the border of the control. By using the Inflate properties of HEdit and BEdit, you can adjust the size and location of the fields to fit the new method of input. The Inflate properties don't change the visible borders of the controls; they affect only the gray area which surrounds them. Thus, the user can write beyond the visible borders without losing ink.

Visual Basic provides several hooks that enable developers to tap into the full functionality supported by the Windows for Pens API. These include the RcResult and Change events and the hInk and hWnd handles.

The RcResult event occurs when a BEdit or HEdit control attempts to recognize the ink. This event can be used as a trigger to create locking form fields in form-based applications where a signature validates the data in the form. Once the user stops inking in the signature field, your program can lock all the input fields in the form so no changes can be made. To lock a field, merely set the Enabled property to False. In PenCheckbook, once the user has signed the check, the only way to unlock the input fields is by pressing the Pay button or selecting Clear in the Edit menu. In both cases, the input field will be initialized.

By combining Visual Basic with pen custom controls, you get a tool that lets you create simple pen applications quickly, and at the same time implement truly pencentric programs via the underlying Windows for Pens API.

DDJ

Copyright © 1992, Dr. Dobb's Journal