Pen for OS/2 Device Driver Reference

Notices
OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)

Copyright Notices
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

'''(C) Copyright International Business Machines Corporation 1996. All rights reserved.'''

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers
References in this publication 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 that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.

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:
 * IBM Director of Licensing
 * IBM Corporation
 * 500 Columbus Avenue
 * Thornwood, NY 10594
 * U.S.A.

Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
 * IBM
 * OS/2
 * Presentation Manager
 * Workplace Shell

About This Book
The Pen for OS/2 Device Driver Reference is a reference to be used with the IBM Developer Connection Device Driver Kit for OS/2. 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.

The examples in this book are written in assembly language to show detail. The definitions and data structures are given in C language for clarity.

Who Should Read This Book
This book is intended for professional programmers who are interested in developing pen device drivers on their hardware product with a Pen for OS/2 system extension. Prior experience developing device drivers would be helpful.

How This Book Is Organized
This book is organized as follows:
 * Architecture contains a description of the pen device driver component structure, logical device types, and driver data.
 * Initialization contains a description of device driver initialization and logical device registration.
 * Operations contains a description of the operations that handle the processing of logical devices.
 * Pen Device Objects contains a description of the new device objects created by Pen for OS/2, instance methods, and class methods.
 * Installation Control Files contains a description of the pen device driver installation process.
 * Programming Interface contains the format for programming interfaces, including request packet interface, generic IOCtl interface, and extended Pen for OS/2 interface.
 * Pen for OS/2 Component of IBM Developer Connection Device Driver Kit for OS/2 contains a description of the sample code in the IBM Developer Connection Device Driver Kit for OS/2.
 * Operational Considerations contains additional information pertaining to device driver development, including configuration limitations and video mode changes.

Related Publications
The following publications are available:
 * Pen for OS/2 Developer's Toolkit: Getting Started, 71G2123
 * Pen for OS/2 Programming Guide and Reference, 71G2124
 * Pen for OS/2 User's Guide, 71G2122

What's New
The Pen for OS/2 Device Driver Reference has not been updated for this version of the DDK.

Assistance
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE". You are encouraged to use the DUDE to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DUDE, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:
 * Internet: ibmsdp@vnet.ibm.com
 * US/Canada: 800-627-8363
 * International: 770-835-9902
 * International Fax: 770-835-9444

Ordering Information
For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.
 * The Physical Device Driver Reference
 * The Storage Device Driver Reference
 * The Input/Output Device Driver Reference
 * The Pen for OS/2 Device Driver Reference
 * The Virtual Device Driver Reference
 * The Presentation Device Driver Reference
 * The Display Device Driver Reference
 * The Printer Device Driver Reference
 * The Graphics Adapter Device Driver Reference
 * The MMPM/2 Device Driver Reference (Multimedia)

Architecture
The IBM OS/2 operating system is an advanced multitasking, single-user operating system for personal computers. The OS/2 operating system provides an application programming interface (API) that supports multitasking, multiple threads, dynamic linking, interprocess communication, a graphical user interface, and a graphics programming interface.

Pen for OS/2 is a series of software extensions to the OS/2 operating system and the Presentation Manager (PM) graphical user interface that enable pen-based input and recognition. The Pen for OS/2 extensions support a variety of computers and peripherals designed for use with a pen as their primary input device.

Because many of the functions of an OS/2 physical device driver are related to system operations in addition to hardware operations, OS/2 services are available through the Device Helper (DevHlp) interface. Refer to the Physical Device Driver Reference for a complete description of OS/2 Device Helper services and responsibilities. The Pen for OS/2 system has extended the OS/2 device driver services providing Pen for OS/2 Device Driver Services unique to pen hardware devices. The Pen for OS/2 Device Driver Service internal structure provides the logical device types and device driver data. The following figure shows the major components of the pen device driver model and how they fit into the Pen for OS/2 design. The developer supplies the items shown in the boxes marked with ██. Pen Device-Driver- OS/2 Applications               Specific Applications ┌──────────────────────┐         ┌─────────────────────────┐ │                      │          │        ┌──────────────┐ │ │     ┌──────────────┐ ├──┐    ┌──┼──┬─────┤Device     ██ │ │ │    │           ██ │ │  │    │  │  │  ┌──┤Objects       │ │ │ ┌───┴──────────┐  │ │  │    │  │  │  │  └──────────────┘ │ │ │           ██ │   │ │  │    │  │  │  │  ┌──────────────┐ │ │ │              ├───┘ │  │    │  │  ├──┼──┤Calibration██ │ │ │ │             │     │  │    │  │  │  │  │Program       │ │ │ └──────────────┘    │  │    │  │  │  ├──┤(Optional)    │ │ │                     │  │    │  │  │  │  └──────────────┘ │ │                      │  │    │  │  │  │  ┌──────────────┐ │ │                      │  │    │  │  ├──┼──┤Delayed-   ██ │ │ │                     │  │    │  │  │  │  │Initialization│ │ │                     │  │    │  │  │  │  │Program       │ │ │    ┌──────────────┐ │  │    │  │  │  ├──┤(Optional)    │ │ │    │           ██ │ │  │    │  │  │  │  └──────────────┘ │ │ ┌───┴──────────┐   │ │  │    │  │  │  │  ┌──────────────┐ │ │ │           ██ │   │ │  │    │  │  ├──┼──┤Auxilliary ██ │ │ │ │             ├───┘ │  │    │  │  │  │  │Program       │ │ │ │             │     │  │    │  │  │  ├──┤(Optional)    │ │ │ └──────────────┘    │  │    │  │  │  │  └──────────────┘ │ │                      │  │    │  │  │  │  ┌──────────────┐ │ │                      │  │    │  │  │  │  │Pen Device-   │ │ │                     │  │    │  │  │  └──┤Driver Tool   │ │ │                     │  │for │  │  │     └──────────────┘ │ └──────────────────────┘ │OS/2│  └──┼──────────────────────┘ OS/2                   │API │     │ ┌───────────────────────┼────┼─────┼────────────────────┐  │ ┌─────────────────────┼────┼──┐  │                    │   │ │ Pen for OS/2 ┌──────▼────▼─┐├─►│                    │ │ │             │Pen for OS/2 ││  ▼                    │ │ │             │Device-Driver││  │Ioctl Interface     │ │ │             │Services     ││  │                    │ │ │             └──┬───────┬──┘│  │  ┌───────────────┐ │   │ └─────────────────┼───────┼───┘  │  │OS/2 Device-   │ │ │                 IDC    Services │  │Helper Services│ │ │              Interface  Calls   │  └───────▲───────┘ │ └───────────────────┼───────┼──────┼──────────┼─────────┘                      │       │      │    Devhlp│Interface ┌─────────────────────▼───────▼──────▼──────────────────────┐ │                 Pen Device Driver                    ██  │ └───────────────────────────▲───────────────────────────────┘                            │                             ▼                       Pen Hardware To develop pen hardware support for the Pen for OS/2 system extension, you provide the following components:
 * Pen device driver

The pen device driver is an OS/2 physical device driver that controls the pen hardware. It has access to all the OS/2 Device Helper services and must adhere to all the OS/2 device driver rules.

The pen device driver calls the Pen for OS/2 Device Driver Services to register Pen for OS/2 device-specific capabilities, deliver Pen for OS/2 events, and make queries. provides a complete specification of this direct call interface.

The pen device driver must provide an IOCtl interface to the Pen for OS/2 system to control the pen device driver. Refer to the Control Program Programming Reference for more information on the Generic IOCtl Interface for applications (DosDevIOCtl) and to the OS/2 2.0 Physical Device Driver Reference for information on the existing IOCtl functions. provides a complete specification of the IOCtl interface.

The pen device driver can provide private IOCtls to permit device-specific control operations that do not involve Pen for OS/2.


 * Device objects

Pen for OS/2 device objects appear as icons in the Devices folder. Device objects provide a means of communication between a computer and another piece of equipment, such as a pen or display. The icons look like the pen hardware they represent. The device objects contain a Settings notebook with Pen for OS/2 variables and device-specific data. The Pen for OS/2 folder contains the Devices folder. These folders are added to the desktop when the Pen for OS/2 system is installed. describes the types of device driver data. describes device objects in more detail.


 * Optional calibration program

You can provide a calibration program. The calibration program, provided with the Pen for OS/2 Developer's Toolkit, can be invoked from a device object which can communicate with the pen device driver through IOCtls.


 * Optional initialization program

You can provide an initialization program to communicate with the pen device driver during OS/2 system initialization, which is described in the section titled.


 * Optional auxiliary programs

You can add other OS/2 application programs, device drivers, and subsystems to enhance or control the operation of the pen device driver beyond the scope specified in the Pen for OS/2 system. For example, you can subclass the basic video system to provide enhanced display support.

Logical Device Types
The following figure illustrates the relationship between a pen device driver and Pen for OS/2 logical devices. PENDD.SYS ┌──────────────────────────────────────────────────────────┐ │                                                          │  │   Device Driver Header                                   │ │  ┌────────┐                                             │  │   │        │                                             │  │   │ PENDD$ │                                             │ │  │        │                                             │  │   └────────┘                                             │  │ ┌──────────────────────────────────────┐                 │  │ │Device MY_HARDWARE, Device Type DRIVER│                 │ │ │   ┌─────────────────────────────────┴───┐             │  │ └────┤Device LCD Device Type DISPLAY       │             │ │     │    ┌────────────────────────────────┴───┐         │  │      └────┤Device BEZEL, Device Type BUTTON    │         │ │          │    ┌───────────────────────────────┴───┐     │  │           └────┤Device FINGER, Device Type LOCATOR │     │ │               │    ┌──────────────────────────────┴───┐ │  │                └────┤Device PEN, Device Type LOCATOR   │ │ │                    │                                  │ │  │                     └──────────────────────────────────┘ │  │                                                          │  └──────────────────────────────────────────────────────────┘ The load module contains the physical device driver. PENDD.SYS is the load module for the sample device driver provided in the Toolkit. The OS/2 operating system recognizes the driver name defined in the device driver header and treats it and its collection of Pen for OS/2 logical devices as one OS/2 character device driver. The driver name in the device driver header must be a unique eight-character name to enable multiple drivers to coexist on a single system. (PENDD$ is the device driver name used for the sample device driver provided in the Toolkit.) Select a name that uniquely identifies your hardware.

The Pen for OS/2 system and Pen for OS/2 Device Driver Services support the following logical device types:
 * Locator
 * Locator devices supply a stream of locator position points and emulated mouse button events. The Pen for OS/2 system has extended the standard OS/2 mouse locator point stream to include:
 * Z-axis information
 * Sequence number
 * High-resolution device time stamp
 * State of all physical buttons
 * Optional locator data (angle theta, angle phi)
 * Optional OEM data area
 * There are three types of locator devices:
 * Pen
 * Pen devices supply high-resolution position points at a high sample rate. Pens can have buttons and can report orientation data. Pens usually report proximity in terms of height. Ink should flow directly from the tip of the pen.
 * Touch
 * Touch devices provide lower resolution and a lower sample rate. A touch device, such as a finger, does not have buttons. Selection ability of a touch device improves by offsetting the OS/2 pointer from the actual hardware coordinate of contact. Touch devices usually do not report proximity but can report pressure.
 * Other
 * Pen for OS/2 provides an other type for locators that have some or none of the characteristics of the previous types; for example, a relative reporting track ball or a joy stick with a trigger button does not have the characteristics of a pen or touch device.
 * describes locator devices in further detail.


 * Button
 * The button device manages all barrel buttons and bezel buttons. Barrel buttons are found on the side of a pen device. Bezel buttons (or nonbarrel buttons) are built into the case of a pen-based computer or peripheral. A device object assigns actions to buttons. The state of all buttons managed by the driver is reported on all locator event streams.
 * Button devices can change the way emulated mouse button events are reported . For example, activating a barrel button on a pen can cause the default button 1 down to be reported as button 2 down instead.
 * Button devices also can produce events independently from the locator position point stream. For example, activating a bezel button can immediately cause the OS/2 Window List to become active. describes button devices in further detail.


 * Display
 * The display device manages the backlight on a liquid crystal display (LCD). The display device automatically turns off the backlight after the system has not been used for a default time period of 20 minutes. The display device turns the backlight back on when the user accesses the system. describes display devices in further detail.

The common capabilities packet contains the driver name and logical device name for the logical devices in the pen device driver. See. Logical device names for the locator, button, and display need not be unique across the system. The names PEN, FINGER, BEZEL, BARREL, MONO, and COLOR are suggested. The logical device name for the driver logical device should identify your hardware device as uniquely as possible. See for a complete configuration description.

Each logical device in the driver is assigned a unit number. A unit number is used to select a logical device within the driver and is unique only within the scope of the driver. The logical devices are numbered sequentially starting at 0. Your optional application programs and the test program use unit numbers with the IOCtl interface to select a particular device for an operation. Unit 0 is the device type "DRIVER" that defines the characteristics of the entire driver.

Query Unit Capabilities of unit 0 returns the total number of logical devices in the driver, including itself. Query Unit Capabilities can be used to query each unit's capabilities data to retrieve its device type and description.

Each device also has a device ID. A device ID is an ID number assigned to a logical device by the Pen for OS/2 Device Driver Services. A device ID is unique across the entire system. Pen for OS/2 uses the device ID to distinguish devices uniquely in the system.

Pen for OS/2 provides API functions to query the device configuration so that an application will not need to use the IOCtl interface.

Device Driver Data
A pen device driver can have data values hard coded when the driver is compiled and linked. Pen for OS/2, or application programs you supply, can generate and store data values that cannot be hard coded and that override the hard-coded values. The pen device driver obtains these values through the IOCtl interface. The pen device driver can also obtain these values directly during initialization using ring 3 OS/2 API functions.

The following figure shows the types of data defined by the Pen for OS/2 system extension. ┌──────────────┐ ┌───────────┐ ┌────────────────────────┐  │Delayed       │ │           │ │                        │ │Initialization│ │Pen Device │ │Pen for OS/2           │ │Program      │ │Driver Tool│ │                        │ │ ┌──────────┐ │ │┌─────────┐│ │┌────────┐ ┌──────────┐ │  │ │ Device   │ │ ││Device   ││ ││Device  │ │Pen for   │ │ │ │ Private │ │ ││Private  ││ ││Specific│ │OS/2      │ │ │ │ Data    │ │ ││Variables││ ││Data    │ │Variables │ │ │ └────┬─────┘ │ │└───┬─────┘│ │└────┬───┘ └─────┬────┘ │  └──────┼───────┘ └────┼──────┘ └─────┼───────────┼──────┘          │              │              │           │       Private        Set Unit       Set Unit   Device Type IOCtls        Variable       Specific    Specific │           IOCtl        Data IOCtl    IOCtls │             │              │           │ ┌────────┼──────────────┼──────────────┼───────────┼────────┐ │ ┌──────┼──────────────┼────┐ ┌───────┼───────────┼──────┐ │ │ │ ┌────▼────┐ ┌───────▼──┐ │ │ ┌─────▼───┐ ┌─────▼────┐ │ │ │ │ │ Device  │ │Device    │ │ │ │Device   │ │Pen for   │ │ │ │ │ │ Private │ │Private  │ │ │ │Specific │ │OS/2      │ │ │ │ │ │ Data   │ │Variables │ │ │ │Data     │ │Variables │ │ │ │ │ └─────────┘ └──────────┘ │ │ └─────────┘ └──────────┘ │ │ │ │ Private Data            │ │Pen for OS/2              │ │ │ │                         │ │Managed Data              │ │ │ └──────────────────────────┘ └──────────────────────────┘ │ │ PEN DEVICE DRIVER                                        │ └───────────────────────────────────────────────────────────┘ The Pen for OS/2 system defines the following types of data, accessible using IOCtls:
 * Private data
 * The Pen for OS/2 system does not maintain persistent values for this data across system restarts and does not provide Pen for OS/2 API access to this data. There are two types of private data:
 * Device-private data
 * You manage device-private data by storing the data and communicating it to the pen device driver through private IOCtls. There can be any number of private data blocks of any size. An example of device-private data is a microcode load for a pen hardware product.
 * A delayed initialization program or an auxiliary program can save the data between restarts and pass device-private data to the driver.
 * Device-private variables
 * Device-private variables can be viewed as an array of ULONGs accessed by an index. The pen device driver defines the number of variables available per logical device. They are provided as a convenience and are intended for temporary use, such as debugging; they are not required to be set for the driver to operate. Set Unit Variable and Query Unit Variable IOCtls communicate private variables to and from the pen device driver. The pen device driver tool, described in, can set and query device-private variables.


 * Pen for OS/2 managed data
 * The Pen for OS/2 system maintains persistent values for this data and provides API functions to access the following two types of data:
 * Device-specific data
 * Pen for OS/2 will manage up to 512 bytes per pen logical device. You set up this data in a single block through the Pen for OS/2 API, WrtSetInputDeviceVariable. The Pen for OS/2 system will pass the data to the pen device driver with the Set Unit Specific Data IOCtl. Pen for OS/2 saves device-specific data across system restarts and passes the data to the pen device driver when Pen for OS/2 starts up. Pen for OS/2 does not examine the contents of the data.
 * Pen for OS/2 variables
 * The Pen for OS/2 system extension provides API functions to individually manage each Pen for OS/2 variable, and there is an IOCtl to pass the value of the variable to the pen device driver. The Pen for OS/2 system maintains the values of these variables across system restarts and initializes the pen device driver with these values through the IOCtl interface during Pen for OS/2 startup.
 * The following list contains the Pen for OS/2 variables related to the pen device driver:
 * Locator Offset
 * Locator Pass Rate
 * Locator Sample Rate
 * Button Assignments
 * Backlight Inactivity Period

The IOCtl method used to control data designates the data types. The designation is independent from the way the pen device driver chooses to organize and store the data within the driver.

For example, calibration data can be managed as Pen for OS/2 device- specific data. Pen for OS/2 maintains the device-specific data block across system restarts and passes the data during Pen for OS/2 initialization. If the calibration data is large, it can be managed as private data and communicated to the pen device driver with private IOCtls from a delayed initialization or auxiliary program you supply.

As a second example, a device-specific variable could be used during development to dynamically set a tuning value that later will be fixed as a hard-coded constant. A device-specific variable could also be used to collect error or diagnostic data for service support.

Initialization
For optimum performance, set the device driver to perform all the initialization required for the device driver to be operational. This has the following advantages:
 * It is not necessary to invoke an initialization program from CONFIG.SYS as a RUN= statement or a program reference in the Startup folder. This simplifies the installation process.
 * The device driver is fully operational with default settings before the startup of the Pen for OS/2 system extension.
 * The device driver is more independent to ensure that mouse emulation always works despite error conditions that prevent other areas of the system from working.

Device driver initialization can be performed in one of two ways: Delayed initialization is designed by the developer depending on the hardware supported. For more information, see.
 * Initialization at startup
 * Delayed initialization

The following figure illustrates the initialization process. ┌────────────────┐ INIT Command       │ Initialization │ │   ┌─ ─ ─ ─ ─┤ Request Packet ├─ ─ ─ ─ CONFIG.SYS │   |         └────────────────┘  ┌───▼────▼───┐                            ┌───────────────┐  │            │                            │               │  │ Pen Device │                            │ Pen for OS/2  │ │ Driver    │                            │ Device Driver │ │           │                            │ Services      │ │           │                            │               │  └──┬─────────┘                            └───────▲───────┘     │                                              │     │                            ┌─────────────┐   │     │ DevHlp_RegisterDeviceClass │ OS/2 Device │   │ └────────────────────────────► Helper     ├───┘ │ Services   │ └─────────────┘ The initialization request packet has a pointer to a string containing the pen device driver's CONFIG.SYS statement, for example: device=c:\penpm\pendd.sys load=c:\penpm\pendd.dat type=3 This string includes any optional device-specific parameters. These device-specific parameters can be used to identify data files containing the information needed during initialization and static parameters required for the operation of the device. For example, type=3 can inform the device driver of a device characteristic the device driver cannot determine.

The Pen for OS/2 system will pass device-specific data to the driver when the system starts up. This data can be used to override default values, such as locator coordinate adjustments. Therefore, do not place variables updated by a device object in the DEVICE= statement. Optimum results will be achieved if the driver can function without device-specific data. See if additional initialization is required.

If for some reason, the device driver can not take device-specific data from the Pen for OS/2 system, then the common capabilites packet flag entry must be set to CCAP_DEFAULTDATA for each device (locator, button, display, and so forth) that cannot be customized. A default entry of CCAP_OS2INI must be made to ensure the flag is initialized.

If the sample rate for the locator can not be changed, set the locator-specific capabilities packet entry max_sample_rate to 0, and set the sample_rate entry to the fixed sample rate. For example, if sample_rate is 100, and max_sample_rate is 0, then the sample_rate will be fixed at 100 points per second.

DevHlp_RegisterDeviceClass
A pen device driver is required to identify that it has Pen for OS/2 logical devices during initialization using DevHlp_RegisterDeviceClass. RegisterDeviceClass eliminates the need to modify the CONFIG.SYS statement for other device drivers, such as MOUSE.SYS with TYPE= statements to establish bindings.

The pen device driver registers as DevClass=DEVCLASS_INPUT with DCFlags declaring that extended information will be generated (allowing for the possibility of future uses of DEVCLASS_INPUT) and identifying the method of attaching the pen hardware product. MOUSE.SYS uses the latter to avoid loading built-in mouse support for devices supported by the pen device driver. The OS/2 mouse driver loads mouse support based on a query of likely mouse hardware connected. This support is called built-in mouse support. ddname db 'PENDD$',0 .       .        .  mov  cx, DEVCLASS_INPUT            ; Device class mov di, REG_EXT_IF                ; Device class flags lea si, ddname                    ; Device driver name (ASCIIZ) mov ax, cs                        ; Ax:bx ->driver entry point lea bx, Idc_DriverEntryPoint mov dl, DevHlp_RegisterDeviceClass call DeviceHelp                   ; Register my driver with Pen for OS/2 The Pen for OS/2 Device Driver Services use the device driver name to perform a DevHlp_AttachDD. The pen device driver's device header must enable AttachDD and declare an AttachDD entry point. describes the use of the driver entry point. The Pen for OS/2 Device Driver Services do not use the AttachDD entry point and it is available for other private uses. See for complete details of the DevHlp_RegisterDeviceClass interface.

Logical Device Registration
┌───────────────┐                     ┌───────────────┐  │               │ QUERY_CAPABILITIES   │               │ │ Pen Device   ◄──────────────────────┤ Pen for OS/2  │ │ Driver       │                      │ Device Driver │ │              │ START_LOGICAL_DEVICE │ Services      │ │              ◄──────────────────────┤               │  │               │                      │               │  │               │ REGISTER_DEVICE      │               │ │              ├──────────────────────►               │  │               │                      │               │  │               │ READ_ENABLE          │               │ │              ◄──────────────────────┤               │  │               │                      │               │  └───────────────┘                      └───────────────┘ After the initialization command has completed, the Pen for OS/2 Device Driver Services, using the driver entry point declared with DevHlp_ egisterDeviceClass, will contact the pen device driver in ring 0 kernel mode. The Pen for OS/2 Device Driver Services will query the driver for the number of defined logical devices (see ). A driver with one logical device would return 2; 1 for unit 0, and 1 for the logical device at unit 1.

Then, Pen for OS/2 Device Driver Services will request the level of the driver's interface (see ), along with the rest of the capabilities information for each logical device. The capabilities information can be requested more than once.

Next, each Pen for OS/2 Device Driver Service identifies itself by passing its direct call service entry point to the driver with a START_LOGICAL_DEVICE IDC request for each logical device supported by the Pen for OS/2 system. The service entry point is passed in the SINFO data structure as shown in the following figure. Before returning from START_LOGICAL_DEVICE, the logical device registers with the Pen for OS/2 Device Driver Services with a REGISTER_DEVICE call to the service entry point of the Pen for OS/2 Device Driver Services. Idc_StartDevice Proc                           ; Start logical device .   .    .  mov  ax, es:[di].sinfo_service_ds              ; The architecture allows for mov [bx].dcb_service_ds, ax                   ; more than one service entry mov ax, word ptr es:[di].sinfo_service_rtn    ; point. Currently, there is mov  word ptr [bx].dcb_service_rtn, ax         ; only one defined. mov ax, word ptr es:[di].sinfo_service_rtn+2 mov word ptr [bx.].dcb_service_rtn+2, ax. .   .  mov  ax, REGISTER_DEVICE mov di, [bx].dcb_@RegCaps push ds push bx                                        ; bx = device control block push ds pop  es  mov  ds,[bx].dcb_service_ds call es:[bx].dcb_service_rtn              ; es:di = device capabilities packet pop bx  pop  ds Unlike the standard MOUSE.SYS protocol, there is no interrupt packet address to remember and an AttachDD to MOUSE.SYS is not needed to pass the event data. See for complete details.

Calling READ_ENABLE is the final step and is issued once by the Pen for OS/2 Device Driver Services to enable event reporting and capability updates for all successfully registered logical devices. Special capabilities and operation styles are identified by the Pen for OS/2 Device Driver Services. You can change the defaults by resetting the bits and returning the value to Pen for OS/2 Device Driver Services.

Delayed Initialization
┌────────────────┐                ┌───────────────┐ │ Initialization │                 │ Pen for OS/2  │ │ Program       │                 │               │ └───┬────────┬───┘                └───────▲───────┘     │        │ Access to                   │ │       │ Device-Specific             │ │       │ Data ┌───────────────┐      │ │       │      │ Configuration │      │ Updated │       └──────► Data          │      │ Capabilities │              │               │      │     │ IOCtl         └───────────────┘      │ │ Interface                           │ ┌───▼────────────┐                ┌───────┴───────┐ │ Initialization │   UPDATE_CAPS   │ Pen for OS/2  │ │ Program       ├─────────────────► Device Driver │ │               │                 │ Services      │ └────────────────┘                └───────────────┘ Setting the driver to perform all its required initialization during device driver initialization results in optimum performance; but if necessary, you can use a program that completes driver initialization depending on your hardware.

One possible purpose for a developer to write a delayed initialization program is to set Pen for OS/2 device variables not exposed on device objects. These variables are: A pen device driver can have a delayed initialization program invoked either as a RUN= statement in CONFIG.SYS or from a program reference in the OS/2 Startup folder. You can pass device-private data to the pen device driver with private IOCtls and do whatever is necessary to initialize the device.
 * PPMID_STABILITY
 * PPMID_DIVIDE_RATE

If the registered capabilities are changed, the pen device driver must update the capabilities with the appropriate device-type service.

It is not necessary to pass device-specific data or Pen for OS/2 variables during initialization. As described in, the Pen for OS/2 system will pass this data when it starts up.

Operations
Pen for OS/2 system extension provides the pen device driver with operations including the processing of locator, button, and display devices. The flow of events is controlled and the device driver configuration can be updated at any time.

Locator Device Processing
┌────────────────┐                   ┌─────────────────┐ │ Pen Device     │                    │ Pen for OS/2    │ │ Driver        │                    │ Device-Driver   │ │               │  QUERY_DEV_CONFIG  │ Services        │ │               ◄────────────────────┤                 │ │                │                    │ Locator Service │ │               │                    │                 │ │                │                    │                 │ └────────────────┘                    └─────────────────┘ In addition to device registration, each locator device receives a call from the QUERY_DEV_CONFIG IDC request. The driver responds by copying its device data back to the Pen for OS/2 Device Driver Services. Unlike the standard MOUSE.SYS protocol, there is no interrupt packet address to remember and an AttachDD to MOUSE.SYS is not needed.

The QUERY_DEV_CONFIG request is defined for all device types, but only the locator device has a data packet defined for return to the Pen for OS/2 Device Driver Services. The other device types do not copy data back to the Pen for OS/2 Device Driver Services.

This process repeats for all registered locator devices.

Interrupt Packet IDC Interface
┌────────────────┐                   ┌─────────────────┐ │ Pen Device     │                    │ Pen for OS/2    │ │ Driver        │                    │ Device Driver   │ │               │    REPORT_EVENT    │ Services        │ │ Locator Device ├────────────────────►                │ │               │                    │                 │ │                │                    │                 │ │                │                    │                 │ └────────────────┘                    └─────────────────┘ The inter-device driver communication (IDC) interface for the locator Pen for OS/2 Device Driver Services is similar to the standard OS/2 mouse device-dependent design. The pen device driver calls the Pen for OS/2 Device Driver Services at the service entry point address passed during service identification instead of the MOUSE.SYS IDC entry point. Locator devices pass an address to an extended information packet instead of filling in the MOUSE.SYS interrupt packet. The REPORT_EVENT service call supports both absolute and relative locator streams.

Along with the locator position, locator devices identify three types of events in the extended information packet: (1) standard mouse button events of button 1, 2, and 3 with and without movement; (2) changes in mouse button position; and (3) devices that support proximity report an event when the proximity zoneis entered and when the proximity zone is exited. The proximity zone is an area where locator action is sensed by a touch-sensitive device without the locator device contacting the touch-sensitive surface.

Event Rate Controls


The Pen for OS/2 system extension controls the rate of events with IOCtls in two ways. First, the sample rate IOCtl requests that the driver control the total number of sample events. Most pen hardware products support this, but if your hardware product does not, the pen device driver would discard locator events to reduce the sample rate as seen by the Pen for OS/ 2 system. The sample rate is set with the category 91 Set Locator Sample Rate IOCtl.

Second, a pass rate filter is used to control the rate of OS/2 events. Every locator event is passed to the Pen for OS/2 system, but only some of those are passed to the OS/2 operating system as standard mouse events. The pass rate is set with the category 91 Set Locator Pass Rate IOCtl.

The Pen for OS/2 Device Driver Services attempt to set the pass rate automatically based on the device's sample rate as reported during registration. Automatic pass rate is requested by setting the pass rate to 0 in the locator capabilities packet. The pen device driver's pass rate variable is set with the category 91 Set Locator Pass Rate IOCtl.

The automatic pass rate can be overridden by setting the pass rate field in the capabilities packet to a positive value. This value determines how many locator events are passed to the Pen for OS/2 system for every one mouse event passed to the OS/2 operating system. For example, if the pass rate is set to 2, then for every 2 locator events only one is passed as a standard OS/2 mouse event.

Events which contain changes in button events will not be discarded.

Coordinate Adjustments


This figure shows a typical digitizer system. The inner rectangle represents the liquid crystal display (LCD) surrounded by its display bezel. The digitizer extends beyond the LCD on all sides and is shown by the outer rectangle. The finger in the center of the screen and the dotted slide region are discussed in.

This model assumes that the LCD has fixed dimensions and that the digitizer has a fixed resolution that is constant and uniform. Therefore, the device extents can be calculated. For example, if an LCD dimension is 10 inches and the digitizer has a resolution of 100 units per inch, then the device extents are 1000. Points are reported with values ranging from 0 to 999. The device extents, as reported in locator capabilities, must not be updated from their initial values set during registration other than to adjust for video mode changes as discussed in.

The diagram shows the raw device coordinate system and the normalized device coordinate system. The raw device coordinate system can have its origin at any corner and report sample points relative to that point over the entire active region of the digitizer. Typically, the origin is at the upper-left corner. The normalized coordinate system must have its origin at the upper-left corner of the LCD and range from 0 to the reported extents less one.

The locator event packet reports the normalized coordinates to the Pen for OS/2 Device Driver Services. The Pen for OS/2 Device Driver Services convert the normalized coordinates to PM screen coordinates. PM screen coordinates for video graphics array (VGA) are 640 x 480 pixels. Pen-aware applications have access to the PM screen coordinates, the more granular normalized coordinates, and standard coordinates based on a standard digitizer resolution of 1000 points per inch.

The calibration process determines the location of the LCD relative to the digitizer by collecting the raw device coordinates of the LCD corners. In the sample calibration program provided in the Pen for OS/2 Developer's Toolkit, the measured extents are found by calculating the corners of the LCD, as shown by the large arrows in the previous figure. (See for a description of the sample calibration program provided in the Pen for OS/2 Developer's Toolkit.)

Raw device coordinates must be transformed to the normalized coordinate system. First, raw device points must be translated from the raw origin to the normalized origin by adding an origin adjustment offset. Next, the value must be scaled in case the measured extent, as determined by the calibration points, does not exactly match the expected fixed device extent. This is done by multiplying the value by the fixed extent, dividing by the measured extent, and rounding up. Round off this value to ensure that it does not exceed the fixed device extent less one. Finally, the value might need to be inverted if the origin of the raw device coordinates is at a corner other than the upper left. Xnorm = (Xraw+Xxadj) (Xextent / Xmeasured)

Ynorm = (Yraw+Yyadj) (Yextent / Ymeasured) Pen for OS/2 Device Driver Services normalize z-coordinates to range from 0 to -4KB (KB equals approximately 1000 bytes) for pressure and 0 to 4KB for height.



Digitizers located below the LCD exhibit parallax as illustrated in this figure. Parallax is a condition that occurs when a gap exists between the locator position and the displayed ink. When the pen is at position A, the locator position and displayed ink at AL match. When the locator is at position B, the ink appears at BL. A gap exists between the locator position and the ink. The ink would appear at position BL*.

The distance between the display surface and the LCD cell is often about 3. 0 millimeters. In this case, where the eye angle is at 45 degrees, the gap is 3.0 millimeters.

The parallax differs in both the horizontal and vertical views by how a user looks at the display. This makes software correction for parallax unreliable. Parallax can result in a difference between the expected device extents and the measured device extents.

Finger Offset
You can improve the finger selection ability by offsetting the OS/2 pointer so it remains visible and appears to be pointing at the tip of the finger, instead of underneath the finger.

The figure, "Digitizer Coordinate Systems", shows a finger with a y- coordinate offset. If the offset were just added to the locator position, there would be a region on the bottom of the screen that could not be selected. To compensate for this, a slide region is used for this part of the screen. Gradually removing the offset in this region makes the entire region selectable.

Offsets are set through a device object and managed through the Pen for OS/ 2 system extension. The category 91 Set Locator Offset IOCtl informs the pen device driver of the change when the variable changes through the Pen for OS/2 system.

High-Resolution Device Time Stamp
The pen device driver can supply a high-resolution, double word (DWORD) device time stamp. The resolution of the high-resolution timer is specified in the capabilities packet in microseconds. For example, if the timer resolution of a device is 256 microseconds, then dev_timestampRes in the locator capabilities packet would be set to 256 and the pen capabilities PENCAP_TIMESTAMP bit would be set.

If the pen hardware product does not supply a high-resolution timer, then the locator capabilities packet's dev_timestampRes field would be set to 0, and the locator event packet's dev_timestamp field would be set to 0.

The pen device driver need not fill in the event time stamp, cev_timestamp. The Pen for OS/2 Device Driver Services handle this operation.

Fake Points and Proximity Events
The pen device driver must set the LOC_FAKE bit in cntrl field of the locator event packet if the coordinates specified are not valid. The last valid coordinates must be used. The first part of a stroke would generate an enter proximity zone event by setting EV_ENTER_PROX in the devicebits field.

If the device supports proximity but the device does not generate an exit proximity zone event, the pen device driver must time out the stroke and generate an event with LOC_FAKE set using the last valid coordinates. Neither LOC_CONTACT nor LOC_PROX must be set in lev_cntrl, and EV_EXIT_PROX must be set in the cev_devicebits field.

Suppressed Duplicate Proximity Points
By default, the device driver ignores duplicate proximity points if the pen has been left on the surface of the display. The mouse is not frozen in place and automatic backlight timeout processing is possible.

Performance Considerations
The following list describes items that affect the performance of a Pen for OS/2 system extension.
 * Locator device performance is critical to the Pen for OS/2 system. Code path lengths would be optimized due to the frequency of execution.
 * Locator devices that can control their interrupt rate would attempt a default rate of about 100 samples per second. Too many interrupts overload the system and too few result in poor stroke processing.
 * If possible, the locator device would self-detect exiting of the proximity zone. Relying on the locator engine to time out the stroke will delay stroke completion processing in the Pen for OS/2 system.

Button Device Processing
▲                                        │ Events Reported │ to Pen for OS/2 ┌────────────────┐                   ┌─┴───────────────┐ │ Pen Device     │                    │ Pen for OS/2    │ │ Driver        │                    │ Device Driver   │ │               │    REPORT_EVENT    │ Services        │ │ Button Device ├────────────────────►                 │ │               │                    │                 │ │                │                    │                 │ │                │                    │                 │ └─▲──────────────┘                    └─────────────────┘   │   │ External Hardware Events A device object assigns actions to the pen hardware product's buttons through the Pen for OS/2 system extension API and informs the pen device driver using the category 92 Set Button Assignment IOCtl. The Query Button Assignment IOCtl can query the current assignment. The number of buttons and a summary of their assignment is obtainable by reading the unit capabilities packet with the Query Unit Capabilities IOCtl.

The driver reports all button events to the Pen for OS/2 Device Driver Services. The Pen for OS/2 Device Driver Services filter some of these events and do not pass them to the Pen for OS/2 system. The pen device driver reports all activations and releases, regardless of the state of the other logical devices.

The following assignments are possible:


 * Null:Buttons assigned to null action generate no action on activation or release. The button states are reported by the locator point stream.


 * Mouse-emulation buttons:Mouse-emulation buttons modify the normal mouse-button event emulation. Instead of the mouse button 1 emulating the stroke, mouse button 1 can be emulated as mouse button 2, mouse button 3, or a combination of mouse button 1, mouse button 2, and mouse button 3. The modification occurs while holding down a button, or during the next stroke after activating and releasing a button. A second activation and release cancels the modification so that the next stroke is not a modified mouse event.
 * Note: Pressing pen buttons is not like pressing mouse buttons. Mouse buttons generate a mouse event when activated and released. Pen buttons change the emulated mouse stream during the pen stroke but do not generate locator events directly as a result of activation or release.


 * Gesture mode:A stroke in gesture mode will force gesture recognition, even though the stroke might be in a drawing mode.


 * Hot-key buttons:The Pen for OS/2 device driver reports hot-key buttons to the Pen for OS/2 Device Driver Services. The pen device driver takes no action. The Pen for OS/2 Device Driver Services conditionally generate an event to the OS/2 operating system, and then report the event to the Pen for OS/2 system. The Pen for OS/2 Device Driver Services might not generate the event if the system is currently locked up or if the display has been turned off. The pen device driver always reports all activations and releases.


 * Other:All other assignments result in the buttons being reported to the Pen for OS/2 system by the device driver. The device driver uses the REPORT_EVENT Pen for OS/2 Device Driver Service to report the buttons. provides a complete list of these assignments.

The state of all buttons is reported on each locator event in the locator event stream.

Display Device Processing
│ Backlight Control                      Events Reported ▲ │ IOCtls                                 to Pen for OS/2 │ ┌─▼─────────────────┐                   ┌──────────────────┼──┐ │ Pen Device Driver │                    │ Pen for OS/2     │  │ │                  │                    │ Device Driver    │  │ │                  │  QUERY_ACTIVITY    │ Services         │  │ │ Poll for Activity ├────────────────────►                 │  │ │                  │                    │                  │  │ │ Turn Off          │  REPORT_EVENT      │                  │  │ │ Backlight +      ├────────────────────┼──────────────────┤  │ │                  │                    │                  │  │ │                   │  REQUEST_CALLBACK  │                  │  │ │                  ├────────────────────►                  │  │ │                   │                    │ Activity Trigger │  │ │ Turn On          │  Call Back         │                  │  │ │ Backlight +      ◄────────────────────┤                  │  │ │                  │                    │                  │  │ │                   │  REPORT_EVENT      │                  │  │ │                  ├────────────────────┼──────────────────┘  │ │                   │                    │                     │ └───────────────────┘                    └─────────────────────┘ The Pen for OS/2 system extension provides APIs to turn on the display's backlight, turn off the display's backlight, and enable automatic backlight control. The Pen for OS/2 system informs the pen device driver of these activities with the category 93 Set Display State and Set Display Inactivity Period IOCtls. Query Display State queries the state of the backlight.

If the pen device driver chooses to support the automatic inactivity period, a timer routine queries the system's input activity with the QUERY_ACTIVITY Pen for OS/2 Device Driver Service. This call returns a summary activity count from the OS/2 mouse devices, all pen device drivers, and the keyboard device. The pen device driver must turn off the display if the returned count has not changed during the assigned inactivity period. The REPORT_EVENT service call reports an event to the Pen for OS/2 system.

The pen device driver can request notification of input activity with the REQUEST_CALLBACK service call. The Pen for OS/2 Device Driver Services will call the device entry point the next time locator, button, mouse, or keyboard activity occurs. The pen device driver must turn the display back on and report the event with REPORT_EVENT.

By default, the Pen for OS/2 Device Driver Services ignore locator mouse-button emulation and button device hot-key generation while the backlight is off. Points are processed if requested through the Set Display Inactivity Period IOCtl by enabling OPAQUE support. See.

QUERY_ACTIVITY and REQUEST_CALLBACK are available to all device types.

A pen device driver can choose to override mouse-button events for a short period of time with the SUPPRESS_STROKE service call and enabling suppress support through the Set Display Inactivity Period IOCtl. For example, the stroke causing an ACTIVITY_CALLBACK which in turn resulted in the display backlight turning on can report to the OS/2 operating system as mouse movement with no mouse-button events to avoid possible unwanted action. The stroke could have originated from any pen device driver. The Pen for OS/2 Device Driver Services control the length of the interval.

Event Flow Control
┌───────────────┐                     ┌───────────────┐ │               │                      │ Pen for OS/2  │ │ Pen Device   │    ENABLE_DEVICE     │ Device Driver │ │ Driver       ◄──────────────────────┤ Services      │ │              │                      │               │ │               │    DISABLE_DEVICE    │               │ │              ◄──────────────────────┤               │ └───────────────┘                      └───────────────┘ The Pen for OS/2 Device Driver Services control the flow of events from the pen device driver with ENABLE_DEVICE and DISABLE_DEVICE. There are brief periods of time, during session switching, for example, when the Pen for OS/2 Device Driver Services will not process events. To stop the flow of events, the Pen for OS/2 Device Driver Services make a call to the pen device driver with the DISABLE_DEVICE IDC request. The pen device driver must mask interrupts from its device when it receives the call from DISABLE_DEVICE to stop the flow of events to the Pen for OS/2 Device Driver Services.

The pen device driver would reenable interrupts, and then resume sending events when it receives the call from the ENABLE_DEVICE IDC request.

The device would start in a disabled state and wait for a call from ENABLE_DEVICE before sending any events or capability updates. ENABLE_DEVICE and DISABLE_DEVICE are issued once globally to the pen device driver. The driver must enable and disable all logical devices.

Configuration Update
┌────────────────┐                    ┌───────────────┐ │ Workplace Shell│        APIs         │ Pen for OS/2  │ │ Configuration ├─────────────────────►               │ │ Object        │ Update Pen for OS/2 │               │ └───┬────────┬───┘   Variables and    └──┬──┬──▲──────┘ │       │     Device-Specific Data   │  │  │ │       │                            │  │  │     │        │      ┌───────────────┐     │  │  │     │        │      │ Device-       │     │  │  │ │       │      │ Specific      │     │  │  │Updated │       └──────► Configuration │     │  │  │Capabilities │              │ Data          │     │  │  │ │              └───────────────┘     │  │  │     │               ┌───────────────┐     │  │  │     │               │ Pen for OS/2  │     │  │  │ │              │ Configuration ◄─────┘  │  │ │ Private      │ Data          │        │  │ │ IOCtls       └───────────────┘        │  │ │          IOCtls                       │  │ │       ┌───────────────────────────────┘  │     │        │                                  │ ┌───▼────────▼───┐                     ┌────────┴──────┐ │ Pen Device     │     UPDATE_CAPS     │ Pen for OS/2  │ │ Driver        ├─────────────────────► Device Driver │ │               │                     │ Services      │ └────────────────┘                    └───────────────┘ The device objects generate device-private data, device-specific data, and Pen for OS/2 system extension variables. The values of this data can be updated at any time.

The previous figure shows the actions taking place during an update. Pen for OS/2 variables change through Pen for OS/2 API functions that inform the pen device driver using the Generic IOCtl Interface.

The Pen for OS/2 system also manages a small amount of device-specific data. This data is changed through WrtSetInputDeviceVariable and the pen device driver is updated with the Set Unit Specific Data IOCtl.

Private IOCtls communicate changes in device-private data to the pen device driver and Pen for OS/2 is not involved. You can define private IOCtls as necessary and save the data as appropriate.

If any field in the registered capabilities changes, the pen device driver must update the capabilities with the appropriate device-type service.

Pen Device Objects
Pen for OS/2 system extension device objects are Workplace objects that provide a means of communication between a computer and another piece of equipment. The Locator object enables the configuration of barrel button settings and hardware that is of the absolute locator device type (LOCTYPE_PEN and LOCTYPE_FINGER). The Display object enables the configuration of LCD display devices and bezel buttons and provides a means for the user to set the timeout for the backlight.

If you supply hardware devices that will interface to the Pen for OS/2 system, you must create a similar object or subclass one of the objects included with Pen for OS/2.

Workplace Object Classes Hierarchy
The following shows the Pen object classes as they fit into the predefined Workplace object class hierarchy. Each branch in the tree represents an immediate descendant (subclass) of a Workplace object class. CLASS NAME                                  CLASS FILE NAME SOMObject                                     SOMOBJ.SC    │ └─WPObject (replaced by PenObject)         PENOBJ.SC         │ └─WPAbstract                          WPABS.SC              │ └─PenButtonDevice                PENBTNDV.SC                   │ ├─PenDisplay                WPDISPLY.SC                   │ └─PenLocator                WPLOCATR.SC                        │ ├─PenLocatorFinger     WPLOCFGR.SC                        │ └─PenLocatorPen        WPLOCPEN.SC Subclassing an object class creates a child class that modifies the behavior of the parent class based on the child's new methods, instance data, and overriding parent methods. An object class is subclassed by deriving the new child class from the parent class. The parent's methods can be altered or supplemented by the new class and new instance data can be added and manipulated by the new child class.

The predefined System Object Model (SOM) object class, SOMObject, is the root class for all SOM object classes, including all Workplace object classes. No external programming interfaces exist permitting another OS/2 process to invoke methods. However, some API functions exist, such as WinSetObjectData, enabling other processes limited communication with an object. The interface to the device objects is through Workplace published classes. Information on SOM and Workplace objects can be found in Workplace Shell Programming Reference and in Workplace Shell Programming Guide.

Invocation of the new device objects will work in a manner similar to the current Mouse object. You can alter the system parameters for these devices using the Settings notebook. While in the Settings notebook of a device object, you can set parameters used by a device driver and the Pen for OS/2 system. These parameters control the operational characteristics of a device. Parameters represent items such as tap rates, delay times, function switches, and the functions performed when device buttons are pressed.

Workplace Object Classes
The following sections describe the object classes listed below:
 * PenButtonDevice
 * PenDisplay
 * PenLocator
 * PenLocatorFinger
 * PenLocatorPen

PenButtonDevice
Class definition file: penbtndv.idl

Class hierarchy:
 * SOMObject
 * WPObject
 * PenObject
 * WPAbstract
 * PenButtonDevice

The following are the PenButtonDevice methods:
 * penAddButtonMappingsPage
 * penQueryButtonData
 * penSetButtonData

The following is the class method for the PenButtonDevice class:
 * penclsQueryButtonData

The following are the methods overridden by the PenButtonDevice class:
 * wpAddSettingsPages
 * wpInitData
 * wpRestoreState
 * wpSaveState
 * wpSetup
 * wpUnInitData

The following is the class method overridden by the PenButtonDevice class:
 * wpclsInitData

When an instance of the PenButtonDevice object is created, it will parse the setup string and scan for two "keyword=value" combinations.

The following table shows the keyword-value pairs supported by the PenButtonDevice class. Note: PenButtonDevice determines if the instance has button capabilities and, if so, a Buttons page is inserted into the Settings notebook of the instance. Because PenDisplay and PenLocatorPen are subclasses of PenButtonDevice, any pen that has button capabilities will automatically have a Buttons page inserted into its Settings notebook when it is installed.

PenDisplay
Class definition file: wpdisply.idl

Class hierarchy: SOMObject WPObject PenObject WPAbstract PenButtonDevice PenDisplay The following is the PenDisplay method:
 * penAddDisplayBacklightPage

The following are the methods overridden by the PenDisplay class:
 * wpAddObjectWindowPage
 * wpAddSettingsPages
 * wpFilterPopupMenu
 * wpOpen

The following are the class methods overridden by the PenDisplay class:
 * wpclsQueryDefaultHelp
 * wpclsQueryDefaultView
 * wpclsQueryIconData
 * wpclsQueryStyle
 * wpclsQueryTitle

Note: If you are developing a device driver for a liquid crystal display (LCD), you must either create an instance of this class in the Devices folder with the appropriate setup string or subclass this object class and add it to the Devices folder. Pages can be added and replaced to fully support the required interface to the device settings. For example, you might want to provide a Settings page that enables the user to adjust the gray scaling for a monochrome LCD.

PenLocator
Class definition file: wplocatr.idl

Class hierarchy: SOMObject WPObject PenObject WPAbstract PenButtonDevice PenLocator The following is the PenLocator method:
 * penAddLocatorTimingPage

The following is the PenLocator class method:
 * penclsQueryDefaultPause
 * penclsQueryPauseEnableDefault

The following are the methods overridden by the PenLocator class:
 * wpAddSettingsPages
 * wpAddObjectWindowPage
 * wpFilterPopupMenu
 * wpInitData
 * wpMenuItemSelected
 * wpMenuItemHelpSelected
 * wpModifyPopupMenu
 * wpRestoreState
 * wpSaveState
 * wpSetup
 * wpUnInitData
 * wpOpen

The following are the class methods overridden by the PenLocator class:
 * wpclsQueryDefaultHelp
 * wpclsQueryDefaultView
 * wpclsQueryIconData
 * wpclsQueryStyle
 * wpclsQueryTitle

When an instance of the PenLocator class is created, it will parse the setup string and scan for two "keyword=value" combinations. The following table shows the keyword-value pairs supported by the PenLocator class.

PenLocatorFinger
Class definition file: wplocfgr.idl

Class hierarchy: SOMObject WPObject PenObject WPAbstract PenButtonDevice PenLocator PenLocatorFinger The following is the PenLocatorFinger method:
 * penAddFingerOffsetPage

The following are the methods overridden by the PenLocatorFinger class:
 * wpInitData
 * wpRestoreState
 * wpSaveState
 * wpAddSettingPages

The following are the class methods overridden by the PenLocatorFinger class:
 * penclsQueryDefaultPause
 * penclsQueryPauseEnableDefault
 * wpclsQueryIconData
 * wpclsQueryTitle
 * wpclsQueryDefaultHelp

PenLocatorFinger is a subclass of the PenLocator class. This class adds an additional page, Offset, to the Settings notebook. The Offset page enables you to set finger offset to the screen pointer. This is accomplished through the penAddLocatorFingerOffsetPage method. If you are developing a device driver for a touch-sensitive display, you must either create an instance of this class in the Devices folder with the appropriate setup string, or subclass this class and add it to the Devices folder. Pages can be added and replaced to fully support the required interface to the device settings.

Note: The Offset page supports only display devices with the origin in the upper-left corner of the device.

PenLocatorPen
Class definition file: wplocpen.idl

Class hierarchy: SOMObject WPObject PenObject WPAbstract PenButtonDevice PenLocator PenLocatorPen The following are the class methods overridden by the PenLocatorPen class:
 * penclsQueryDefaultPause
 * penclsQueryPauseEnableDefault
 * wpclsQueryIconData
 * wpclsQueryTitle
 * wpclsQueryDefaultHelp

Workplace Instance Methods
The following sections describe the Workplace instance methods listed below:
 * 
 * 
 * 
 * 
 * 
 * 

penAddButtonsMappingsPage
This method enables the object to add the Buttons page to its Settings notebook. PenButtonDevice    *self; HWND                hwndNotebook; ULONG               rc;

rc = _penAddButtonsMappingsPage(self, hwndNotebook);

self(PenButtonDevice *) - input The pointer to this object.
 * Parameters

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

rc(ULONG) - returns Page indentifier:
 * 0 Error occurred.
 * PageId Identifier for the inserted page.

This method must be called from within an override of the wpAddSettingsPages method.
 * Usage

This method is overridden to replace or remove the Buttons page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent.
 * Override Methods

penQueryButtonData
This method enables the object to query the button bit maps and names to be used for this object instance. PenButtonDevice    *self; PPENEVENTDATA       pPenEventData; ULONG               ulBufSize;

ulBufSize = _penQueryButtonData(self, pPenEventData);

self (PenButtonDevice *) - input The pointer to this object.
 * Parameters

pPenEventData (PPENEVENTDATA) - in/out A pointer to a buffer that will receive an array of PENEVENTDATA structures. The structures contain the data to be used for the button list box in the Settings notebook of this object instance. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will be returned.

ulBufSize (ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this object.

This method can be called at any time to query the current button bit map and name data for this object.
 * Usage

This method is generally not overridden.
 * Override Methods


 * Related Methods
 * 
 * 

penSetButtonData
This method enables the object to set the button bit maps and names to be used for this object instance. PenButtonDevice    *self; PPENEVENTDATA       pPenEventData; BOOL                rc;

rc = _penSetButtonData(self, pPenEventData);

self (PenButtonDevice *) - input The pointer to this object.
 * Parameter - self

self (PenButtonDevice *) - input The pointer to this object.
 * Parameters

pPenEventData (PPENEVENTDATA) - input A pointer to an array of PENEVENTDATA structures. These structures contain data to be used for the button list box in the Settings notebook of this object instance.

The pPenEventData buffer must contain one PENEVENTDATA structure for each button that is registered by the device driver. Also, the order in which these structures are placed within the buffer must match the order in which the buttons are registered by the device driver with the Pen for OS/2 system.

rc(BOOL) - returns Success indicator:
 * TRUE Successful completion.
 * FALSE Error occurred.

This method can be called at any time to change the current button bit map and name data for this object.
 * Usage

This method is generally not overridden.
 * Override Methods


 * Related Methods
 * 
 * 

penAddLocatorTimingPage
This method enables the object to add the Timing page to its Settings notebook. PenLocator    *self; HWND           hwndNotebook; ULONG          rc;

rc = _penAddLocatorTimingPage(self, hwndNotebook);

self (PenLocator *) - input The pointer to this object.
 * Parameters

hwndNotebook (HWND) - input The handle of the notebook in which to insert the page.

rc (ULONG) - returns Page identifier:
 * 0 Error occurred.
 * PageId Identifier for the inserted page.

This method must be called from within an override of the wpAddSettingsPages method.
 * Usage

This method is overridden in order to replace or remove the Timing page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent.
 * Override Methods

penAddDisplayBacklightPage
This method enables the object to add the Backlight page to its Settings notebook. PenDisplay    *self; HWND           hwndNotebook; ULONG          ulPageId;

ulPageId = _penAddDisplayBacklightPage(self,            hwndNotebook);

self (PenDisplay *) - input The pointer to this object.
 * Parameters

hwndNotebook (HWND) - input The handle of the notebook in which to insert the page.

ulPageId (ULONG) - returns Page identifier:
 * 0 Error occurred.
 * PageId Identifier for the inserted page.

This method must be called from within an override of the wpAddSettingsPages method.
 * Usage

This method is overridden in order to replace or remove the Backlight page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent.
 * Override Methods

penAddFingerOffsetPage
This method enables the object to add the Offset page to its Settings notebook. PenLocatorFinger    *self; HWND                 hwndNotebook; ULONG                rc;

rc = _penAddFingerOffsetPage(self, hwndNotebook);

self (PenLocatorFinger *) - input The pointer to this object.
 * Parameters

hwndNotebook (HWND) - input The handle of the notebook in which to insert the page.

rc(ULONG) - returns Page identifier:
 * 0 Error occurred.
 * PageId Identifier for the inserted page.

This method must be called from within an override of the wpAddSettingsPages method.
 * Usage

This method is overridden in order to replace or remove the Offset page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent.
 * Override Methods

Workplace Class Methods
The following sections describe the Workplace Class methods listed below:
 * 
 * 
 * 

penclsQueryButtonData
This method specifies the default button bit maps and names used by PenButtonDevice instances. M_PenButtonDevice    *self;           /*  The pointer to the class object. */ PPENEVENTDATA         pPenEventData; ULONG                 ulSize;

ulSize = _penclsQueryButtonData(self, pPenEventData);

self (M_PenButtonDevice *) - input The pointer to the class object.
 * Parameters

pPenEventData (PPENEVENTDATA) - in/out A pointer to a buffer that will receive the array of PENEVENTDATA structures. These structures contain the data to be used for the button list box in the Settings notebooks of instances of this class. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will still be returned. This buffer must always contain one valid PENEVENTDATA structure for each button registered with the Writing subsystem by the device driver.

ulSize(ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this particular class object.

If NULL is passed for the pPenEventData parameter, the size of the PENEVENTDATA array buffer needed for this class will be returned. This can be used for memory allocation purposes. Otherwise, the pPenEventData parameter will always be assumed to be large enough to accommodate the array of PENEVENTDATA structures for this class.
 * Remarks

This method can be called at any time. Typically, it would not be useful for another object class to call this method.
 * Usage

Workplace classes that wish to have unique button bit maps and name text must override this method and fill out the appropriate fields within the array of PENEVENTDATA structures. In addition, the correct size of PENEVENTDATA structures must always be returned.
 * Override Methods

The pPenEventData buffer must contain one PENEVENTDATA structure for each button that is registered by the device driver. Also, the order in which these structures are placed in the buffer must match the order in which the buttons are registered by the device driver with the Pen for OS/2 system.


 * Related Methods
 * 
 * 

penclsQueryDefaultPause
This method enables the object to query the default pause setting for the Pen for OS/2 system. M_PenLocator    *self; ULONG            pause;  /*  The default system setting for pause in milliseconds. */

pause = _penclsQueryDefaultPause(self);

self (M_PenLocator *) - input The pointer to the PenLocator class object.
 * Parameter - self

pause (ULONG) - returns The default system setting for pause in milliseconds.
 * Return Value - pause

self (M_PenLocator *) - input The pointer to the PenLocator class object.
 * Parameters

pause (ULONG) - returns The default system setting for pause in milliseconds.

This method can be called at any time.
 * Usage

This method can be overridden to specify a different default pause value.
 * Override Methods

penclsQueryPauseEnableDefault
This method enables the object to query the default pause-enable setting for the Pen for OS/2 system. M_PenLocator    *self; ULONG            rc;    /*  The default system setting for pause-enable is returned. */

rc = _penclsQueryPauseEnableDefault(self);

self (M_PenLocator *) - input The pointer to the class object.
 * Parameter - self

rc (ULONG) - returns The default system setting for pause-enable is returned.
 * Return Value - rc

Possible values are:
 * TRUE Pause is enabled.
 * FALSE Pause is not enabled.

self(M_PenLocator *) - input The pointer to the class object.
 * Parameters

rc(ULONG) - returns The default system setting for pause-enable is returned.

Possible values are:
 * TRUE Pause is enabled.
 * FALSE Pause is not enabled.

This method can be called at any time.
 * Usage

This method can be overridden to specify a different default pause enable value.
 * Override Methods

Modifying the Pen for OS/2 Device Objects
The Pen for OS/2 system extension device objects provide a generic set of functions for customizing device settings, such as, pen and finger pause rate, double-tap rate, button mappings, and backlight timeout. You can use the provided classes and create object instances of these classes in your install procedure, or you can modify the classes to further refine their behavior.

Subclassing is the process of modifying the behavior of an existing object class. This section provides information on how to subclass Pen for OS/2 device object classes to modify their behavior. For general information on SOM and Workplace Shell programming, refer to:
 * Workplace Shell Programming Guide
 * System Object Model Programming Guide
 * Workplace Shell Programming Reference
 * Pen for OS/2 Programming Guide and Reference

Creating Default Instances of Pen for OS/2 Object Classes
Creating default instances of the Pen for OS/2 object classes is done by setting up an XXXX.WPO file. See, for a description of how the XXXX.WPO file is set up to create the default Pen for OS/2 device objects.

Slight Modification of a Pen for OS/2 Object Class
If the behavior of the Pen for OS/2 object class meets your requirements, with the exception of the icon and icon title, you can subclass, and with slight modification, customize the object to your liking.

For example, to subclass PenLocatorPen, you will need to create a class definition file (.CSC) to define your class. You also will need files WPLOCPEN.H and WPLOCPEN.IDL from the Pen for OS/2 Developer's Toolkit. In the .IDL file, you will need to define method overrides for the following methods: An example .CSC file is detailed in the following figure. #ifndef mypen_idl #define mypen_idl
 * wpclsQueryTitle
 * wpclsQueryIconData

#include "wplocpen.idl" #include 

interface M_MyPenClass;

interface MyPenClass:PenLocatorPen {

#ifdef __SOMIDL__ implementation {

//# Class Modifiers local; major version = 1; minor version = 1; filestem      = mypen; functionprefix = mypenm_; metaclass     = M_MyPenClass; callstyle     = oidl;

};  #endif /* __SOMIDL__ */ };

interface M_MyPenClass; {

#ifdef __SOMIDL__ implementation {

//# Class Modifiers local; functionprefix = mypenM_; major version = 1; minor version = 2; filestem      = mypen; callstyle     = oidl;

//# Method Modifiers

wpclsQueryTitle:override; wpclsQueryIconData:override;

};  #endif /* __SOMIDL__ */ };

# /* mypen_idl */ After creating the .C source file (and other SOM emitted files) by running the SOM compiler (the SOM compiler will create stubs for the methods in the .C source), modify the .C source as follows: SOM_Scope PSZ  SOMLINK mypenM_wpclsQueryTitle(M_MyPenClass *somSelf) {    return ((PSZ) "MyIconName"); } SOM_Scope ULONG SOMLINK mypenM_wpclsQueryIconData(M_MyPenClassName *somSelf,                                                    PICONINFO pIconInfo) {    if (pIconInfo) {       pIconInfo->fFormat = ICON_RESOURCE; pIconInfo->hmod   = MyModuleHandle; pIconInfo->resid  = ID_MYICON; }
 * wpclsQueryTitle would return a pointer to the name of the icon. Do not call the parent. An example follows:
 * wpclsQueryIconData would fill out the appropriate information in the ICONINFO structure and return the size of the structure. Do not call the parent. An example follows:

return (sizeof(ICONINFO)); } Finally, modify your installation procedure to register your new class and create an instance of your class. You will now have an object that has all the behavior of the Pen for OS/2 PenLocatorPen class, except the object will have the icon and title you specified through the method overrides above.

Increased Modification of a Pen for OS/2 Object Class
If your device requires additional settings, then you can accomplish this through subclassing and making more sizable modifications to the behavior. Or, if you do not want a Pen for OS/2 system extension page to be present in a Settings notebook, you might remove it through subclassing. For this example, the PenLocatorFinger class will be used. The Touch Offset Page will be removed from the Settings notebook of the Touch class.

To subclass PenLocatorFinger, you will need to create a class definition file (.IDL) to define your class. You also will need files WPLOCFGR.H and WPLOCFGR.IDL from the Pen for OS/2 Developer's Toolkit. In the .IDL file, you will need to define overrides for the method, penAddFingerOffsetPage.

An example .IDL file follows: #ifndef mytouch_idl #define mytouch_idl

#include "wplocfgr.idl" #include 

interface MyTouchClassName:PenLocatorFinger {

#ifdef __SOMIDL__ implementation {

//# Class Modifiers local; functionprefix = mytch_; majorversion  = 1; minorversion  = 1; filestem      = mytouch; callstyle     = oidl;

//# Method Modifiers penAddFingerOffsetPage:override; };  #endif /* __SOMIDL__ */ };

# /* mytouch_idl */

After creating the .C source file (and other SOM emitted files) by running the SOM compiler, modify the .C source as shown in the following example.

Note: penAddFingerOffsetPage would return SETTINGS_PAGE_REMOVED. Do not call the parent.

SOM_Scope ULONG  SOMLINK mytch_penAddFingerOffsetPage(MyTouchClassName *somSelf,                                                          HWND hwndNotebook) {     return (SETTINGS_PAGE_REMOVED); } Finally, modify your installation procedure to register your new class and create an instance of your class. You will now have an object that has all the behavior of the Pen for OS/2 PenLocatorFinger class, except the object will not have the Touch Offset page in its Settings notebook, as you specified through the method override above.

To perform more advanced modifications of a Pen for OS/2 object class (for example, adding your own Settings page), refer to Workplace Shell Programming Guide, System Object Model Programming Guide, Workplace Shell Programming Reference, and Pen for OS/2 Programming Guide and Reference.

The class definition files PENBTNDV.IDL, WPDISPLY.IDL, WPLOCATR.IDL, WPLOCPEN.IDL, and WPLOCFGR.IDL are included in the Pen for OS/2 Developer's Toolkit.

Installation Control Files
There are four control files used by the device driver installation program. The files must be created and placed on a device driver installation diskette along with the pen device driver and any optional programs you choose to provide such as calibration programs, auxiliary programs, or other utilities. The files might be in their original format or may be compressed into bundles using the IBM PACK.EXE utility program. The device driver installation program is invoked during Pen for OS/2 system extension installation. The user receives the option to install a pen device driver and specify where the pen device driver files are located. The pen device driver, ring 3 support programs, and dynamic link libraries are installed using the Pen for OS/2 installation program.

A description of each of the control files follows.

xxxxx.MCF Control File
xxxxx.MCF is the initial control file processed by the Pen for OS/2 installation program. In the Pen for OS/2 Developer's Toolkit, this file is PENDD.MCF for installation of the device driver named PENDD. The installation program searches for this file in the directory defined in the source path. The installation terminates if the file is not found. The contents of this file are detailed in the following figure. package="Your Device" filelist="PENDD.LST" groupcount=1 munitcount=1 medianame="Device Driver Installation Diskette" sourcedir = "\\"                 = 0 sourcedir = "\\HDCONTRL\\"       = 1 sourcedir = "\\INSTALL\\MMLCKDIR" = 2 /* Location of the unpacked files */ destindir = "\\"                 = 0 destindir = "\\INSTALL\\"        = 1 destindir = "\\DLL\\"            = 2 destindir = "\\INSTALL\\MMLCKDIR" = 3 /* For unpacking files           */ ssgroup=0 sssize=3500 ssname="PENDD device drivers" ssversion="0.00" ssinich="PENDD.WPO" ssconfigch="PENDD.CCH" ssdll="PENDD.DLL" ssdllentry="installentry"

The first five statements provide information about the installation process. The package keyword represents the name of the device driver installation package in the form of a quoted string. The string is displayed in the Specify the Pen device you want to install list box on the Pen for OS/2 device-driver target installation screen.

The filelist keyword is used during the installation process to identify the file that contains the list of files to be processed; for the Pen for OS/2 device driver named PENDD provided in the Pen for OS/2 Developer's Toolkit, the list is in PENDD.LST. The groupcount keyword defines the number of groups that make up the pen device-driver installation. A group is a collection of information that pertains to the installation of this device. In a Pen for OS/2 device driver installation, only one group is needed and groupcount must be 1. The munitcount and medianame keywords list the number of device-driver installation diskettes and the names of the diskettes.

The next seven statements define the source and target subdirectories used for the PENDD installation. The directories are defined by the entries numbered 0 and greater. Special mention must be made of the temporary subdirectory represented as both a source subdirectory, 2, and target subdirectory, 3. This is a temporary subdirectory that is used only at installation time. It is the destination for the unpacking of the compressed files. When the files are unpacked into this subdirectory, it becomes the source subdirectory because the files are moved from this temporary location to the permanent subdirectory. The IBM program, PACK.EXE, is the only supported compression program. The Pen for OS/2 device driver installation program uses UNPACK.EXE to decompress the packed files. PACK.EXE can be obtained from the Pen for OS/2 Developer's Toolkit.

The final eight statements define the installation group. The installation of PENDD utilizes only one group, named PENDD device drivers. If additional groups are added to the PENDD installation, they would require their own group definition statements. The sssize field shows how much space is required to install this group; the value is displayed on the User Prompts screen under the heading "Code to Install". The target drive must have at least the required amount of space or an error can occur when the user attempts to install to this location. The ssinich and ssconfigch fields define the other control files to be used during Pen for OS/2 installation. The final two fields, ssdll and ssdllentry, identify a group-specific dynamic link library (DLL) to be loaded and run during installation which permits some type of specialized processing to occur that is not covered during general installation of PENDD. If you are subclassing the device objects, you must include a DLL with an entry point to register and create an object of your new class. These last two fields are optional.

In addition to what is displayed are seven other fields that are used only to set additional information that cannot be set from the device driver. The fields are:
 * drivername = "Digitizer Mod 1 (The name is device-driver specific.)
 * PPMID_MOTION_STOP = "Pen", 14
 * PPMID_MOTION_START = "Pen", 32
 * PPMID_MINGESTURELENGTH = "Pen", 78
 * PPMID_TAPLENGTH = "Pen", 37
 * PPMID_TOUCHOFFSET_X = "Finger", 100
 * PPMID_TOUCHOFFSET_Y = "Finger", 100

"Pen" is the locator device name. It can be "Locator" or whatever other locator device you have. This information also is in the device driver. The six PPMID_ fields are used to customize the way the Pen Input subsystem interprets information from the device driver. These fields are useful for small tablets such as the Wacom Artpad.

xxxxx.LST Control File
This file contains a listing of the files to be processed by the device driver installation software and the location of the files. The first entry in this file is a number identifying the number of files to process during the installation. Next is a listing of those files, as shown in the following figure. /* File count                                                       */ 10 /* Disk   installation   target  source   file                 file */ /* Number group          subdirectories   name                 type */ 0      0              0       0       "PENDD.MCF"           2 0      0              0       0       "PENDD.LST"           2 0      0              1       0       "PENDD.CCH"           2 0      0              1       0       "PENDD.WPO"           2 0      0              0       0       "PENDD.SYS"           2 0      0              3       0       "PENDD.LS@"           3 0      0              2       2       "PROGR.EXE"           1 0      0              2       0       "PENDD.DLL"           2 0      0              0       0       "CAL.EXE"             2 0      0              0       0       "HELLO.EXE"           4

The first nonblank, noncomment record is a file count of the files that follow. All other entries have six fields. The first field is Disk Number. Disk numbering begins at 0. The largest number in this field must be less than the munitcount field in the xxxxx.MCF file.

The second field identifies the installation group that this file belongs to. PENDD contains only one installation group, so all entries will have 0 in this field. The third and fourth fields identify the target and source subdirectories to be used when processing this file. The fifth entry is the file name and the sixth entry is the file type. A description of the file types follows:
 * 1) The file was compressed in a packed file.
 * 2) The file is in original format.
 * 3) A packed file.
 * 4) The file is to be deleted.

From the preceding figure, the sixth, seventh, and tenth lines are as follows:
 * PENDD.LS@ is an packed file residing in directory 0 (that is, the root directory) on the diskette. This packed file is unpacked into its component file(s) into target destination directory 3 (for example, INSTAL\MMLCKDIR) on the target.
 * PROGR.EXE is a file that was compressed into PENDD.LS@. This file is moved from source subdirectory 2 (for example, INSTAL\MMLCKDIR) into target destination subdirectory 2 (for example, \DLL).
 * The file HELLO.EXE might exist from a previous installation of PENDD; it is no longer supported or needed and will be deleted at installation time if it still exists in the destination location.

xxxxx.WPO Control File
This control file defines the objects in the new Pen for OS/2 folder. The following figure is a sample entry used to create a Pen for OS/2 device object. The first entry in this file represents the number of WPObject entries to follow. The second entry is used to show the percent completed on the Updating system files progress indicator. The percent complete value from this file plus the percent values from .WPO and .CCH must equal 100 percent. 1 80 WPObject = ( WPClassName  = "WPFolder" WPTitle       = "Devices" WPSetupString = "OBJECTID=" WPLocation    = "" WPFlags       = OL ) WPObject = ( WPClassName  = "PenLocatorPen" WPTitle       = "Pen" WPSetupString = "OBJECTID=;CALPROG=$(DEST)CAL.EXE;                  CALPARMS=TRUE;                  PEN_DRIVER=Digitizer Mod 3;                  PEN_DEVICE=Pen" WPLocation    = "" WPFlags       = 1L ) Where:

$(DEST) A macro that is replaced by the full path that was specified as the destination path during device driver installation.

Pen The sample entry identifies a new object as a device object titled "Pen". It will be known by the OS/2 operating system as PENDD_STYLUS and reside in the Devices folder.

WPFLags Specifies an action on PENDD_STYLUS as follows:
 * 0 Indicates the creation should fail if PENDD_STYLUS already exists.
 * 1 Indicates the folder should replace PENDD_STYLUS if it already exists.
 * 2 Specifies that this folder should update the PENDD_STYLUS if it already exists.

CALPROG Specifies the name of the calibration program. If your calibration program does not need the PEN_DRIVER and PEN_DEVICE parameters passed to it as input parameters, do not use this keyword. CALPARMS=TRUE is used to tell the object to pass the PEN_DRIVER and PEN_DEVICE names as input parameters when starting CAL.EXE. The sample program, CAL.EXE, needs these two parameters to be passed in when starting. For more information, see.

PEN_DRIVER Refers to the string specified by the device driver in the Common Capabilities Packet defined as ccap_device_name for logical device unit 0.

PEN_DEVICE Refers to the string specified by the device driver in the Common Capabilities Packet defined as ccap_device_name for logical device units other than zero.

xxxxx.CCH Control File
This control file defines the changes to be made to CONFIG.SYS as shown in the following figure. 20 MERGE "LIBPATH"   = 2 MERGE "SET PATH"  = 0 MERGE "SET DPATH" = 0 DELETE "DEVICE=MOUSE.SYS" REPLACE "SET PENDD" = 0 DEVICE = "$(DEST)PENDD.SYS TYPE=3" DEVICE = "$(BOOT):\\OS2\\MOUSE.SYS"

Where:

20 The first entry in this file represents the percentage to paint the Updating system filesprogress indicator.

MERGE The MERGE statements add information to existing CONFIG.SYS statements. For example, the first statement adds an additional directory to the LIBPATH statement in CONFIG.SYS. The directory being added is represented by the number 2. This number corresponds with the destindir statement in the xxxxx.MCF control file described earlier. The PENDD.MCF file has the following statement: destindir = "\\DLL\\"         = 2

If the user accepts the default PENDD directory name, the LIBPATH statement is changed to reflect the addition of the x:\PENDD\DDL subdirectory (where x is the drive letter specified by the user).

DELETE The DELETE statement is used to remark out lines in CONFIG.SYS. In the DELETE statement above, the DEVICE=MOUSE.SYS statement is remarked out.

REPLACE The REPLACE statement is used to change the value of a CONFIG.SYS environment setting. The directory being pointed to in the existing SET PENDD statement will be replaced by the base directory the user specifies in the target path field on the User Prompts screen.

DEVICE The DEVICE statement permits additional device drivers to be loaded by the CONFIG.SYS file. The DEVICE statement is written to CONFIG.SYS with the fully qualified file name.

$(DEST) A macro that is resolved to the fully qualified destination path to which the device is being installed.

$(BOOT) A macro that is replaced by the start drive letter of the operating system.

The installation script files also support two additional macros. A description of these macros follows:

$(DIR)# Where # is a number of the destination directory as stated in the file XXX.MCF. The full macro is replaced by the complete path of the destination directory.

$(DRIVE) This macro is replaced by the installation target drive letter. No colon is appended.

Programming Interface
The device-driver-socket programming interface of the pen device driver is made up of the following: The examples in this book are written in assembly language to show detail. The definitions and data structures in this chapter are given in C language for clarity. The following table shows C data types and the equivalent assembly language data lengths. Variables are usually referred to using the name that is used in the sample pen device driver. For example, pqusd.capabilities is referred to in. This is the name of the variable used in the sample.
 * Request packet interface
 * Generic IOCtl interface
 * Pen for OS/2 extended interface

Request Packet Interface
The pen device driver is a character device driver and implements the following OS/2 device driver strategy commands: Note: BAD_COMMAND (8103H) is returned for all other commands that are not supported. DosDevIOCtl2 is not supported.

INIT is described in. There is minimal support for OPEN and CLOSE commands, only a count for the number of OPENs is maintained. Generic IOCtl processing by the device driver is described in. describes the IOCtl functions the device driver must support.

Generic IOCtl Interface
The IOCtl functions provide a method for an application to send device-specific control commands to a pen device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl API function request. The following table lists the categories and functions for the generic IOCtl functions. ERROR_INVALID_PARAMETER (8113H) is returned for invalid unit or for parameters out of the specified range.

General defines:
 * 1) define PEN_CAT_DRIVER 0x090        /* Driver category       */
 * 2) define PEN_CAT_LOCATOR 0x091       /* Locator category      */
 * 3) define PEN_CAT_BUTTON 0x092        /* Button category       */
 * 4) define PEN_CAT_DISPLAY 0x093       /* Display category      */

The rest of this section describes the IOCtl functions defined in PENIOCTL.H.
 * 1) define PEN_IOCTL_LEV_MAJOR 0       /* IOCtl interface level */
 * 2) define PEN_IOCTL_LEV_MINOR 3       /* IOCtl interface level */

Category 90h - Driver IOCtls
The following are Category 90h - Driver IOCtls:
 * - Set Unit Specific Data
 * - Set Unit Variable
 * - Reset Trace Table
 * - Set Trace Table Size
 * - Query Unit Specific Data
 * - Query Unit Variables
 * - Query Unit Capabilities
 * - Query Trace Table
 * - Query Trace Table Size

Set Unit Specific Data - Function 50h
Category 90h, Driver IOCtls - Set Unit Specific Data

This function sets the device-specific data for the requested unit.
 * 1) define PEN_FUNC_SUSD 0x050

Device specific structure, first LONG has byte count.
 * Parameter Packet Format
 * Data Packet Format

Note: If the device supports standard locator unit-specific data, this structure is used by the sample driver to maintain calibration alignment data. Other driver information can be appended after this standard structure.

Set Unit Variable - Function 51h
Category 90h, Driver IOCtls- Set Unit Variable

This function sets the device-specific variable for the requested unit.
 * 1) define PEN_FUNC_SUV 0x051


 * Parameter Packet Format

None.
 * Data Packet Format

Reset Trace Table - Function 52h
Category 90h, Driver IOCtls - Reset Trace Table

This function resets the transaction trace buffer. Resetting the trace buffer is a convenient way to view only current stroke data.
 * 1) define PEN_FUNC_RTT 0x052


 * Parameter Packet Format:None.
 * Data Packet Format:None.

Set Trace Table Size - Function 53h
Category 90h, Driver IOCtls- Set Trace Table Size

This function allocates a trace table for tracing.
 * 1) define PEN_FUNC_STTS 0x053


 * Parameter Packet Format
 * Data Packet Format:None.

Query Unit Specific Data - Function 60h
Category 90h, Driver IOCtls - Query Unit Specific Data

This function reads the device-specific data for the requested unit. The device-specific data area is truncated when the pqusd.byteCount is less than the length of the device-specific data. The first ULONG in the unit-specific data is the entire length of the area. This is not reduced to reflect a truncated query.
 * 1) define PEN_FUNC_QUSD 0x060


 * Parameter Packet Format
 * Data Packet Format:Device specific structure.

Values for pqusd.capabilities:
 * Remarks
 * 1) define QUSD_RESERVD 0x0000FFFF      /* Reserved for architected use        */
 * 2) define QUSD_OEM    0xFFFF0000       /* Reserved for OEM use                */

The following are defined for all device types: device-specific layout. */ The following are locator specific:
 * 1) define QUSD_LENGTH  0x00000001      /* First word of unit data is length.  */
 * 2) define QUSD_STANDARD 0x00000002     /* Starts with standard
 * 1) define QUSD_X_INVERT 0x00000004     /* X raw coordinate is inverted.       */
 * 2) define QUSD_Y_INVERT 0x00000008     /* Y raw coordinate is inverted.       */

Values for pqusd.rc:
 * 1) define QUSD_OK    0       /* All data was copied.                */
 * 2) define QUSD_TRUNC 1       /* Data was truncated.                 */
 * 3) define QUSD_NA    2       /* Data is not available; none copied. */

typedef struct _SLUSD { ULONG  length;           /* Length of entire data area             */ ULONG  XoriginDefault;   /* Default x origin coordinate adjustment */ ULONG  Xorigin;          /* x-coordinate origin adjustment         */ ULONG  XmeasuredExtent;  /* Measured x extent                      */ ULONG  YoriginDefault;   /* Default y origin coordinate adjustment */ ULONG  Yorigin;          /* y-coordinate origin adjustment         */ ULONG  YmeasuredExtent;  /* Measured y extent                      */ } SLUSD;

Query Unit Variables - Function 61h
Category 90h, Driver IOCtls - Query Unit Variables

This function gets the device-specific variable from the requested unit. Unit 0, variable 0, returns an error counter. Unit 0, variable 1, returns a panic flag word.
 * 1) define PEN_FUNC_QUV 0x061


 * Parameter Packet Format


 * Data Packet Format

typedef struct _D_QUV { ULONG  value;           /* Value returned */ } DQUV; Note: The sample program provided in the Pen for OS/2 Developer's Toolkit uses unit 0 and variable 0 to report the error count. To report the panic values (internal errors), the Pen for OS/2 Developer's Toolkit sample program uses unit 0 and variable 1. The numerical panic values are mapped to their meanings in the PEN.INC file.
 * Data Structure

Query Unit Capabilities - Function 62h
Category 90h, Driver IOCtls - Query Unit Capabilities

This function returns the capabilities for the unit.
 * 1) define PEN_FUNC_QUC 0x062


 * Parameter Packet Format

Area to receive extended information registration packet (defined in PENEI.H).
 * Data Packet Format

Values for pquc.rc are the same as for spqusd.rc.
 * Remarks

Query Trace Table - Function 63h
Category 90h, Driver IOCtls - Query Trace Table

This function returns the valid entries in the trace table. Each entry is a DWORD (4 bytes) and can be considered an array of ULONGs. The first entry has the number of valid entries to follow.
 * 1) define PEN_FUNC_QTT 0x063


 * Parameter Packet Format


 * Data Packet Format:PLONG to trace table array.
 * Remarks:Each entry has a trace code describing the contents of the entry:
 * 1) define TRACE_MASK     0x0FF000000   /* Isolate trace code from entry.          */
 * 2) define TRACE_MASK_SUB 0x0F0000000   /* Isolate sub code value.                 */


 * 1) define TRACE_INT      0x0F0000000   /* Interrupt event                         */
 * 2) define TRACE_INT_H    0x0F000


 * 1) define TRACE_TICK     0x0C0000000   /* Timer tick; low word is tick count.     */
 * 2) define TRACE_TICK_H   0x0C000
 * 3) define TRACE_ABS      0x010000000   /* Absolute packet sub trace code          */
 * 4) define TRACE_ABS_E    0x01E000000   /* -- Mouse button event is low word.      */
 * 5) define TRACE_ABS_EH   0x01E00
 * 6) define TRACE_ABS_X    0x011000000   /* -- x-coordinate is low word.            */
 * 7) define TRACE_ABS_XH   0x01100
 * 8) define TRACE_ABS_Y    0x012000000   /* -- y-coordinate is low word.            */
 * 9) define TRACE_ABS_YH   0x01200
 * 10) define TRACE_ABS_Z    0x014000000   /* -- z-coordinate is low word.            */
 * 11) define TRACE_ABS_ZH   0x01400
 * 12) define TRACE_ABS_D    0x015000000   /* -- EI device bits                       */
 * 13) define TRACE_ABS_DH   0x01500
 * 14) define TRACE_ABS_C    0x016000000   /* -- EI control word
 * 15) define TRACE_ABS_CH   0x01600


 * 1) define TRACE_ERROR    0x0E0000000   /* Error trace; word is error count.       */
 * 2) define TRACE_ERROR_H  0x0E000


 * 1) define TRACE_DATA     0x000000000   /* Raw data trace; byte is in low byte.    */
 * 2) define TRACE_DATA_1   0x001000000   /* -- First byte of a packet (optional)    */
 * 3) define TRACE_DATA_1H  0x00100
 * 4) define TRACE_DATA_H   0x00000       /* -- Not first byte                       */


 * 1) define TRACE_SYS      0x020000000   /*  System device event (EMI only)         */
 * 2) define TRACE_SYS_H    0x02000       /*                                         */
 * 3) define TRACE_BUTTON   0x0B0000000   /* Button event sub trace code             */
 * 4) define TRACE_BREL     0x0B0000000   /* Button release mask is low word.        */
 * 5) define TRACE_BREL_H   0x0B000
 * 6) define TRACE_BACT     0x0B1000000   /* Button activation mask is low word.     */
 * 7) define TRACE_BACT_H   0x0B100

/* Low word is data; second byte is index. */
 * 1) define TRACE_DISPLAY  0x0D0000000   /* Display event sub trace code            */
 * 2) define TRACE_DOFF     0x0D0000000   /* Display is turned off.                  */
 * 3) define TRACE_DOFF_H   0x0D000
 * 4) define TRACE_DON      0x0D1000000   /* Display is turned on.                   */
 * 5) define TRACE_DON_H    0x0D100
 * 6) define TRACE_DD       0x090000000   /* Trace is device dependent.              */
 * 1) define TRACE_DD_H     0x09000

Query Trace Table Size - Function 64h
Category 90h, Driver IOCtls - Query Trace Table Size

This function returns the size of the entire trace table. This function can be used to obtain the memory allocation size to be used for the Query Trace Table function.
 * 1) define PEN_FUNC_QTTS 0x064

typedef struct _D_QTTS { ULONG  size;         /* Number of LONG values in table (number of bytes/4)           */ } DQTTS;
 * Parameter Packet Format:None.
 * Data Packet Format
 * Data Structure

Category 91h - Locator IOCtls
The following are Category 91h - Locator IOCtls:
 * - Set Locator Offset
 * - Set Locator Pass Rate
 * - Set Locator Sample Rate
 * - Query Locator Variables
 * - Query Locator Raw Coordinates

Set Locator Offset - Function 50h
Category 91, Locator IOCtls - Set Locator Offset

This function is used to change the finger offset of the digitizer. An offset can be negative. Both or either offsets can be changed according to the functions ORed in the command field.
 * 1) define PEN_FUNC_SLO 0x050


 * Parameter Packet Format


 * Data Packet Format:None.
 * Remarks:Values for pslo.command:
 * 1) define PSLO_SET_X  0x01      /* Set x offset        */
 * 2) define PSLO_SET_Y  0x02      /* Set y offset        */

Set Locator Pass Rate - Function 51h
Category 91h, Locator IOCtls - Set Locator Pass Rate

This function is used to change the OS/2 event rate. If the rate=2, then for every 2 digitizer samples only 1 is reported to Pen for OS/2 as a mouse event. All samples are reported to Pen for OS/2.
 * 1) define PEN_FUNC_SLPR 0x051

If left at 0, Pen for OS/2 device driver services will calculate the pass rate automatically. This variable should be used only if the automatic value requires manual tuning.


 * Parameter Packet Format
 * Data Packet Format:None.

Set Locator Sample Rate - Function 52h
Category 91h, Locator IOCtls - Set Locator Sample Rate

This function is used to change the sample rate. The device must round the rate to the closest value.
 * 1) define PEN_FUNC_SLSR 0x052


 * Parameter Packet Format

None.
 * Data Packet Format

Query Locator Variables - Function 60h
Category 91, Locator IOCtls - Query Locator Variables

This function returns the Pen for OS/2 locator variables.
 * 1) define PEN_FUNC_QLV 0x060


 * Parameter Packet Format
 * Data Packet Format

typedef struct _D_QLV { LONG  xOffset;      /* x offset in digitizer units       */ LONG  yOffset;      /* y offset in digitizer units       */ ULONG passRate;     /* Pass rate                         */ ULONG sampelRate;   /* Sample rate in samples per second */ } DQLV;
 * Data Structure

Query Locator Raw Coordinates - Function 61h
Category 91h, Locator IOCtls - Query Locator Raw Coordinates

This function returns the next valid raw locator coordinate. The dqlrc.rc value reflects whether a coordinate value was available within the specified timeout period.
 * 1) define PEN_FUNC_QLRC 0x061


 * Parameter Packet Format

typedef struct _D_QLRC { LONG  rc;            /* Return code              */ LONG  xRaw;          /* x in raw digitizer units */ LONG  yRaw;          /* y in raw digitizer units */
 * Data Packet Format
 * Data Structure

} DQLRC; Values for dqlrc.rc:
 * Remarks
 * 1) define QLRC_VALID      0     /* Valid coordinates returned.           */
 * 2) define QLRC_TIMEOUT    1     /* Timed out, coordinates are not valid. */
 * 3) define QLRC_BUSY       2     /* Only one thread at a time allowed.    */

Query Default Locator Extents - Function 62h
Category 91h, Locator IOCtls - Query Default Locator Extents

This function returns the default locator extents. The dqdle.rc value reflects whether the default extents were retrieved.
 * 1) define PEN_FUNC_QDLE 0x062


 * Parameter Packet Format


 * Data Packet Format

typedef struct _D_QDLE { ULONG  rc;            /* Return code              */ ULONG  Xdefault;      /* x default extent         */ ULONG  Ydefault;      /* y default dextent        */
 * Data Structure

} DQDLE;

Values for dqdle.rc:
 * Remarks


 * 1) define QDLE_OK         0     /* The default extents were valid.       */
 * 2) define QDLE_FAIL       1     /* The default extents were not valid.   */

Category 92h - Button IOCtls
The following are Category 92h - Button IOCtls:
 * - Set Button Assignment
 * - Query Button Assignment

Set Button Assignment - Function 50h
Category 92h, Button IOCtls- Set Button Assignment

This function sets the assignment for a button.
 * 1) define PEN_FUNC_SBA 0x050


 * Parameter Packet Format
 * Data Packet Format:None.
 * Remarks:Values for psba.action:

Note: Values must match order of capability fields in DCAP struct. Values for psba.value for action = SHIFTBUTTON: Values for psba.value for action = SENDHOTKEY:
 * 1) define NOBUTTONACTION     0     /* Null - do nothing (the default).            */
 * 2) define SENDHOTKEY         1     /* Send hot key; value in PSBA.hotkey.         */
 * 3) define SHIFTBUTTON        2     /* Set shift for button using mouseButtonMask. */
 * 4) define APPLBUTTON         3     /* Assign button for application use.          */
 * 5) define AUGMENTATIONBUTTON 4     /* Assign button for key augmentation.         */
 * 6) define GESTUREMODE        5     /* Assign button for gesture mode.             */
 * 1) define MOUSEBUTTON1     0x04    /* Mouse button 1                              */
 * 2) define MOUSEBUTTON2     0x10    /* Mouse button 2                              */
 * 3) define MOUSEBUTTON3     0x40    /* Mouse button 3                              */
 * 1) define HOTKEY_CNTRL_ESC   1     /* Do a Ctrl+Esc.                              */
 * 2) define HOTKEY_ALT_ESC     2     /* Do an Alt+Esc.                              */

Query Button Assignment - Function 60h
Category 92h, Button IOCtls - Query Button Assignment

This function returns the assignment of a button.
 * 1) define PEN_FUNC_QBA 0x060


 * Parameter Packet Format


 * Data Packet Format

typedef struct _D_QBA { ULONG  action;           /* Action to perform                    */ ULONG  value;            /* Hot-key value for hot-key assignment or mouse button selection mask      */ } DQBA;
 * Data Structure

Category 93h - Display IOCtls
The following are Category 93h - Display IOCtls:
 * - Set Display State
 * - Set Display Inactivity Period
 * - Query Display State

Set Display State - Function 50h
Category 93h, Display IOCtls - Set Display State


 * 1) define PEN_FUNC_SDS 0x050       /* Set display state.          */

This function is used to turn the backlight either on or off. Turning on the backlight restarts the inactivity timer. The inactivity timer is used only if automatic control is enabled.
 * 1) define TURNBACKLIGHTON    1     /* Value to turn backlight on  */
 * 2) define TURNBACKLIGHTOFF   0     /* Value to turn backlight off */


 * Parameter Packet Format
 * Data Packet Format:None.

Set Display Inactivity Period - Function 51h
Category 93h, Display IOCtls - Set Display Inactivity Period

This function controls how the driver handles turning the display backlight on and off automatically. The following options can be set: All of these options are independent. All combinations can be specified on a single IOCtl call. AutoEnable, Suppress, and Period are processed only if the display device capabilities allow automatic backlight control.
 * 1) define PEN_FUNC_SDIP 0x051
 * AutoEnable = (enable | disable) When enabled, the backlight is turned off after a period of no user activity. User activity turns the backlight back on. User activity consists of input from any locator device, buttons, the OS/2 mouse, or the keyboard.
 * Opaque = (enable | disable) When enabled, button actions and locator points from this driver are processed even though the backlight is off. When disabled, button actions are not processed, and locator points are sent to the device driver services but are not processed by the OS/2 operating system.
 * Suppress = (enable | disable) When enabled, button down action from the locator or a mouse action that turned the backlight on will be ignored and reported as a movement only. Button actions will be ignored.
 * Period = The length of the inactivity period in seconds.


 * Parameter Packet Format

None.
 * Data Packet Format

PSDIP.command values:
 * Remarks
 * 1) define SDIP_PERIOD     0x01    /* Change period value                   */
 * 2) define SDIP_EN_AUTO    0x02    /* Enable automatic inactivity period    */
 * 3) define SDIP_DI_AUTO    0x04    /* Disable automatic inactivity period   */
 * 4) define SDIP_EN_OPAQUE  0x08    /* Process events while backlight is off */
 * 5) define SDIP_DI_OPAQUE  0x10    /* Ignore events while backlight is off  */
 * 6) define SDIP_EN_SUPPRESS 0x20   /* Suppress after auto turn on           */
 * 7) define SDIP_DI_SUPPRESS 0x40   /* Do not suppress after auto turn on    */

Query Display State - Function 60h
Category 93h, Display IOCtls - Query Display State

This function returns whether the automatic inactivity period monitor is enabled or disabled, and if enabled, the time remaining in the inactivity period.
 * 1) define PEN_FUNC_QDS 0x060


 * Parameter Packet Format


 * Data Packet Format

typedef struct _D_QDS { ULONG state;        /* State of backlight                          */ ULONG automatic;    /* Automatic options                           */ ULONG period;       /* Inactivity period in seconds                */ } DQDS;
 * Data Structure


 * Remarks

DQDS.state uses same values as PSDIP.state.

DQDS.automatic uses same values as PSDIP.command.

Pen for OS/2 Extended Interface
This section describes the extended Pen for OS/2 system extension interface, including the direct call interface to the device driver services.

General defines:
 * 1) define PEN_DDS_LEV_MAJOR 0            /* Level of this specification           */
 * 2) define PEN_DDS_LEV_MINOR 3            /* Level of this specification           */

DevHlp_RegisterDeviceClass values:
 * 1) define DEVCLASS_INPUT 2               /* Device class for RegisterDeviceClass  */

Defines for DCFlags:
 * 1) define REG_EXT_IF 0x0001              /* Supports extended interface           */
 * 2) define REG_AUX    0x8000              /* Keyboard AUX port used                */

Pen Device Driver IDC Interface
These IDC requests are provided by the pen device driver at the IDC entry point declared with DevHlp_RegisterDeviceClass and are defined in PENIDC.H:                                      bl = unit es:di = Area to copy capabilities packet; first word has size of copy buffer Successful return nc (no carry), ax = 0, Packet copied Error return cy (carry), ax == Error code             */
 * 1) define QUERY_CAPABILITIES    1    /* Request unit capabilities

bl = unit es:di = target DevData packet address     */ bl = unit es:di = SINFO packet Successful return nc, ax = 0, Registration accepted Error return cy, ax = = Error code 4 and 5 are reserved for future "by unit" calls                          */
 * 1) define QUERY_DEV_CONFIG      2    /* Query optional device configuration
 * 1) define START_LOGICAL_DEVICE  3    /* Start logical device

These functions invoke global calls to the driver: pass  cx:dx style capabilities to driver return cx:dx style request to services    */ as result of REQUEST_CALLBACK)            */                                       cl == -1 Start of change                                              0 End of change                                       ch == -1 Packet is valid                                              0 Packet is invalid                                       es:di = VINFO packet                       */
 * 1) define READ_ENABLE           6    /* Enable reporting of events
 * 1) define READ_DISABLE          7    /* Disable reporting of events                */
 * 2) define ENABLE_DEVICE         8    /* Enable the device to interrupt             */
 * 3) define DISABLE_DEVICE        9    /* Disable the device from interrupting       */
 * 4) define ACTIVITY_CALLBACK    10    /* System activity callback (called
 * 1) define VIDEO_MODE_CHANGE    11    /* Video mode change

Style capabilities for READ_ENABLE (See 6 above): CX register is reserved, must be 0.

Style capabilities for READ_ENABLE: DX register: on = DON'T report, reset to receive events          */
 * 1) define STYLE_NOTIFY_VMCHANGE 0x0001 /* Report VM_CHANGE

Error Codes: buffer small                     */
 * 1) define DRV_ERR_GEN_ERROR  1         /* General error                     */
 * 2) define DRV_ERR_NOT_FOUND  2         /* Unit number not found             */
 * 3) define DRV_ERR_BUFF_TRUNC 3         /* Registration packet truncated,
 * 1) define DRV_ERR_LEVEL      4         /* Level mismatch                    */
 * 2) define DRV_ERR_NOT_ALLOWED 5        /* Request not allowed at this time  */
 * 3) define DRV_ERR_NO_FUNC    6         /* Function not supported            */

The following packet is passed on READ_ENABLE. The packet and service routine is valid only during the READ_ENABLE call. typedef struct _SINFO {    /* sinfo                                    */ USHORT length;           /* Total length of packet                   */ UCHAR eif_major;         /* Major level (PEN_EI_LEV_MAJOR)           */ UCHAR eif_minor;         /* Minor level (PEN_EI_LEV_MINOR)           */ UCHAR idc_major;         /* Major level (PEN_DDS_LEV_MAJOR)          */ UCHAR idc_minor;         /* Minor level (PEN_DDS_LEV_MINOR)          */ USHORT service_ds;       /* Data segment to load for service routine */ ULONG service_rtn;       /* 16:16 address for service routine        */

} SINFO;

The following packet is passed on VIDEO_MODE_CHANGE. typedef struct _VINFO  {        /* vinfo                      */ UCHAR Mtype;                  /* Video mode type            */ UCHAR Color;                  /* Number of colors           */ UCHAR TCol_res;               /* Text column resolution     */ USHORT TRow_res;              /* Text row resolution        */ USHORT GCol_res;              /* Graphics column resolution */ USHORT GRow_res;              /* Graphics row resolution    */

} VINFO;

Defines for vinfo.Mtype:
 * 1) define MTYPE_GRAPHICS 0x0002  /* Graphics mode */

Device data structure is returned by locator devices on QUERY_DEV_CONFIG. The other devices do not have device configuration data to return. typedef struct _DevData {        /* DevData             */ USHORT CfgDataLen;             /* Length of data      */ UCHAR NumMics;                 /* Number mickeys/cm   */ UCHAR NumButt;                 /* Number of buttons   */ UCHAR IRQ;                     /* IRQ level           */ UCHAR MouseType;               /* Mouse type attached */ UCHAR ComPortNum;              /* Com port number     */ USHORT ComPortAddr;            /* Com port address    */ } DevData;

Pen for OS/2 Device Driver Services
These services are provided by the Pen for OS/2 system extension at the service entry point and are defined in PENIDC.H:                                        es:di = Capabilities packet         */ es:di = Event packet               */ es:di = Capabilities packet        */ Returns dx = low word count cx = high word count edx = dword count           */ cl = Driver device ID              */ cl = Driver device ID              */ cl = Driver device ID              */ cl = Driver device ID              */
 * 1) define REGISTER_DEVICE      1       /* Register device
 * 1) define REPORT_EVENT         2       /* Report event
 * 1) define UPDATE_CAPS          3       /* Update registration packet
 * 1) define QUERY_ACTIVITY       4       /* Query user input activity
 * 1) define REQUEST_CALLBACK     5       /* Request callback for system activity
 * 1) define CANCEL_CALLBACK      6       /* Cancel callback for system activity
 * 1) define SUPPRESS_STROKE      7       /* Suppress stroke
 * 1) define DISABLE_SUPPORT      8       /* Disable driver

Extended Information Structures
Defines for all dev_type:
 * 1) define PEN_EI_LEV_MAJOR 0       /* Level of this specification             */
 * 2) define PEN_EI_LEV_MINOR 6       /* Level of this specification             */

<pre
 * 1) define DT_DRIVER    0x00        /* Index to access driver                  */
 * 2) define DT_CONTROL   0x01        /* Control (not used by pen device driver) */
 * 3) define DT_SYSTEM    0x02        /* System  (not used by pen device driver) */
 * 4) define DT_LOCATOR   0x03        /* Locator                                 */
 * 5) define DT_BUTTON    0x04        /* Button                                  */
 * 6) define DT_DISPLAY   0x05        /* Display                                 */

Common Capabilities Packet
Each capability packet starts with these common fields: typedef struct _CCAP   {   /* ccap                                     */ USHORT length;           /* Total length of capabilities packet      */ USHORT device_type       /* Device type                              */ UCHAR device_id;         /* Device ID (is returned from registration)*/ UCHAR unit;              /* Unit number within the driver            */ UCHAR flags;             /* Round to word boundary                   */ UCHAR driver_name[8];    /* Device driver name                       */ UCHAR device_name[32];   /* Device name                              */ USHORT event_caps;       /* Events that will be generated            */ } CCAP; Note: CCAP.event_capsis defined by lev.cev.devicebits, bev.cev.devicebits, and dev.cev.devicebits.

Defines for word boundary flags:
 * 1) define CCAP_DEFAULTDATA 0x00        /* Use the data from the device driver    */
 * 2) define DT_CONTROL       0x01        /* Use the data stored in OS2.INI         */

Driver-Specific Capabilities Packet
The unit 0 device capabilities describe the entire driver and are used to: typedef struct _DDCAP  {    /* ddcap                                 */ CCAP  ccap;               /* Common capabilities packet            */ ULONG capabilities;       /* Reserved                              */ UCHAR unitCount;          /* Number of logical devices, including one for the driver device            */ UCHAR rev_major;          /* Driver major level                    */ UCHAR rev_minor;          /* Driver minor level                    */ UCHAR ioc_major;          /* IOCtl interface major level           */ UCHAR ioc_minor;          /* IOCtl interface minor level           */ UCHAR eif_major;          /* Extended interface major level        */ UCHAR eif_minor;          /* Extended interface minor level        */ UCHAR idc_major;          /* DDS IDC interface major level         */ UCHAR idc_minor;          /* DDS IDC interface minor level         */
 * Verify the expected levels of the driver match
 * Determine the number of logical devices in the driver

} DDCAP;

Locator-Specific Capabilities Packet
Defines for LCAP.type: Defines for LCAP.pen_type: Defines for LCAP.std_res: points per inch. */
 * 1) define LOCTYPE_MOUSE      0x0001   /* Stock device                    */
 * 2) define LOCTYPE_PEN        0x0002   /* Pen                             */
 * 3) define LOCTYPE_FINGER     0x0004   /* Finger                          */
 * 4) define LOCTYPE_OTHER      0x0008   /* Other                           */
 * 5) define LOCTYPE_ABSOLUTE   0x0010   /* Absolute                        */
 * 6) define LOCTYPE_RELATIVE   0x0020   /* Relative                        */
 * 1) define PENCAP_TETHERED  0x0001    /* 1 - Tethered, 0 - Untethered     */
 * 2) define PENCAP_PROXIMITY 0x0002    /* Generates enter and exit events  */
 * 3) define PENCAP_TILT      0x0004    /* Stylus tilt angle reported       */
 * 4) define PENCAP_ROTATE    0x0008    /* Stylus rotation reported         */
 * 5) define PENCAP_OEMDATA   0x0010    /* OEM data reported                */
 * 6) define PENCAP_TIMESTAMP 0x0020    /* dev_timestamp reported           */
 * 7) define PENCAP_ZPRESSURE 0x0040    /* z-axis represents pressure       */
 * 8) define PENCAP_ZHEIGHT   0x0080    /* z-axis represents height         */
 * 9) define PENCAP_PIN       0x0100    /* 1=Personal Identification Number */
 * 10) define PENCAP_ERASER    0x0200    /* 1=device used as an eraser       */
 * 11) define PENCAP_DISPLAY   0x0400    /* 1=integrated display             */
 * 1) define STD_RESOLUTION   1000      /* Standard resolution is 1000

typedef struct _LCAP  {  /* lcap                                       */ CCAP  ccap;            /* Common capabilities packet                 */ USHORT type;           /* Locator type                               */ USHORT caps;           /* Locator capabilities                       */ USHORT sample_rate;    /* Device sample rate                         */ USHORT max_sample_rate; /* Maximum device sample rate                */ UCHAR barrel_num;      /* Number of barrel buttons                   */ UCHAR barrel_mask;     /* Bit position of barrel buttons             */ ULONG dev_x_extent;    /* Device x-axis extent                       */ ULONG dev_y_extent;    /* Device y-axis extent                       */ ULONG std_x_extent;    /* Standard x-axis extent                     */ ULONG std_y_extent;    /* Standard y-axis extent                     */ SHORT dev_z_p_extent;  /* Device z-axis pressure extent (negative)   */ SHORT dev_z_h_extent;  /* Device z-axis height extent (positive)     */ UCHAR pass_rate;       /* Device pass rate                           */ UCHAR num_mouse_but;   /* Number of mouse buttons emulated by device */ USHORT std_res;        /* Points per inch for standard resolution    */ USHORT dev_x_res;      /* Points per inch on x-axis                  */ USHORT dev_y_res;      /* Points per inch on y-axis                  */ ULONG dev_timestampRes;/*Device time stamp resolution in microseconds*/ } LCAP; Note: This structure can be imbedded into an OEM Capabilities Structure if you need to pass additional information such as whether the device time stamp or the OEM_data field is being used, or how many bytes of the OEM_ data field are being used.

Button-Specific Capabilities Packet
Defines for BCAP.barrel and BCAP.nonBarrel capabilities (If these bits are set, the action is supported by the barrel or nonbarrel buttons):
 * 1) define CAP_NOBUTTONACTION    0x0001  /* Null; do nothing (the default) */
 * 2) define CAP_SENDHOTKEY        0x0002  /* Hot-key support                */
 * 3) define CAP_SHIFTBUTTON       0x0004  /* Shift button support           */
 * 4) define CAP_APPLBUTTON        0x0008  /* Button for application use     */
 * 5) define CAP_AUGMENTATIONBUTTON 0x0010 /* Button for key augmentation    */
 * 6) define CAP_GESMODEBUTTON     0x0020  /* Button for gesture mode        */

CAP_SENDHOTKEY|CAP_APPLBUTTON|CAP_AUGMENTATIONBUTTON
 * 1) define CAP_DEFAULT_BARREL CAP_NOBUTTONACTION|CAP_SHIFTBUTTON|CAP_GESMODEBUTTON
 * 2) define CAP_DEFAULT_NBARREL CAP_DEFAULT_BARREL|

typedef struct _BCAP { /* bcap                                        */ CCAP  ccap;          /* Common capabilities packet                  */ USHORT num;          /* Number of buttons (0 to 16)                 */ USHORT typeMask;     /* Bit mask for type (1=barrel, 0=not barrel)  */ USHORT nullMask;     /* Bit mask to show null assignment            */ USHORT hotKeyMask;   /* Bit mask to show assignment to hot key      */ USHORT oneTimeMask;  /* Bit mask to show assignment to mouse mode   */ USHORT shiftMask;    /* Bit mask to show assignment to mouse mode   */ USHORT appKeyMask;   /* Bit mask to show assignment to appl key     */ USHORT augKeyMask;   /* Bit mask to show assignment to augmentation */ } BCAP; Note:Button index 0 is represented with the least significant bit in the mask (0x0001).

Display-Specific Capabilities Packet
Defines for DCAP.type:
 * 1) define DISPTYPE_LCD      0x0001    /* 1 - LCD,      0 - not LCD         */
 * 2) define DISPTYPE_CRT      0x0002    /* 1 - CRT,      0 - not CRT         */
 * 3) define DISPTYPE_BLANKING 0x0004    /* Display performs screen blanking. */
 * 4) define DISPTYPE_COLOR    0x0008    /* 1 - Color,    0 - Monochrome      */
 * 5) define DISPTYPE_ATTACHED 0x0010    /* 1 - Attached, 0 - Portable        */
 * 6) define DISPTYPE_NO_KBD   0x0020    /* No Keyboard Attached              */
 * 7) define DISPTYPE_BATTERY  0x0040    /* 1 - Battery,  0 - AC power        */
 * 8) define DISPTYPE_SPEAKER  0x0080    /* 1 - Speaker is close to display.  */

typedef struct _DCAP  {  /* dcap                                       */ CCAP  ccap;            /* Common capabilities packet                 */ USHORT type;           /* Display type                               */ USHORT auto_flag;      /* Capable of supporting automatic inactivity period (1=yes, 0 = no)                    */ ULONG height;          /* Screen height in .01 of an inch            */ ULONG width;           /* Screen width in .01 of an inch             */ } DCAP;

Common Event Packet
This is a common prefix to all events: locator, button, and display. typedef struct _CEV { /* cev                                           */ USHORT length;     /* Total length of eiq event packet               */ UCHAR device_type; /* Event category - system, locator, display, control                             */ UCHAR device_id;   /* Identity of device that generated event        */ ULONG timestamp;   /* Millisecond time stamp (not for DD)            */ UCHAR session;     /* Foreground session number (not for DD)         */ UCHAR cntrl;       /* Control info (not for DD)                      */ USHORT devicebits; /* Event field (defined by device type)           */ } CEV;

Locator-Specific Event Packet
Defines for LEV.cntrl: (used by pass rate filter)               */
 * 1) define LOC_PASS_ON       0x0001     /* If set, event is to be passed to PM.
 * 1) define LOC_ARBITRATED_OUT 0x0002    /* For use by arbitration (treat as reserved)  */
 * 2) define LOC_SUPPRESSED    0x0004     /* Suppressed contact due to backlight auto on */
 * 3) define LOC_BKLT_OFF      0x0008     /* Suppressed contact due to backlight off     */
 * 4) define LOC_REL           0x0010     /* dev_x and dev_y are relative                */
 * 5) define LOC_ABS           0x0020     /* dev_x and dev_y are absolute                */
 * 6) define LOC_FAKE          0x0040     /* Device coordinates are valid, but fake.     */
 * 7) define LOC_INVALID       0x0080     /* Coordinates are not valid.                  */
 * 8) define LOC_CONTACT       0x0100     /* Indicates the locator is in contact.        */
 * 9) define LOC_PROX          0x0200     /* Indicates the locator is in proximity.      */
 * 10) define LOC_GSTMODE       0x0400     /* Force gesture mode                          */

Defines for LEV.cev.devicebits (low-order byte = mouse event):
 * 1) define EV_NONE        0x00           /* No buttons, no movement                    */
 * 2) define EV_MOVE        0x01           /* Movement only, no buttons                  */
 * 3) define EV_BUTTON1_MOVE 0x02          /* Movement and button 1 down                 */
 * 4) define EV_BUTTON1     0x04           /* Button 1 down only, no movement            */
 * 5) define EV_BUTTON2_MOVE 0x08          /* Movement and button 2 down                 */
 * 6) define EV_BUTTON2     0x10           /* Button 2 down only, no movement            */
 * 7) define EV_BUTTON3_MOVE 0x20          /* Movement and button 3 down                 */
 * 8) define EV_BUTTON3     0x40           /* Button 3 down only, no movement            */


 * 1) define EV_ANY_STAT_BUTTON  EV_BUTTON1 | EV_BUTTON2 | EV_BUTTON3
 * 2) define EV_ANY_MOVE_BUTTON  EV_BUTTON1_MOVE | EV_BUTTON2_MOVE | EV_BUTTON3_MOVE
 * 3) define EV_ANY_MOVE         EV_MOVE | EV_ANY_MOVE_BUTTON
 * 4) define EV_ANY_BUTTON       EV_ANY_STAT_BUTTON | EV_ANY_MOVE_BUTTON
 * 5) define EV_STD_MOUSE        EV_ANY_STAT_BUTTON | EV_ANY_MOVE

(high-order byte = mouse events that changed):
 * 1) define EV_BUTTON1_CHANGED   0x0400   /* Button 1 changed                           */
 * 2) define EV_BUTTON2_CHANGED   0x1000   /* Button 2 changed                           */
 * 3) define EV_BUTTON3_CHANGED   0x4000   /* Button 3 changed                           */


 * 1) define EV_BUTTON_CHG       EV_BUTTON1_CHANGED|EV_BUTTON2_CHANGED|EV_BUTTON3_CHANGED

Stroke events:
 * 1) define EV_EXIT_PROX 0x0080           /* Exit proximity                             */
 * 2) define EV_ENTER_PROX 0x8000          /* Enter proximity                            */
 * 3) define EV_PROX             EV_EXIT_PROX | EV_ENTER_PROX

typedef struct _LEV   {      /* lev                                    */ CEV cev;                   /* Common event packet                    */ USHORT cntrl;              /* Locator control info                   */ USHORT scr_x;              /* Screen coordinates (NOT filled in by  USHORT scr_y;                  pen device driver)                     */ SHORT scr_z;               /* Normalized z coord (-4k to 4k)         */ USHORT buttons;            /* State of buttons 0 - 15;               */ ULONG dev_x;               /* Device coordinates                     */ ULONG dev_y; ULONG std_x;               /* Standard coordinates                   */ ULONG std_y; SHORT dev_z;               /* Negative = pressure, positive = height */ ULONG dev_timestamp;       /* High resolution device time stamp      */ USHORT dev_sequence;       /* Increment for each event               */ /* Angles range from +180 to -180 degrees */ SHORT dev_angle_theta;     /* Pen angle from vertical, increases     */ /* in positive x direction. */ SHORT dev_angle_phi;        /* Pen angle from vertical, increases     */ /* in positive y direction. */ UCHAR  OEM_data[8];         /* OEM-specific locator data (optional)   */ } LEV;

Button-Specific Event Packet
Defines for BEV.cev.devicebits: Defines for BEV.cntrl:
 * 1) define BEV_BUTTON_CHANGE      0x01  /* Button change event                     */
 * 1) define BEV_SUPPRESSED LOC_SUPPRESSED /* Suppressed contact due to bklt auto-on */
 * 2) define BEV_BKLT_OFF LOC_BKLT_OFF    /* Suppressed contact due to backlight off */

typedef struct _BEV {   /* bev                                         */ CEV cev;              /* Common event packet                         */ USHORT cntrl;         /* Button control info                         */ USHORT state;         /* Button state mask (1=activated, 0=released) */ USHORT change;        /* Mask, 1= Changed since last event report    */ UCHAR action;         /* Action to perform                           */ UCHAR value;          /* Hot-key value for hot-key assignment or     */ /* Mouse button selection mask                */ UCHAR OEM_data[8];    /* OEM-specific display data (optional)        */ } BEV;

Display-Specific Event Packet
Defines for DEV.cev.devicebits:
 * 1) define DEV_BACKLIGHT_CHANGE   0x01 /* State of backlight changed */

typedef struct _DEV    {     /* dev                                  */ CEV cev;                   /* Common event packet                  */ USHORT state;              /* State of backlight (0=off, 1=on)     */ USHORT OEM_data[8];        /* OEM-specific display data (optional) */ } DEV;

Pen for OS/2 Component of IBM Developer Connection Device Driver Kit for OS/2
This appendix describes the contents of the Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 pertaining to the development of a pen device driver.

Subdirectory Structure
The subdirectory structure is created when you install the Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 on a hard disk. The following portion of the subdirectory structure contains the information relating to the development of a device driver. ──PENTKT ├──PENBASE │   ├──INC │   └──PENDD │     └──UTIL ├──DDINST ├──PENCAL └──PENTL The subdirectories and their contents are:
 * PENTKT\PENBASE This subdirectory contains the device driver subcomponent modules.
 * PENTKT\PENBASE\INC This subdirectory contains the include and header files. These files must not be changed because the files define the interface with the system.
 * PENTKT\PENBASE\PENDD This subdirectory contains the device-dependent code and the PENDD.SYS load module for the sample pen device driver.
 * PENTKT\UTIL\DDINST This subdirectory contains the sample control files used to install a device driver. provides a description of these files.
 * PENTKT\UTIL\PENCAL This subdirectory contains the sample code for a pen calibration program.
 * PENTKT\UTIL\PENTL This subdirectory contains the sample code for a tool to test and call the pen device driver.

Pen Device Driver Tool
The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 provides a test tool. This diagnostic program extracts the trace buffer and generates IOCtls. The program runs interactively or accepts commands from a file. The tool provides a means to control and query all aspects of the pen device driver, assisting in program development and in debugging of the pen device driver. It can be extended for any device-specific functions but is not intended to be shipped as part of the finished product.

There are commands for each of the IOCtls, including Category 90h Function 51h Set Unit Variable and Category 90h Function 61h Query Unit Variable, whose purposes are debugging. These commands can direct operation in the pen device driver or extract collected debug data.

There also are commands to control the format of the trace output. You can dynamically set and change the size of the trace table. Resetting the trace to empty separates future activity from past.

The following example code shows how the device driver tool can extract a trace of locator events sent to the Pen for OS/2 Device Driver Services. c:>pentl The tool can be started in either an OS/2 full-screen session or OS/2 window session. In this case, the tool is in interactive mode, showing that it is ready for a command by displaying a. prompt.

To display a trace, the first step is to allocate a trace buffer. By default, no trace buffer is allocated.

The command to allocate a trace buffer is stts, which stands for Set Trace Table Size, and corresponds to the Set Trace Table Size IOCtl. As in all the commands, this command is composed of the first letter of the IOCtl name. In the following example, we have allocated a trace table with 1000 DWORD entries. .stts 1000 . If you query the trace table before making a stroke with the pen, you see only a tick count entry: .qtt (tick 152) . This entry shows that 152 timer ticks occurred since the creation of the trace. If you query it again, you see: .qtt (tick 4157) . This means that 4157 - 152 = 4005 ticks passed between queries of the trace buffer.

After a stroke is made and you enter the commands: .hd .hi .pa .qtt and the buffer displays the following: (tick 7169) (abs 8406 645 505 0) (abs 0004 645 505 0) (abs 0004 645 505 0) (abs 0002 646 505 0) (abs 0004 646 505 0) (abs 0002 648 506 0) (abs 0002 650 507 0)(tick 1) (abs 0002 653 508 0) (abs 0002 657 509 0) (abs 0002 662 511 0) (abs 0002 668 514 0) (abs 0002 675 517 0) (abs 0002 682 520 0)(tick 1) (abs 0002 691 524 0) (abs 0002 701 528 0) (abs 0002 712 533 0) (abs 0002 724 539 0) (abs 0002 738 545 0) (abs 0002 753 552 0)(tick 1) (abs 0002 770 559 0) (abs 0002 789 567 0) (abs 0002 809 575 0) (abs 0002 830 584 0) (abs 0002 852 594 0) (abs 0002 876 604 0) (abs 0002 900 613 0) (tick 1) (abs 0002 922 623 0) (abs 0002 943 631 0) (abs 0002 975 644 0) (abs 0002 1007 656 0) (abs 0002 1042 668 0) (abs 0401 1077 680 0) (abs 0001 1113 692 0) (tick 1) (abs 0001 1148 703 0) (abs 0001 1183 714 0) (abs 0001 1215 723 0) (abs 0001 1246 731 0) (abs 0001 1275 738 0) (abs 0001 1302 744 0) (abs 0001 1326 750 0) (tick 1) (abs 0001 1348 754 0) (abs 0001 1370 759 0) (abs 0001 1392 763 0) (abs 0001 1414 768 0) (tick 5) (abs 0081 1414 768 0) (tick 54353) The PA command formats the trace with line feeds before each event packet. The HD command hides the data events and the HI command hides the interrupt events. All events reside in the trace buffer; the H commands only affect the way the trace is displayed.

The format of the trace is (abs devicebits xcoord ycoord zcoord). The abs parameter identifies the event as an absolute locator event packet. The devicebits parameter identifies mouse-emulation-button activity and proximity events. The first entry is 8406. The 8000 bit indicates enter proximity. The 0400 indicates that the state of emulated mouse button 1 has changed. This was a rapid touch-down point with no proximity points before contact. The 0006 bits indicate that emulated mouse button 1 is down and that movement occurred.

The next devicebits entries in the example with 0002 and 0004 identify a point in the stroke. The 0002 bit indicates button 1 movement, and 0004 bit indicates button down with no movement. Entry 0401 indicates the locator device was removed from the sensor. The 0400 bit indicates that the state of mouse button 1 has changed. The 0001 bit indicates mouse movement with no buttons down.

The last entry is 0081. Entry 0080 indicates an exit proximityevent. Entry 0001 indicates mouse movement with no buttons down.

The xcoord and ycoord indicate the locator position in normalized device coordinates for each point in the stroke. The zcoord is not valid for the device in the example and is always 0. The tick entries show how many sample points are being collected in each timer tick.

The tool processes five groups of commands. The first group consists of unit commands corresponding to the category 90 IOCtls. These commands are listed by typing: H U or ? U. The next group consists of locator commands and correspond to the category 92 IOCtls. These commands are listed by typing: H L or ? L. Likewise, there are a set of button commands and display commands that correspond to category 92 and 93 IOCtls listed by typing: H B or ? B and H D or ? D, respectively. The final group consists of general commands; they are listed by typing H G or ? G. All five groups of commands can be listed together by typing: H or ?.

The general commands do not correspond to IOCtls but are used to control the tool. The hide (H) and linefeed (P) commands have been discussed in the stroke events example. Trace entries are hidden with H commands and shown with S commands. Linefeeds are placed before events with the P commands and removed with the C commands. There are six types of events controlled by the H, S, P, and C commands:
 * I Interrupts
 * T Timer ticks
 * A Event packets
 * D Raw data bytes
 * E Error events
 * X Special device driver-specific events

There are also three assignment (A) commands. For convenience, the locator, button, and display commands assume a unit number for the IOCtls to the pen driver. By default, the locator is unit 1, button is unit 2, and display is unit 3. The assignment commands can change these implicit unit numbers.

Calibration Program
The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 provides a sample calibration program to supply alignment adjustments for the position of the digitizer in relation to the display panel. The program aligns the location of the pointer seen on the display to be the same as where the actual pen device touches the display.



The program provides the following functions: Alignment data is collected by instructing the user to place the locator in the center of a target at each corner of the screen as shown in the preceding figure. The target moves to the next corner of the screen after the program has collected enough samples to get a valid position.
 * OK:Accept new alignment.
 * Align:Collect alignment data and calculate adjustments used by the pen driver.
 * Defaults:Reset the alignment adjustment to those shipped in the driver.
 * Test:Test alignment using a target for the mouse pointer.
 * Cancel:Restore alignment to the alignment when the program started.

The program consists of two threads: a PM thread and an alignment thread. The PM thread executes in a standard PM window procedure and handles routine PM messages and messages from the alignment thread. The alignment thread processes three commands from the PM thread: (1) align; (2) cancel an alignment; and (3) terminate. The alignment thread controls the screen by sending messages to the PM thread to paint a target in a rectangle. Points in the rectangle are ignored by the PM thread but are collected by the alignment thread. Points outside the rectangle are ignored by the alignment thread but used by the PM thread to control the selection of operations through the button controls.

The calibration program can be invoked from the device object associated with it or from the command line in the following form: cal driver_name device_name where:

driver_name is the name of the hardware; for example, "IBM Color Workpad".

device_name is the name of the device; for example, pen.

Note: The input parameters must be put in quotes if spaces occur in the names.

When making changes to the calibration program, a debug mechanism is available. If a file named pencal.log exists, debug information is written to it. This is helpful for determining what data is being collected and used to do the calibration. Libraries and headers from Pen for OS/2 Developer's Toolkit are required to build this program.

Sample Pen Device Driver
The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 contains a sample pen device driver that uses all the Pen for OS/2 system extension interfaces and implements the semantics of all the API functions. You need only modify the device-specific sections of the example code.

You can implement the pen device driver and meet the architected interfaces in any fashion. The sample pen device driver can help you get your pen hardware product working with Pen for OS/2. It also minimizes the experience you must have in developing OS/2 device drivers and Workplace Shell objects.

The following sections give an overview of the sample pen device driver. Each subcomponent has additional information in its routine entry-point comments and module prolog comments.

Driver Organization
Pen Device Driver ┌────────────────────────────────────────────┐ │   ┌──────────────────────────────────┐    │ │    │ Device-Type-Independent Routines │    │ │   │                                  │    │ │    └──────────────────────────────────┘    │ │                                            │ │ ┌──────────────────────────────┐           │ │ │ Device-Type-DISPLAY Routines │           │ │ │   ┌─────────────────────────┴────┐      │ │ └────┤ Device-Type-BUTTON Routines  │      │ │     │    ┌─────────────────────────┴────┐ │ │      └────┤ Device-Type-LOCATOR Routines │ │ │          │                              │ │ │           └──────────────────────────────┘ │ │                                            │ │    ┌──────────────────────────────────┐    │ │    │     Device-Dependent Routines    │    │ │   │                                  │    │ │    └──────────────────────────────────┘    │ │                                            │ └────────────────────────────────────────────┘ The sample pen device driver is organized into three types of code:
 * Device-Type-Independent Code
 * This code provides services common to all device types and is shared, or called, by all devices in the pen device driver.


 * Device-Type-Dependent Code
 * There are three types of device-type-dependent code, one for each of the three device types: locator, button, and display. The device-type-dependent code provides the logic to produce the behavior of the logical device type.
 * The device-type-independent code can call the device-type-dependent code to perform generic operations, like initializing and starting the device. The device-type-dependent code performs the operations appropriate for its device type.


 * Device-Dependent Code
 * You must provide the device-dependent code and address the details of the particular pen hardware product. The pen hardware product device-dependent code is linked with the supplied sample pen device driver code to build the pen device driver. The device-type-dependent code calls the device-dependent code to perform operations specific to the hardware.
 * The device-dependent code manages the device while the device-type-dependent code produces the Pen for OS/2 device behavior.

Driver Subcomponents
The driver is further organized into multiple subcomponents, each with a specific duty as shown in the following figure. Pen Device Driver ┌─────────────────────────────────────────────┐ │ ┌───────────────────────────────────────┐  │ │  │ Device-Type-Independent Subcomponents │  │ │ │  ┌───────┐    ┌───────┐    ┌───────┐  │  │ │  │  │ STRAT │    │  GIO  │    │  IDC  │  │  │ │ │  └───────┘    └───────┘    └───────┘  │  │ │  │  ┌───────┐    ┌───────┐    ┌───────┐  │  │ │  │  │ INIT  │    │ TRACE │    │ TIMER │  │  │ │ │  └───────┘    └───────┘    └───────┘  │  │ │  └───────────────────────────────────────┘  │ │  ┌───────────────────────────────────────┐  │ │  │   Locator-Device-Type Subcomponents   │  │ │ │          ┌────────────────┐           │  │ │  │          │ LOCATOR ENGINE │           │  │ │ │          └────────────────┘           │  │ │  └───────────────────────────────────────┘  │ │  ┌───────────────────────────────────────┐  │ │  │   Button-Device-Type Subcomponents    │  │ │ │          ┌───────────────┐            │  │ │  │          │ BUTTON ENGINE │            │  │ │ │          └───────────────┘            │  │ │  └───────────────────────────────────────┘  │ │  ┌───────────────────────────────────────┐  │ │  │   Display-Device-Type Subcomponents   │  │ │ │          ┌────────────────┐           │  │ │  │          │ DISPLAY ENGINE │           │  │ │ │          └────────────────┘           │  │ │  └───────────────────────────────────────┘  │ │  ┌───────────────────────────────────────┐  │ │  │ Device-Type Subcomponents             │  │ │ │                                       │  │ │  └──┬──────────────────┬─────┬────────┬──┘  │ │     │ DEVICE DEPENDENT │     │ SERIAL │     │ │    └──────────────────┘     └────────┘     │ └─────────────────────────────────────────────┘
 * Device-Type-Independent Subcomponents
 * STRAT
 * OS/2 strategy entry point. OS/2 device driver commands are handled and routed to worker routines in device-type-dependent subcomponents. Most notable are the Generic IOCtl handler and the INIT command handler.
 * INIT
 * The OS/2 operating system issues the INIT command after loading the driver. The STRAT subcomponent routes the command to the INIT command handler routine. The INIT routine takes care of OS/2 details and calls each subcomponent's INIT entry routine. After all INIT routines are called, the declared logical device types are identified to the Pen for OS/2 system extension with the DevHlp_RegisterDeviceClass routine.
 * The initialization code and data segments are returned to the system after the INIT command returns to the OS/2 operating system.
 * GIO
 * Generic IOCtl handler. Architected IOCtls are routed to a subcomponent for processing. Device-specific IOCtls are routed to the device-dependent routine.
 * IDC
 * Inter-device-driver communication (IDC) entry points. This subcomponent processes IDC calls to the Pen for OS/2 Device Driver Services.
 * TRACE
 * The trace subcomponent provides trace services useful for driver debugging.
 * TIMER
 * The timer provides timer services in the form of per-tick callouts to subcomponents and the device-dependent code. Timers are used to manage the backlight and ensure that exit proximity is reported.


 * Device-Type-Dependent Subcomponents
 * ENGINE
 * There is a device-type-dependent engine subcomponent for each of the logical device types. The engine is called from the device-dependent code to process locator, button, or display operations. The engine shields the details of the Pen for OS/2 interface and calls back to the device- dependent code for hardware-specific operations.


 * Device-Dependent Subcomponents
 * DEVICE DEPENDENT
 * The device-dependent subcomponent supplies the specific hardware-handling operations.
 * SERIAL
 * A serial subcomponent for hardware devices attached by way of a serial port.

The detailed design of each subcomponent can be found in the module prolog of the assembly file (*ASM) for that subcomponent.

Driver Data Structures
Pen Device Driver DEVICE CONTROL BLOCK (DCB) ┌───────────────────┐  DCB_anchor ────►     dcb_link      ├────► Next DCB ├───────────────────┤      ┌──────────┤ Device-Type       │ │         │ Independent       │  ┌──────────────┐ │         │ Section      ┌────┼──┤ Device-Type- │ ▼         │              │    │  │ Independent  │ Pointers to Data │             │ ┌──┼──┤ Code         │ Common to       │              │ │  │  └──────────────┘ All Types       │              │ │  │ │             │ │  │  ┌──────────────┐                  │              │ └──┼──► Device-Type- │ ├──────────────┼────┤ │ Dependent    │ ┌──────────┤ Device-Type- │ ┌──┼──┤ Code        │ │         │ Dependent    │ │  │  └──────────────┘ │         │ Section      │ │  │ ▼         │              │ │  │ Pointers to Data │              │ │  │  ┌──────────────┐ Common to this  │              │ └──┼──► Device-      │ Device Type     │              │    │  │ Dependent    │ │             └────┼──► Code         │ │                  │  └──────────────┘                  ├───────────────────┤       ┌──────────┤ Device-           │ │         │ Dependent         │ │         │ Section           │ ▼         │                   │ Pointers to Data │                   │ Private to the  │                   │ Device          │                   │ │                  │                  │                   │                  └───────────────────┘ The sample pen device driver has very few global variables. Each device has its own device-control block (DCB). There are three sections in each DCB, one for each of the three code organizations: device-type-independent, device-type-dependent, and device-dependent. The first two are provided with the sample pen device driver, and you must define the device-dependent section.

The DCB has data fields and pointers to data structures and routines needed by particular layers of the driver. The indirect call pointers declare device type-dependent and device-dependent routines, enabling common code to support different device types and physical devices without conditional logic and naming conventions to select a routine.

Upward calls from device-dependent code to device type-dependent code or device type-independent code, and from device type-dependent code to device type-independent code can be made by global reference.

Device-dependent routines can access the entire DCB. Device type-dependent code can access the device type-dependent and device type-independent sections, but cannot refer to the private device section because it not aware of the layout. Similarly, the device type-independent code can access only the device type-independent section of the DCB.

Data and routines provided by a lower layer in the device driver are located in the DCB section that requires the access. These fields are generic to all lower-level code and must be supported by all lower-level code.

Operational Considerations
This appendix provides operational considerations pertaining to the performance of a pen device driver.

Support Level Control
The level of Pen for OS/2 system extension support is passed to the pen device driver with the START_LOGICAL_DEVICE IDC request. The support level can be used to distinguish old versions of the Pen for OS/2 system extension with fewer capabilities and different structure layout from the expected level. The pen device driver can choose to support back levels by disabling functions and supplying the expected control block layouts, or the pen device driver can decline to register its devices.

Likewise, the pen device driver identifies its level to Pen for OS/2 in the driver-specific capabilities packet (driver unit 0 capabilities packet), so Pen for OS/2 can interpret the pen device driver's communication or can choose not to identify its Pen for OS/2 Device Driver Services.

The driver-specific capabilities packet identifies the level of the IOCtl interface, Pen for OS/2 Device Driver Service IDC interface, Pen for OS/2 extended information packet interface, and version of the pen device driver.

Configuration Limitations
A pen device driver is limited to one button and one display device. There can be four locator devices of any mix of locator types. There can be only one display device per system. Pen for OS/2 Device Driver Services will not issue START_LOGICAL_DEVICE to logical devices that would cause these limits to be exceeded.

There can be one pen device driver in the system.

Stand-Alone Operation
Pen device drivers created with the Pen for OS/2 Developer's Toolkit are not intended to be used in a system without the Pen for OS/2 system extension. The OS/2 2.1 MOUSE.SYS, without the Pen for OS/2 Device Driver Services, supports only a single device-dependent driver with a single locator device and no extended information packet. Other logical device types are not supported.

It is possible for a pen device driver to run without the Pen for OS/2 system extension. The locator Pen for OS/2 Device Driver Service interface is similar to the OS/2 2.1 MOUSE.SYS IDC interface. The MOUSE.SYS statement in the CONFIG.SYS must include a TYPE= for the pen device driver. The TYPE= in the MOUSE.SYS statement in the CONFIG.SYS must not be present on a Pen for OS/2 system if the device driver has registered with DevHlp_RegisterDeviceClass. The pen device driver's AttachDD IDC entry point must be used for the standard MOUSE.SYS protocol. Being called at the AttachDD entry point by MOUSE.SYS can be used to determine the device driver's mode of operation. An AttachDD to MOUSE.SYS must be performed during READ_ ENABLE to locate the MOUSE.SYS IDC entry point. The MOUSE.SYS interrupt packet must be used instead of the extended information packet.

DevHlp_RegisterDeviceClass can be called on an OS/2 2.1 system without the Pen for OS/2 system extension, but it will be ignored, and the driver entry point will not be called. The Pen for OS/2 device driver is not supported in previous versions of the OS/2 operating system.

If the pen device driver has multiple locator devices, either they must share the MOUSE.SYS interrupt packet or only one device can be supported. The IDC entry point, as defined in the device driver header, must fan out the calls to all locator device entry points if the interrupt packet is shared.

There is no requirement for interrupt packet sharing, and it will require additional programming in the device driver. Supporting both interfaces might be useful if the device driver will be used on OS/2 systems without the Pen for OS/2 system extension.

Multiple Device Drivers
A pen device driver can be composed of a complex number of physical device drivers connected by private IDC calls. One driver should register on behalf of the collection of drivers. This driver will be called by the Pen for OS/2 system extension for IOCtls. The other physical device drivers are invisible to Pen for OS/2. Pen for OS/2 Device Driver Services must be called from the device driver that registered with Pen for OS/2 Device Driver Services.

Resource Utilization
The sample pen device driver uses statically allocated memory in its device driver data segment. You can allocate dynamic memory, but this is not required by the device driver model. There will be no per-process data requirements.

Resources required by the device objects are similar to all Workplace Shell objects.

Video Mode Changes
The pen device driver can request to be informed of video mode and session changes. The ability to report these events is identified with the READ_ENABLE request. See. By default, events are not reported to the device driver. If events are desired, the STYLE_NOTIFY_VMCHANGE style bit must be reset and returned by way of READ_ENABLE.

Events are reported to the pen device driver with the VIDEO_MODE_CHANGE IDC request. This is a global call to the device driver, not to a specific logical device. If the visible portion of the LCD changes for different video modes, the device driver must modify the extents to reflect the new dimensions and inform Pen for OS/2 with the capabilities update Pen for OS/ 2 Device Driver Service (UPDATE_CAPS).

Glossary
This glossary contains terms and definitions that are, for the most part, used specifically with the Pen for OS/2 products. This is not a complete dictionary of computer terms.

Introduction
This glossary includes terms and definitions from:
 * The American National Dictionary for Information Systems, ANSI X3.172-1990, copyright 1990 by the American National Standards Institute (ANSI). Copies may be purchased from the American National Standards Institute, 11 West 42 Street, New York, New York 10036. Definitions are identified by the symbol (A) after the definition.


 * The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.

Glossary Listing
Select a starting letter of glossary terms:

A

 * American National Standard Code for Information Interchange (ASCII):The standard code, using a coded character set consisting of 7-bit coded characters (8-bits including parity check), that is used for information interchange among data processing systems, data communication systems, and associated equipment. The ASCII set consists of control characters and graphic characters. (A)
 * API:Application programming interface.
 * application programming interface (API):A functional interface supplied by the operating system or by a separately orderable licensed program that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.
 * ASCII:American National Standard Code for Information Interchange
 * ASCIIZ format:A string of ASCII characters ending with a null character.
 * assignment:A unique setting that can be changed. See also button assignment and gesture assignment.

B

 * backlight:The fluorescent lighting on a device such as a liquid crystal display (LCD).
 * barrel buttons:Buttons on the side of a pen device, used to request or initiate an action.
 * bezel buttons:Buttons built into the case (bezel) of a pen-based computer or peripheral device, used to request or initiate an action.
 * button:A mechanism used to request or initiate an action. See also barrel buttons and bezel buttons.
 * button assignment:An assignment that defines the action or actions performed as a result of activating a button or combination of buttons.

C

 * calibration:The adjustment of a piece of equipment so that it meets normal operational standards. For example, calibration could refer to adjusting the alignment of a pen.
 * call:(1) The action of bringing a computer program, a routine, or a subroutine into effect, usually by specifying the entry conditions and jumping to an entry point. (I) (A) (2) To transfer control to a procedure, program, routine, or subroutine.
 * cathode ray tube display (CRT display):(1) A device that presents data in visual form by means of controlled electron beams. (A) (2) The data display produced by the device in (1). (A)
 * child class:See subclass.
 * child process:A process, started by a parent process, that shares the resources of the parent process.
 * class:The description of a set of objects and their behavior. New classes can be defined in terms of existing classes through a technique known as inheritance.
 * class method:An action that can be performed on a class object. Class methods also are called factory methods.
 * configure:To describe to a system the devices, optional features, and programs installed on the system.
 * control ball:In computer graphics, a ball, rotatable about its center, that is used as an input device, normally as a locator. (I) (A) Synonymous with track ball.
 * CRT display:Cathode ray tube display.

D

 * DCB:Device control block.
 * debug:To detect, diagnose, and eliminate errors in programs. (T)
 * descendant:See subclass.
 * device control block (DCB):A data structure that contains data and addresses for indirect calls for a logical device.
 * device driver:A program that enables the computer to communicate with a specific peripheral device such as a pen, videodisc player, or CD drive.
 * device helper (DevHlp) functions:Kernel services (memory, hardware interrupts, software interrupts, queuing, semaphores, and so forth) provided to physical device drivers.
 * device ID:A unique ID number assigned to a logical device. A device ID is unique across an entire system.
 * device object:An object that provides a means of communication between a computer and another piece of equipment, such as a pen or display.
 * digitizer:An electronic device that transmits coordinate data to software running on a computer.
 * display bezel:The case surrounding the display of a pen-based computer.
 * DLL:Dynamic link library.
 * double-tap:To touch a sensor twice in rapid succession within a small area.
 * drag:To use a pen or another pointing device to move an object.
 * dynamic link library (DLL):A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously.
 * dynamic link module:A module that is linked at load time or run time.

E

 * emulation:The use of one system to imitate another system so that the imitating system accepts the same data, runs the same programs, and achieves the same results as the imitated system.

F

 * flag
 * 1) A variable indicating that a certain condition holds. (T)
 * 2) A character that signals the occurrence of some condition, such as the end of a word. (A)
 * function
 * 1) In a programming language, a block, with or without formal parameters, whose execution is invoked by means of a call.
 * 2) A set of related control statements that cause one or more programs to be performed.

G

 * gesture:A hand-drawn symbol or uppercase letter which, when recognized by the system, invokes an action or a series of actions. Gestures denote an action and a target for the action.
 * gesture assignment:An assignment that defines the action or actions performed as a result of a gesture.
 * group:A collection of files that can be presented to the user as an installation option.

H

 * header
 * 1) System-defined control information that precedes user data.
 * 2) The portion of a message that contains control information for the message, such as one or more destination fields, name of originating station, input sequence number, character string indicating the type of message, and priority level for the message.
 * hot key
 * 1) The key combination used to change from one session to another on the workstation.
 * 2) To jump, or hot key, from a host session to an application on the workstation, or from the workstation to the host session.
 * hot spot:The area of a display screen that is activated to accept user input. Synonymous with touch area.

I

 * IDC:Inter-device-driver communication.
 * ink:The trail resulting from writing with the pen.
 * inheritance
 * 1) In the OS/2 Presentation Manager interface, the technique of specifying the shape and behavior of one window (called a child window) as incremental differences from another window (called a parent window).
 * 2) In System Object Model, implications of derivation of new classes from existing classes. Child classes inherit methods from parent and ancestor classes.
 * input/output control (IOCtl):A system service that provides a way for an application to send device-specific control commands to a device driver.
 * instance:A specific object belonging to a class.
 * instance method:Actions that can be performed on instances of class objects.
 * inter-device-driver communication (IDC):A mechanism that enables a physical device driver to communicate with another physical device driver.
 * IOCtl:Input/output control.

J

 * joy stick:In computer graphics, a lever that can pivot in all directions and that is used as a locator device. (T)

K

 * kernel:The part of an operating system that performs basic functions, such as allocating hardware resources.

L

 * LCD:Liquid crystal display.
 * line feed
 * 1) The movement of the print or display position to the corresponding position on the next line. (T)
 * 2) The incremental relative movement between the paper carrier and the type carrier in a direction perpendicular to the writing line.
 * liquid crystal display (LCD):A display device that creates characters by means of the action of reflected light on patterns formed by a liquid that becomes opaque when it is energized.
 * logical device
 * 1) A file for conducting input or output with a physical device.
 * 2) A file for mapping user I/O between virtual and real devices. A logical device can be accessed using the file system API.

M

 * metaclass:A class of a class. In System Object Model, a metaclass defines class methods for a class object.
 * method:An action that can be performed on an object.
 * mouse-emulation mode:An input mode in which the system interprets pen input as mouse input.

O

 * object
 * 1) A graphic symbol that a user works with to perform a task.
 * 2) In System Object Model, a set of data and the actions that can be performed on that data.
 * object definition:See class.
 * object instance:See instance.
 * OEM:Original equipment manufacturer.
 * Original equipment manufacturer (OEM):A manufacturer of equipment that may be marketed by another manufacturer.

P

 * parallax:A condition that occurs when a gap exists between the locator position and the displayed trail resulting from writing with the pen. Parallax differs in both the horizontal and vertical views by how a user looks at the display.
 * parent class:A class from which another class inherits. See inheritance.
 * parent process:A process that creates other processes. Contrast with child process.
 * path:The part of a file specification that lists the drive name and a series of directory names that give the location of the file. Each directory name is separated by the backslash character. In the specification C:\MYFILES\MISC\GLOSSARY.SCR, the path consists of C:\MYFILES \MISC\.
 * pause:An action where the pen remains motionless for an interval of time while it is in the proximity zone or touching a touch-sensitive surface. This interval of time starts a new action (for example, mouse-emulation mode).
 * pel:Picture element.
 * pen:A pointing and input device used with a touch-sensitive device.
 * pen-aware programs:Programs that are written or modified to use a pen or a finger as the standard input device rather than a keyboard or a mouse.
 * pen-unaware programs:Programs that are written to use a keyboard or a mouse and are not written to use a pen.
 * picture element:In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T)
 * pixel:Picture element.
 * privilege level:A protection method supported by the hardware architecture of IBM personal computer systems. This method consists of four privilege levels know as rings (numbered 0 through 3). Only certain types of programs are allowed to execute at each privilege level.
 * program-file object:An object that starts a program. Program files commonly have extensions of .EXE, .COM, .CMD, or .BAT.
 * program object:An object representing the file that starts a program. A user can change the settings for a program object to specify the gesture assignments for a particular program.
 * proximity zone:An area where action is sensed by a touch-sensitive device without the input device touching the touch-sensitive surface. The zone varies depending on the technology of the digitizer in the device, but it is usually no more than 6.35 mm (0.25 in.) from the surface.

R

 * return code:
 * 1) A code used to influence the execution of succeeding instructions.
 * 2) A value returned to a program to indicate the results of an operation requested by that program.
 * ring level:See privilege level.

S

 * screen:The physical surface of a display device upon which information is shown to a user.
 * settings:Characteristics of objects that the user can view and sometimes alter.
 * shift:An action during mouse-emulation mode in which the default mouse button 1 down action emulates another button or combination of buttons for the duration of the stroke.
 * shutdown:The procedure required before the computer is switched off to ensure that data is not lost.
 * SOM:System Object Model.
 * source directory:The directory from which information is read. Contrast with target directory.
 * stroke:The collection of points between the point where the pen touches a touch-sensitive surface and the point where the pen is removed from the surface.
 * subclass:A class that is derived from another class. The subclass inherits the data and methods from the parent class and can define new methods or override existing methods to define new behavior not inherited from the parent class. See inheritance.
 * System Object Model:A mechanism for language-neutral, object-oriented programming for the OS/2 environment.

T

 * tap:To briefly touch a touch-sensitive surface with a pointing device and then quickly remove it.
 * target:The location to which the information is destined.
 * target directory:The directory to which information is written. Contrast with source directory.
 * tick count:A value registered with the Pen for OS/2 extension that causes the Pen for OS/2 timer handler to be called on every ntimer ticks instead of every timer tick.
 * toggle:To switch between two modes; for example, to switch between selected and deselected mode.
 * touch area:Synonym for hot spot.
 * touch-down point:Location, plotted by a digitizer, on screen where contact is made with touch-sensitive surface.
 * touch screen:A display device that allows the user to interact with a computer system by touching an area on its screen.
 * touch-sensitive:Pertaining to a device such as a keypad or screen that generates coordinate data when a pointing device approaches or contacts the surface, thereby allowing a user to interact directly with a computer without entering commands from a keyboard.
 * track ball:Synonym for control ball.

U

 * unit number:A number used by a device driver to select a specific logical device. A unit number is unique only within the scope of the driver.

V

 * VGA:Video graphics array.

W

 * window:An area of the screen with visible boundaries within which information is displayed. A window can be smaller than or the same size as the screen. Windows can appear to overlap on the screen.
 * window class:The grouping of windows whose processing requirements conform to the services provided by one window procedure.

Trademarks
Trademark of the Microsoft Corporation.