home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
pentlk11.zip
/
README
< prev
next >
Wrap
Text File
|
1994-02-03
|
26KB
|
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 (404) 835-9900 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