## Pen for OS/2 Device Driver Reference

[prev][next][parent][TOC]

### 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.

Locator Device Processing 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. Button Device Processing 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. Display Device Processing 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 Common Capabilities Packet. 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 Configuration Limitations 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 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.