═══ 1. Notices ═══ Third Edition (September 1994) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM authorized reseller or IBM marketing representative. ═══ 1.1. 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 1994. 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. ═══ 1.2. 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 IBMs product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBMs intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the users responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 1.3. Trademarks ═══ The following terms, denoted by an asterisk (*) in this publication, are trademarks of the IBM Corporation in the United States or other countries: IBM OS/2 Presentation Manager Workplace Shell ═══ 2. 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. ═══ 2.1. 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. ═══ 2.2. Summary of Changes ═══ The following list summarizes the changes in this release. o Function 62h - Query Default Locator Extents was added to category 91h. o The common capabilities packet added defines for word boundary flags. ═══ 2.3. How This Book Is Organized ═══ This book is organized as follows: o Architecture contains a description of the pen device driver component structure, logical device types, and driver data. o Initialization contains a description of device driver initialization and logical device registration. o Operations contains a description of the operations that handle the processing of logical devices. o Pen Device Objects contains a description of the new device objects created by Pen for OS/2, instance methods, and class methods. o Installation Control Files contains a description of the pen device driver installation process. o Programming Interface contains the format for programming interfaces, including request packet interface, generic IOCtl interface, and extended Pen for OS/2 interface. o 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. o Operational Considerations contains additional information pertaining to device driver development, including configuration limitations and video mode changes. ═══ 2.4. Related Publications ═══ The following publications are available: o Pen for OS/2 Developers Toolkit: Getting Started, 71G2123 o Pen for OS/2 Programming Guide and Reference, 71G2124 o Pen for OS/2 Users Guide, 71G2122 ═══ 2.5. 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 407-982-3217 (using a modem) to register and access the support system. For voice support in the United States, call 407-982-4239. Additional assistance is available through the IBM Developer Assistance Program. For membership information: Telephone: 407-982-6408 Fax: 407-988-7610 (U.S.A.) or Fax: 407-982-4259 (worldwide) ═══ 2.6. Ordering Information ═══ For an illustration of OS/2 Technical Publications and other related product documents, see the following figure. The IBM Developer Connection Device Driver Kit for OS/2 on CD-ROM contains actual source code for sample device drivers, as well as the complete text of the books in online form. To order any of the publications shown in the illustration, call: ┌────────────────────┬─────────────────────┬─────────────────────┐ │U.S.A.: │1-800-633-8266 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Canada: │1-800-561-5293 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Europe, Middle East,│ English language │(+45) 48101500 │ │Africa, and │ French language │(+45) 48101200 │ │Latin America: │ Italian language │(+45) 48101600 │ │ │ German language │(+45) 48101000 │ │ │ Spanish language │(+45) 48101100 │ │ │ Dutch language │(+45) 48101400 │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Asia/Pacific: │ All except Japan │(61) 2-354-7684 │ │ │ Japan │(81) 3-3495-2045(Fax)│ │ │ │Fax request to: │ │ │ │DAP-J, IBM Japan │ ├────────────────────┼─────────────────────┼─────────────────────┤ │SE Brazil: │(021) 800-6120(Voice)│ │ │ │(021) 800-6936(Fax) │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Mexico: │ Mexico City │627-2444 │ │ │ Country │91-800-00639 │ └────────────────────┴─────────────────────┴─────────────────────┘ ═══ 3. 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: o 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. Pen for OS/2 Extended Interface 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. Generic IOCtl Interface 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. o 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. Device Driver Data describes the types of device driver data. Pen Device Objects describes device objects in more detail. o Optional calibration program You can provide a calibration program. The calibration program, provided with the Pen for OS/2 Developers Toolkit, can be invoked from a device object which can communicate with the pen device driver through IOCtls. o 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 Initialization. o 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. ═══ 3.1. 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: o 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. o 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. o 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 units 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. ═══ 3.2. 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: o 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 Pen Device Driver Tool, can set and query device-private variables. o 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: o Locator Offset o Locator Pass Rate o Locator Sample Rate o Button Assignments o 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. ═══ 4. 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: o 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. o The device driver is fully operational with default settings before the startup of the Pen for OS/2 system extension. o 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: o Initialization at startup o Delayed initialization Delayed initialization is designed by the developer depending on the hardware supported. For more information, see 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 drivers 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 Delayed Initialization 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. ═══ 4.1. 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 drivers device header must enable AttachDD and declare an AttachDD entry point. Logical Device Registration 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 Pen for OS/2 Extended Interface for complete details of the DevHlp_RegisterDeviceClass interface. ═══ 4.2. 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_RegisterDeviceClass, 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 Logical Device Types). 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 drivers interface (see Support Level Control), 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 Pen for OS/2 Extended Interface 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. ═══ 4.3. 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: o PPMID_STABILITY o PPMID_DIVIDE_RATE 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. 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 Device Driver Data, the Pen for OS/2 system will pass this data when it starts up. ═══ 5. 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. ═══ 5.1. 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. ═══ 5.1.1. 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 zone is 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. ═══ 5.1.2. 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 devices 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 drivers 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. ═══ 5.1.3. 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 Finger Offset. 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 Video Mode Changes. 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 Developers Toolkit, the measured extents are found by calculating the corners of the LCD, as shown by the large arrows in the previous figure. (See Calibration Program for a description of the sample calibration program provided in the Pen for OS/2 Developers 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. ═══ 5.1.4. 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. ═══ 5.1.5. 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 packets dev_timestampRes field would be set to 0, and the locator event packets 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. ═══ 5.1.6. 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. ═══ 5.1.7. 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. ═══ 5.1.8. Performance Considerations ═══ The following list describes items that affect the performance of a Pen for OS/2 system extension. o Locator device performance is critical to the Pen for OS/2 system. Code path lengths would be optimized due to the frequency of execution. o 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. o 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. ═══ 5.2. 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 products 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. Generic IOCtl Interface provides a complete list of these assignments. The state of all buttons is reported on each locator event in the locator event stream. ═══ 5.3. 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 displays backlight, turn off the displays 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 systems 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 Function 51h. 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. ═══ 5.4. 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. ═══ 5.5. 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. ═══ 6. 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. ═══ 6.1. Workplace Object Classes Hierarchy ═══ The following figure lists the new 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 childs new methods, instance data, and overriding parent methods. An object class is subclassed by deriving the new child class from the parent class. The parents 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. ═══ 6.2. Workplace Object Classes ═══ The following sections describe the object classes listed below: o PenButtonDevice o PenDisplay o PenLocator o PenLocatorFinger o PenLocatorPen ═══ 6.2.1. PenButtonDevice ═══ Class definition file: PENBTNDV.SC Class hierarchy: SOMObject PenObject WPAbstract PenButtonDevice The following are the PenButtonDevice methods: o penAddButtonMappingsPage o penQueryButtonData o penSetButtonData The following is the class method for the PenButtonDevice class: o penclsQueryButtonData The following are the methods overridden by the PenButtonDevice class: o wpAddSettingsPages o wpInitData o wpRestoreState method. o wpSaveState method. o wpSetup o wpUnInitData The following is the class method overridden by the PenButtonDevice class: o wpclsInitData When an instance of the Display 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 PenDisplay class. ┌───────────────┬───────────────┬──────────────────────────────┐ │Keyword │Example Value │Description │ ├───────────────┼───────────────┼──────────────────────────────┤ │PEN_DRIVER │Your Device │The device name of the driver │ │ │Name │logical device that this │ │ │ │instance is representing. │ │ │ │This determines which set of │ │ │ │Pen for OS/2 variables will be│ │ │ │affected by the controls in │ │ │ │the notebook. │ ├───────────────┼───────────────┼──────────────────────────────┤ │PEN_DEVICE │Display │The device name of the driver │ │ │ │logical device that this │ │ │ │instance is representing. │ │ │ │This determines which set of │ │ │ │Pen for OS/2 variables will be│ │ │ │affected by the controls in │ │ │ │the notebook. │ └───────────────┴───────────────┴──────────────────────────────┘ 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 PenLocatorPen is a subclass of PenButtonDevice, any pen that is installed which has button capabilities will automatically have a Buttons page inserted into its Settings notebook. ═══ 6.2.2. PenDisplay ═══ Class definition file: WPDISPLY.SC Class hierarchy: SOMObject PenObject WPAbstract PenButtonDevice PenDisplay The following is the PenDisplay method: o penAddDisplayBacklightPage The following are the methods overridden by the PenDisplay class: o wpAddObjectWindowPage o wpAddSettingsPages o wpFilterPopupMenu o wpOpen The following are the class methods overridden by the PenDisplay class: o wpclsQueryDefaultHelp o wpclsQueryDefaultView o wpclsQueryIconData o wpclsQueryStyle o 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 which enables the user to adjust the grey scaling for a monochrome LCD. ═══ 6.2.3. PenLocator ═══ Class definition file: WPLOCATR.SC Class hierarchy: SOMObject PenObject WPAbstract PenButtonDevice PenLocator The following is the PenLocator method: o penAddLocatorTimingPage The following is the PenLocator class method: o penclsQueryDefaultPause o penclsQueryPauseEnableDefault The following are the methods overridden by the PenLocator class: o wpAddSettingsPages o wpAddObjectWindowPage o wpFilterPopupMenu o wpInitData o wpMenuItemSelected o wpMenuItemHelpSelected o wpModifyPopupMenu o wpRestoreState o wpSaveState o wpSetup o wpUnInitData o wpOpen The following are the class methods overridden by the PenLocator class: o wpclsQueryDefaultHelp o wpclsQueryDefaultView o wpclsQueryIconData o wpclsQueryStyle o wpclsQueryTitle When an instance of the locator 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 PenLocator class. ┌───────────────┬───────────────┬──────────────────────────────┐ │Keyword │Example Value │Description │ ├───────────────┼───────────────┼──────────────────────────────┤ │CALPROG │.EXE filename │The executable file name of │ │ │ │the OS/2 application program │ │ │ │that will be started when │ │ │ │Calibrate is selected from the│ │ │ │menu. │ ├───────────────┼───────────────┼──────────────────────────────┤ │CALPARMS │TRUE │The presence of this keyword │ │ │ │indicates that the Driver and │ │ │ │Device names are to be passed │ │ │ │to the Calibration program as │ │ │ │arguments. If the Calibration│ │ │ │program has no arguments then │ │ │ │omit this keyname from the │ │ │ │setup string. │ └───────────────┴───────────────┴──────────────────────────────┘ ═══ 6.2.4. PenLocatorFinger ═══ Class definition file: WPLOCFGR.SC Class hierarchy: SOMObject PenObject WPAbstract PenButtonDevice PenLocator PenLocatorFinger The following is the PenLocatorFinger method: o penAddFingerOffsetPage The following are the methods overridden by the PenLocatorFinger class: o wpInitData o wpRestoreState o wpSaveState o wpAddSettingPages The following are the class methods overridden by the PenLocatorFinger class: o penclsQueryDefaultPause o penclsQueryPauseEnableDefault o wpclsQueryIconData o wpclsQueryTitle o wpclsQueryDefaultHelp PenLocatorFinger is a new class and is a subclass of the PenLocator class. This class adds an additional page, Offset, to the Settings notebook which enables you to set finger offset to the screen pointer. This is accomplished through the penAddLocatorFingerOffsetPage method and a corresponding dialog procedure. Note: The Offset page supports only display devices with the origin in the upper-left corner of the device. ═══ 6.2.5. PenLocatorPen ═══ Class definition file: WPLOCPEN.SC Class hierarchy: SOMObject PenObject WPAbstract PenButtonDevice PenLocator PenLocatorPen The following are the class methods overridden by the PenLocatorPen class: o penclsQueryDefaultPause o penclsQueryPauseEnableDefault o wpclsQueryIconData o wpclsQueryTitle o wpclsQueryDefaultHelp ═══ 6.3. Workplace Instance Methods ═══ The following sections describe the Workplace instance methods listed below: o penAddButtonMappingsPage o penQueryButtonData o penSetButtonData o penAddLocatorTimingPage o penAddDisplayBacklightPage o penAddFingerOffsetPage ═══ 6.4. penAddButtonMappingsPage ═══ ═══ - penAddButtonMappingsPage ═══ /*******************************************/ /* This method enables the object to add */ /* the Buttons page to its Settings */ /* notebook. */ /*******************************************/ PenButtonDevice *self; HWND hwndNotebook; ULONG rc; rc = penAddButtonMappingsPage(self, hwndNotebook); ═══ Parameter - self ═══ self (PenButtonDevice *) - input The pointer to this object. ═══ Parameter - hwndNotebook ═══ hwndNotebook (HWND) - input The handle of the notebook in which to insert the page. ═══ Return Value - rc ═══ rc (ULONG) - returns Page indentifier: 0 Error occurred. PageId Identifier for the inserted page. ═══ Usage - penAddButtonMappingsPage ═══ This method must be called from within an override of the wpAddSettings Pages method. ═══ Override Methods - penAddButtonMappingsPage ═══ It is overridden in order to replace or remove the Buttons page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent. ═══ Related Methods - penAddButtonMappingsPage ═══ None. ═══ Topics - penAddButtonMappingsPage ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.5. penQueryButtonData ═══ ═══ - 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 rc; rc = penQueryButtonData(self, pPenEventData); ═══ Parameter - self ═══ self (PenButtonDevice *) - input The pointer to this object. ═══ Parameter - pPenEventData ═══ pPenEventData (PPENEVENTDATA) - input 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. ═══ Return Value - rc ═══ rc (ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this object. ═══ Usage - penQueryButtonData ═══ This method can be called at any time to query the current button bit map and name data for this object. ═══ Override Methods - penQueryButtonData ═══ This method is generally not overridden. ═══ Related Methods - penQueryButtonData ═══ o penclsQueryButtonData o penSetButtonData ═══ Topics - penQueryButtonData ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.6. penSetButtonData ═══ ═══ - 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); ═══ Parameter - self ═══ self (PenButtonDevice *) - input The pointer to this object. ═══ Parameter - pPenEventData ═══ 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. ═══ Return Value - rc ═══ rc (BOOL) - returns Success indicator: TRUE Successful completion. FALSE Error occurred. ═══ Usage - penSetButtonData ═══ This method can be called at any time to change the current button bit map and name data for this object. ═══ Override Methods - penSetButtonData ═══ This method is generally not overridden. ═══ Related Methods - penSetButtonData ═══ o penclsQueryButtonData o penQueryButtonData ═══ Topics - penSetButtonData ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.7. penAddLocatorTimingPage ═══ ═══ - penAddLocatorTimingPage ═══ /*******************************************/ /* This method enables the object to add */ /* the Timings page to its Settings */ /* notebook. */ /*******************************************/ PenLocator *self; HWND hwndNotebook; ULONG rc; rc = penAddLocatorTimingPage(self, hwndNotebook); ═══ Parameter - self ═══ self (PenLocator *) - input The pointer to this object. ═══ Parameter - hwndNotebook ═══ hwndNotebook (HWND) - input The handle of the notebook in which to insert the page. ═══ Return Value - rc ═══ rc (ULONG) - returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. ═══ Usage - penAddLocatorTimingPage ═══ This method must be called from within an override of the wpAddSettingsPages method. ═══ Override Methods - penAddLocatorTimingPage ═══ 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. ═══ Related Methods - penAddLocatorTimingPage ═══ None. ═══ Topics - penAddLocatorTimingPage ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.8. penAddDisplayBacklightPage ═══ ═══ - penAddDisplayBacklightPage ═══ /*******************************************/ /* This method enables the object to add */ /* the Backlight page to its Settings */ /* notebook. */ /*******************************************/ PenDisplay *self; HWND hwndNotebook; ULONG rc; rc = penAddDisplayBacklightPage(self, hwndNotebook); ═══ Parameter - self ═══ self (PenDisplay *) - input The pointer to this object. ═══ Parameter - hwndNotebook ═══ hwndNotebook (HWND) - input The handle of the notebook in which to insert the page. ═══ Return Value - rc ═══ rc (ULONG) - returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. ═══ Usage - penAddDisplayBacklightPage ═══ This method must be called from within an override of the wpAddSettingsPages method. ═══ Override Methods - penAddDisplayBacklightPage ═══ 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. ═══ Related Methods - penAddDisplayBacklightPage ═══ None. ═══ Topics - penAddDisplayBacklightPage ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.9. penAddFingerOffsetPage ═══ ═══ - 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); ═══ Parameter - self ═══ self (PenLocatorFinger *) - input The pointer to this object. ═══ Parameter - hwndNotebook ═══ hwndNotebook (HWND) - input The handle of the notebook in which to insert the page. ═══ Return Value - rc ═══ rc (ULONG) - returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. ═══ Usage - penAddFingerOffsetPage ═══ This method must be called from within an override of the wpAddSettingsPages method. ═══ Override Methods - penAddFingerOffsetPage ═══ 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. ═══ Related Methods - penAddFingerOffsetPage ═══ None. ═══ Topics - penAddFingerOffsetPage ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.10. Workplace Class Methods ═══ The following sections describe the Workplace Class methods listed below: o penclsQueryButtonData o penclsQueryDefaultPause o penclsQueryPauseEnableDefault ═══ 6.11. penclsQueryButtonData ═══ ═══ - penclsQueryButtonData ═══ /*******************************************/ /* This method enables the class object to */ /* specify default button bit maps and */ /* names used by its instances. */ /*******************************************/ M_PenButtonDevice *self; /* The pointer to the class object. */ PPENEVENTDATA pPenEventData; ULONG rc; rc = penclsQueryButtonData(self, pPenEventData); ═══ Parameter - self ═══ self (M_PenButtonDevice *) - input The pointer to the class object. ═══ Parameter - pPenEventData ═══ pPenEventData (PPENEVENTDATA) - input 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 correctly. This buffer must always contain one valid PENEVENTDATA structure for each button registered with the writing input subsystem by the device driver. ═══ Return Value - rc ═══ rc (ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this particular class object. ═══ Remarks - penclsQueryButtonData ═══ 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. ═══ Usage - penclsQueryButtonData ═══ This method can be called at any time. Typically, it would not be useful for another object class to call this method. ═══ Override Methods - penclsQueryButtonData ═══ 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. 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 - penclsQueryButtonData ═══ o penQueryButtonData o penSetButtonData ═══ Topics - penclsQueryButtonData ═══ Select an item: Returns Remarks Override Methods Usage Related Methods ═══ 6.12. penclsQueryDefaultPause ═══ ═══ - penclsQueryDefaultPause ═══ /*******************************************/ /* This method enables the object to query */ /* the default Pen for OS/2 pause system */ /* setting. */ /*******************************************/ M_PenLocator *self; ULONG rv; rv = penclsQueryDefaultPause(self); ═══ Parameter - self ═══ self (M_PenLocator *) - input The pointer to the class object. ═══ Return Value - rv ═══ rv (ULONG) - returns The default Pen for OS/2 system setting for pause is returned. ═══ Usage - penclsQueryDefaultPause ═══ This method can be called at any time. ═══ Override Methods - penclsQueryDefaultPause ═══ This method can be overridden to specify a different default pause value. ═══ Related Methods - penclsQueryDefaultPause ═══ None. ═══ Topics - penclsQueryDefaultPause ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.13. penclsQueryPauseEnableDefault ═══ ═══ - penclsQueryPauseEnableDefault ═══ /*******************************************/ /* This method is called to allow the */ /* object to query the default Pen for */ /* OS/2 pause-enable system setting. */ /*******************************************/ M_PenLocator *self; ULONG rc; rc = penclsQueryPauseEnableDefault(self); ═══ Parameter - self ═══ self (M_PenLocator *) - input The pointer to the class object. ═══ Return Value - rc ═══ rc (ULONG) - returns The default Pen for OS/2 system setting for pause is returned. ═══ Usage - penclsQueryPauseEnableDefault ═══ This method can be called at any time. ═══ Override Methods - penclsQueryPauseEnableDefault ═══ This method can be overridden to specify a different default pause enable value. ═══ Related Methods - penclsQueryPauseEnableDefault ═══ None. ═══ Topics - penclsQueryPauseEnableDefault ═══ Select an item: Returns Override Methods Usage Related Methods ═══ 6.14. 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, and Workplace Shell Programming Reference. ═══ 6.14.1. 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 Installation Control Files, for a description of how the XXXX.WPO file is set up to create the default Pen for OS/2 device objects. ═══ 6.14.2. 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, then 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 will also need files WPLOCPEN.H and WPLOCPEN.SC from the Pen for OS/2 Developers Toolkit. In the .CSC file, you will need to define method overrides for the following methods: o wpclsQueryTitle o wpclsQueryIconData An example .CSC file is detailed in the following figure. ────────────────────────────────────────────────────────────────────────── include class: MyPenClassName, external stem = Mypen, local, external prefix = mypen_, classprefix = mypenM_, major version = 1, minor version = 1; parent: PenLocatorPen; methods: override wpclsQueryTitle, class; override wpclsQueryIconData, class; ────────────────────────────────────────────────────────────────────────── 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: o wpclsQueryTitle would return a pointer to the name of the icon. Do not call the parent. An example follows: ────────────────────────────────────────────────────────────────────────── SOM_Scope PSZ SOMLINK mypenM_wpclsQueryTitle(M_MyPenClassName *sonSelf) { return ("MyIconName"); } ────────────────────────────────────────────────────────────────────────── o 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: ────────────────────────────────────────────────────────────────────────── SOM_Scope ULONG SOMLINK mypenM_wpclsQueryIconData( M_MyPenClassName *somSelf, PICONINFO pIconInfo) { if (pIconInfo { pIconInfo->fFormat = ICON_RESOURCE; pIconInfo->hmod = myHmod; pIconInfo->resid = IDP_MYICON; } 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. ═══ 6.14.3. 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 then 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 (.CSC) to define your class. You will also need files WPLOCFGR.H and WPLOCFGR.SC from the Pen for OS/2 Developers Toolkit. In the .CSC file, you will need to define method for the following methods: o penAddFingerOffsetPage An example .CSC file follows: ────────────────────────────────────────────────────────────────────────── include class: MyTouchClassName, external stem = Mytch, local, external prefix = mytch_, classprefix = mytchM_, major version = 1, minor version = 1; parent: PenLocatorFinger; methods: override penAddFingerOffsetPage; ────────────────────────────────────────────────────────────────────────── After creating the .C source file (and other SOM emitted files) by running the SOM compiler, modify the .C source as follows: o penAddFingerOffsetPage would return SETTINGS_PAGE_REMOVED. Do not call the parent. An example follows: ────────────────────────────────────────────────────────────────────────── 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, and Workplace Shell Programming Reference. The class definition files PENBTNDV.SC, WPDISPLY.SC, WPLOCATR.SC, WPLOCPEN.SC, and WPLOCFGR.SC are included in the Pen for OS/2 Developers Toolkit. ═══ 7. 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. ═══ 7.1. 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 Developers 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" ────────────────────────────────────────────────────────────────────────── These 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 Developers 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 Developers 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. ═══ 7.2. 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: o 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. o 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). o 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. ═══ 7.3. 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 Calibration Program. 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. ═══ 7.4. 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 files progress 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. ═══ 8. Programming Interface ═══ The device-driver-socket programming interface of the pen device driver is made up of the following: o Request packet interface o Generic IOCtl interface o Pen for OS/2 extended interface 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. ┌──────────────┬──────────────────────┐ │C │ASM │ ├──────────────┼──────────────────────┤ │LONG │DD │ ├──────────────┼──────────────────────┤ │SHORT │DW │ ├──────────────┼──────────────────────┤ │UCHAR │DB │ ├──────────────┼──────────────────────┤ │ULONG │DD │ ├──────────────┼──────────────────────┤ │USHORT │DW │ └──────────────┴──────────────────────┘ 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 Function 60h. This is the name of the variable used in the sample. ═══ 8.1. Request Packet Interface ═══ The pen device driver is a character device driver and implements the following OS/2 device driver strategy commands: ┌──────────────┬──────────────────────┐ │Code │Command │ ├──────────────┼──────────────────────┤ │0H │INIT │ ├──────────────┼──────────────────────┤ │DH │OPEN DEVICE │ ├──────────────┼──────────────────────┤ │EH │CLOSE DEVICE │ ├──────────────┼──────────────────────┤ │10H │GENERIC IOCtl │ └──────────────┴──────────────────────┘ Note: BAD_COMMAND (8103H) is returned for all other commands that are not supported. DosDevIOCtl2 is not supported. INIT is described in Initialization. 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 Driver Subcomponents. Generic IOCtl Interface describes the IOCtl functions the device driver must support. ═══ 8.2. 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. ┌───────────────┬───────────────┬──────────────────────────────┐ │Category │Function │Description │ ├───────────────┼───────────────┼──────────────────────────────┤ │90H │ │Driver │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │50H │Set Unit Specific Data │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │51H │Set Unit Variable │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │52H │Reset Trace Table │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │53H │Set Trace Table Size │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │60H │Query Unit Specific Data │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │61H │Query Unit Variable │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │62H │Query Unit Capabilities │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │63H │Query Trace Table │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │64H │Query Trace Table Size │ ├───────────────┼───────────────┼──────────────────────────────┤ │91H │ │Locator │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │50H │Set Locator Offset │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │51H │Set Locator Pass Rate │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │52H │Set Locator Sample Rate │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │60H │Query Locator Variables │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │61H │Query Locator Raw Coordinates │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │62H │Query Default Locator Extents │ ├───────────────┼───────────────┼──────────────────────────────┤ │92H │ │Button │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │50H │Set Button Assignment │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │60H │Query Button Assignment │ ├───────────────┼───────────────┼──────────────────────────────┤ │93H │ │Display │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │50H │Set Display State │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │51H │Set Display Inactivity Period │ ├───────────────┼───────────────┼──────────────────────────────┤ │ │60H │Query Display State │ └───────────────┴───────────────┴──────────────────────────────┘ ERROR_INVALID_PARAMETER (8113H) is returned for invalid unit or for parameters out of the specified range. General defines: ────────────────────────────────────────────────────────────────────────── #define PEN_CAT_DRIVER 0x090 /* Driver category */ #define PEN_CAT_LOCATOR 0x091 /* Locator category */ #define PEN_CAT_BUTTON 0x092 /* Button category */ #define PEN_CAT_DISPLAY 0x093 /* Display category */ #define PEN_IOCTL_LEV_MAJOR 0 /* IOCtl interface level */ #define PEN_IOCTL_LEV_MINOR 3 /* IOCtl interface level */ ────────────────────────────────────────────────────────────────────────── The rest of this section describes the IOCtl functions defined in PENIOCTL.H. ═══ 8.2.1. Category 90h - Driver IOCtls ═══ The following are Category 90h - Driver IOCtls: o Function 50h - Set Unit Specific Data o Function 51h - Set Unit Variable o Function 52h - Reset Trace Table o Function 53h - Set Trace Table Size o Function 60h - Query Unit Specific Data o Function 61h - Query Unit Variables o Function 62h - Query Unit Capabilities o Function 63h - Query Trace Table o Function 64h - Query Trace Table Size ═══ 8.3. Set Unit Specific Data - Function 50h ═══ ═══ Description - Category 90h, Function 50h ═══ #define PEN_FUNC_SUSD 0x050 This function sets the device-specific data for the requested unit. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Byte count of the ULONG │ │device-specific data area │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ Device specific structure, first LONG has byte count. 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. ═══ Category 90h, Function 50h ═══ Category 90h, Driver IOCtls - Set Unit Specific Data Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.4. Set Unit Variable - Function 51h ═══ ═══ Description - Category 90h, Function 51h ═══ #define PEN_FUNC_SUV 0x051 This function sets the device-specific variable for the requested unit. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌───────────────────────────────────────┐ │Field Length │ ├───────────────────────────────────────┤ │Requested unit ULONG │ ├───────────────────────────────────────┤ │Index of variable to set ULONG │ ├───────────────────────────────────────┤ │Value to set LONG │ └───────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ None. ═══ Category 90h, Function 51h ═══ Category 90h, Driver IOCtls - Set Unit Variable Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.5. Reset Trace Table - Function 52h ═══ ═══ Description - Category 90h, Function 52h ═══ #define PEN_FUNC_RTT 0x052 This function resets the transaction trace buffer. Resetting the trace buffer is a convenient way to view only current stroke data. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ None. ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ None. ═══ Category 90h, Function 52h ═══ Category 90h, Driver IOCtls - Reset Trace Table Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.6. Set Trace Table Size - Function 53h ═══ ═══ Description - Category 90h, Function 53h ═══ #define PEN_FUNC_STTS 0x053 This function allocates a trace table for tracing. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Number of LONG values in table ULONG │ │(Number of bytes/4) │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ None. ═══ Category 90h, Function 53h ═══ Category 90h, Driver IOCtls - Set Trace Table Size Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.7. Query Unit Specific Data - Function 60h ═══ ═══ Description - Category 90h, Function 60h ═══ #define PEN_FUNC_QUSD 0x060 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. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Byte count of the device ULONG │ │specific data area │ ├─────────────────────────────────────────┤ │Bytes returned (output ULONG │ │parameter) │ ├─────────────────────────────────────────┤ │Return code (output parameter) ULONG │ ├─────────────────────────────────────────┤ │Capabilities (output ULONG │ │parameter) │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ Device specific structure. ═══ Remarks - Category 90h, Function 60h ═══ Values for pqusd.capabilities: #define QUSD_RESERVD 0x0000FFFF /* Reserved for architected use */ #define QUSD_OEM 0xFFFF0000 /* Reserved for OEM use */ The following are defined for all device types: #define QUSD_LENGTH 0x00000001 /* First word of unit data is length. */ #define QUSD_STANDARD 0x00000002 /* Starts with standard device-specific layout. */ The following are locator specific: #define QUSD_X_INVERT 0x00000004 /* X raw coordinate is inverted. */ #define QUSD_Y_INVERT 0x00000008 /* Y raw coordinate is inverted. */ Values for pqusd.rc: #define QUSD_OK 0 /* All data was copied. */ #define QUSD_TRUNC 1 /* Data was truncated. */ #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; ═══ Category 90h, Function 60h ═══ Category 90h, Driver IOCtls - Query Unit Specific Data Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.8. Query Unit Variables - Function 61h ═══ ═══ Description - Category 90h, Function 61h ═══ #define PEN_FUNC_QUV 0x061 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. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌───────────────────────────────────────┐ │Field Length │ ├───────────────────────────────────────┤ │Requested unit ULONG │ ├───────────────────────────────────────┤ │Index of variable to set ULONG │ └───────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────┐ │Field Length │ ├─────────────────────────────┤ │Value returned ULONG │ └─────────────────────────────┘ ═══ Data Structure - Category 90h, Function 61h ═══ typedef struct _D_QUV { ULONG value; /* Value returned */ } DQUV; Note: The sample program provided in the Pen for OS/2 Developers Toolkit uses unit 0 and variable 0 to report the error count. To report the panic values (internal errors), the Pen for OS/2 Developers Toolkit sample program uses unit 0 and variable 1. The numerical panic values are mapped to their meanings in the PEN.INC file. ═══ Category 90h, Function 61h ═══ Category 90h, Driver IOCtls - Query Unit Variables Select an item: Description Parameter Packet Format Data Packet Format Data Structure ═══ 8.9. Query Unit Capabilities - Function 62h ═══ ═══ Description - Category 90h, Function 62h ═══ #define PEN_FUNC_QUC 0x062 This function returns the capabilities for the unit. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Size in bytes of area to ULONG │ │receive data │ ├─────────────────────────────────────────┤ │Bytes returned (output ULONG │ │parameter) │ ├─────────────────────────────────────────┤ │Return code (output parameter) ULONG │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ Area to receive extended information registration packet (defined in PENEI.H). ═══ Remarks - Category 90h, Function 62h ═══ Values for pquc.rc are the same as for spqusd.rc. ═══ Category 90h, Function 62h ═══ Category 90h, Driver IOCtls - Query Unit Capabilities Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.10. Query Trace Table - Function 63h ═══ ═══ Description - Category 90h, Function 63h ═══ #define PEN_FUNC_QTT 0x063 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. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Number of LONGs in allocated ULONG │ │table │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ PLONG to trace table array. ═══ Remarks - Category 90h, Function 63h ═══ Each entry has a trace code describing the contents of the entry: #define TRACE_MASK 0x0FF000000 /* Isolate trace code from entry. */ #define TRACE_MASK_SUB 0x0F0000000 /* Isolate sub code value. */ #define TRACE_INT 0x0F0000000 /* Interrupt event */ #define TRACE_INT_H 0x0F000 #define TRACE_TICK 0x0C0000000 /* Timer tick; low word is tick count. */ #define TRACE_TICK_H 0x0C000 #define TRACE_ABS 0x010000000 /* Absolute packet sub trace code */ #define TRACE_ABS_E 0x01E000000 /* -- Mouse button event is low word. */ #define TRACE_ABS_EH 0x01E00 #define TRACE_ABS_X 0x011000000 /* -- x-coordinate is low word. */ #define TRACE_ABS_XH 0x01100 #define TRACE_ABS_Y 0x012000000 /* -- y-coordinate is low word. */ #define TRACE_ABS_YH 0x01200 #define TRACE_ABS_Z 0x014000000 /* -- z-coordinate is low word. */ #define TRACE_ABS_ZH 0x01400 #define TRACE_ABS_D 0x015000000 /* -- EI device bits */ #define TRACE_ABS_DH 0x01500 #define TRACE_ABS_C 0x016000000 /* -- EI control word #define TRACE_ABS_CH 0x01600 #define TRACE_ERROR 0x0E0000000 /* Error trace; word is error count. */ #define TRACE_ERROR_H 0x0E000 #define TRACE_DATA 0x000000000 /* Raw data trace; byte is in low byte. */ #define TRACE_DATA_1 0x001000000 /* -- First byte of a packet (optional) */ #define TRACE_DATA_1H 0x00100 #define TRACE_DATA_H 0x00000 /* -- Not first byte */ #define TRACE_SYS 0x020000000 /* System device event (EMI only) */ #define TRACE_SYS_H 0x02000 /* */ #define TRACE_BUTTON 0x0B0000000 /* Button event sub trace code */ #define TRACE_BREL 0x0B0000000 /* Button release mask is low word. */ #define TRACE_BREL_H 0x0B000 #define TRACE_BACT 0x0B1000000 /* Button activation mask is low word. */ #define TRACE_BACT_H 0x0B100 #define TRACE_DISPLAY 0x0D0000000 /* Display event sub trace code */ #define TRACE_DOFF 0x0D0000000 /* Display is turned off. */ #define TRACE_DOFF_H 0x0D000 #define TRACE_DON 0x0D1000000 /* Display is turned on. */ #define TRACE_DON_H 0x0D100 #define TRACE_DD 0x090000000 /* Trace is device dependent. */ /* Low word is data; second byte is index. */ #define TRACE_DD_H 0x09000 ═══ Category 90h, Function 63h ═══ Category 90h, Driver IOCtls - Query Trace Table Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.11. Query Trace Table Size - Function 64h ═══ ═══ Description - Category 90h, Function 64h ═══ #define PEN_FUNC_QTTS 0x064 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. ═══ Parameter Packet Format - Category 90h, Driver IOCtls ═══ None. ═══ Data Packet Format - Category 90h, Driver IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Number of LONG values in table ULONG │ │(Number of bytes/4) │ └─────────────────────────────────────────┘ ═══ Data Structure - Category 90h, Function 64h ═══ typedef struct _D_QTTS { ULONG size; /* Number of LONG values in table (number of bytes/4) */ } DQTTS; ═══ Category 90h, Function 64h ═══ Category 90h, Driver IOCtls - Query Trace Table Size Select an item: Description Parameter Packet Format Data Packet Format Data Structure ═══ 8.12. Category 91h - Locator IOCtls ═══ The following are Category 91h - Locator IOCtls: o Function 50h - Set Locator Offset o Function 51h - Set Locator Pass Rate o Function 52h - Set Locator Sample Rate o Function 60h - Query Locator Variables o Function 61h - Query Locator Raw Coordinates ═══ 8.13. Set Locator Offset - Function 50h ═══ ═══ Description - Category 91h, Function 50h ═══ #define PEN_FUNC_SLO 0x050 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. ═══ Parameter Packet Format - Category 91, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Command ULONG │ ├─────────────────────────────────────────┤ │X offset in digitizer units ULONG │ ├─────────────────────────────────────────┤ │Y offset in digitizer units ULONG │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 91, Locator IOCtls ═══ None. ═══ Remarks - Category 91h, Function 50h ═══ Values for pslo.command: #define PSLO_SET_X 0x01 /* Set x offset */ #define PSLO_SET_Y 0x02 /* Set y offset */ ═══ Category 91h, Function 50h ═══ Category 91, Locator IOCtls - Set Locator Offset Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.14. Set Locator Pass Rate - Function 51h ═══ ═══ Description - Category 91h, Function 51h ═══ #define PEN_FUNC_SLPR 0x051 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. 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 - Category 91h, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Number of ext events for each ULONG │ │OS/2 event │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 91h, Locator IOCtls ═══ None. ═══ Category 91h, Function 51h ═══ Category 91h, Locator IOCtls - Set Locator Pass Rate Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.15. Set Locator Sample Rate - Function 52h ═══ ═══ Description - Category 91h, Function 52h ═══ #define PEN_FUNC_SLSR 0x052 This function is used to change the sample rate. The device must round the rate to the closest value. ═══ Parameter Packet Format - Category 91h, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Sample rate in samples per ULONG │ │second │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 91h, Locator IOCtls ═══ None. ═══ Category 91h, Function 52h ═══ Category 91h, Locator IOCtls - Set Locator Sample Rate Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.16. Query Locator Variables - Function 60h ═══ ═══ Description - Category 91h, Function 60h ═══ #define PEN_FUNC_QLV 0x060 This function returns the Pen for OS/2 locator variables. ═══ Parameter Packet Format - Category 91, Locator IOCtls ═══ ┌─────────────────────────────┐ │Field Length │ ├─────────────────────────────┤ │Requested unit ULONG │ └─────────────────────────────┘ ═══ Data Packet Format - Category 91, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │X offset in digitizer units LONG │ ├─────────────────────────────────────────┤ │Y offset in digitizer units LONG │ ├─────────────────────────────────────────┤ │Pass rate ULONG │ ├─────────────────────────────────────────┤ │Sample rate in samples per ULONG │ │second │ └─────────────────────────────────────────┘ ═══ Data Structure - Category 91h, Function 60h ═══ 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; ═══ Category 91h, Function 60h ═══ Category 91, Locator IOCtls - Query Locator Variables Select an item: Description Parameter Packet Format Data Packet Format Data Structure ═══ 8.17. Query Locator Raw Coordinates - Function 61h ═══ ═══ Description - Category 91h, Function 61h ═══ #define PEN_FUNC_QLRC 0x061 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. ═══ Parameter Packet Format - Category 91h, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Timeout value in milliseconds ULONG │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 91h, Locator IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Return code LONG │ ├─────────────────────────────────────────┤ │X offset in raw digitizer LONG │ │units │ ├─────────────────────────────────────────┤ │Y offset in raw digitizer LONG │ │units │ └─────────────────────────────────────────┘ ═══ Data Structure - Category 91h, Function 61h ═══ typedef struct _D_QLRC { LONG rc; /* Return code */ LONG xRaw; /* x in raw digitizer units */ LONG yRaw; /* y in raw digitizer units */ } DQLRC; ═══ Remarks - Category 91h, Function 61h ═══ Values for dqlrc.rc: #define QLRC_VALID 0 /* Valid coordinates returned. */ #define QLRC_TIMEOUT 1 /* Timed out, coordinates are not valid. */ #define QLRC_BUSY 2 /* Only one thread at a time allowed. */ ═══ Category 91h, Function 61h ═══ Category 91h, Locator IOCtls - Query Locator Raw Coordinates Select an item: Description Parameter Packet Format Data Packet Format Data Structure Remarks ═══ 8.18. Query Default Locator Extents - Function 62h ═══ ═══ Description - Category 91h, Function 62h ═══ #define PEN_FUNC_QDLE 0x062 This function returns the default locator extents. The dqdle.rc value reflects whether the default extents were retrieved. ═══ Parameter Packet Format - Category 91h, Locator IOCtls ═══ ┌─────────────────────────────┐ │Field Length │ ├─────────────────────────────┤ │Requested unit ULONG │ └─────────────────────────────┘ ═══ Data Packet Format - Category 91h, Locator IOCtls ═══ ┌──────────────────────────┐ │Field Length │ ├──────────────────────────┤ │Return code LONG │ ├──────────────────────────┤ │X extent ULONG │ ├──────────────────────────┤ │Y extent ULONG │ └──────────────────────────┘ ═══ Data Structure - Category 91h, Function 62h ═══ typedef struct _D_QDLE { ULONG rc; /* Return code */ ULONG Xdefault; /* x default extent */ ULONG Ydefault; /* y default dextent */ } DQDLE; ═══ Remarks - Category 91h, Function 62h ═══ Values for dqdle.rc: #define QDLE_OK 0 /* The default extents were valid. */ #define QDLE_FAIL 1 /* The default extents were not valid. */ ═══ Category 91h, Function 62h ═══ Category 91h, Locator IOCtls - Query Default Locator Extents Select an item: Description Parameter Packet Format Data Packet Format Data Structure Remarks ═══ 8.19. Category 92h - Button IOCtls ═══ The following are Category 92h - Button IOCtls: o Function 50h - Set Button Assignment o Function 60h - Query Button Assignment ═══ 8.20. Set Button Assignment - Function 50h ═══ ═══ Description - Category 92h, Function 50h ═══ #define PEN_FUNC_SBA 0x050 This function sets the assignment for a button. ═══ Parameter Packet Format - Category 92h, Button IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Index of button (0 to 15) ULONG │ ├─────────────────────────────────────────┤ │Action to perform ULONG │ ├─────────────────────────────────────────┤ │Hot-key value for hot-key ULONG │ │assignment │ ├─────────────────────────────────────────┤ │Mouse button selection mask ULONG │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 92h, Button IOCtls ═══ None. ═══ Remarks - Category 92h, Function 50h ═══ Values for psba.action: Note: Values must match order of capability fields in DCAP struct. #define NOBUTTONACTION 0 /* Null - do nothing (the default). */ #define SENDHOTKEY 1 /* Send hot key; value in PSBA.hotkey. */ #define SHIFTBUTTON 2 /* Set shift for button using mouseButtonMask. */ #define APPLBUTTON 3 /* Assign button for application use. */ #define AUGMENTATIONBUTTON 4 /* Assign button for key augmentation. */ #define GESTUREMODE 5 /* Assign button for gesture mode. */ Values for psba.value for action = SHIFTBUTTON: #define MOUSEBUTTON1 0x04 /* Mouse button 1 */ #define MOUSEBUTTON2 0x10 /* Mouse button 2 */ #define MOUSEBUTTON3 0x40 /* Mouse button 3 */ Values for psba.value for action = SENDHOTKEY: #define HOTKEY_CNTRL_ESC 1 /* Do a Ctrl+Esc. */ #define HOTKEY_ALT_ESC 2 /* Do an Alt+Esc. */ ═══ Category 92h, Function 50h ═══ Category 92h, Button IOCtls - Set Button Assignment Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.21. Query Button Assignment - Function 60h ═══ ═══ Description - Category 92h, Function 60h ═══ #define PEN_FUNC_QBA 0x060 This function returns the assignment of a button. ═══ Parameter Packet Format - Category 92h, Button IOCtls ═══ ┌────────────────────────────────────────┐ │Field Length │ ├────────────────────────────────────────┤ │Requested unit ULONG │ ├────────────────────────────────────────┤ │Index of button (0 to 15) ULONG │ └────────────────────────────────────────┘ ═══ Data Packet Format - Category 92h, Button IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Action to perform ULONG │ ├─────────────────────────────────────────┤ │Hot-key value for hot-key ULONG │ │assignment or mouse button │ │selection mask │ └─────────────────────────────────────────┘ ═══ Data Structure - Category 92h, Function 60h ═══ typedef struct _D_QBA { ULONG action; /* Action to perform */ ULONG value; /* Hot-key value for hot-key assignment or mouse button selection mask */ } DQBA; ═══ Category 92h, Function 60h ═══ Category 92h, Button IOCtls - Query Button Assignment Select an item: Description Parameter Packet Format Data Packet Format Data Structure ═══ 8.22. Category 93h - Display IOCtls ═══ The following are Category 93h - Display IOCtls: o Function 50h - Set Display State o Function 51h - Set Display Inactivity Period o Function 60h - Query Display State ═══ 8.23. Set Display State - Function 50h ═══ ═══ Description - Category 93h, Function 50h ═══ #define PEN_FUNC_SDS 0x050 /* Set display state. */ #define TURNBACKLIGHTON 1 /* Value to turn backlight on */ #define TURNBACKLIGHTOFF 0 /* Value to turn backlight off */ 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. ═══ Parameter Packet Format - Category 93h, Display IOCtls ═══ ┌────────────────────────────────────────┐ │Field Length │ ├────────────────────────────────────────┤ │Requested unit ULONG │ ├────────────────────────────────────────┤ │Command to turn on or off ULONG │ └────────────────────────────────────────┘ ═══ Data Packet Format - Category 93h, Display IOCtls ═══ None. ═══ Category 93h, Function 50h ═══ Category 93h, Display IOCtls - Set Display State Select an item: Description Parameter Packet Format Data Packet Format ═══ 8.24. Set Display Inactivity Period - Function 51h ═══ ═══ Description - Category 93h, Function 51h ═══ #define PEN_FUNC_SDIP 0x051 This function controls how the driver handles turning the display backlight on and off automatically. The following options can be set: 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. 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. ═══ Parameter Packet Format - Category 93h, Display IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │Requested unit ULONG │ ├─────────────────────────────────────────┤ │Command to turn enable and ULONG │ │disable │ ├─────────────────────────────────────────┤ │Inactivity period in seconds ULONG │ └─────────────────────────────────────────┘ ═══ Data Packet Format - Category 93h, Display IOCtls ═══ None. ═══ Remarks - Category 93h, Function 51h ═══ PSDIP.command values: #define SDIP_PERIOD 0x01 /* Change period value */ #define SDIP_EN_AUTO 0x02 /* Enable automatic inactivity period */ #define SDIP_DI_AUTO 0x04 /* Disable automatic inactivity period */ #define SDIP_EN_OPAQUE 0x08 /* Process events while backlight is off */ #define SDIP_DI_OPAQUE 0x10 /* Ignore events while backlight is off */ #define SDIP_EN_SUPPRESS 0x20 /* Suppress after auto turn on */ #define SDIP_DI_SUPPRESS 0x40 /* Do not suppress after auto turn on */ ═══ Category 93h, Function 51h ═══ Category 93h, Display IOCtls - Set Display Inactivity Period Select an item: Description Parameter Packet Format Data Packet Format Remarks ═══ 8.25. Query Display State - Function 60h ═══ ═══ Description - Category 93h, Function 60h ═══ #define PEN_FUNC_QDS 0x060 This function returns whether the automatic inactivity period monitor is enabled or disabled, and if enabled, the time remaining in the inactivity period. ═══ Parameter Packet Format - Category 93h, Display IOCtls ═══ ┌─────────────────────────────┐ │Field Length │ ├─────────────────────────────┤ │Requested unit ULONG │ └─────────────────────────────┘ ═══ Data Packet Format - Category 93h, Display IOCtls ═══ ┌─────────────────────────────────────────┐ │Field Length │ ├─────────────────────────────────────────┤ │State of backlight ULONG │ ├─────────────────────────────────────────┤ │Automatic options ULONG │ ├─────────────────────────────────────────┤ │Inactivity period in seconds ULONG │ └─────────────────────────────────────────┘ ═══ Data Structure - Category 93h, Function 60h ═══ typedef struct _D_QDS { ULONG state; /* State of backlight */ ULONG automatic; /* Automatic options */ ULONG period; /* Inactivity period in seconds */ } DQDS; ═══ Remarks - Category 93h, Function 60h ═══ DQDS.state uses same values as PSDIP.state. DQDS.automatic uses same values as PSDIP.command. ═══ Category 93h, Function 60h ═══ Category 93h, Display IOCtls - Query Display State Select an item: Description Parameter Packet Format Data Packet Format Data Structure Remarks ═══ 8.26. 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: ────────────────────────────────────────────────────────────────────────── #define PEN_DDS_LEV_MAJOR 0 /* Level of this specification */ #define PEN_DDS_LEV_MINOR 3 /* Level of this specification */ ────────────────────────────────────────────────────────────────────────── DevHlp_RegisterDeviceClass values: ────────────────────────────────────────────────────────────────────────── #define DEVCLASS_INPUT 2 /* Device class for RegisterDeviceClass */ ────────────────────────────────────────────────────────────────────────── Defines for DCFlags: ────────────────────────────────────────────────────────────────────────── #define REG_EXT_IF 0x0001 /* Supports extended interface */ #define REG_AUX 0x8000 /* Keyboard AUX port used */ ────────────────────────────────────────────────────────────────────────── ═══ 8.27. 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: ────────────────────────────────────────────────────────────────────────── #define QUERY_CAPABILITIES 1 /* Request unit capabilities 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 */ #define QUERY_DEV_CONFIG 2 /* Query optional device configuration bl = unit es:di = target DevData packet address */ #define START_LOGICAL_DEVICE 3 /* Start logical device 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 */ ────────────────────────────────────────────────────────────────────────── These functions invoke global calls to the driver: ────────────────────────────────────────────────────────────────────────── #define READ_ENABLE 6 /* Enable reporting of events pass cx:dx style capabilities to driver return cx:dx style request to services */ #define READ_DISABLE 7 /* Disable reporting of events */ #define ENABLE_DEVICE 8 /* Enable the device to interrupt */ #define DISABLE_DEVICE 9 /* Disable the device from interrupting */ #define ACTIVITY_CALLBACK 10 /* System activity callback (called as result of REQUEST_CALLBACK) */ #define VIDEO_MODE_CHANGE 11 /* Video mode change cl == -1 Start of change 0 End of change ch == -1 Packet is valid 0 Packet is invalid es:di = VINFO packet */ ────────────────────────────────────────────────────────────────────────── Style capabilities for READ_ENABLE (See 6 above): CX register is reserved, must be 0. Style capabilities for READ_ENABLE: DX register: ────────────────────────────────────────────────────────────────────────── #define STYLE_NOTIFY_VMCHANGE 0x0001 /* Report VM_CHANGE on = DON'T report, reset to receive events */ ────────────────────────────────────────────────────────────────────────── Error Codes: ────────────────────────────────────────────────────────────────────────── #define DRV_ERR_GEN_ERROR 1 /* General error */ #define DRV_ERR_NOT_FOUND 2 /* Unit number not found */ #define DRV_ERR_BUFF_TRUNC 3 /* Registration packet truncated, buffer small */ #define DRV_ERR_LEVEL 4 /* Level mismatch */ #define DRV_ERR_NOT_ALLOWED 5 /* Request not allowed at this time */ #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: ────────────────────────────────────────────────────────────────────────── #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; ────────────────────────────────────────────────────────────────────────── ═══ 8.28. 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: ────────────────────────────────────────────────────────────────────────── #define REGISTER_DEVICE 1 /* Register device es:di = Capabilities packet */ #define REPORT_EVENT 2 /* Report event es:di = Event packet */ #define UPDATE_CAPS 3 /* Update registration packet es:di = Capabilities packet */ #define QUERY_ACTIVITY 4 /* Query user input activity Returns dx = low word count cx = high word count edx = dword count */ #define REQUEST_CALLBACK 5 /* Request callback for system activity cl = Driver device ID */ #define CANCEL_CALLBACK 6 /* Cancel callback for system activity cl = Driver device ID */ #define SUPPRESS_STROKE 7 /* Suppress stroke cl = Driver device ID */ #define DISABLE_SUPPORT 8 /* Disable driver cl = Driver device ID */ ────────────────────────────────────────────────────────────────────────── ═══ 8.29. Extended Information Structures ═══ ────────────────────────────────────────────────────────────────────────── #define PEN_EI_LEV_MAJOR 0 /* Level of this specification */ #define PEN_EI_LEV_MINOR 6 /* Level of this specification */ ────────────────────────────────────────────────────────────────────────── Defines for all dev_type: ────────────────────────────────────────────────────────────────────────── #define DT_DRIVER 0x00 /* Index to access driver */ #define DT_CONTROL 0x01 /* Control (not used by pen device driver) */ #define DT_SYSTEM 0x02 /* System (not used by pen device driver) */ #define DT_LOCATOR 0x03 /* Locator */ #define DT_BUTTON 0x04 /* Button */ #define DT_DISPLAY 0x05 /* Display */ ────────────────────────────────────────────────────────────────────────── ═══ 8.30. 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_caps is defined by lev.cev.devicebits, bev.cev.devicebits, and dev.cev.devicebits. Defines for word boundry flags: ────────────────────────────────────────────────────────────────────────── #define CCAP_DEFAULTDATA 0x00 /* Use the data from the device driver */ #define DT_CONTROL 0x01 /* Use the data stored in OS2.INI */ ────────────────────────────────────────────────────────────────────────── ═══ 8.31. Driver-Specific Capabilities Packet ═══ The unit 0 device capabilities describe the entire driver and are used to: o Verify the expected levels of the driver match o Determine the number of logical devices in the driver ────────────────────────────────────────────────────────────────────────── 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 */ } DDCAP; ────────────────────────────────────────────────────────────────────────── ═══ 8.32. Locator-Specific Capabilities Packet ═══ Defines for LCAP.type: ────────────────────────────────────────────────────────────────────────── #define LOCTYPE_MOUSE 0x0001 /* Stock device */ #define LOCTYPE_PEN 0x0002 /* Pen */ #define LOCTYPE_FINGER 0x0004 /* Finger */ #define LOCTYPE_OTHER 0x0008 /* Other */ #define LOCTYPE_ABSOLUTE 0x0010 /* Absolute */ #define LOCTYPE_RELATIVE 0x0020 /* Relative */ ────────────────────────────────────────────────────────────────────────── Defines for LCAP.pen_type: ────────────────────────────────────────────────────────────────────────── #define PENCAP_TETHERED 0x0001 /* 1 - Tethered, 0 - Untethered */ #define PENCAP_PROXIMITY 0x0002 /* Generates enter and exit events */ #define PENCAP_TILT 0x0004 /* Stylus tilt angle reported */ #define PENCAP_ROTATE 0x0008 /* Stylus rotation reported */ #define PENCAP_OEMDATA 0x0010 /* OEM data reported */ #define PENCAP_TIMESTAMP 0x0020 /* dev_timestamp reported */ #define PENCAP_ZPRESSURE 0x0040 /* z-axis represents pressure */ #define PENCAP_ZHEIGHT 0x0080 /* z-axis represents height */ #define PENCAP_PIN 0x0100 /* 1=Personal Identification Number */ #define PENCAP_ERASER 0x0200 /* 1=device used as an eraser */ #define PENCAP_DISPLAY 0x0400 /* 1=integrated display */ ────────────────────────────────────────────────────────────────────────── Defines for LCAP.std_res: ────────────────────────────────────────────────────────────────────────── #define STD_RESOLUTION 1000 /* Standard resolution is 1000 points per inch. */ ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── 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. ═══ 8.33. 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): ────────────────────────────────────────────────────────────────────────── #define CAP_NOBUTTONACTION 0x0001 /* Null; do nothing (the default) */ #define CAP_SENDHOTKEY 0x0002 /* Hot-key support */ #define CAP_SHIFTBUTTON 0x0004 /* Shift button support */ #define CAP_APPLBUTTON 0x0008 /* Button for application use */ #define CAP_AUGMENTATIONBUTTON 0x0010 /* Button for key augmentation */ #define CAP_GESMODEBUTTON 0x0020 /* Button for gesture mode */ #define CAP_DEFAULT_BARREL CAP_NOBUTTONACTION|CAP_SHIFTBUTTON|CAP_GESMODEBUTTON #define CAP_DEFAULT_NBARREL CAP_DEFAULT_BARREL| CAP_SENDHOTKEY|CAP_APPLBUTTON|CAP_AUGMENTATIONBUTTON ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── 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). ═══ 8.34. Display-Specific Capabilities Packet ═══ Defines for DCAP.type: ────────────────────────────────────────────────────────────────────────── #define DISPTYPE_LCD 0x0001 /* 1 - LCD, 0 - not LCD */ #define DISPTYPE_CRT 0x0002 /* 1 - CRT, 0 - not CRT */ #define DISPTYPE_BLANKING 0x0004 /* Display performs screen blanking. */ #define DISPTYPE_COLOR 0x0008 /* 1 - Color, 0 - Monochrome */ #define DISPTYPE_ATTACHED 0x0010 /* 1 - Attached, 0 - Portable */ #define DISPTYPE_NO_KBD 0x0020 /* No Keyboard Attached */ #define DISPTYPE_BATTERY 0x0040 /* 1 - Battery, 0 - AC power */ #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; ────────────────────────────────────────────────────────────────────────── ═══ 8.35. 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; ────────────────────────────────────────────────────────────────────────── ═══ 8.36. Locator-Specific Event Packet ═══ Defines for LEV.cntrl: ────────────────────────────────────────────────────────────────────────── #define LOC_PASS_ON 0x0001 /* If set, event is to be passed to PM. (used by pass rate filter) */ #define LOC_ARBITRATED_OUT 0x0002 /* For use by arbitration (treat as reserved) */ #define LOC_SUPPRESSED 0x0004 /* Suppressed contact due to backlight auto on */ #define LOC_BKLT_OFF 0x0008 /* Suppressed contact due to backlight off */ #define LOC_REL 0x0010 /* dev_x and dev_y are relative */ #define LOC_ABS 0x0020 /* dev_x and dev_y are absolute */ #define LOC_FAKE 0x0040 /* Device coordinates are valid, but fake. */ #define LOC_INVALID 0x0080 /* Coordinates are not valid. */ #define LOC_CONTACT 0x0100 /* Indicates the locator is in contact. */ #define LOC_PROX 0x0200 /* Indicates the locator is in proximity. */ #define LOC_GSTMODE 0x0400 /* Force gesture mode */ ────────────────────────────────────────────────────────────────────────── Defines for LEV.cev.devicebits (low-order byte = mouse event): ────────────────────────────────────────────────────────────────────────── #define EV_NONE 0x00 /* No buttons, no movement */ #define EV_MOVE 0x01 /* Movement only, no buttons */ #define EV_BUTTON1_MOVE 0x02 /* Movement and button 1 down */ #define EV_BUTTON1 0x04 /* Button 1 down only, no movement */ #define EV_BUTTON2_MOVE 0x08 /* Movement and button 2 down */ #define EV_BUTTON2 0x10 /* Button 2 down only, no movement */ #define EV_BUTTON3_MOVE 0x20 /* Movement and button 3 down */ #define EV_BUTTON3 0x40 /* Button 3 down only, no movement */ #define EV_ANY_STAT_BUTTON EV_BUTTON1 | EV_BUTTON2 | EV_BUTTON3 #define EV_ANY_MOVE_BUTTON EV_BUTTON1_MOVE | EV_BUTTON2_MOVE | EV_BUTTON3_MOVE #define EV_ANY_MOVE EV_MOVE | EV_ANY_MOVE_BUTTON #define EV_ANY_BUTTON EV_ANY_STAT_BUTTON | EV_ANY_MOVE_BUTTON #define EV_STD_MOUSE EV_ANY_STAT_BUTTON | EV_ANY_MOVE ────────────────────────────────────────────────────────────────────────── (high-order byte = mouse events that changed): ────────────────────────────────────────────────────────────────────────── #define EV_BUTTON1_CHANGED 0x0400 /* Button 1 changed */ #define EV_BUTTON2_CHANGED 0x1000 /* Button 2 changed */ #define EV_BUTTON3_CHANGED 0x4000 /* Button 3 changed */ #define EV_BUTTON_CHG EV_BUTTON1_CHANGED|EV_BUTTON2_CHANGED|EV_BUTTON3_CHANGED ────────────────────────────────────────────────────────────────────────── Stroke events: ────────────────────────────────────────────────────────────────────────── #define EV_EXIT_PROX 0x0080 /* Exit proximity */ #define EV_ENTER_PROX 0x8000 /* Enter proximity */ #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; ────────────────────────────────────────────────────────────────────────── ═══ 8.37. Button-Specific Event Packet ═══ Defines for BEV.cev.devicebits: ────────────────────────────────────────────────────────────────────────── #define BEV_BUTTON_CHANGE 0x01 /* Button change event */ ────────────────────────────────────────────────────────────────────────── Defines for BEV.cntrl: ────────────────────────────────────────────────────────────────────────── #define BEV_SUPPRESSED LOC_SUPPRESSED /* Suppressed contact due to bklt auto-on */ #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; ────────────────────────────────────────────────────────────────────────── ═══ 8.38. Display-Specific Event Packet ═══ Defines for DEV.cev.devicebits: ────────────────────────────────────────────────────────────────────────── #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; ────────────────────────────────────────────────────────────────────────── ═══ 9. Pen for OS/2 Component of IBM Developer Connection Device Driver Kit for OS/2 ═══ This chapter 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. ═══ 9.1. Subdirectory Structure ═══ The subdirectory structure is created when you install the 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. Installation Control Files 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. ═══ 9.2. 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 proximity event. 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. ═══ 9.3. 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: 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. 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. 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 Developers Toolkit are required to build this program. ═══ 9.4. 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 prologue comments. ═══ 9.4.1. 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: o 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. o 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. o 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. ═══ 9.4.2. 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 │ │ │ └──────────────────┘ └────────┘ │ └─────────────────────────────────────────────┘ o 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 subcomponents 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. o 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. o 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 prologue of the assembly file (*ASM) for that subcomponent. ═══ 9.4.3. 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. ═══ 10. Operational Considerations ═══ This appendix provides operational considerations pertaining to the performance of a pen device driver. ═══ 10.1. 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 drivers 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. ═══ 10.2. 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. ═══ 10.3. Stand-Alone Operation ═══ Pen device drivers created with the Pen for OS/2 Developers 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 drivers 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 drivers 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. ═══ 10.4. 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. ═══ 10.5. 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. ═══ 10.6. 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 Pen Device Driver IDC Interface. 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). ═══ 11. 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. ═══ 11.1. Introduction ═══ This glossary includes terms and definitions from: o 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. o 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. ═══ 11.2. Glossary Listing ═══ Select a starting letter of glossary terms: A N B O C P D Q E R F S G T H U I V J W K X L Y M Z ═══ Glossary - A ═══ 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. ═══ Glossary - B ═══ 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. ═══ Glossary - C ═══ 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. ═══ Glossary - D ═══ 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. ═══ Glossary - E ═══ 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. ═══ Glossary - F ═══ 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. ═══ Glossary - G ═══ 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. ═══ Glossary - H ═══ 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. ═══ Glossary - I ═══ 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. ═══ Glossary - J ═══ J joy stick - In computer graphics, a lever that can pivot in all directions and that is used as a locator device. (T) ═══ Glossary - K ═══ K kernel - The part of an operating system that performs basic functions, such as allocating hardware resources. ═══ Glossary - L ═══ 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. ═══ Glossary - M ═══ 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. ═══ Glossary - N ═══ N There are no glossary terms for this initial letter. ═══ Glossary - O ═══ 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. ═══ Glossary - P ═══ 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. ═══ Glossary - Q ═══ Q There are no glossary terms for this initial letter. ═══ Glossary - R ═══ 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. ═══ Glossary - S ═══ 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. ═══ Glossary - T ═══ 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 n timer 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. ═══ Glossary - U ═══ 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. ═══ Glossary - V ═══ V VGA - Video graphics array. ═══ Glossary - W ═══ 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. ═══ Glossary - X ═══ X There are no glossary terms for this initial letter. ═══ Glossary - Y ═══ Y There are no glossary terms for this initial letter. ═══ Glossary - Z ═══ Z There are no glossary terms for this initial letter. ═══ IBM Trademark ═══ Trademark of the IBM Corporation. ═══ Trademarks ═══ Trademark of the Microsoft Corporation.