The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/devtools/penos2/readme

Text File | 1994-02-02 | 25.5 KB | 613 lines

             Pen for OS/2 Developer's Toolkit:  Getting Started
             --------------------------------------------------

Contents
========
This README contains the following sections:

Pen for OS/2 Toolkit 1.1   New Content
Introduction
Toolkit Installation
  Requirements
  List of Suggested Tools
  CD-ROM Installation Options
  Pen for OS/2 Toolkit Installation
  Subdirectory Created during Installation
Toolkit Sample Programs
  APPLIC Sketch/Handwriting Sample (APPLIC.EXE)
  SKETSAMP Sketch Control Sample (SKETSAMP.EXE)
  HWX_SAMP Handwriting Control Sample (HWX_SAMP.EXE)
  HIDEKBD Hide the Pop-Up Keyboard Sample (HIDEKBD.EXE)
  ISM_SAMP Input Subsystem Message Sample (ISM_SAMP.EXE)
  LOADKBD Load the Pop-Up Keyboard Sample (LOADKBD.EXE)
  MOVEKBD Move the Pop-Up Keyboard Sample (MOVEKBD.EXE)
  OEM Pen Subclass Sample (OEM.DLL)
  WM_RECO_COMMAND Message Handler (RECODISP.EXE)
  WM_RECO Message Handler (WMRECO.EXE)
  WRT API Sample (WRTSAMPL.EXE)
  MultiMedia Ink ( MMINK.EXE )
Known Problems and Limitations
Notices
  Trademarks

Pen for OS/2 Toolkit 1.1   New Content
========================================

  o MultiMedia Ink, a sample application that demonstrates a simple
    method of synchronizing audio and ink. It also demonstrates a method of
    capturing ink at high resolution and scaling the ink back down to a lower
    resolution for display.

Introduction
============
This Readme describes how to install the Pen for OS/2 Developer's Toolkit
(Toolkit) and summarizes the sample programs included in the Toolkit.  Use this
document as an overview of the Toolkit, as a guide when installing the Toolkit,
and as a reference.

o  Please call 1-800-3IBMOS2 to purchase a copy of the Pen for OS/2
   product. The IBM PenAssist program is also available.
   A developer can join this program which offers discounts
   on software and other useful information and assistance.
   For more information concerning the Pen Assist program,
   please call [phone] and ask for the Pen Assist program.

The following related Pen for OS/2 publications are available:

o   Pen for OS/2 Device Driver Reference, 71G2125
    ------------------------------------

    This book provides information on how to develop the device drivers that
    act as an interface between the Pen for OS/2 system extension and pen
    hardware products.

o   Pen for OS/2 Programming Guide and Reference, 71G2124
    --------------------------------------------

    This book is available online in the Pen for OS/2 Toolkit folder.  The book
    is divided into two parts.  Part 1 is a programming guide for the Pen for
    OS/2 system extension.  It provides an overview of the system and describes
    how to create pen-aware applications.  It also describes how pen-unaware
    applications can be used with Pen for OS/2.  Part 2 is a reference that
    lists the Pen for OS/2 application programming interface (API), messages,
    and data structures.

o   Pen for OS/2 User's Guide, 71G2122
    -------------------------

    This book introduces the Pen for OS/2 system extension and helps you get
    started using it.


Toolkit Installation
====================
The Toolkit is a collection of library files, header files, documentation, and
sample code designed to help you develop applications for use with Pen for OS/2.

Requirements
============
Before beginning the installation procedure, make sure you have the following:

o   A computer with IBM(Trademark of the IBM Corporation)
    OS/2(Trademark of the IBM Corporation) 2.1 installed.
o   A minimum of 8MB of memory
o   A CD-ROM (high-capacity read-only memory in the form of an optically read
     compact disc) drive
o   A hard disk drive with 3264KB of free disk space for the Toolkit

List of Suggested Tools
=======================
The following tools are used in conjunction with the Pen for OS/2 Toolkit.

o   IBM C Set/2 Compiler
o   IBM Developer's Toolkit for OS/2 2.1
o   Pen for OS/2

CD-ROM Installation Options
===========================
The Pen for OS/2 Toolkit is located in the Development Tools Directory on the
Developer Connection CD-ROM. There are two ways to install the Pen for OS/2
Toolkit:

o   Installing directly from the CD-ROM.
o   Creating two diskettes from the CD-ROM and installing from diskette.

Refer to the Developer Connection documentation for instructions on installing
tools directly from the CD-ROM and for diskette creation instructions.

Pen for OS/2 Toolkit Installation
=====================================
Follow these steps to install the Toolkit:

1.  Begin the IBM Pen for OS/2 Toolkit installation program:

    o If you are installing directly from the CD-ROM, the installation program
      is started by selecting the IBM Pen for OS/2 Toolkit, Install product
      option
    o If you are installing from Diskette, insert the Toolkit Installation
      diskette 1 in Drive A and type the following at the command
      prompt:  A:PINSTALL

    The Toolkit installation program is a Presentation Manager (Trademark of
    the IBM Corporation) application that will enable you to install the Toolkit
    onto your system.

    While you are installing the Toolkit, few decisions are necessary.  However,
    if you need help, you can press the F1 key or select the Help push button.

2.  Before you continue installing the Pen for OS/2 Toolkit, review the ReadMe
    file.  To do so, select ReadMe from the IBM Pen for OS/2 Toolkit - Options
    window.  When you have completed reviewing the ReadMe, select Close from
    the system menu to return to this window.

    The CONFIG.SYS file must be updated to successfully install the Pen for OS/2
    Toolkit.  The Options window has a group box labeled CONFIG.SYS with two
    radio buttons:

    o   Pen for OS/2 Toolkit updates
    o   You will update

    If you select the first option, the Pen for OS/2 Toolkit installation
    program will update your CONFIG.SYS automatically.  It will also back up
    your initial CONFIG.SYS to CONFIG.XXX.

    If you select the second option, the Pen for OS/2 Toolkit installation
    program will create a file CONFIGCH.XXX in the root directory.  This file
    contains a suggested version of the CONFIG.SYS.  You must either
    incorporate these changes into your CONFIG.SYS or use this file as your
    CONFIG.SYS.

3.  Select OK to continue with the installation.

4. The default "source drive" (the drive from which information is read) is
   drive A.  The default "target drive" (the drive to which information is
   written) is drive C.  You can change either drive by clicking on the down
   arrow in either field and making another drive selection.

   The default "target path" installs the Pen for OS/2 Toolkit in the
   directory C:\TLKTPPM.  You can change the path by typing a new path in the
   "Target path" window or by selecting an entry in the "Target directory"
   list box.

   Note:  The Toolkit can be installed from a Local Area Network (LAN) to your
          hard disk.  It can be installed on a server and then all requestor
          machines connected to the server can install from it.

5. Select Install.  Follow the online directions.

6. For changes to take effect when the installation is complete, you MUST
   shut down your system and restart your computer.


Note:  The installation program checks the target drive to ensure there is
       enough room to install the entire Pen for OS/2 Toolkit.  A warning
       message is displayed if it is determined that there is not enough room
       on the target drive.  You have the option of continuing with the
       installation and potentially receiving an out of space error or
       cancelling the installation.

Note:  If installing directly from the CD-ROM, the toolkit files will be
       created on your hard disk with the Read-Only attribute.  Use the OS/2
       System Command ATTRIB -R to remove the Read-Only restriction.


Subdirectory Created during Installation
========================================
The subdirectory TLKTPPM is created when you install Toolkit components
on a hard disk.  The following is the subdirectory structure for the
Toolkit:

        ──TLKTPPM
             ├──LIB
             ├──SC
             ├──H
             ├──INSTALL
             ├──HELP
             ├──BOOK
             ├──ICONS
             └──SAMPLES
                  ├──APPLIC
                  ├──SKETSAMP
                  ├──HWX_SAMP
                  ├──HIDEKBD
                  ├──ISM_SAMP
                  ├──LOADKBD
                  ├──MOVEKBD
                  ├──OEMPEN
                  ├──RECODISP
                  ├──WMRECO
                  ├──WRTSAMPL
                  └──MMINK

The subdirectories and their contents are:

LIB                Library files

SC                 System Object Model class definition files for
                   Workplace Shell(Trademark of the IBM Corporation) objects

H                  Include and header files

INSTALL            Toolkit installation control files

HELP               Toolkit installation help files

BOOK               Online Pen for OS/2 Programming Guide and Reference
                          --------------------------------------------
ICONS              Installation icons

SAMPLES            Sample programs

APPLIC             APPLIC demonstrates how to create a Handwriting control and
                   a Sketch control.  This program also shows how to save and
                   restore the sketch strokes to and from disk.

SKETSAMP           SKETSAMP demonstrates how to create a Sketch control and to
                   use the Sketch control messages and notification messages.

HWX_SAMP           This sample program demonstrates how to create and use
                   the handwriting control.

HIDEKDB            This sample program demonstrates how to use the keyboard
                   APIs to hide and show a pop-up keyboard.

ISM_SAMP           This sample program demonstrates how to use the Pen for OS/2
                   input subsystem messages.

LOADKBD            This sample program demonstrates how to use the pop-up
                   keyboard APIs to start the pop-up keyboard program and load
                   different types of keyboards.

MOVEKBD            This sample program demonstrates how to use the keyboard
                   APIs to resize and move a pop-up keyboard.

OEMPEN             The OEM Pen sample demonstrates how to use subclassing to
                   customize the setup object associated with a device.

RECODISP           The RECODISP program demonstrates how a command handler
                   registers itself, retrieves the RECODATA from the
                   environment, and handles the WM_RECO_COMMAND message.

WMRECO             This sample program displays all RECODATA information
                   when a gesture is drawn and recognized.

WRTSAMPL           WRTSAMPL demonstrates how to use the WRT APIs.  The WRTSAMPL
                   is a drawing program using WM_MOUSEMOVE or WM_SENSOR_MOVE
                   messages for drawing.

MMINK              MultiMedia Ink is a sample application that demonstrates a
                   simple method of synchronizing audio and ink. It also
                   demonstrates a method of capturing ink at high resolution
                   and scaling the ink back down to a lower resolution for
                   display.


Toolkit Sample Programs
=======================
The sample programs available with the Toolkit are written in C and demonstrate
the use of the API functions of Pen for OS/2.  Each sample program serves as a
template that can be easily modified for your own purposes.  Names of the sample
programs correspond to their Toolkit subdirectory names.

When the Toolkit is installed, a Pen for OS/2 Toolkit folder is created on the
desktop.  Inside this folder are online documents and a Samples folder
containing objects for each of the samples.  To start a sample program from
an OS/2 command prompt, type the name of the executable file and press Enter.

Note:  For the RECODISP.EXE program, follow the instructions in the
       heading:  WM_RECO_COMMAND Message Handler (RECODESP.EXE).

If you have edited source code of a sample program and want to recompile, link,
and run the files, change to the subdirectory where the sample program resides
and type:

NMAKE SAMPLE.MAK

where sample is the name of the sample program you want to build.


APPLIC Sketch/Handwriting Sample (APPLIC.EXE)
=============================================
APPLIC demonstrates how to create Handwriting and Sketch Controls by defining
them as part of a dialog template in a resource definition file.  The name,
address, city, state, and zip code fields are Handwriting Controls and the
signature field is a Sketch Control.

The three selectable colored pen pointers used to write in the Sketch Control
demonstrate the SKM_SET_CTL_DRAW_POINTER and SKM_SET_CTL_INK_COLOR control
messages.  The SKM_DELETE_ALL_STROKES control message is demonstrated when you
press the Clear button.

This program also shows how to save and restore the sketch strokes to and from
disk by using the following sketch controls:

  SKM_QUERY_CTL_STROKE_COUNT
  SKM_QUERY_STROKE_LENGTH
  SKM_QUERY_STROKE_DATA
  SKM_ADD_STROKE


SKETSAMP Sketch Control Sample (SKETSAMP.EXE)
=============================================
SKETSAMP demonstrates how to create a sizeable Sketch Control in a client
window and how to use the Sketch Control Messages and Notifications Messages.
A Sketch window will display and accept freehand input.  When you press the
"Select Control" push button, a list box containing SKETCH Control Messages
will be displayed and you can select a message to execute.  To execute a
particular message, you highlight the message and press "OK".  To get help for
a particular message, you highlight the message and press "Help".

The following messages and notification messages are demonstrated:

  SKM_DELETE_ALL_STROKES
  SKM_UNDO_LAST_STROKE
  SKM_QUERY_CTL_DRAW_POINTER
  SKM_SET_CTL_DRAW_POINTER
  SKM_QUERY_CTL_INK_WIDTH
  SKM_SET_CTL_INK_WIDTH
  SKM_QUERY_CTL_INK_COLOR
  SKM_SET_CTL_INK_COLOR
  SKM_QUERY_CTL_INVISIBLE_MODE
  SKM_SET_CTL_INVISIBLE_MODE
  SKM_RENDER_TO_CLIPBOARD
  SKM_QUERY_CTL_STROKE_COUNT
  SKM_QUERY_STROKE_INK_COLOR
  SKM_SET_STROKE_INK_COLOR
  SKM_QUERY_STROKE_INK_WIDTH
  SKM_SET_STROKE_INK_WIDTH
  SKM_GET_BITMAP
  SKM_QUERY_BITMAP_SIZE
  SKM_QUERY_STROKE_LENGTH
  SKM_QUERY_STROKE_DATA
  SKM_SET_CTL_AUXDATA_MODE
  SKN_INK_COLOR_CHANGE
  SKN_INK_WIDTH_CHANGE
  SKN_STROKE_ADD
  SKN_STROKE_UNDO
  SKN_CONTROL_CLEARED

To exit, press Cancel at the Sketch Input window.


HWX_SAMP Handwriting Control Sample (HWX_SAMP.EXE)
==================================================
HWX_SAMP demonstrates several methods of creating and using the handwriting
controls for pen-aware applications.  HWX_SAMP is a multiwindow application.
It consists of a single executable file (HWX_SAMP.EXE) and a dynamic link
library (HWXPROCS.DLL).  The application creates a main window with a menu bar.
The menu contains items for several variations for control creation and
manipulation.  The following are a list of the variations demonstrated:

  Window Styles
  Window Text Control
  Resizing of Control
  Notification Messages
  Multiple Controls
  Related APIs


HIDEKBD Hide the Pop-Up Keyboard Sample (HIDEKBD.EXE)
=====================================================
HIDEKBD demonstrates how to use the keyboard APIs to hide and show a pop-up
keyboard on the desktop.  The sample program initially displays the default
keyboard.  Selecting the Hide button on the HIDEKBD program window will remove
the pop-up keyboard from view.  The pop-up keyboard can be restored to view by
selecting the Restore button on the program window.  Finally, the program
closes the keyboard and stops the pop-up keyboard process.  The following APIs
are demonstrated:

  VkpLoadKeyboard
  VkpIsKbRunning
  VkpIsKbHidden
  VkpHideKeyboard
  VkpCloseKb

ISM_SAMP Input Subsystem Message Sample (ISM_SAMP.EXE)
======================================================
ISM_SAMP demonstrates the uses of Pen for OS/2-generated window messages in the
construction of a pen-aware application.  ISM_SAMP is a multiwindow application.
It consists of a single executable file (ISM_SAMP.EXE) and a dynamic link
library (ISMPROCS.DLL).  The application creates a main window with a menu bar.
The menu contains items for variations of each the Pen for OS/2-generated
window messages.  The variations consist of the different MRESULT codes for the
window messages.  Selecting the menu item will create a child window to
demonstrate the use of the associated window message and the effect of the
various MRESULT codes.  The following messages and their associated MRESULT
codes are demonstrated:

  WM_TOUCHDOWN
  WM_LIFTOFF
  WM_STROKE
  WM_SENSOR_MOVE
  WM_EXIT_PROXIMITY
  WM_WRT_DEV_CAPS_CHANGE
  WM_WRT_SYSVALUECHANGED
  WM_PAUSE_TIMEOUT
  WM_TAP
  WM_DBL_TAP

LOADKBD Load the Pop-Up Keyboard Sample (LOADKBD.EXE)
=====================================================
LOADKBD demonstrates how to use the pop-up keyboard APIs to start the pop-up
keyboard program and load different types of keyboards.  The sample program
opens a window, loads the default keyboard and asks you to enter some
information using the pop-up keyboard.  The program then closes the default
keyboard, starts a numeric keyboard, and asks you to enter some numeric data.
Finally, the sample program closes the keyboard and ends the pop-up keyboard
process.  The following APIs are demonstrated:

  VkpLoadKeyboard
  VkpIsKbRunning
  VkpDeleteKeyboard
  VkpCloseKb

MOVEKBD Move the Pop-Up Keyboard Sample (MOVEKBD.EXE)
=====================================================
MOVEKBD demonstrates how to use the pop-up keyboard APIs to resize and move a
pop-up keyboard to different places on the desktop.  The sample program
initially displays the default keyboard in the lower-left corner of the desktop.
Selecting the Move button will reposition the pop-up keyboard just below the
MOVEKBD window.  Moving the window and then selecting the Move button will
change the pop-up keyboard position to just above or below the MOVEKBD
window.  Selecting the Enlarge and Skrink buttons will change the size of the
pop-up keyboard.  Finally, the program closes the keyboard and stops the pop-up
keyboard process.  The following APIs are demonstrated:

  VkpLoadKeyboard
  VkpIsKbRunning
  VkpQueryKbPos
  VkpSetKbPos
  VkpCloseKb

OEM Pen Subclass Sample (OEM.DLL)
=================================
The OEM Pen sample demonstrates how to use the method of subclassing to
customize the setup object associated with a device.  For example, you can
choose to change the default icon or title of the object when it is installed,
or you can choose to add or remove pages from the notebook.

Specifically, this sample subclasses the PenLocatorPen class to change the
default icon and title of the Pen object and also adds a Settings page to
the notebook.  Sample script files are provided and can be used in
conjunction with the PENDD.SYS sample device driver which uses CAL.EXE
for a calibration program.

Upon opening the OEM Pen object after installing and restarting the system,
an "OEM" page will be added to the notebook, and the icon and title are
customized as specified in the subclass.  The calibration program can be run
by selecting Open and then Calibrate from the pop-up menu.

WM_RECO_COMMAND Message Handler (RECODISP.EXE)
==============================================
This program demonstrates how a recognition command handler works.  This
program name should be given as the command name of a gesture in the Gesture
Edit page.  When the gesture is drawn on the program window, Pen for OS/2 will
run this program.

The RECODISP program demonstrates how a command handler registers itself,
retrieves the RECODATA structure from the environment, and handles the
WM_RECO_COMMAND message.  The RedRegisterRecoCommand and RedRecoDataFromEnv
APIs are used.  When a gesture is drawn on an application window and the
application does not handle, Pen for OS/2 invokes the command handler shown in
the Gesture Assignment page.  The command handler can then retrieve the
information within the RECODATA structure.  The RECODATA structure contains
the argument.

To assign this command to a gesture for a specific program:

1.  Open the Settings notebook for the program.
2.  Select the Gesture page.
3.  Select the Gesture page from the Settings notebook; select a gesture and
    click on the "Edit" button.  In the Edit window, you can enter the command
    handler name, parameters, and description.  If the gesture is made on the
    application window after editing, the command handler will be activated by
    Pen for OS/2.

This program should be in a directory given by PATH= in CONFIG.SYS or
the full path name of the command handler should be given in Edit window.

WM_RECO Message Handler (WMRECO.EXE)
====================================
When a gesture is made in an application window, a WM_RECO message is sent to
the window.  The WMRECO program is a pen-aware application that handles the
WM_RECO message.  When it receives the message, it retrieves the RECODATA
structure and displays it in a dialog box.

WRT API Sample (WRTSAMPL.EXE)
=============================
WRTSAMPL demonstrates how to use the WRT APIs.  The WRTSAMPL is a drawing
program using WM_MOUSEMOVE or WM_SENSOR_MOVE messages for drawing.
WrtWaitActive, WrtQueryStrokeData, WrtMapPointLong, WrtQueryPointAuxData,
and WrtQueryEventData are demonstrated in the WRTSAMPL program.

After invoking WRTSAMPL, different system values and system variables
can be chosen from the menu bar to be displayed and set.

Selecting Capabilities produces the following choices and related APIs as
listed:

System Caps           WrtQuerySystemCaps
Locator Caps          WrtQueryLocatorCaps
Button Caps           WrtQueryButtonCaps
Display Caps          WrtQueryDisplayCaps

Selecting "System Value" produces the following choices and related APIs as
listed:

Query Value           WrtQuerySysValue
Set Value             WrtSetSysValue
Write Value           WrtWriteSysValue
Read Value            WrtReadSysValue

Selecting "Devices" produces the following choices and related APIs as listed:

Enum Drivers          WrtEnumInputDrivers
Query Names           WrtQueryInputDevicesNames
Query Variable        WrtQueryInputDeviceVariable
Set Variable          WrtSetInputDeviceVariable

Selecting Miscellaneous produces the following choices and related APIs as
listed:

Strict Emulation      WrtSetStrictEmulation
Backlight             WrtControlDisplayBacklight
Toggle M/S            Toggle between mouse move and sensor move
Toggle Aux            Toggle between display Aux Data and not display Aux Data
Toggle Event          Toggle between display Event Data and not display Event
                       Data

MultiMedia Ink ( MMINK.EXE )
==============================
MultiMedia Ink ( MMINK ) is a sample application that demonstrates a simple
method of synchronizing audio and ink. It also demonstrates a method of
capturing ink at high resolution and scaling the ink back down to a lower
resolution for display.

You will need an system with OS/2 2.1, Pen for OS/2 1.0, and MMPM/2 1.1 in
in order to execute the application. You will need the OS/2 2.1 Toolkit,
Pen for OS/2 1.0 Toolkit, MMPM/2 1.1 Toolkit, and C Set/2 1.0 compiler in
order to compile and link the application.

To run the sample:
        Run MMINK.EXE

Once the application is up and running select the Voice and Ink option from
the menu or gesture A-tap in the client area to activate the annotation
dialog.

Known Problems and Limitations
==============================
o   HWX control does not allow you to create a window if the window is
    smaller than the width or height of a bounding box.
o   The HWX control does not send you a WM_CONTROLLPOINTER message as
    stated in Pen for OS/2 Programming Guide and Reference.
              --------------------------------------------

Notices
=======
References in this document to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates.  Any reference to an IBM product, program or service is not intended
to state or imply that only IBM's product, program, or service may be used.
Any functionally equivalent product, program, or service that does not infringe
any of IBM's intellectual property rights or other legally protectable rights
may be used instead of the IBM product, program, or service.  Evaluation and
verification of operation in conjunction with other products, programs, or
services, except those expressly designated by IBM, are the user's
responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document.  The furnishing of this document does not give you any license
to these patents.  You can send license inquiries, in writing, to the
IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.

Trademarks
==========
The following terms in this document, are trademarks of the IBM Corporation
in the United States or other countries:

  IBM
  OS/2
  Presentation Manager
  Workplace Shell