MFC TN015--Windows for Pen Computing Interface to MFC

Created: March 25, 1992

Abstract

This technical note describes the extra interfaces in AFXPEN.H that provide a C++ interface to the Windows for Pen Computing environment.

The Microsoft Foundation Class (MFC) library provides a full-featured set of C++ object classes for the MicrosoftÒ WindowsÔ graphical environment. It includes classes that directly support application development for Windows as well as general-purpose classes for collections, files, persistent storage, exceptions, diagnostics, memory management, strings, and time. Each MFC technical note describes a feature of MFC using code fragments and examples.

What Is Windows for Pen Computing?

Windows for Pen Computing is an extension to MicrosoftÒ WindowsÔ version 3.1 that provides a new input paradigm that uses a pen or stylus for handwriting input.

If you already have Windows for Pen Computing running on your system, you don't need any more description. If you don't have it running already, please read on, because you can try Windows for Pen Computing without having to buy any extra hardware.

Installing the Driver

The Microsoft Windows version 3.1 Software Development Kit (SDK) includes a sample driver and associated dynamic-link libraries (DLLs) for a subset of the Windows for Pen Computing environment. The Microsoft mouse can be used to get a rough idea of how recognition and a pen will work.

The file \WINDEV\PEN\README.TXT describes the steps needed to install the pen driver for either a mouse or a tablet-based system.

MFC Samples

All of the MFC samples (in the Sample Code, MFC Samples area on this disc), and all MFC applications, automatically are pen aware. That means that all standard edit controls will respond to handwriting.

Two of the MFC samples support specialized Windows for Pen Computing features:

CTRLTEST is a general control test applet that includes tests for the extra pen controls (described below). If CTRLTEST is run without Windows for Pen Computing installed, the Pen test menu will be disabled.

SPEAKN is a sample that uses multimedia sound output and the pen input for a simple spelling test. This sample requires a sound-capable machine (for example, a full multimedia personal computer [MPC] is not required) and the Windows for Pen Computing drivers and DLLs.

Being Pen Aware

There are various degrees of support for pen. MFC gives your applications the first level of support for free. All MFC applications are pen aware so that normal EDIT/CEdit edit items will recognize handwriting automatically.

With work on your part, you can make your application exploit more of the features of pen.

Pen-Only Applications

If you want to write a pen-only application, an application that requires features of the pen API or the special pen edit controls, you must do an extra test in your application's InitInstance to make sure that the current running system supports pen input (and the PENWIN.DLL is loaded).

The SPEAKN example shows such a test (using ::GetSystemMetrics for SM_PENWINDOWS) and a reasonable MessageBox to alert the user that Windows for Pen Computing is required to run this application.

Pen-only applications should be marked as Windows version 3.1-only applications as well (that is, pass '/31' to the second pass RC command line; see SPEAKN for an example).

Pen Edit Controls

There are two special handwriting input edit controls supported by Windows for Pen Computing and MFC. HEDIT is for handwriting edit input, and BEDIT is for boxed input (those little boxes or combs that show where the letters should go). These controls and the C++ class interfaces to them provide many ways to customize visuals, recognition, and so on.

Handling Writing

Another way of exploiting the pen is to actually process writing in your client area of your application. The complete C Pen API is available to you. Please refer to the Windows for Pen Computing documentation in the Windows SDK for more details.

Two Special Controls

The header file AFXPEN.H includes two C++ classes that interface with the Windows for Pen Computing controls HEDIT and BEDIT.

HEDIT is the general handwriting edit item that you can place in dialogs or wherever you would place a normal edit item. The C++ class CHEdit gives you a C++ interface to this control (just as CEdit gives you a C++ interface to the Windows-based EDIT control).

BEDIT provides additional functionality for boxed edits. The C++ class CBEdit gives you a C++ interface to this control.

For more details on these functions and the behavior of these two edit controls, please refer to the Pen SDK documentation (\BIN\PENAPIWH.HLP or \HELP\PENAPIQH.HLP). Most of the HEDIT and BEDIT behavior is documented in the topic for WM_HEDITCTL.

CHEdit Member Functions

CBEdit Member Functions

Pen Samples

Along with the samples in the Windows SDK, the sample application CTRLTEST provides several custom control examples, including samples of CHEdit and CBEdit controls. This shows you how to create them from C++ code and how to create them from dialog templates.

Other Pen APIs

If you start using some of the more sophisticated features of Windows for Pen Computing, some of these interfaces require HWNDs or Windows callbacks.

You can use the extensible message map architecture to handle the new pen messages.

New pen-specific Windows-based messages:

ON_MESSAGE(WM_RCRESULT, OnRcResult)

// notification of recognition result

ON_MESSAGE(WM_GLOBALRCCHANGE, OnGlobalRcChange)

// notification of global recognition parameter changes

ON_MESSAGE(WM_SKB, OnSystemKeyboardChange)

// notification of system keyboard change

New pen-specific HEDIT control notifications:

ON_CONTROL(HN_ENDREC, IDC_???, OnEndRec)

ON_CONTROL(HN_DELAYEDRECOGFAIL, IDC_???, OnDelayedRecogFail)

ON_CONTROL(HN_ENDREC, IDC_???, OnRcResult)

// where IDC_??? is the control ID of an HEDIT control

New pen-specific combo-box control notifications:

ON_CONTROL(CBN_ENDREC, IDC_???, OnEndRec)

ON_CONTROL(CBN_DELAYEDRECOGFAIL, IDC_???, OnDelayedRecogFail)

ON_CONTROL(CBN_ENDREC, IDC_???, OnRcResult)

// where IDC_??? is the control ID of a combo box control