Microsoft Foundation Classes                           Microsoft Corporation
Technical Notes

#15 : Windows for Pen interface to MFC

This note describes the extra interfaces in 'afxpen.h' that
provide a C++ interface to the Windows for Pen environment.

=============================================================================
What is Windows for Pen ?
=========================

Windows for Pen is an extension to Windows 3.1 that provides
a new input paradigm that uses a pen or stylus for hand writing input.

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

Installing the driver:
----------------------
The Windows SDK includes a sample driver and associated DLLs for a subset
of the Pen Windows 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 tablet based system.

MFC Samples:
------------
All the the MFC samples, 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 features.

CTRLTEST (\c700\mfc\samples\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 installed, the "Pen" test menu
will be disabled.

SPEAKN (\c700\mfc\samples\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 (eg: a full MPC machine
is not required) and the Window for Pen 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 apps:
--------------
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 is required to run this application.

Pen-only applications should be marked as Win3.1 only applications
as well (i.e. 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 and MFC.  HEdit is for handwriting edit input,
and BEdit is like HEdit, but 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 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 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 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 behaviour 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:
------------------------
    GetInflate/SetInflate       Get/set the inflation size
    GetRC/SetRC                 Get/set the local recognition context
    GetUnderline/SetUnderline   Get/set the HEdit underline mode

    GetInkHandle                Get the current captured ink (can be NULL)
    SetInkMode                  Start capturing ink
    StopInkMode                 Stop capturing ink

CBEdit member functions:
------------------------
    CharOffset                  Get byte offset from logical position
    CharPosition                Get logical position from byte offset
    Get/SetBoxLayout            Get/set the BOXLAYOUT structure
    DefaultFont                 Set back to default font

=============================================================================
Pen samples:
============

Along with the samples in the Win SDK (\SAMPLES\...) there are two
MFC specific sample applications that illustrate the use of Pen.

CTRLTEST (\C700\MFC\SAMPLES\CTRLTEST) provides several custom control
examples, including samples of CHEdit and CBEdit controls.  This shows
you both how to create them from C++ code, as well as creating them
from dialog templates.

=============================================================================
Other Pen APIs:
===============

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

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

New Pen specific windows messages:
    ON_MESSAGE(WM_RCRESULT, OnRcResult)
            // notification of recognition result
    ON_MESSAGE(WM_GLOBALRCCHANGE, OnGlobalRcChange)
            // notification of global recongnition 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 combobox control

=============================================================================
