═══ 1. Using the Online Reference ═══ Before you begin to use this reference, it would be helpful to understand how you can: o Expand the Contents to see all available topics o Obtain additional information for a highlighted word or phrase o Use action bar choices. How To Use the Contents When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available. To expand the Contents if you are using a mouse, select the plus sign (+). If you are using a keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus key (+). To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press Enter). How To Obtain Additional Information After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are highlighted in green letters, or in white letters on a black background. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information will appear in a window. How To Use Action Bar Choices Several choices are available for managing information presented in the Pen for OS/2 Programming Guide and Reference. There are three pull-down menus on the action bar: the Services menu, the Options menu, and the Help menu. The actions that are selectable from the Services menu operate on the active window currently displayed on the screen. These actions include the following: Bookmark Sets a place holder so you can retrieve information of interest to you. Search Finds occurrences of a word or phrase in the current topic, selected topics, or all topics. Print Prints one or more topics. You can also print a set of topics by first marking the topics in the Contents list. Copy Copies a topic you are viewing to a file you can edit. Options Changes the way the Contents is displayed. ═══ 2. About This Book ═══ The Pen for OS/2 Programming Guide and Reference is a guide and reference for developing applications that make use of the Pen for OS/2 system extension. ═══ 2.1. Who Should Use This Book ═══ This book is for developers who are creating Pen for OS/2 program applications, or those developers who want their existing applications to make use of Pen for OS/2 features. ═══ 2.2. How This Book Is Organized ═══ This book is organized in two parts: o A Pen for OS/2 programming guide o A Pen for OS/2 application programming interface (API) reference Part 1: "Pen for OS/2 Programming Guide" provides an overview of Pen for OS/2 and describes how to create pen-aware applications. It also provides information about how pen-unaware applications can be used with Pen for OS/2. Part 1 contains the following chapters: o "Pen for OS/2 System Extension Overview" introduces Pen for OS/2, describes its components, and discusses the program from an application developer's point of view. "Pen for OS/2 System Extension Architecture" describes how Pen for OS/2 is structured. This chapter also includes an introduction to programming with Pen for OS/2 and provides a discussion of design considerations. o "Using Ink" describes the different ways in which input strokes can be inked. It explains how you can use notification messages to do your own inking in an application, or let Pen for OS/2 do the inking for you. o "Using Gestures" explains what gestures are and how they can be used with Pen for OS/2. This chapter lists and describes the three types of predefined Pen for OS/2 gestures: core gestures, noncore gestures, and letter gestures. o "Using the Sketch Control" describes the sketch input control. This control can be included in any Presentation Manager (PM) application to let users input strokes and then have the strokes copied to the clipboard or saved as a bit map. You can control the pointer shape, ink color, and ink width. o "Using the Handwriting Entry Control" describes the handwriting control that lets users input handwritten text. This control recognizes and converts handwritten text to characters and can be included in any PM application. The chapter explains how a handwriting input control can be used in a client window or as part of a dialog template. o "Using Virtual Keyboards and the Pop-Up Keyboard Tool" describes the Pen for OS/2 keyboards that can be displayed in an application. Keyboards let users create keystokes using a pointing device. The chapter also explains how to select and control keyboards. o "Using System Variables" explains how to use system variables to query system information and customize the operation of your system. o "Using Device Drivers" explains how to use Pen for OS/2 device drivers to control and manage pen hardware. Part 2: "Pen for OS/2 Programming Reference" lists API functions, messages, and data structures. Part 2 contains the following chapters: o "Pen for OS/2 Writing Subsystem API" lists the syntax, parameters, return codes, and remarks for the Pen for OS/2 API. o "Pen for OS/2 Writing Subsystem Messages" lists and describes the Pen for OS/2 writing subsystem messages. o "Pen for OS/2 Writing Subsystem Data Structures" lists the Pen for OS/2 writing subsystem data structures. o "Recognition Event Delivery Subsystem API" lists the syntax, parameters, return codes, and remarks for the Recognition Event Delivery Subsystem APIs. o "Recognition Event Delivery Subsystem Messages" lists and describes the Recognition Event Delivery Subsystem messages. o "Recognition Event Delivery Subsystem Data Structure" lists the Recognition Event Delivery Subsystem data structures. o "Sketch Control Programming Interface" lists the sketch control style bits, control messages, and notification messages. o "Handwriting Input Control Programming Interface" lists and describes the handwriting input control style bits, notification messages, and display colors. o "Virtual Keyboard Playback API" lists and describes the Pop-Up Keyboard APIs. o "Pen for OS/2 Setup Objects" lists and describes the Workplace Shell that make up the Pen for OS/2 Setup Objects. o "Appendix A. Pen for OS/2 Libraries and Header Files" describes the Pen for OS/2 libraries and header files. ═══ 2.3. Related Publications ═══ The Pen for OS/2 library includes the following related publications: o Pen for OS/2 Developer's Toolkit: Getting Started, 71G2123 o Pen for OS/2 Device Driver Reference, 71G2125 o Pen for OS/2 User's Guide, 71G2122 The following books contain information you might need to reference when using this book: o Developer's Toolkit for OS/2, Version 2.1, 61G1416 o OS/2 System Object Model Guide and Reference, 10G6309 ═══ 3. Part 1: Pen for OS/2 Programming Guide ═══ ═══ 4. Pen for OS/2 System Extension Overview ═══ The Pen for OS/2 system extension is a series of software extensions to the IBM OS/2 2.1 operating system and the Presentation Manager (PM) component that provide for pen-based input and recognition. Pen for OS/2 supports a variety of computers and peripherals that are designed for use with a pen as a primary input device. Pen for OS/2 encourages the design and development of new pen-oriented application programs, provides a means for enhancing existing applications with new features, and allows for the continued use of the existing OS/2 operating system PM programs without change. ═══ 4.1. Introduction ═══ Pen for OS/2 provides support for the pen as a new input device for the OS/2 operating system in desktop and portable environments. There are many applications for the pen in the desktop environment, such as interactive teleconferencing, the annotation of electronic mail or scanned forms, quick notes taken and appended to a customer file by a service representative, and even forms fill-in by customers sitting at a sales desk. Presentations can now include hand-drawn sketches previously impractical with the mouse, and documents (letters, credit card slips, and so forth) can now be signed online and stored without scanning. The pen is a natural writing and pointing device. By replacing the mouse for navigating the Workplace Shell and all application windows, the result is a better user interface for OS/2 PM on the desktop. Pen for OS/2 supports all existing, unmodified applications through pen-based pointing and selection techniques and hand-drawn gesture commands to invoke actions. In essence, the pen looks like a mouse to most applications. However, the user has access to a new series of tools to manipulate those "pen-unaware" applications. The APIs described in this book allow you to access the new capabilities of these pen-based computers. These include the smooth tracking of a user's handwriting for annotating text or images, and the use of special pen features, such as pressure or height above the screen, or buttons on the pen barrel, to enhance user-interface techniques. Pen digitizers are generally packaged under flat LCD displays to allow the easy placement of the writing surface on the desk or on a person's lap. You will also have access to new display capabilities, such as auxiliary buttons on the bezel and control of the LCD's backlight. To capture and recognize printed characters, you will be able to include handwriting fields in dialogs and forms. Pen for OS/2 provides pen-based facilities for writing new Presentation Manager applications that take advantage of the pen/ink on paper metaphor. However, although the emphasis is on Presentation Manager applications, a level of compatibility is provided for unmodified applications running in the full-screen sessions that OS/2 provides. The full-screen OS/2 and DOS sessions are supported with mouse emulation and any other features that the device support provides, such as hot key buttons on the bezel or mouse button 2 emulation on the pen's side button. However, gesture recognition, handwriting recognition, and the ink display is not provided for full-screen programs. The Pen for OS/2 API is not available to full-screen sessions. ═══ 4.2. Developer's Perspective ═══ Pen for OS/2 is designed to provide multiple approaches for pen-based functions. Pen for OS/2 primarily provides pen computing functions for the Presentation Manager environment. However, compatibility support is provided for OS/2, DOS, and Windows programs when they are running in the PM environment. ═══ 4.2.1. Pen for OS/2 Extensions to the OS/2 Toolkit ═══ Pen for OS/2 extensions to the OS/2 Toolkit provides a toolkit for software developers. It extends the same programming environment already provided by the OS/2 operating system and PM component, so the programming concepts in Pen for OS/2 will not be new to developers. This enables developers to easily add Pen for OS/2 features to their programs. Pen for OS/2 runs on a variety of pen computers made by different manufacturers, and because Pen for OS/2 provides a device-independent interface to programs, all developers are encouraged to include Pen for OS/2 features. The Pen for OS/2 extensions to the OS/2 Toolkit provides files additional to those received with the basic OS/2 2.1 Toolkit. The OS/2 2.1 Toolkit is a prerequisite, and the same compilers and debuggers used to develop OS/2 2.1 programs can be used to develop pen programs. The Pen for OS/2 extensions to the OS/2 Toolkit contains all the header and import library files necessary to write pen-aware programs and gesture-mapping tools. The runtime components of Pen for OS/2 contain the DLLs necessary for executing these programs. ═══ 4.2.2. Categories of Pen Applications ═══ To aid in the description of pen computing, it is useful to define the different categories of pen applications. They fall into two categories: pen-unaware and pen-aware. o Pen-unaware applications are those that are written to use a keyboard and mouse; this category includes all current PM and Windows programs. Pen for OS/2 supports these unmodified applications through a Compatibility Layer, which assigns pen usage to messages that these applications are already programmed to expect. o Pen-aware applications are those that have been modified through procedures from the Pen for OS/2 extensions to the OS/2 Toolkit. The degree to which a program is pen-aware spans a broad range. It usually depends on the level of integration of pen concepts by the developer of the program. The degree of pen-awareness has a direct effect on: - The user interface, especially direct manipulation - The level of pen-specific functionality - The level of effort to integrate Pen for OS/2 facilities The following are the high and low ends of the range of pen-awareness: o At the low end of the range, applications make entry-level usage of the Pen for OS/2 extensions to the OS/2 Toolkit. Capabilities such as detecting which gesture is drawn or detecting that the pen came near the screen are examples of functions in this category. o At the high end of the range, programs are designed with the pen in mind. Developers of these programs use many features of the Pen for OS/2 extensions to the OS/2 Toolkit and to a large degree control processing and interpretation of the pen input. These programs also can assist the system during handwriting recognition by specifying the context of the writing and constantly updating this information based on what the user is doing at any time. It is not necessary for programs to register themselves with the system as "pen-aware". The amount of pen-awareness is up to the developer; the system will detect the level of awareness through the responses to several new messages and through the use of new function calls provided with Pen for OS/2. ═══ 4.2.3. Approaches to Writing Pen for OS/2 Applications ═══ There are three approaches which a developer can take to exploit the Pen for OS/2 system extension. The approaches are: o Writing gesture-mapping tools o Modifying existing application code o Writing new pen-specific applications The first approach, writing gesture-mapping tools, requires the least effort. The recommended gesture-mapping tools are included as part of the installation utility. These tools convert gesture commands to actions understood by existing programs. This approach requires no change to the application code. The second approach is to identify specific areas of your existing application which would benefit from integrating some of the Pen for OS/2 tools at points within the program code. An example is adding the ability to attach a freehand note to a spreadsheet cell. In this approach, most of the application's code remains unchanged. The third approach, which requires the most effort, is writing pen applications from scratch. Generally, these applications include some of the following traits: o Highly interactive freehand drawing which would be "unnatural" with a mouse o Application participation in the recognition process o Dynamic changes in gesture- and character-recognition modes ═══ 4.2.4. Application Considerations ═══ The following are considerations in using Pen for OS/2 applications: o Although the emphasis is on pen interfaces, many of the benefits of the pen can also be achieved through the use of finger touch on devices. Application developers can distinguish between pen and finger when input devices support such a distinction. o The primary hardware components of pen computing are the display and the digitizer. Because digitizer hardware is evolving, Pen for OS/2 is flexible in accommodating a wide range of features. Some manufacturers allow for finger as well as pen input, for example. o The pen allows the keyboard to be eliminated in many applications and therefore reduces the physical dimensions and weight of the system. The pen can scale down to smaller writing surfaces better than the keyboard can. o The most innovative feature of pen computing is the ability to recognize handwriting. Pen for OS/2 has integrated features built around its ability to interpret the "ink" from the pen as commands and data. o Pen for OS/2 allows a user to more easily annotate spreadsheets and documents, because a pen is a more natural tool to make freehand drawings, legible writing, and signatures. ═══ 5. Pen for OS/2 System Extension Architecture ═══ This chapter highlights the primary hardware components of pen computing and its 2-tier architecture. It describes how the Pen for OS/2 system extension is structured in terms of its device-independent interface and writing subsystem. Also included is a description of how Pen for OS/2 accommodates existing pen-unaware programs. Some design considerations are discussed, and the developer is introduced to APIs in the Pen for OS/2 extensions to the OS/2 Toolkit. ═══ 5.1. System Structure ═══ The following block diagram shows the various Pen for OS/2 subsystem components and how they relate to each other. ┌──────────────────┐ │ │ Pen │ Device Drivers │ Mouse │ │ Keyboard └────────┬─────────┘ Events  ┌──────────────────┐ ┌───────────────┐ │ System Queues │ │ │ └────────┬─────────┘ │ OS/2 PM │ ┌────────┼───────────┘ │ └────────┼───────────────────────────┘ │ ┌──────────────────┐ │ │ Handwriting │ │ ┌─────────────────────────────────│ Recognition │ │ │ │ │   └──────────────────┘ ┌──────────────────┐ ┌──────────────────┐ │ Pen Extensions │ │ Compatibility │ ┌──────────────────┐ │ and New ├───│ Layer │───│ Gesture │ │ Window Controls │ │ │ │ Recognition │ └────────┬─────────┘ └──────┬─────┬─────┘ │ │ │ │ │ └──────────────────┘ │ │ │ │ │ │ ┌──────────────────┐ │ │ │ │ Recognition │ │ │ └───────│ Event │ │ │ │ Delivery │ │ │ └────┬─────────────┘ │ │ ┌────┴───┐ ┌───────┐ │ │ │ │ │ │ │ │ │Profiles│ │ Tools │ │ │ │ │ │ │ │ │ └────────┘ └───┬───┘   │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ Pen-Aware ├┐ │ Unaware │────────────────┘ │ Applications ││ │ Applications │ └─┬────────────────┘│ └──────────────────┘ │Mini-Applications│ └─────────────────┘ ┌─────────────────────┐ ┌─────────┐ │ Pen for OS/2 │ │ Setup │ │ Installation │ │ Objects │ └─────────────────────┘ └─────────┘ System Structure ═══ 5.2. Device-Independent Interface ═══ Pen for OS/2 has a device-independent interface that allows Pen for OS/2 to provide a consistent programming model to developers. Pen for OS/2 achieves independence through the definition of an "input model", which is the basis for the programming interfaces that developers will use. This model isolates the programmer from the differences between the various manufacturers and allows extensions to the model. This allows original equipment manufacturers (OEMs) to deliver some unique device data to programs written specifically to expect them. Device independence is achieved through a 2-tier architecture. Hardware manufacturers supply a device-dependent pen device driver to handle the low level device-specific requirements of their hardware device. This device-dependent driver registers with the IBM-supplied device-independent pen device driver services during initialization. They communicate all events and device capabilities though a well-documented set of interfaces. The types of information supplied include: o Mouse emulation o Position (X,Y) o Contact status o Proximity status o Time stamp o Pressure value o Height value o Angle/rotation of the pen o Status of buttons on the pen o Status of buttons on the tablet or bezel o Resolution and sampling rate information o Smart pen features (memory, personal identification number (PIN)) The device-independent device driver services provide the following: o A common interface for all pointing devices. o A means to deliver the stroke event data to higher-level operating system components. Because these interfaces might change in future releases of the operating system, this module serves to isolate original equipment manufacturers from these details. o The ability to have several physical pointing devices active concurrently. It is reasonable to expect that users of mouse devices will eventually convert completely to a pen when available. In the interim, however, Pen for OS/2 will support the use of the pen and the mouse on the same system. It will determine which device is being used and dynamically disable the other devices. o The registration of several logical subdevices so that unique device features such as bezel buttons or the use of finger or pen can be monitored and reported to the system independently. o The mapping of device information into a consistent model for delivery to higher-level components. o The emulation of standard mouse events for compatibility with existing programs and operating system components. This includes the translation from high resolution (digitizer) to low resolution (screen/mouse) coordinate systems and the simulation of mouse button clicks. o The buffering of high-speed data into an internal cache. ═══ 5.3. API Categories ═══ The application programming interfaces supplied with the Pen for OS/2 extensions to the OS/2 Toolkit fall into four categories: Pen Writing Subsystem (WRT) These are the main APIs that allow developers to see and control pen and stroke data and to interact with the general pen subsystem facilities. This category also includes new OS/2 messages which report the various asynchronous events and state changes associated with the pen extensions. Recognition Event Delivery (RED) This set of APIs aids developers in the interpretation of command-recognition events, such as gestures. The purpose of RED is to deliver recognition results to aware and unaware programs. In the case of unaware programs, RED further handles the process of delivering the events to them by using a set of profiles to invoke special-purpose tools and command handlers. The RED APIs let developers write and register these command handlers with the system. Virtual Keyboard Playback These APIs provide a level of control over the Pop-Up Keyboard tool. New Window Controls Two new window controls are provided: the handwriting input control and the sketch control. A set of APIs (messages) are defined for these controls to allow for the customization of their behavior and for the input and output data flows to and from the controls. The handwriting input pad and the sketch pad are tools provided in the Pen for OS/2 extensions to the OS/2 Toolkit. These tools are clients of the two controls. ═══ 5.4. Writing Subsystem ═══ Pen for OS/2 provides a functional extension to the existing PM input subsystem. Programs written to expect mouse-event messages will continue to see these messages, but a new set of messages are also provided to applications. The definition of new messages, APIs, and data structures are provided in this book. The Pen for OS/2 writing subsystem is responsible for receiving stroke data from the input queue and the internal cache, determining which window gets the data, and sending PM messages to that window. A new set of messages comes with Pen for OS/2. The following briefly describes a few of the key messages: WM_TOUCHDOWN This message is sent whenever the pen tip, mouse, or finger comes in contact with the surface. For compatibility reasons, this message normally is followed by a WM_BUTTONxDOWN. However, WM_TOUCHDOWN should not be confused with WM_BUTTONxDOWN, which might be delayed or suppressed by the user-interface components of Pen for OS/2. This message also signals the start of a stroke. The application should use this message to specify the processing options. WM_LIFTOFF This message is sent when the pen tip, mouse, or finger comes out of contact with the surface. This message also signals the ending of a stroke. WM_EXIT_PROXIMITY This message is sent whenever the pen leaves the proximity zone. Usually, this message is used to signal the end of a series of strokes for recognition. If the device does not support proximity detection, another detection method is necessary, such as position of the pen or a timeout. WM_STROKE This message signals that a stroke is available and the application can access a structure that represents that stroke. WM_SENSOR_MOVE This message is similar to WM_MOUSEMOVE, but it is generated whenever there is movement on the surface. The coordinates reported are in digitizer resolution, which is usually higher than the resolution of the display device. WM_PAUSE_TIMEOUT This message signals that after coming in contact with the surface, the user did not move the pen for a preset time interval (usually about 200-300 milliseconds). This is sometimes known as the pause gesture. By default, this gesture results in an emulated mouse-button event, which is used to signal the start of a selection or move. This message will not be sent after users start a move, even if they subsequently pause. WM_RECO This message informs an application that a recognition event, such as a gesture shape, is being delivered to its window. It can interpret the event itself or it can have the system do it on its behalf. Pen for OS/2 maintains a stroke buffer to collect all the points in the movement of the pen between the touch-down point and the lift-off point. For the majority of cases, this will eliminate the need for developers to have to track the movement of the pen themselves. At the completion of a stroke, the application receives a WM_STROKE message and it can access the stroke data through an API. Optionally, conversion options can be requested during the retrieval of the stroke buffer. This is useful if the application writer wants to convert the high-resolution point stream to screen resolution or to have the points translated to the origin of a specific window on the screen. As points are entered into the stroke buffer, they are connected to previous points and displayed on the screen to give the appearance of ink flowing from the point of the pen. The inking is performed in such a way as to not interfere with the underlying graphical display data. ═══ 5.5. Compatibility Layer ═══ Pen for OS/2 accommodates existing pen-unaware applications. To accomplish this, Pen for OS/2 provides a Compatibility Layer. In many cases, the Pen for OS/2 extensions to the OS/2 Toolkit allows these applications to be augmented by the user with pen features, such as handwriting recognition and gesture-invoked shortcuts or editing. The basic function that the Compatibility Layer provides is the conversion of pen events to mouse and keyboard events or the invocation of special-purpose command handlers that can be registered with the system. Because all PM applications are already designed to work with mouse and keyboard input, compatibility is achieved at this level for all applications. The conversion of pen events to mouse and keyboard events is accomplished either in the writing subsystem or by tools invoked through gestures or other means that send mouse and keyboard events to unaware applications. Although these tools are usually pen-aware, there is no requirement that they be pen-aware. The following list shows how some pen operations are mapped to mouse events: Touch down and pause Mouse button down Touch down, pause, move Begin drag or selection Lift off Mouse button up Tap Mouse button click (down/up) Double-tap Mouse double-click (down/up/dblclk/up) Move pen Mouse move In certain cases, a touchdown will immediately be mapped to a mouse-button-down event, without requiring the user to pause. This usually happens in an area of the screen that has no function other than to select or start to drag. However, this is not the standard behavior because most areas of the screen are capable of having gesture commands drawn on them and, therefore, need the pause. The Pen for OS/2 mouse emulation for pen and finger devices allows for the emulation of 2- and 3-button mice. This emulation is usually set to On by pressing an auxiliary button on the pen or a bezel button on the digitizer or display. If these buttons do not exit, a mouse button 2 emulation can be set using the Pen for OS/2 Tool Bar. An OS/2 system without Pen for OS/2 will often coalesce incremental movements from the mouse, especially during periods of high-system or background activity. This usually results in "jumpy" selections or uneven curves in drawing. Pen for OS/2 solves this problem for handwriting tracking, it has the ability to reinsert points that the PM component discarded. This feature, the high-frequency mouse move, is implemented as an option that the user can turn on through the program object Settings notebook. It is provided especially for existing unmodified applications. ═══ 5.6. Recognition Event Delivery ═══ For unaware applications, the Compatibility Layer will collect strokes and build a doodle on behalf of the unaware application. When the "doodle" is complete, an attempt will be made to recognize it as a gesture. If it matches one of the shapes in the gesture library, the Compatibility Layer will send the event on to the Recognition Event Delivery (RED) component to map the gesture into a command, using a set of profiles the user has supplied. These mapping profiles are associated with the program and program file objects. The profiles can be queried and set through the gestures-mapping page of the Setting notebook for the program and program file objects. The result of gesture assignment is a command and optional parameters. the command can take the form of a built-in function provided by Pen for OS/2 (such as the playing back of keystrokes or minimizing a window), a built-in function supplied by the user or an application, or simply the name of a program to be invoked. The following is a description of the flow between the Pen for OS/2 Writing Subsystem, the Pen for OS/2 Compatibility Layer, and the Recognition Event Delivery Subsystem. The following figure graphically shows this flow. ┌─ Digitizer ─┐ │ ┌─────────┐ │ ┌────────┐ │O│ │O│ │ Pen │ │ │ │ ├───│ Device │ │O│ │O│ │ Driver │ │ └─────────┘ │ └───┬────┘ ┌─────────────────┐ └──┬──────────┘ │ │ Gesture │ └────===== │ │ Recognition │ Pen │ │ Gesture │ │ └────┬────────────┘ │   │ ┌────────────┴────┐ │ │ Compatibility │ ┌──────┐ │ ┌──┤ Layer ├──┐ o Gesture │Buffer│ │ │ └─────────────────┘ │ o Summation │ │ │ │ │ o Hot Spot │Stroke│    └───┬──┘ ┌─Pen for OS/2─────────────┐ ┌─RED───────────────────────┐ │ │ Writing Subsystem │ │ Recognition Event │ └───────┤ PM Extensions │ │ Delivery │ └─────────┬────────────────┘ └────────────┬──────────────┘ │  │ ┌─────────────┐ o Source │ │ Recognition │ o Event │ │ Event │ o Target o Pen Messages │ ┌─────────┐ └─────────────┘ o Data o Mouse Emulation │ │ Profile │ │ o Stroke Collection │ ┌┤ Default ├──┐ │ for Gestures │ │└─────────┘ ├┐ ───┘ o Ink Tracing │ │ Application │├┐ ───┐ o Recognition Results │ │ Profiles │││ │ o Pressure Data and │ └─┬───────────┘││ │ ┌─────┐ so forth │ └┬───────────┘│ └─── │User ├┐ o Activity Detection │ └────────────┘ │Tools│├┐ for Backlight │ Set Through ┌──── └┬────┘││ o High/Low-Resolution │ Profile Editor │ └─┬───┘│ Conversion │ │ ┌──┴──┬─┘ │ │ │ Pen ├┐ │ │ │Tools│├┐ │ Standard PM and │ └─┬───┘││ │ Application Messages │ └┬───┘│   └────┘ ┌────────────────────────────────────────────────────┐ │ Aware and Unaware Applications │ └────────────────────────────────────────────────────┘ Pen for OS/2 Compatibility and RED Flows ═══ 5.7. Program Design Considerations ═══ The following points should be used as guidelines when writing applications that will run with Pen for OS/2. Because you cannot be sure when your program will be running with the Pen for OS/2 system, you should take these guidelines into account when writing any OS/2 Presentation Manager program: o Resist implementing features that can be reached through only one mechanism, such as the keyboard. Implement a tool bar, or at least a menu item, to ensure that a user can access a function even if a keyboard is not available. o Provide accelerator-key mappings for most menu and dialog functions so that they can readily be assigned to recognition-invoked (for example, gesture-invoked) keystroke macros. This will let a user bypass a series of menu taps and go directly to an action merely by drawing a gesture shape. o Provide list boxes or combination boxes as much as possible. Pointing to a list is a simple operation and never results in a recognition error. Entry fields, especially on a keyboardless machine, will require handwriting recognition or the request of a Pop-Up Keyboard; therefore, always try to provide a list of choices when possible. o Take into account that many pen-based displays are monochrome. This will affect the appearance of bit maps, foreground and background colors, and choices of ink color. o Keep internal and external resource requirements to a minimum for programs that expect to run on mobile computers. o Take advantage of the handwriting-recognition control provided with the Pen for OS/2 extensions. You must use the control in dialogs or other writing areas in your windows or forms, or you can use the supplied handwriting-recognition pad when a pop-up tool is appropriate. o Design drawing and annotation facilities into your applications. The inability to draw with a mouse hindered the development of these features into programs, but the pen makes all of this a reality. o Supply recognition-mapping (for example, gesture-mapping) tools with your applications when possible. This is a simpler way to provide unique pen capabilities to your application without necessarily having to modify it. ═══ 6. Using Ink ═══ Pen for OS/2 provides functions and messages to enable your application to process pointing-device movement to produce ink and other pen-aware characteristics. You can design your application program to do its own inking of pointing-device movement or let Pen for OS/2 do the inking. Your application program can collect and manage pointing-device movement, or let Pen for OS/2 build a stroke buffer that contains all the pointing-device movement positions. Device-specific data is available for each pointing-device movement and is also maintained in the stroke buffer. ═══ 6.1. Receiving Notification Messages ═══ You can use the following messages to process ink in your application. ┌───────────────────────────┬─────────────────────────────────────┐ │ MESSAGE │ DESCRIPTION │ ├───────────────────────────┼─────────────────────────────────────┤ │ WM_TOUCHDOWN │ Makes contact with the surface │ ├───────────────────────────┼─────────────────────────────────────┤ │ WM_LIFTOFF │ Breaks contact with the surface │ ├───────────────────────────┼─────────────────────────────────────┤ │ WM_MOUSEMOVE │ Moves pointing device │ ├───────────────────────────┼─────────────────────────────────────┤ │ WM_SENSOR_MOVE │ Moves pointing device │ └───────────────────────────┴─────────────────────────────────────┘ ═══ 6.2. Using Ink without a Stroke Buffer ═══ Pen for OS/2 can ink a stroke and collect in a stroke buffer all pointing-device movements in that stroke for you. But, if you need to ink the stroke, for example, because you want to manage the color or width of the ink yourself, Pen for OS/2 will send you notification messages for each pointing-device movement event. This will enable you to do your own inking. And if you need your own format for a stroke buffer, or do not need the collection of the pointing-device movements that composed a stroke, Pen for OS/2 can be instructed not to build a stroke buffer. This will save time and the resources that the stroke buffer would have required. You will receive the WM_TOUCHDOWN message when the pointing device makes contact with the surface. You inform Pen for OS/2 as to how the stroke is to be processed through the return code from the WM_TOUCHDOWN message. To not have a stroke buffer built, your application returns TDN_NO_PAUSE and TDN_NO_INK_STROKE to the WM_TOUCHDOWN message. In order to receive all pointing-device movements at the hardware sample rate, your application also returns TDN_HIFREQ_MOUSEMOVE to receive the position in screen coordinates or TDN_SENSOR_MOVE to receive the position in digitizer coordinates. The return code for the WM_TOUCHDOWN message is the result of logically ORing all options that your application selects. You must capture all pointing-device messages to be sure your application does not miss the WM_LIFTOFF message that terminates the stroke. A call to the WinSetCapture function while your application is processing the WM_TOUCHDOWN message will allow your application to always obtain the WM_LIFTOFF message. Your application will receive movement messages while the pointing device is in contact with the surface. Your application will receive WM_SENSOR_MOVE messages if your application returned TDN_SENSOR_MOVE on the WM_TOUCHDOWN message; otherwise, your application will receive WM_MOUSEMOVE messages. Your application can ink the stroke or perform other operations, such as erasing, as points are received. Your application can use the WrtMapPointLong function to scale the position coordinates to a different resolution or translate to the origin of a different window. Your application can use this function to scale digitizer coordinates to screen coordinates needed to ink in a given window. Due to the high rate of movement messages at the hardware sample rate, each message must be processed in a short period of time. Use a target time of 2 milliseconds per message, for example. If your application falls behind, your application will still receive all movement messages, but the processing of the points will appear to slow the user's movement. Points are not coalesced as with normal OS/2 mouse-event processing if you requested TDN_HIFREQ_MOUSEMOVE or TDN_SENSOR_MOVE on the WM_TOUCHDOWN message. Your application receives the WM_LIFTOFF message at the end of the stroke. Call WinSetCapture with NULLHANDLE to release the pointing-device capture. Your application needs to pass back LO_STROKE_PROCESSED to indicate that your application has handled the stroke. ═══ 6.3. Using Ink with a Stroke Buffer ═══ Your application can process the points of a stroke itself and have Pen for OS/2 build a stroke buffer to collect the points for future processing. Your application returns TDN_INFINITE_PAUSE and TDN_NO_INK_STROKE to the WM_TOUCHDOWN message. Your application also can choose to receive all pointing-device movement messages by returning TDN_HIFEQ_MOUSEMOVE or TDN_SENSOR_MOVE. As with processing the stroke without a stroke buffer, your application will receive WM_MOUSEMOVE or WM_SENSOR_MOVE messages while the pointing device is in contact with the surface. At the end of the stroke, your application will receive the WM_LIFTOFF message. The WRT_STROKE_AVAIL flag will be set in the flEventStatus field of the WRTEVENTDATA structure pointed to by mp2. Your application can obtain a copy of the stroke buffer with WrtQueryStrokeData. Your application can manage the collected stroke buffers to meet the needs of your application. Your application must capture the pointing-device messages with WinSetCapture as previously discussed, to be sure your application receives the WM_LIFTOFF message. ═══ 6.4. Letting Pen for OS/2 Do the Inking ═══ Your application can also let Pen for OS/2 do the inking of the stroke and provide a stroke buffer. You return TDN_INFINITE_PAUSE and TDN_LEAVE_INK to the WM_TOUCHDOWN message. This eliminates the need for your application to ink and keep track of the movement, point by point, yourself. As points are entered into the stroke buffer, they are connected to the previous points and displayed on the screen to give the appearance of ink flowing from the point of the pointing device. The inking is performed in such a way as to not interfere with the underlying graphical display data. At the end of the stroke, your application will receive the WM_LIFTOFF message, and a stroke buffer will be available for use in your application. Pen for OS/2 will not de-ink the stroke if the entire stroke is in the window of your application. However, if the stroke does leave the window, Pen for OS/2 will de-ink the stroke after the return from the WM_LIFTOFF message. This is because ink cannot be left in the window of another application. The WM_LIFTOFF flags will indicate whether the stroke left the window and whether the ink was left or removed. At the lift-off point, your application must request the stroke buffer and re-ink it. Your application can use the GpiPolyline function for fast inking. This will improve the appearance of the ink and avoid "stroke flash", which occurs when a stroke is de-inked and then immediately re-inked. Your application must capture the pointing-device messages with WinSetCapture as previously discussed, to be sure your application receives the WM_LIFTOFF message. ═══ 6.5. Using Auxiliary Data ═══ Along with the pointing device position data supplied in the WRTEVENTDATA structure, Pen for OS/2 also provides the following hardware-specific information: o Additional flags o High resolution device time stamp o Z-coordinate value o Device angle o Device rotation o Button status o Original equipment manufacturer data o A word for application use All of this data is provided in the AUXPOINTDATA structure and can be obtained with the WrtQueryPointAuxData function during processing of a WM_MOUSEMOVE or WM_SENSOR_MOVE message. You also can select auxiliary data items in the stroke buffer. You indicate which items you need with the flAuxData parameter when you request the stroke buffer with the WrtQueryStrokeData function. ═══ 6.6. Using Device Capabilities ═══ You can get the complete capabilities for the pointing device if you would like to take advantage of specific device characteristics in your application. A device ID for the pointing device is provided in field ulLocatorID in the WRTEVENTDATA structure pointed to by mp2 for the WM_TOUCHDOWN and WM_LIFTOFF message. You can get the device capabilities using this device ID with the WrtQueryLocatorCaps function. The device capabilities are returned in structure WRTLOCACTORDEVINFO. ═══ 7. Using Gestures ═══ Gestures are symbols that are drawn on the computer screen by the user, as a shorthand method to direct an application to perform a particular action. Gestures allow the user to specify both an action to be performed and an object to perform the action on. Each gesture in the Pen for OS/2 system extension has a hot spot. The hot spot is a single point on the gesture or within the bounding box of the gesture. For most gestures, the hot spot is used to target the object of the gesture. A few gestures use the bounding box of the gesture to target the objects. Pen for OS/2 provides support to: o Capture the strokes that a user draws to form a gesture. o Recognize the strokes to determine which gesture was drawn. o Notify the application, through a WinSendMsg, which gesture was drawn. When Pen for OS/2 recognizes a gesture, it first builds a RECODATA structure for the gesture. The RECODATA structure contains information on which gesture was drawn, where it was drawn, and which command and arguments have been mapped to the gesture. (The command and arguments are set in the Gesture page of the Settings notebook for program and program-file objects.) Pen for OS/2 then sends a WM_RECO message to the window under the hot spot of the gesture. You have two ways to handle the gesture: o You can process the WM_RECO message inside your window and return TRUE. If you return TRUE, Pen for OS/2 will do no further processing on this gesture. o Or, you can return FALSE to the WM_RECO message and use the Pen for OS/2 Recognition Command Handler interface to handle the gesture. This interface allows you to develop gesture-mapping tools that can be invoked with a gesture. ═══ 7.1. Recognition Command Handlers ═══ If the window procedure does not handle the WM_RECO message (that is, it returns FALSE), then Pen for OS/2 maps the gesture to a recognition command. Pen for OS/2 checks to see if the command in the RECODATA structure is one of the Pen for OS/2 recognition commands. The following is a list of the built-in recognition commands and a short description of the command is provided. (These commands are documented in Appendix C, in the Pen for OS/2 User's Guide.) NULL Does nothing RESTMAX Restores window if minimized, maximizes window if restored RESTMIN Restores window if maximized, minimizes window if restored MAXIMIZE Maximizes window MINIMIZE Minimizes window WINCLOSE Closes window TASKLIST Displays the task list MENUSEL Selects an item from a menu KEYPLAY Plays back keystrokes OPEN Opens the object at the hot spot of the gesture SYSMENU Selects an item from the system menu CONTEXT Selects an item from the context menu GESTHELP Displays gesture assignments for the window at the hot spot If the command is not identified as one of the Pen for OS/2 recognition commands, then Pen for OS/2 looks to see if there is a registered handler for the command. If a registered handler is found, Pen for OS/2 sends the registered handler's window a WM_RECO_COMMAND message. If no handler is found, then Pen for OS/2 searches the directories in the PATH environment for the executable file (that is, .EXE, .COM, .CMD, or .BAT) with the same name as the recognition command. If it finds an executable file, it invokes the file. The following RECODATA structure contains information about the gesture recognition event. typedef struct _RECODATA { ULONG cbSize; /* Size of structure */ RECOID id; /* Recognition event ID */ HRECO hReco; /* Recognition subsystem handle */ ULONG virtual_id; /* Virtual ID of event */ ULONG char_code; /* Character code, if letter gesture */ RECTL bound_box; /* Bounding box of gesture */ POINTL ptlHotSpot; /* Hot spot, X/Y screen coordinates */ HWND hwnd; /* Window under hot spot of gesture */ HWND hwndActive; /* Active window */ HWND hwndFocus; /* Window that has the focus */ PSZ pszCommand; /* Command assigned to gesture */ PSZ pszCmdArgs; /* Argument of command */ PSZ pszPrefixCmd /* Prefix assigned to gesture */ } RECODATA; typedef RECODATA *PRECODATA; RECODATA Data Format There are essentially two ways to package a recognition command handler. o You can package the handler as part of an application, as a .DLL or an .EXE. In this case, the application will create a window to receive WM_RECO_COMMAND messages, and then call RedRegisterRecoCommand, passing it the name of the command and the window handle that is to receive WM_RECO_COMMAND messages. o You also can package a recognition command handler as a stand-alone program file. In this case, the first time the gesture mapped to the recognition command is recognized, Pen for OS/2 invokes the program file. The program can then recover the RECODATA structure by using the RedQueryRecoDataFromEnv API. At this point, the program file would also create a window to receive WM_RECO_COMMAND messages and call RedRegisterRecoCommand, passing it the name of the program file and the hwnd of the created window. The next time the gesture is recognized, Pen for OS/2 will find the command as a registered recognition handler and will send it a WM_RECO_COMMAND message directly instead of starting the program again. The following APIs are used by registered recognition command handlers: RedRegisterRecoCommand RedQueryRecoCommand RedDeregisterRecoCommand RedRecoDataFromEnv ═══ 7.2. Using the Virtual ID ═══ The preferred method for handling a gesture is to use the virtual_id field (see the previous RECODATE Date Format figure. to determine the intent of the gesture. The virtual_id field isolates the application from having to know the actual shape of the gesture. If for some reason a gesture shape needs to be changed for a particular action, using the virtual_id field allows the shape to be changed without affecting the application. Each gesture in Pen for OS/2 has an intended action. Use hwnd to determine the window where the gesture was drawn. Use ptlHotSpot to target the object within the window that is under the hot spot of the gesture. ═══ 7.3. Using the Event ID ═══ If your application needs to determine the actual shape of the gesture, use RedQueryEventName to determine the name of the gesture. RedQueryEventName takes as input a recognition event ID and a handle to a recognition subsystem. These parameters are available in the id and hReco fields of the RECODATA structure. RedQueryEventName will return the name (EventName) of the gesture. ═══ 7.4. Letter Gestures ═══ Letter gestures are formed by drawing any one of the capital letters and then tapping in the center of the letter. An application can determine when and which letter gesture was drawn by looking at the virtual_id field in the RECODATA structure. If virtual_id = VE_LETTERGESTURE, the char_code field contains the actual letter gesture that was drawn. ═══ 7.5. The Pen for OS/2 Gesture Set ═══ The Pen for OS/2 gesture set has been divided into three types of gestures: o Core gestures o Noncore gestures o Letter gestures Both core gestures and noncore gestures have recommended actions. In order to maintain gesture consistency across applications, applications should use the gestures to perform the actions that have been recommended for the gesture. Core gestures have been chosen to perform the most frequently used actions, such as single selection, scrolling, and editing. Each core gesture has a recommended action. All applications should support the core gestures as they have been defined. The Noncore gestures have been defined to perform less frequently used actions or actions that might be more specific to a type of application, such as text application. If an application provides the action defined for a noncore gesture, the application should support the gesture. Letter gestures are gestures that are available for use by end users. Because these gestures are intended for use by the end user, an application that chooses to use a letter gesture should allow a user to reassign that letter gesture to a different action. If the user assigns a command to a gesture, the pszCommand field in the RECODATA structure will contain the assigned command. ═══ 7.5.1. Core Gestures ═══ Core gestures have been chosen to handle frequently used actions. The following figures illustrate each core gesture, the EventName of the gesture, and the gesture's Virtual ID. For each gesture, a recommended action is provided and a description of the difference between the recommended action and the Pen for OS/2 default gesture assignment. The default gesture assignment is provided by Pen for OS/2 primarily for pen-unaware applications. Differences between the recommended action and the Pen for OS/2 default assignment are usually because Pen for OS/2 does not know the contents of a program's client window and therefore cannot target the object under the hot spot of the gesture. -------------------------------------------------------------------------------- Core Gestures: FlickDown,FlickUp EventName: FlickDown FlickUp Virtual ID: VE_SCROLLDOWN VE_SCROLLUP Description: Recommended Action: Scroll. Scroll towards the bottom one page (FlickDown) or towards the top one page (FlickUp). Hot spot: Touch down point of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Core Gesture: Question EventName: Question Virtual ID: VE_HELP Description: Recommended Action: Help. Display help information adapted to the current context. Either help for an active window, an object, selected objects, or a selected menu choice. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Core Gesture: Checkmark EventName: Checkmark Virtual ID: VE_CONTEXTMENU Description: Recommended Action: Pop-Up Menu. Display the pop-up menu of the object under the hot spot. Hot spot: Bottom tip of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Core Gesture: Circle EventName: Circle Virtual ID: VE_EDIT Description: Recommended Action: Edit. Edit the object or selected objects under the hot spot of the gesture. o If no object is selected under the hot spot of the gesture, use the bounding box of the gesture to determine which object(s) should be edited. o For text, open a handwriting window in boxed mode. Initialize the window with the text under the bounding box of the gesture. Allow the user to edit the text. When the user is complete, replace the original text with the text in the handwriting window. o Use this same editing model with any object(s) that can be selected with the Circle gesture, edited and replaced. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Core Gesture: UpCaret EventName: UpCaret Virtual ID: VE_INSERT Description: Recommended Action: Insert. Open a window that will allow the user to insert information into your program. When the user has completed, insert the information at the hot spot of the gesture. For text, open a handwriting window in boxed mode. Allow the user to input and edit text. When the user has completed, insert the text from the handwriting window at the hot spot of the gesture. Hot spot: Top tip of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Core Gesture: DownRight EventName: DownRight Virtual ID: VE_SPACE Description: Recommended Action: Insert space. Insert at least one space at the hot spot of the gesture. o The Pen for OS/2 handwriting control window inserts one or more spaces at the hot spot of the gesture. The number of spaces inserted is determined by the length of the horizontal portion of the gesture. o If the distance between objects such as text characters in the boxed handwriting control or monospaced characters are fixed size, allows multiple spaces to be inserted by using the length of the horizontal portion of the gesture to determine the number of spaces. Hot spot: Midpoint of the vertical segment of the gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will attempt to set a text cursor by emulating a WM_BUTTON1CLICK at the hot spot of the gesture. It will insert one space by sending a WM_CHAR to the window under the hot spot. -------------------------------------------------------------------------------- Core Gesture: Xout EventName: Xout Virtual ID: VE_DELETE Description: Recommended Action: Delete. Delete the objects or selected objects under the hot spot of the gesture. o Delete a selection when drawn over selected text. o Delete a word when drawn over unselected text. Hot spot: Crossover point of the two strokes. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will send a delete keystroke, through WM_CHAR, to the window under the hot spot. This gesture assignment does not use the hot spot of the gesture to target the object to be deleted. -------------------------------------------------------------------------------- Core Gesture: PigTail EventName: PigTail Virtual ID: VE_DELETECHAR Description: Recommended Action: Delete character. Delete the object or selected objects under the hot spot of the gesture o Delete selection when drawn over selected text. o Delete a character when drawn over unselected text. Hot spot: Touch down point of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Core Gesture: AlphaXout EventName: AlphaXout Virtual ID: VE_CUT Description: Recommended Action: Cut. Cut the object or selected objects under the hot spot of the gesture to the clipboard. Note: The target object or selection is removed and placed in the clipboard. Hot spot: Center of the gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will cut the current selection to the clipboard. It does not use the hot spot of the gesture to target the object. -------------------------------------------------------------------------------- Core Gesture: Alpha EventName: Alpha Virtual ID: VE_COPY Description: Recommended Action: Copy. Copy the object or selected objects under the hot spot of the gesture to the clipboard. Hot spot: Center of the gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will copy the current selection to the clipboard. It does not use the hot spot of the gesture to target the object. -------------------------------------------------------------------------------- Core Gesture: CaretTap EventName: CaretTap Virtual ID: VE_PASTE Description: Recommended Action: Paste. Paste the contents of the clipboard at the hot spot of the gesture. o If nothing is selected under the hot spot, inserts the contents of the clipboard at the hot spot of the gesture. o If a selection exists under the hot spot, replaces the selection with the contents of the clipboard. Hot spot: Top tip of caret. Difference Between Recommended Action and Default Gesture Assignments: The default assignment will insert the contents of the clipboard at the text insertion point or it will replace the current selection with the contents of the clipboard. It does not use the hot spot of the gesture to determine the insertion point of the paste operation. -------------------------------------------------------------------------------- Core Gesture: CircleXout EventName: CircleXout Virtual ID: VE_UNDO Description: Recommended Action: Undo. Undo the previous action. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. ═══ 7.5.2. Noncore Gestures ═══ Noncore gestures also have recommended actions. These actions tend to be less frequently used actions or actions that might be more specific to a type of application, such as text applications. If an application supports the recommended action, it should use the recommended gesture. The following figures illustrate each noncore gesture, the EventName of the gesture, and the gesture's Virtual ID. For each gesture, a recommended action is provided and a description of the difference between the recommended action and the Pen for OS/2 default gesture assignment. The default gesture assignment is provided by Pen for OS/2 primarily for pen-unaware applications. Differences between the recommended action and the Pen for OS/2 default assignment are usually because Pen for OS/2 does not know the contents of a program's client window and therefore cannot target the object under the hot spot of the gesture. -------------------------------------------------------------------------------- Noncore Gesture: Tilde EventName: Tilde Virtual ID: VE_TOGGLESELECTION Description: Recommended Action: Toggle selection. Toggle the selection state of the object under the hot spot of the gesture. If the object is selected, deselect it. If the object is not selected, select it. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Noncore Gesture: FlickDownUp EventName: FlickDownUp Virtual ID: VE_EXTENDSELECTION Description: Recommended Action: Extend selection. Extend the current selection from the cursor (or anchor point) to the hot spot of the gesture. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Noncore Gesture: Leftbracket EventName: Leftbracket Virtual ID: VE_BOUNDSELECTIONLEFT Description: Recommended Action: Bound selection. Set the left boundary of the selection at the hot spot of the gesture. o If a selection exists to the right of the bracket, extend the selection to the bracket. o If no selection exists to the right of the bracket, select the first object to the right of the bracket (for text, this is a word). o If the bracket is drawn over a selection, deselect all contiguous selected objects to the left of the bracket. Hot spot: Midpoint of vertical segment of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Gesture: RightBrackt EventName: RightBrackt Virtual ID: VE_BOUNDSELECTIONRIGHT Description: Recommended Action: Bound selection. Set the right boundary of the selection at the hot spot of the gesture. o If a selection exists to the left of the bracket, extend the current selection to the bracket. o If no selection exists to the left of the bracket, select the first object to the left of the bracket (for text, this is a word) o If the bracket is drawn over a selection, deselect all contiguous selected objects to the right of the bracket. Hot spot: Midpoint of vertical segment of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Editing Gesture: ScratchOut EventName: ScratchOut Virtual ID: VE_SCRATCHOUT Description: Recommended Action: Scratch out. Delete the object or selected objects under the hot spot of the gesture. o If a selection exists under the hot spot of the gesture, delete the selection. o If no selection exists under the hot spot of the gesture, use the bounding box of the gesture to determine the object(s) to delete. o The handwriting control window deletes the characters in any box that is at least 50% covered by the bounding box of the gesture. Hot spot: Center of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Editing Gesture: DownLeft EventName: DownLeft Virtual ID: VE_ENTER Description: Recommended Action: Enter. Insert a line break at the hot spot of the gesture. Hot spot: Midpoint of vertical segment of gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will perform a WM_BUTTON1CLICK at the hot spot of the gesture and a WM_CHAR with the enter keystroke. -------------------------------------------------------------------------------- Noncore Editing Gesture: UpRight EventName: UpRight Virtual ID: VE_TAB Description: Recommended Action: Tab. Insert a tab at the hot spot of the gesture. Hot spot: Midpoint of vertical segment of gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will perform a WM_BUTTON1CLICK at the hot spot of the gesture and a WM_CHAR with the tab keystroke. -------------------------------------------------------------------------------- Noncore Editing Gesture: UpLeft EventName: UpLeft Virtual ID: VE_BACKSPACE Description: Recommended Action: Backspace. Set the text cursor at the hot spot of the gesture. Delete the character to the left of the text cursor. Hot spot: Midpoint of vertical segment of gesture. Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will perform a WM_BUTTON1CLICK at the hot spot of the gesture and a WM_CHAR with the backspace keystroke. -------------------------------------------------------------------------------- Noncore Scrolling Gestures: FlickLeft, FlickRight EventName: FlickLeft FlickRight Virtual ID: VE_SCROLLLEFT VE_SCROLLRIGHT Description: Recommended Action: Scrolls towards the left (FlickLeft) or right (FlickRight) one page. Hot spot: Touch down point of gesture. Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Scrolling Gestures: DFlickDown, DFlickUp EventName: DFlickDown DFlickUp Virtual ID: VE_SCROLLDOWNMORE VE_SCROLLUPMORE Description: Recommended Action: Scrolls towards the bottom (DFlickDown) or top (DFlickUp). Typically, these gestures should scroll to the bottom or top of the document. However, if your application provides an intermediate level of scrolling, use these gestures to scroll to the intermediate level. If your application supports only two lengths of scrolling, then assign both the DFlickUp/DFlickDown and TFlickUp/TFlickDown gesture to the same action. Hot spot: Top center of the bounding box (DFlickDown). Bottom center of the bounding box (DFlickUp). Difference Between Recommended Action and Default Gesture Assignments: The default gesture assignment will always scroll to the bottom or the top. -------------------------------------------------------------------------------- Noncore Scrolling Gestures: DFlickLeft, DFlickRight EventName: DFlickLeft DFlickRight Virtual ID: VE_SCROLLLEFTMORE VE_SCROLLRIGHTMORE Description: Recommended Action: Scrolls towards the left (DFlickLeft) or right (DFlickRight). Typically, these gestures should scroll to the leftmost (DFlickLeft) or rightmost (DFlickRight) position. However, if your application provides an intermediate level of left/right scrolling, use these gestures to scroll to the intermediate level. If your application supports only two lengths of scrolling, then assign both the DFlickLeft/DFlickRight and TFlickLeft/TFlickRight gesture to the same action. Hot spot: Right center of bounding box (DFlickLeft). Left center of bounding box (DFlickRight). Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Scrolling Gestures: TFlickUp, TFlickDown EventName: TFlickUp TFlickDown Virtual ID: VE_SCROLLUPMAX VE_SCROLLDOWNMAX Description: Recommended Action: Scrolls to the top (TFlickUp) or bottom (TFlickDown). Hot spot: Bottom center of bounding box (TFlickUp). Top center of bounding box (TFlickDown). Difference Between Recommended Action and Default Gesture Assignments: No difference. -------------------------------------------------------------------------------- Noncore Scrolling Gestures: TFlickLeft, TFlickRight EventName: TFlickLeft TFlickRight Virtual ID: VE_SCROLLLEFTMAX VE_SCROLLRIGHTMAX Description: Recommended Action: Scrolls to the far left (TFlickLeft) or far right (TFlickRight). Hot spot: Right center of bounding box (TFlickLeft). Left center of bounding box (TFlickRight). Difference Between Recommended Action and Default Gesture Assignments: No default gesture assignment is provided. -------------------------------------------------------------------------------- Noncore Settings Gesture: CheckmrkTap EventName: CheckmrkTap Virtual ID: VE_ASSIGNMENTS Description: Recommended Action: Display the gesture assignments for the program file or program object associated with the window under the hot spot. Hot spot: Bottom tip of check mark. Difference Between Recommended Action and Default Gesture Assignments: No difference. ═══ 7.5.3. Letter Gestures ═══ Letter gestures are made by drawing any of the capital letters and augmenting the letter with a tap in the center of the letter. The tap must be the last stroke of the gesture and must be on top of the letter. -------------------------------------------------------------------------------- Letter Gestures: UppercaseA-UppercaseZ EventName: UppercaseA-UppercaseZ Virtual ID: VE_LETTERGESTURE Description: Recommended Action: These gestures are reserved for end user assignments. Applications that use any of the gestures should allow the end user to reassign the gesture to a different action. Hot spot: Center of gesture. ═══ 8. Using the Sketch Control ═══ The sketch input control (WC_SKETCH window class) is a pen-aware PM control that provides ink capture and rendering. The control can be included in any PM application through window creation or by inclusion into a standard PM dialog. The sketch control has defaults of 1 pel for the ink width and blue for the ink color. The sketch control allows users to input strokes and have the strokes captured into a sketch database. The strokes can then be rendered into the clipboard or returned to the application as a bit map. ═══ 8.1. How the Sketch Control Operates ═══ The appearance of the sketch control can be specified in the dialog template or when the control is created as a window. You can specify the color and width of the ink used to input strokes and set the shape of the pointer used to input strokes. The sketch controls use a default of 1 pel for the ink width, blue ink color, and a pen cursor for the drawing pointer. Operation of the control begins when the pen enters the proximity area of the control. While the pen is in proximity, but before the touch-down point, a pen mouse pointer is displayed. After the pen touches down on the control window, the pen cursor is displayed. The user then enters strokes within the bounding area of the client window. After a stroke has been completed, the user lifts the pen off the display surface. When the pen has made contact with the surface, the control captures all pointing-device messages and paints the points in the control-display window. At the lift-off point, the control adds the stroke to the sketch database. You can use the sketch control in your application to make a bit map or an addition to the clipboard. It is not necessary to deal with the details of managing individual point events. You can use the sketch control as a transparent overlay, for example, to capture a signature over a bit map of a signature line annotated with "Sign here". ═══ 8.2. Defining Sketch Controls in a Dialog Window ═══ The following example shows how sketch controls can be defined as part of a dialog template in a resource definition file. DLGTEMPLATE IDD_DIALOG BEGIN DIALOG "", ID_DLG1, 10, 10, 100, 100, WS_VISIBLE, FCF_DLGBORDER BEGIN LTEXT "Enter your Name:", -1, 10, 20, 80, 10 CONTROL "", ID_NAME, 10, 40, 80, 20, WC_SKETCH, WS_VISIBLE | SKS_B ORDER DEFPUSHBUTTON "OK", DID_OK, 35, 85, 30, 10, WS_GROUP END END The procedure for a dialog window that contains sketch controls must respond to WM_CONTROL messages. ═══ 8.3. Defining Sketch Controls in a Client Window ═══ You can define a sketch control using an application client window as the owner. The following example shows how. #define ID_SKETCH1 110 HWND hWndClient, hWndEntryControl; hWndEntryControl = WinCreateWindow( hWndClient, /* Parent Window */ WC_SKETCH, /* Class Name */ "", /* Control Text */ WS_VISIBLE, /* Style Bits */ 10, 10, /* x, y */ 50, 20, /* cx, cy */ hWndClient, /* Owner */ HWND_TOP, /* Top of Z-Order */ ID_SKETCH1, /* ID */ NULL, /* Control Data */ NULL ); /* Parameters */ When defined in a client window, the sketch control sends WM_CONTROL messages to its parent client window procedure. An application that has sketch controls in its client area can move and size the controls when the client window receives a WM_SIZE message. ═══ 8.4. Using Control Style Bits ═══ The control style bits let you specify the display attributes of a sketch control. The following table lists the sketch control style bit. ┌────────────────────────────────┬────────────────────────────────┐ │ SKETCH CONTROL STYLE BIT │ ACTION │ ├────────────────────────────────┼────────────────────────────────┤ │ SKS_BORDER │ Displays a border around its │ │ │ input area. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKS_3DBORDER │ Displays a 3-dimensional │ │ │ border around its input area. │ └────────────────────────────────┴────────────────────────────────┘ ═══ 8.5. Sending Control Messages ═══ You can send control messages to the sketch entry control to query, set, or change the state of the window containing the sketch control. Messages are sent in the following manner: WinSendMsg(hWndSiCtl, MessageID, mp1, mp2); Where: hWndSiCtl = The handle of the sketch entry control window MessageID = The ID of the control message mp1 = Message data as defined by the control message mp2 = Message data as defined by the control message See "Sketch Control Programming Interface" for more information on these control messages and the format of the message to the sketch entry control. ┌────────────────────────────────┬────────────────────────────────┐ │ CONTROL MESSAGE │ ACTION │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_DELETE_ALL_STROKES │ Tells the sketch control to │ │ │ delete all strokes in the │ │ │ stroke database. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_GET_BITMAP │ Creates a screen resolution │ │ │ bit-map image from the sketch │ │ │ control and returns its │ │ │ handle. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_UNDO_LAST_STROKE │ Tells the sketch control to │ │ │ clear the ink of the last │ │ │ stroke and to delete it from │ │ │ the control. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_BITMAP_SIZE │ Returns the size of the bit │ │ │ map that could be returned. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_RENDER_TO_CLIPBOARD │ Renders the screen resolution │ │ │ bit-map image from the sketch │ │ │ control to the clipboard. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_CTL_DRAW_POINTER │ Returns the drawing pointer │ │ │ handle. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_CTL_INK_COLOR │ Returns the control's current │ │ │ ink color. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_CTL_INK_WIDTH │ Returns the control's current │ │ │ ink width. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_CTL_INVISIBLE_MODE │ Returns the value of the │ │ │ invisible mode flag. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_CTL_STROKE_COUNT │ Gets the count of strokes in │ │ │ the stroke control. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_STROKE_DATA │ Retrieves stroke from the │ │ │ stroke control. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_STROKE_INK_COLOR │ Queries the color of stroke. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_STROKE_INK_WIDTH │ Queries the ink width of │ │ │ stroke. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_QUERY_STROKE_LENGTH │ Retrieves the size in bytes of │ │ │ stroke. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_CTL_AUXDATA_MODE │ Informs the control that sub- │ │ │ sequent strokes will retrieve │ │ │ the specified pen stroke aux- │ │ │ iliary data. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_CTL_DRAW_POINTER │ Sets the drawing point handle │ │ │ and returns the previous │ │ │ pointer. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_CTL_INK_COLOR │ Sets the control's current ink │ │ │ color. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_CTL_INK_WIDTH │ Sets the control's ink width. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_CTL_INVISIBLE_MODE │ Turns on or off the invisible │ │ │ mode of the control. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_STROKE_INK_COLOR │ Resets the color attribute of │ │ │ stroke in the stroke database. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_SET_STROKE_INK_WIDTH │ Resets the ink width attribute │ │ │ of stroke(i) in the stroke │ │ │ database. │ ├────────────────────────────────┼────────────────────────────────┤ │ SKM_ADD_STROKE │ Adds a stroke to the control. │ └────────────────────────────────┴────────────────────────────────┘ ═══ 8.6. Receiving Notification Messages ═══ Notification messages are sent by the sketch control to notify its owner of significant events. Messages are received as follows: WinSendMsg(hWndOwner, WM_CONTROL, MPFROM2SHORT(ID, NotifyCode) mp2); Where: hWndOwner = The owner of the sketch control window ID = The ID assigned to the control at creation NotifyCode = An event notification code mp2 = Notify code-specific information The following notification messages are defined for sketch control. See "Sketch Control Programming Interface" for more information on these notification messages for sketch control. ┌───────────────────────────┬────────────────────────────────┐ │ MESSAGE │ PURPOSE │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_FOCUS_ACTIVATE │ Informs the parent that the │ │ │ control has been given input │ │ │ focus. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_FOCUS_DEACTIVATE │ Informs the parent that the │ │ │ control has lost input focus. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_STROKE_ADD │ Sent to the parent when a │ │ │ stroke is about to be added to │ │ │ the stroke database. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_STROKE_UNDO │ Sent to the parent when a │ │ │ stroke is about to be deleted │ │ │ from the stroke database. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_CONTROL_CLEARED │ Sent to the parent when the │ │ │ stroke database is about to be │ │ │ cleared of all strokes. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_INK_COLOR_CHANGE │ Sent to the parent when the │ │ │ ink color for the drawing │ │ │ stroke has been changed. │ ├───────────────────────────┼────────────────────────────────┤ │ SKN_INK_WIDTH_CHANGE │ Sent to the parent when the │ │ │ width for the ink has been │ │ │ changed. │ └───────────────────────────┴────────────────────────────────┘ ═══ 9. Using the Handwriting Entry Control ═══ The handwriting entry control is a standard PM control that can be included in any PM application through window creation or inclusion into a standard PM dialog. The handwriting control lets a Pen for OS/2 program user input handwritten text and have the text recognized and converted to characters. ═══ 9.1. How the Handwriting Entry Control Operates ═══ The input area is a grid of cells arranged in rows and columns. After entering text, a user can edit the text by using gestures to erase a single character, erase multiple characters, or insert space in a line of text. The window containing the handwriting control can be resized like a normal PM window; the text is reflowed when the window is sized. As the size of a handwriting control is increased, more input cells become available. If a user subsequently reduces the size of the handwriting control, the text will still exist but might not be displayed. Users can enter up to 1024 characters into a handwriting control. Text strings longer than 1024 characters are truncated. ═══ 9.2. Supported Gestures ═══ The following figure illustrates the gestures supported by the handwriting control. The Virtual ID is shown below each gesture illustration. A description of the result is included in the table. -------------------------------------------------------------------------------- DELETECHAR Gesture, Handwriting Entry Control Virtual ID: VE_DELETECHAR Description: Deletes the character in the box that is under the hot spot of the gesture. Hot spot: Touch down point of gesture. -------------------------------------------------------------------------------- SCRATCHOUT Gesture, Handwriting Entry Control Virtual ID: VE_SCRATCHOUT Description: Deletes the character in any box that is at least 50% covered by the bounding box of the gesture. Hot spot: Center point of gesture. -------------------------------------------------------------------------------- SPACE Gesture, Handwriting Entry Control Virtual ID: VE_SPACE Description: One space is inserted for each character cell boundary that is crossed by the horizontal segment of the gesture. Hot spot: Midpoint of the vertical segment of the gesture. -------------------------------------------------------------------------------- ═══ 9.3. Using Handwriting Controls in a Dialog Window ═══ Handwriting controls can be defined as part of a dialog template in a resource definition file, as shown in the following example: DLGTEMPLATE IDD_DIALOG BEGIN DIALOG "", ID_DLG1, 10, 10, 100, 100, WS_VISIBLE, FCF_DLGBORDER BEGIN LTEXT "Enter your Name:", -1, 10, 20, 80, 10 CONTROL "", ID_NAME, 10, 40, 80, 20, WC_HWXENTRY, WS_VISIBLE | HX_BORDER DEFPUSHBUTTON "OK", DID_OK, 35, 85, 30, 10, WS_GROUP END END The dialog window procedure for a dialog window that contains handwriting controls must respond to WM_CONTROL messages. See Part 2: Pen for OS/2 Programming Reference "Handwriting Input Control Programming Interface" for a complete description of the handwriting control notification and control messages. ═══ 9.4. Using Handwriting Controls in a Client Window ═══ An application can create a handwriting control using an application client window as the owner, as shown in the following example: #define ID_ENTRY1 110 HWND hWndClient, hWndEntryControl; hWndEntryControl = WinCreateWindow( hWndClient, /* Parent Window */ WC_HWXENTRY, /* Class Name */ "", /* Control Text */ WS_VISIBLE | HX_BORDER, /* Style Bits */ 10, 10, /* x, y */ 50, 20, /* cx, cy */ hWndClient, /* Owner */ HWND_TOP, /* Top of Z-Order */ ID_ENTRY1, /* ID */ NULL, /* Control Data */ NULL ); /* Parameters */ After it is created in the client window, the handwriting control sends WM_CONTROL messages its parent client window procedure. An application that has created handwriting controls in its client area can move and size the controls when the client window receives a WM_SIZE message. ═══ 9.5. Using Control Style Bits ═══ Control Style bits let you specify the display attributes of a handwriting control. The following table lists the handwriting control style bits. ┌────────────────────────────────┬────────────────────────────────┐ │ HANDWRITING CONTROL STYLE BITS │ ACTION │ ├────────────────────────────────┼────────────────────────────────┤ │ HX_3DBORDER │ Displays a three-dimensional │ │ │ border around the edge of the │ │ │ control's client area. │ ├────────────────────────────────┼────────────────────────────────┤ │ HX_BORDER │ Displays a black border around │ │ │ the edge of the control's │ │ │ client area. │ └────────────────────────────────┴────────────────────────────────┘ ═══ 9.6. Receiving Notification Messages ═══ Notification messages are sent by the handwriting control to notify its owner of significant events. Messages are received as follows: WinSendMsg(hOwnerWnd, WM_CONTROL, MPFROM2SHORT(ID, NotifyCode) mp2); Where: hOwnerWnd = The owner window of the handwriting control window ID = The ID assigned to the control at creation NotifyCode = The notification message ID mp2 = Notify code specific information The following notification messages are defined for handwriting control. ┌───────────────────────────┬─────────────────────────────────────┐ │ MESSAGE │ PURPOSE │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_OVERFLOW │ Informs the owner of the control │ │ │ that the current operation has │ │ │ caused the text area of the control │ │ │ to overflow. The text limit for a │ │ │ handwriting control is 300 charac- │ │ │ ters. Overflow text is lost. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_SETFOCUS │ Informs the owner of the control │ │ │ that the control has gained the │ │ │ focus. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_KILLFOCUS │ Informs the owner of the control │ │ │ that the control has lost focus. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_CONTENTS_CHANGED │ Sent to the control when the text │ │ │ contents of the control has │ │ │ changed. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_STROKE_ADDED │ Informs the owner that the control │ │ │ has received a pen stroke that is │ │ │ destined to be sent to the recogni- │ │ │ tion system. If the owner returns │ │ │ TRUE to the message, the control │ │ │ takes no further action. If the │ │ │ owner returns FALSE, the control │ │ │ sends the pen stroke to the recog- │ │ │ nition system. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_DELETE_PENDING │ Informs the owner the control │ │ │ intends to delete a range of char- │ │ │ acters due to a user gesture. If │ │ │ the owner returns TRUE to the │ │ │ message, the control takes no │ │ │ further action. If the owner │ │ │ returns FALSE to the message, the │ │ │ control deletes the characters in │ │ │ the range. │ │ │ │ │ │ Message parameter 2 (mp2) contains │ │ │ two 16-byte fields to denote the │ │ │ range as follows: │ │ │ │ │ │ o HIUSHORT (mp2) - Start of range │ │ │ of deleted characters. │ │ │ o LOUSHORT (mp2) - End of range │ │ │ of deleted characters. │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_INSERT_PENDING │ Informs the owner the control │ │ │ intends to insert spaces into the │ │ │ control. If the owner returns TRUE │ │ │ to the message, the spaces are not │ │ │ inserted. If the owner returns │ │ │ FALSE to the message, the spaces │ │ │ are inserted. │ │ │ │ │ │ Message parameter 2 (mp2) contains │ │ │ the following values: │ │ │ │ │ │ o usPosition (USHORT) - Position │ │ │ in the current text where │ │ │ spaces will be inserted. │ │ │ o usCount (USHORT) - Number of │ │ │ spaces that will be inserted. │ └───────────────────────────┴─────────────────────────────────────┘ ┌───────────────────────────┬─────────────────────────────────────┐ │ MESSAGE │ PURPOSE │ ├───────────────────────────┼─────────────────────────────────────┤ │ HXN_GESTURE_PENDING │ Informs the owner of the control │ │ │ that the user has just entered a │ │ │ gesture in the control. If the │ │ │ owner returns TRUE to the message, │ │ │ the gesture is not executed. If │ │ │ the owner returns FALSE to the │ │ │ message, the gesture is executed. │ │ │ │ │ │ Message parameter 2 (mp2) contains │ │ │ the gesture ID. Possible values │ │ │ for mp2 are: │ │ │ │ │ │ o VE_SPACE │ │ │ o VE_SCRATCHOUT │ │ │ o VE_DELETECHAR │ └───────────────────────────┴─────────────────────────────────────┘ ═══ 9.7. Sizing a Handwriting Control ═══ A handwriting control can be sized with the OS/2 PM WinSetWindowPos function. When the handwriting control is sized larger, more rows and columns are added, as many as will fit into the current control size, allowing borders on each side of the character input area. When sizing the control for a given number of rows and columns, the border areas must be added to the sizing. For example, to size a control to 5 rows with 12 columns the following calculation is performed: Rows = 5 Columns = 12 CharBoxDX = WrtQuerySysValue(HWND_DESKTOP, PPMSV_CHARACTER_BOX_DX) CharBoxDY = WrtQuerySysValue(HWND_DESKTOP, PPMSV_CHARACTER_BOX_DY) BaseLineDY = CharBoxDY / 3 ControlDY = ( Rows * (CharBoxDY + BaseLineDY) ) + BaseLineDY ControlDX = ( Columns * CharBoxDX) + (CharBoxDX / 2) Using these calculations gives an optimal size control with even-centering borders on top, bottom, left, and right. ═══ 10. Using Virtual Keyboards and the Pop-Up Keyboard Tool ═══ The Pen for OS/2 program displays virtual keyboards that resemble physical keyboards using the Pop-Up Keyboard Tool. Keystrokes are sent to an application as the user selects keys using a pointing device, such as a pen or finger. This is particularly useful for systems that do not include a physical keyboard, or for applications that require specialized keyboards. You can load a keyboard and have it associated with your application. Keystrokes entered on the keyboard are sent to your application. Your application can hide and control the location of the Pop-Up Keyboard Tool. ═══ 10.1. Selecting a Keyboard ═══ Keyboard data files are loaded from the disk and kept in memory to provide faster access. The following keyboard data files are currently shipped with the Pen for OS/2 program. Each keyboard data file represents one keyboard. Default Always in memory TRAINER.KB1 Keyboard used in training FULLSIZE.KB1 Full keyboard 3270PFK.KB1 3270 emulation PF keys NUMKEY.KB1 Number pad NUMBER.KBL Number pad ═══ 10.2. Key Actions ═══ Each key might have one action or a set of actions. These actions can be any one of the following: o A character or character string o A virtual keystroke (Insert, Delete, Up Arrow, Down Arrow, and so forth) o A defined function (Current Date, Current Time, and so forth) o The setting of a state variable (Shift, Ctrl, Alt, and so forth) Generated character strings and virtual keys are directed to the application as WM_CHARs, as if entered from a physical keyboard. ═══ 10.3. Controlling the Pop-Up Keyboard Tool ═══ Several APIs are provided for you to control the Pop-Up Keyboard Tool. For example, you can load, delete, position, and hide a keyboard. The following table shows the APIs you can use and the functions they provide. ┌──────────────────────┬──────────────────────────────────────────┐ │ API │ FUNCTION │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpDeleteKeyboard │ Deletes a keyboard from memory. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpHideKeyboard │ Hides a keyboard if it is currently │ │ │ visible. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpIsKbHidden │ Determines if the Pop-Up Keyboard Tool │ │ │ is currently hidden. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpIsKbRunning │ Determines if the Pop-Up Keyboard Tool │ │ │ is currently running. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpLoadKeyboard │ Loads a new keyboard into memory and │ │ │ displays it. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpCloseKb │ Enables an application to close the │ │ │ Pop-Up Keyboard Tool. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpQueryKbPos │ Returns the current position of the │ │ │ Pop-Up Keyboard Tool in desktop coordi- │ │ │ nates. │ ├──────────────────────┼──────────────────────────────────────────┤ │ VkpSetKbPos │ Sets the Pop-Up Keyboard Tool position │ │ │ on the desktop. │ └──────────────────────┴──────────────────────────────────────────┘ ═══ 10.4. Changing Keyboard Views ═══ Although multiple keyboards might be loaded in memory at one time, only one keyboard is displayed at a time. When a new keyboard is displayed, the current keyboard display is destroyed, but the keyboard data is kept in memory for later use, until deleted. Your application must ensure that its keyboard is displayed. When your application regains focus, you should reload the keyboard. If your keyboard has moved, you can reposition it. ═══ 11. Using System Variables ═══ The Pen for OS/2 program provides system variables that let your application query system information and customize the Pen for OS/2 system. The following system variables are provided. ┌────────────────────────────────┬──────────────────────┬─────────────────┐ │ SYSTEM VARIABLE │ DESCRIPTION │ CONFIGURED BY │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_VERSION │ Pen for OS/2 version │ Pen for OS/2 │ │ │ │ system │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_SUSPEND │ Pen for OS/2 sus- │ Pen for OS/2 │ │ │ pended │ system │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_PEN_PAUSE │ Pen pause variable │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_TOUCH_PAUSE │ Touch pause │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_MOUSE_PAUSE │ Mouse pause │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_OTHER_PAUSE │ Other device pause │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_PEN_PAUSE_ENABLE │ Enable pen pause │ User │ │ │ variable │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_TOUCH_PAUSE_ENABLE │ Enable touch pause │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_MOUSE_PAUSE_ENABLE │ Enable mouse pause │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_OTHER_PAUSE_ENABLE │ Enable other device │ User │ │ │ pause │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_PAUSEBEEPFREQ │ Pause beep frequency │ User │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_RECO_BEEP_ENABLE │ Enable recognition │ User │ │ │ beep │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_MINGESTUREPOINTS │ Minimum number of │ OEM or │ │ │ points │ Recognition │ │ │ │ Provider │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_GESTURE_TIMEOUT │ Gesture interstroke │ User │ │ │ timeout │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_GESTURE_CANCEL_TIMEOUT │ Cancel gesture timer │ User │ │ │ value │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_RECOPTRTIMER │ Recognition pointer │ User │ │ │ change time │ │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_STANDARDIZED_RESOLUTION │ Standardized resol- │ Pen for OS/2 │ │ │ ution │ system │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_CHARACTER_BOX_DX │ Size of character │ Pen for OS/2 │ │ │ input box (x) │ system │ ├────────────────────────────────┼──────────────────────┼─────────────────┤ │ PPMSV_CHARACTER_BOX_DY │ Size of character │ Pen for OS/2 │ │ │ input box (y) │ system │ └────────────────────────────────┴──────────────────────┴─────────────────┘ System variables are kept in memory and maintained persistently so that the values do not need to be set on each system startup. ═══ 11.1. Controlling System Variables ═══ You can query the value of a system variable kept in memory with the WrtQuerySysValue function. WrtReadSysValue retrieves the value of the system variable from the Pen for OS/2 profile maintained on disk and updates the memory copy. You can set a value for a system variable in memory with the WrtSetSysValue function. The persistent value on disk is not changed. You can change the persistent value with the WrtWriteSysValue function. Note: You must send the notification message WM_WRT_SYSVALUECHANGED with WinBroadcastMsg after changing the value of a system variable. For example, if you have changed the PPMSV_RECO_BEEP_ENABLE system variable, then you must do the following broadcast: WinBroadcastMsg (HWND_DESKTOP, WM_WRT_SYSVALUECHANGED, (MPARAM) VT_PPMSV, (MPARAM) PPMSV_RECO_BEEP_ENABLE, BMSG_DESCENDANTS|BMSG_POST); Most of the system variables will need to be set only once. If the system variables are set incorrectly, the user can render the user interface unusable. The following table provides the minimum and maximum settings, the default setting, and if the setting can be disabled. ┌───────────────────────────────┬──────────┬──────────┬──────────┬─────────────┐ │ │ │ │ DEFAULT │ DISABLE │ │ SYSTEM VARIABLE │ MINIMUM │ MAXIMUM │ SETTING │ SETTING │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_PEN_PAUSE │ 150 │ 2000 │ 400 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_TOUCH_PAUSE │ 150 │ 2000 │ 300 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_MOUSE_PAUSE │ 150 │ 2000 │ 0 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_OTHER_PAUSE │ 150 │ 3500 │ 200 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_PEN_PAUSE_ENABLE │ 0 │ 1 │ 1 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_TOUCH_PAUSE_ENABLE │ 0 │ 1 │ 1 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_MOUSE_PAUSE_ENABLE │ 0 │ 1 │ 0 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_OTHER_PAUSE_ENABLE │ 0 │ 1 │ 1 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_PAUSEBEEPFREQ │ 100 │ 4000 │ 100 │ Yes │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_RECO_BEEP_ENABLE │ 0 │ 1 │ 1 │ Yes │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_MINGESTUREPOINTS │ 1 │ 20 │ 5 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_GESTURE_TIMEOUT │ 100 │ 2000 │ 900 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_GESTURE_CANCEL_TIMEOUT │ 500 │ 3000 │ 1200 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_RECOPTRTIMER │ 200 │ 1250 │ 350 │ Yes │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_STANDARDIZED_RESOLUTION │ 1000 │ 1000 │ 1000 │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_CHARACTER_BOX_DX │ - │ - │ Dynamic │ No │ ├───────────────────────────────┼──────────┼──────────┼──────────┼─────────────┤ │ PPMSV_CHARACTER_BOX_DY │ - │ - │ Dynamic │ No │ └───────────────────────────────┴──────────┴──────────┴──────────┴─────────────┘ ═══ 11.2. Receiving Notification Messages ═══ You will receive a WM_WRT_SYSVALUECHANGED notification message whenever any of the system variables are changed by any application. Your application would obtain the new values of the system variables that your application is using. ═══ 12. Using Device Drivers ═══ The Pen for OS/2 program uses pen device drivers to generate hardware-specific information such as: o Position (x,y) o Contact status o Proximity status o High precision device time stamp o Pressure value o Height value (proximity) o Angle and rotation o Status of buttons o Resolution and sampling rate o Smart pen features ═══ 12.1. Logical Devices ═══ Each physical pen device driver contains logical devices which manage the pen hardware. There are three types of logical devices: o Locator devices o Buttons o The backlight of an LCD display Your application can enumerate, or make a list of, the driver name for each pen device driver present in your system with the pen device driver functions described in this chapter. Your application can obtain the capabilities of each logical device using the driver name obtained from the enumeration. The Pen for OS/2 program has a set of device variables which provide low-level control over the device characteristics. Your application can query and set these device variables. Some of these variables are managed through the user interface by Workplace Shell objects provided with the physical pen device driver. Your application can choose to manage the device variables that are not managed from the user interface in your application. The Pen for OS/2 program manages the backlight of your display to save power and extend the life of the display. Your application can control this automatic support through the functions described in this chapter. Your application also can turn the backlight on and off to provide security in "sensitivity" environments or to directly manage the power and life of your display. With the functions described in this chapter, your application can take advantage of hardware-specific capabilities of your system's pen device drivers in your application. ═══ 12.2. Determining Device Configuration and Capabilities. ═══ Each pen device driver has a unique driver name. Your application can enumerate the driver names present in your system with the WrtEnumInputDrivers function. WrtEnumInputDrivers returns an array of null-terminated driver names. Each driver name is a 32 character array. For example: "ABC Color Tablet\0 WACOM SD-510C\0 MOUSE\0 " Your application can find out the logical devices in each physical pen device driver using the driver name and the WrtQueryInputDeviceNames function. WrtQueryInputDeviceNames returns three arrays per driver name: a null-terminated logical device-name array, a device-type array, and a device-ID array. There are three logical device types: locator devices, buttons, and the backlight of an LCD display. Each logical device is assigned a unique ID within its device type. Your application uses this ID to select a logical device in the device capability functions that will be described next. The locator device ID is passed on every point of a stroke. The ID can be found in the point's event data structure. Note: On a WM_MOUSEMOVE, your application can obtain the current event data structure by calling WRT_QUERYEVENTDATA. To continue our example, the results of three WrtQueryInputDeviceNames (one for each Driver Name), could be: Driver Name - "ABC Color Tablet" Device Name - "Pen" "Touch" "BezelButton" "ColorLCD" Device Type - DT_LOCATOR DT_LOCATOR DT_BUTTON DT_DISPLAY Device ID - 1 2 1 1 Driver Name - "WACOM SD-510C" Device Name - "Pen" "BarrelButton" Device Type - DT_LOCATOR DT_BUTTON Device ID - 3 2 Driver Name - "MOUSE" Device Name - "StockMouse" Device Type - DT_LOCATOR Device ID - 4 Your application can obtain the device capabilities of your logical devices using the device ID obtained from WrtQueryInputDeviceNames with the WrtQueryLocatorCaps, WrtQueryButtonCaps, and WrtQueryDisplayCaps functions. WrtQuerySystemCaps returns the capabilities of the system. The following table shows the function and the structure returned for capabilities information. ┌──────────────────────┬────────────────────┬───────────────────┐ │ FUNCTION │ STRUCTURE RETURNED │ DESCRIPTION │ ├──────────────────────┼────────────────────┼───────────────────┤ │ WrtQueryLocatorCaps │ WRTLOCATORDEVINFO │ Locator device │ │ │ │ capabilities │ │ │ │ information │ ├──────────────────────┼────────────────────┼───────────────────┤ │ WrtQueryButtonCaps │ WRTBUTTONDEVINFO │ Button device │ │ │ │ capabilities │ │ │ │ information │ ├──────────────────────┼────────────────────┼───────────────────┤ │ WrtQueryDisplayCaps │ WRTDISPLAYDEVINFO │ Display device │ │ │ │ capabilities │ │ │ │ information │ ├──────────────────────┼────────────────────┼───────────────────┤ │ WrtQuerySystemCaps │ WRTSYSTEMINFO │ System capabili- │ │ │ │ ties information │ └──────────────────────┴────────────────────┴───────────────────┘ ═══ 12.3. Controlling Device Variables ═══ The Pen for OS/2 program maintains the following variables for each individual logical device. ┌──────────────────────────┬──────────────────────┬──────────────┬────────────┐ │ │ │ │ CONFIGURED │ │ INPUT DEVICE VARIABLE │ DESCRIPTION │ DEVICE TYPE │ BY │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_MOTION_STOP │ Stops motion filter │ DT_LOCATOR │ OEM │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_MOTION_START │ Starts motion filter │ DT_LOCATOR │ OEM │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_MINGESTURELENGTH │ Minimum gesture size │ DT_LOCATOR │ OEM or │ │ │ │ │ Recogni- │ │ │ │ │ tion │ │ │ │ │ Provider │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_DISABLE_PROXIMITY │ Disables proximity │ DT_LOCATOR │ User │ │ │ events │ │ │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_POINT_RATE │ Maximum point rate │ DT_LOCATOR │ User │ │ │ │ │ Pen for │ │ │ │ │ OS/2 │ │ │ │ │ recommen- │ │ │ │ │ dation │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_DIVIDE_RATE │ Divide rate │ DT_LOCATOR │ Pen for │ │ │ │ │ OS/2 │ │ │ │ │ recommen- │ │ │ │ │ dation │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_BACKLIGHTBLANK │ Blanking enable │ DT_DISPLAY │ User │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_BACKLIGHTBLANK_INT │ Blanking timer │ DT_DISPLAY │ User │ │ │ interval in seconds │ │ │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_TOUCHOFFSET_X │ Displays offset │ DT_LOCATOR │ User │ │ │ between fingertip │ │ │ │ │ and the screen's │ │ │ │ │ pointer icon (X). │ │ │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_TOUCHOFFSET_Y │ Displays offset │ DT_LOCATOR │ User │ │ │ between fingertip │ │ │ │ │ and the screen's │ │ │ │ │ pointer icon (Y). │ │ │ ├──────────────────────────┼──────────────────────┼──────────────┼────────────┤ │ PPMID_DEVICE_PARMS │ Device-specific data │ ALL │ OEM │ └──────────────────────────┴──────────────────────┴──────────────┴────────────┘ Your application can query, set, and manage these device variables. However, these variables have a global and persistent effect. They are not intended to be changed frequently or to be set for a particular application's needs. Most of the input device variables will need to be set only once. If the input device variables are set incorrectly, the user can render the user interface unusable. The following table provides the minimum and maximum settings, the default setting, and if the setting can be disabled. ┌───────────────────────────┬───────────┬───────────┬───────────┬───────────┐ │ │ │ │ DEFAULT │ DISABLE │ │ INPUT DEVICE VARIABLE │ MINIMUM │ MAXIMUM │ SETTING │ SETTING │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_MOTION_STOP │ 28 │ 300 │ 28-56 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_MOTION_START │ 1 │ 1000 │ 25-104 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_MINGESTURELENGTH │ 1 │ 1-8000 │ 156-233 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_DISABLE_PROXIMITY │ 0 │ 1 │ 0 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_POINT_RATE │ 40 │ 200 │ 100 │ Yes │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_DIVIDE_RATE │ 1 │ 8 │ 2 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_BACKLIGHTBLANK │ 0 │ 1 │ 1 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_BACKLIGHTBLANK_INT │ 10 │ 500000 │ 1200 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_TOUCHOFFSET_X │ -1000 │ 1000 │ 0 │ No │ ├───────────────────────────┼───────────┼───────────┼───────────┼───────────┤ │ PPMID_TOUCHOFFSET_Y │ -1000 │ 1000 │ 0 │ No │ └───────────────────────────┴───────────┴───────────┴───────────┴───────────┘ o Your application can query the current value of these variables with the WrtQueryInputDeviceVariable function and your application can set the values with the WrtSetInputDeviceVariable function. o Your application can use PPMID_MOTION_STOP, PPMID_MOTION_START, PPMID_MINGESTURELENGTH, and PPMID_DISABLE_PROXIMITY to configure the system's response for special cases. o Your application can use PPMID_POINT_RATE to control the interrupt rate of the pen device driver. PPMID_DIVID_RATE controls the number of high-frequency locator events that update the OS/2 mouse-pointer position. All locator events are available to the application program. If your application set PPMID_DIVID_RATE to the value 2, all locator events are available for your application, but only every other point will be used to update the OS/2 mouse pointer for applications that do not request to process all locator events. o The hardware original equipment manufacturer provides Workplace Shell configuration objects to control PPMID_BACKLIGHTBLANK and PPMID_BACKLIGHTBLANK_INT through the user interface, but your application might want to control these yourself. This procedure is described later in this chapter. The hardware original equipment manufacturer uses PPMID_DEVICE_PARMS to control the device and it must be used only for this purpose. It is listed here only for completeness. Note: Your application must send the notification message WM_WRT_SYSVALUECHANGED with WinBroadcastMsg after using WrtSetInputDeviceVariables. For example, if your application has changed the PPMID_BACKLIGHT device variable, then your application must do the following broadcast: WinBroadcastMsg (HWND_DESKTOP, WM_WRT_SYSVALUECHANGED, (MPARAM) VT_PPMID, (MPARAM) (PPMID_BACKLIGHT, BMSG_DESCENDANTS|BMSG_POST); ═══ 12.4. Receiving Notification Messages ═══ Your application will receive a WM_WRT_SYSVALUECHANGED notification message whenever any of the device variables are changed by any application. Your application will receive a WM_WRT_DEV_CAPS_CHANGE notification message whenever the device capabilities for any device is updated. Your application would obtain the new device configuration and capabilities after receiving the WM_WRT_DEV_CAPS_CHANGE message. ═══ 12.5. Controlling the Display Backlight ═══ Your application can control the LCD backlight with the WrtControlDisplayBacklight function and device variables PPMID_BACKLIGHT and PPMID_BACKLIGHT_INT. Your application can turn the display backlight on and off with the WrtControlDisplayBacklight function. Your application can use the PPMID_BACKLIGHT device variable to enable automatic display backlight control. The Pen for OS/2 program will automatically turn off the backlight when there has been no activity for a specific time period. This time period (in seconds) can be set with the PPMID_BACKLIGHT_INT device variable. The Pen for OS/2 program automatically turns the backlight back on again when the system is next used. ═══ 12.6. Using Buttons ═══ Your application can use the button device capabilities to determine the number of buttons present in a pen device driver. Your application can also determine if the buttons are on a locator device or on a display device. The state of all buttons is reported on each locator event. A hardware original equipment manufacturer would provide Workplace Shell configuration objects that assign actions to the buttons. ═══ 13. Part 2: Pen for OS/2 Programming Reference ═══ ═══ 14. Pen for OS/2 Writing Subsystem API ═══ The APIs in this chapter let developer's view and control stroke data and interact with the Pen for OS/2 system extension writing subsystem. ═══ 14.1. WrtQuerySysValue ═══ Syntax value = WrtQuerySysValue (HWND deskTop, ULONG valueid); Purpose This function queries the Pen for OS/2 writing input subsystem system value from memory. Parameters deskTop (HWND) - input The window handle of the PM deskTop. valueid (ULONG) - input Pen for OS/2 system value identity. (See description of values in "Using System Variables" .) PPMSV_PEN_PAUSE Pen pause variable PPMSV_TOUCH_PAUSE Touch pause PPMSV_MOUSE_PAUSE Mouse pause PPMSV_OTHER_PAUSE Other pause PPMSV_PEN_PAUSE_ENABLE Pen pause timeout enable PPMSV_TOUCH_PAUSE_ENABLE Touch pause timeout enable PPMSV_MOUSE_PAUSE_ENABLE Mouse pause timeout enable PPMSV_OTHER_PAUSE_ENABLE Other pause timeout enable PPMSV_PAUSEBEEPFREQ Pause beep frequency PPMSV_RECO_BEEP_ENABLE Enable beep for no recognition mapping PPMSV_MINGESTUREPOINTS Minimum number of gesture points PPMSV_RECOPTRTIMER Recognition pointer change time PPMSV_GESTURE_CANCEL_TIMEOUT Cancel gesture timeout value PPMSV_GESTURE_TIMEOUT Inter-stroke gesture timeout PPMSV_STANDARDIZED_RESOLUTION Standardized resolution (.001") PPMSV_CHARACTER_BOX_DX Character box cell width and height for PPMSV_CHARACTER_BOX_DY the handwriting pop-up window Character box dx and dy are read-only variables value (LONG) - return Pen for OS/2 system value. Returns Return codes indicating success or type of failure: WRTERR_INVALID_PARM Invalid parameter. Other System value. Remarks The valueid must be one of the PPMSV_* constants. If valueid is not valid, the value returned is WRTERR_INVALID_PARM. DeskTop is for future expansion. For the current version of the Pen for OS/2 program, it must be HWND_DESKTOP. ═══ 14.2. WrtSetSysValue ═══ Syntax rc = WrtSetSysValue (HWND deskTop, ULONG valueid, LONG value); Purpose This function sets the Pen for OS/2 system value in memory. Parameters deskTop (HWND) - input The window handle of the PM deskTop. valueid (ULONG) - input Pen for OS/2 system value identity. See PPMSV_* values. value (LONG) - input Pen for OS/2 system value. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_HWND deskTop is invalid. WRTERR_INVALID_ID The valueid is invalid. WRTERR_INVALID_PARM Invalid parameter. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_PARM_OUT_OF_RANGE Parameter out of range. Remarks The valueid must be one of the PPMSV_* constants. If valueid is not valid, the value returned is WRTERR_INVALID_PARM. DeskTop is for future expansion. For the current version of the Pen for OS/2 program, it must be HWND_DESKTOP. ═══ 14.3. WrtWriteSysValue ═══ Syntax rc = WrtWriteSysValue (HWND deskTop, ULONG valueid); Purpose This function writes the Pen for OS/2 system value from memory to the Pen for OS/2 profile. Parameters deskTop (HWND) - input The window handle of the PM deskTop. valueid (ULONG) - input Pen for OS/2 system value identity. See PPMSV_* values. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_HWND deskTop is invalid. WRTERR_INVALID_ID Invalid valueid for profile. WRTERR_INVALID_PARM Invalid parameter. WRTERR_WRITE_FAILED Error return from WinWriteProfileString. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. Remarks The valueid must be one of the PPMSV_* constants. If valueid is not valid, the value returned is WRTERR_INVALID_PARM. DeskTop is for future expansion. For the current version of the Pen for OS/2 program, it must be HWND_DESKTOP. WrtWriteSysValue writes the desired Pen for OS/2 system value from memory to the Pen for OS/2 profile. ═══ 14.4. WrtReadSysValue ═══ Syntax rc = WrtReadSysValue (HWND deskTop, ULONG valueid); Purpose This function reads the Pen for OS/2 system value for the Pen for OS/2 profile and sets the value in memory. Parameters deskTop (HWND) - input The window handle of the PM deskTop. valueid (ULONG) - input Pen for OS/2 system value identity. See PPMSV_* values. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_HWND deskTop is invalid. WRTERR_INVALID_ID Invalid valueid for profile. WRTERR_INVALID_PARM Invalid parameter. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. Remarks The valueid must be one of the PPMSV_* constants. If valueid is not valid, the value returned is WRTERR_INVALID_PARM. DeskTop is for future expansion. For the current version of the Pen for OS/2 system extension, it must be HWND_DESKTOP. WrtReadSysValue reads the desired Pen for OS/2 system value from the Pen for OS/2 profile and sets it in memory. Pen for OS/2 system values are not written to the Pen for OS/2 profile unless they have been changed through WrtWriteSysValue. When reading a value that has not been changed, a WRT_NO_ERROR return code will be returned, even though there was no entry for it in the Pen for OS/2 profile. ═══ 14.5. WrtWaitActive ═══ Syntax rc = WrtWaitActive (ULONG timeout); Purpose This function causes applications to wait until the pen subsystem has completed initialization. It is provided to prevent an application from making pen subsystem calls before the subsystem is ready to process them. Parameters timeout (ULONG) - input The number of milliseconds to wait for the pen subsystem to become active. A value of SEM_INDEFINITE_WAIT or SEM_IMMEDIATE_RETURN can also be specified. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_PARM Invalid parameter. WRTERR_PEN_NOT_STARTING The pen subsystem is not being started. WRTERR_WAIT_TIMEOUT Pen subsystem did not complete initialization. Remarks Typically, this function would be called during WM_CREATE message processing. If a faulty return code is returned and the application is reliant upon the pen subsystem, the window procedure would display an error message box to the user and post a WM_QUIT to itself to terminate the application. ═══ 14.6. WrtQueryStrokeData ═══ Syntax rc = WrtQueryStrokeData (PBYTE pStrokeBuf, PULONG pBufLen, HWND hwnd, ULONG flConvopt, ULONG ulXOutput, ULONG ulYOutput, ULONG flAuxData); Purpose This function is used to retrieve the current stroke buffer. Parameters pStrokeBuf (PBYTE) - output Address of the buffer in which the current stroke data is copied. If pBufLen is nonzero, pStrokeBuf must be a valid pointer. pBufLen (PULONG) - input/output Size of the buffer specified by the pStrokeBuf parameter. Overwritten with the number of bytes copied into the buffer. If the buffer size is insufficient, no stroke data is returned. If the ULONG pointed to by this parameter equals 0, the amount of storage required to buffer the stroke data is calculated and returned to the application in this field. hwnd (HWND) - input Handle of window for relative coordinates. NULL Coordinates are relative to DESKTOP window origin. Other Coordinates are made relative to specified window. flConvopt (ULONG) - input Conversion option for the X/Y coordinate array. QSD_NO_CNV No conversion from stroke device. QSD_SCALE Return in screen or specified resolution. QSD_STANDARDIZED_RES Return in standardized resolution. QSD_RESOLUTION If QSD_SCALE is specified, ulXOutput and ulYOutput are specified as X- and Y-axis resolution expressed in dots per inch. When QSD_RESOLUTION is not set, ulXOutput and ulYOutput are specified as X- and Y-axis extents. ulXOutput (ULONG) - input This parameter is only valid if QSD_SCALE was set in the flConvopt parameter. If QSD_RESOLUTION option is set, this value is the X-axis resolution to which to scale the X values in the POINTL structure array. If QSD_RESOLUTION option is not set, this value is the maximum X extent to which scale the X coordinates. If this value is NULL, the coordinate array will be converted to display resolution. NULL Coordinates are scaled to screen resolution. Other Coordinates are scaled to the specified resolution. ulYOutput (ULONG) - input This parameter is only valid if QSD_SCALE was set in the flConvopt parameter. If QSD_RESOLUTION option is set, this value is the X-axis resolution to which to scale the X values in the POINTL structure array. If QSD_RESOLUTION option is not set, this value is the maximum X extent to which scale the X coordinates. If this value is NULL, the coordinate array will be converted to display resolution. NULL Coordinates are scaled to screen resolution. Other Coordinates are scaled to the specified resolution. flAuxData (ULONG) - input Auxiliary data fields to be retrieved. A value of 0 will result in no auxiliary data being returned. One or more of the following flags may be specified: ADF_TIMESTAMP Point time stamp. ADF_FLAGS Point flags. ADF_USER For program use. ADF_SCREENZ Display Z-axis value. ADF_DEVZ Device Z-axis value. ADF_ANGLE Device angle. ADF_ROTATION Device rotation. ADF_BUTTON Button status. ADF_OEM Original equipment manufacturer specific data. ADF_ALL All fields. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_HWND Invalid window handle specified. WRTERR_INVALID_OPTION Invalid option bits specified. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid buffer pointer. WRTERR_STROKE_INVALID No stroke available or invalid. WRTERR_BUFFER_TOO_SMALL Too small. No data copied. WRTERR_STRUCT_NOT_INIT cbStructSize was not initialized. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. Remarks WRTERR_STROKE_INVALID is returned if no stroke is available. Strokes are only available for retrieval during WM_LIFTOFF or WM_STROKE message processing. The X/Y points are passed back as an array of POINTLs structures. Some pointing devices have a digitizer resolution equal to the display resolution (for example, a mouse). The cbStructSize field of the StrokeData structure must be initialized before calling WrtQueryStrokeData to actually retrieve the stroke data. /* Query amount of storage needed to buffer stroke data */ buflen = 0; option = ADF_TIMESTAMP | ADF_FLAGS; rc = WrtQueryStrokeData(NULL, &buflen, hwnd, QSD_SCALE, 0,0, option); if (!rc) { /* Allocate memory */ DosAllocMem((VOID *)pStrokeData, buflen, PAG_COMMIT | PAG_READ | PAG_WRITE); /* Initialize structure size */ pStrokeData->cbStructSize = sizeof (STROKEDATA); rc = WrtQueryStrokeData(pStrokeData, &buflen, hwnd, QSD_SCALE, 0,0, option); } If QSD_NORMALIZED_RES is specified, the ulXOutput and ulYOutput parameters are ignored and the coordinates are scaled up to a standardized resolution used by the installed handwriting and gesture recognition processors. Typically, this is 1000 points per inch resolution. Some auxiliary point data might not be supported by the configured hardware. Applications might query device capabilities to determine which auxiliary data is supported by the devices. When unsupported auxiliary data is retrieved, the value will be zero. No error is returned informing the application of the lack of hardware support. Examples /* Example - Handling auxiliary stroke data */ /* */ /* Get stroke data at display resolution and have the */ /* points mapped to the client window to ink and */ /* get point time stamps and flags. The time stamps and */ /* flags are moved into separate buffers for post */ /* processing. */ ULONG i; APIRET apirc; ULONG sdata_size; /* Size of stroke data */ PSTROKEDATA strokep; /* Ptr to stroke data */ PAUXDATAINFO pdi; /* Ptr to aux data description*/ PAUXSTROKEDATA psd; /* Ptr to aux stroke data */ ULONG ts_array[1000]; /* Buffer to hold time stamps */ USHORT fl_array[1000]; /* Buffer to hold flags */ ULONG fieldcnt, ts_ent, fl_ent; /* workers */ PULONG pul; PUSHORT pus; case WM_LIFTOFF: sdata_size = 0; apirc = WrtQueryStrokeData(NULL, &sdata_size, /* stroke size */ hwnd, /* hwnd */ QSD_SCALE, /* flConvt */ 0, /* ulXExtent */ 0, /* ulYExtent */ ADF_TIMESTAMP | /* flAuxData */ ADF_FLAGS | ADF_USER); if (apirc) return (MRESULT) LO_STROKE_PROCESSED; /* Quit if error */ /* occurred */ DosAllocMem((VOID *) &strokep, sdata_size, PAG_COMMIT | PAG_READ | PAG_WRITE); strokep->cbStructSize = sizeof (STROKEDATA); apirc = WrtQueryStrokeData(strokep, &sdata_size, /* stroke size */ hwnd, /* hwnd */ QSD_SCALE, /* flConvt */ 0, /* ulXExtent */ 0, /* ulYExtent */ ADF_TIMESTAMP | /* flAuxData */ ADF_FLAGS | ADF_USER); if (apirc) { DosFreeMem(strokep); /* Return memory */ return (MRESULT) LO_STROKE_PROCESSED; /* Quit if error occurred */ } /* Establish pointer to the time stamps */ pdi = strokep->pAuxInfo; /* Address desc block */ psd = strokep->pAuxData; /* Set aux data pointer */ /* Loop through each data item to find the entry for time stamps and flags */ for (i=0 ; i < pdi->ulNumElements ; i++ ) { if (pdi->addAuxDesc[i].id == ADT_TIMESTAMP) ts_ent = i; if (pdi->addAuxDesc[i].id == ADT_FLAGS) fl_ent = i; } /* Copy time stamps and flags to separate arrays */ for (i=0, k=0 ; i < strokep->ulNumPoints ; i++, k = i * pdi->ulAuxSize) { pul = (PULONG) &psd->bAuxData[k][pdi->addAuxDesc[ts_ent].offset]; ts_array[i] = *pul; pus = (PUSHORT) &psd->bAuxData[k][pdi->addAuxDesc[fl_ent].offset]; fl_array[i] = *pus; } return (MRESULT) LO_STROKE_PROCESSED; ═══ 14.7. WrtMapPointLong ═══ Syntax rc = WrtMapPointLong (HWND hwnd, PPOINTL pXY, ULONG flParms, ULONG ulXInput, ULONG ulYInput, ULONG ulXOutput, ULONG ulYOutput, ULONG ulCount); Purpose This function is used to scale an array of coordinates from a given resolution to a specified resolution with an option of mapping the points to a window. Parameters hwnd (HWND) - input Handle of window for relative coordinates. NULL Coordinates are relative to DESKTOP window origin. Other Coordinates are made relative to specified window. pXY (PPOINTL) - input/output Address of POINTL structure containing the X/Y coordinate to map. flParms (ULONG) - input Indicates whether the ulXInput, ulYInput, ulXOutput, and ulYOutput parameters are specified as resolution or as maximum extents. Contains none or some of the following flags: MP_RESOLUTION Parameters are specified as X-and Y-axis resolution expressed in dots per inch. If MP_RESOLUTION is not set, the parameters are expressed as maximum extents. MP_NO_SCALE Do not scale coordinates. MP_SCALE (Default) Scale points. ulXInput (ULONG) - input Extent or resolution of the X-axis for the input coordinates. If MP_RESOLUTION is not set, this value is X-axis extent of the input X coordinates. If MP_RESOLUTION is set, this value is the resolution of the X-axis in dots per inch. This parameter must be nonzero. ulYInput (ULONG) - input Extent or resolution of the Y-axis for the input coordinates. If MP_RESOLUTION is not set, this value is the Y-axis extent of the input Y coordinates. If MP_RESOLUTION is set, this value is the resolution of the Y-axis in dots per inch. This parameter must be nonzero. ulXOutput (ULONG) - input Extent or resolution of the X-axis for the output coordinates. If MP_RESOLUTION is not set, this value is the X-axis extent to which to scale the X coordinates in the POINTL structure array. If MP_RESOLUTION is set, this value is the X-axis resolution in dots per inch. This parameter is ignored if MP_NO_SCALE is specified. 0 Coordinates are scaled to screen resolution. Other Coordinates are scaled to the specified resolution. ulYOutput (ULONG) - input Extent or resolution of the Y-axis for the output coordinates. If MP_RESOLUTION is not set, this value is the Y-axis extent to which to scale the X coordinates in the POINTL structure array. If MP_RESOLUTION is set, this value is the Y-axis resolution in dots per inch. This parameter is ignored if MP_NO_SCALE is specified. 0 Coordinates are scaled to screen resolution. Other Coordinates are scaled to the specified resolution. ulCount (ULONG) - input The number of POINTLs in the array pointed to by pXY. Must be nonzero. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_INPUT Invalid input resolution. WRTERR_INVALID_HWND Invalid window handle specified. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid POINTL pointer. WRTERR_INVALID_COUNT Invalid POINTL count. WRTERR_INVALID_OPTION No hwnd and no scaling specified. Remarks When scaling coordinates, it always is more accurate to specify extents than resolution. The most common use of this function is to convert coordinates from either standardized or digitizer resolution to screen resolution to facilitate inking the stroke to the display. Both the resolution and the extents of a stroke can be found in the stroke data structure fields ulResolution, ulXExtent, and ulYExtent. When converting to display resolution, specify ulXOutput and ulYOutput as NULL. An error will be returned if no scaling (MP_NO_SCALE) is specified and no hwnd is provided to which to map the input coordinates. This function might be called either on a point-by-point basis to rescale each point or, at the lift-off point, to rescale all the points in the stroke. To optimize execution for calling the function as each point is received, no exception handling is performed if the count of coordinates is equal to 1. Programs will therefore take Trap D addressing exceptions if the POINTL array address is a nonzero, invalid address. For any given pointing device, WrtQueryLocatorCaps will provide: o Digitizer resolution o Digitizer X/Y extents o Standardized resolution X/Y extents The system standardized resolution can be determined by querying system value PPMSV_STANDARDIZED_RESOLUTION through the WrtQuerySysValue function. Typically, standardized resolution is 1000 points per inch resolution. For the display, WrtQuerySystemCaps will provide: o Display resolution o Display X/Y extents Due to rounding errors, scaling coordinates back and forth between high and low resolution will produce a set of coordinates slightly different from the original input. Generally, the coordinates will be off by a value of 1. Any time high resolution coordinates are scaled down to a lower resolution, information is lost. If accuracy is important, maintain high resolution and display-resolution stroke buffers instead of scaling the coordinates to display resolution and then rescaling back to high resolution. /* Query amount of storage needed to buffer stroke data */ buflen = 0; option = ADF_TIMESTAMP | ADF_FLAGS; rc = WrtQueryStrokeData(NULL, &buflen, NULL, 0, 0, 0, option); if (!rc) { /* Allocate memory */ DosAllocMem((VOID *)pStrokeData, buflen, PAG_COMMIT | PAG_READ | PAG_WRITE); /* Initialize structure size */ pStrokeData->cbStructSize = sizeof (STROKEDATA); /* Retrieve coordinates at digitizer resolution */ rc = WrtQueryStrokeData(pStrokeData, &buflen, NULL, 0, 0, 0, option); /* Scale coordinates to display resolution and map */ /* them to the client window. */ WrtMapPointLong(hwnd, pStrokeData->pXY, MP_SCALE, pStrokeData->ulYExtents, pStrokeData->ulYExtents, 0, 0, pStrokeData->ulNumPoints); } ═══ 14.8. WrtQueryPointAuxData ═══ Syntax rc = WrtQueryPointAuxData (PAUXPOINTDATA papdExtra); Purpose This function returns the auxiliary data associated with current point. A call to WrtQueryLocatorCaps will determine which fields in the structure are supported by the device and are valid. Parameters papdExtra (PAUXPOINTDATA) - output Pointer to an auxiliary point data structure. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid structure pointer. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. Remarks The structure returned is the device-specific data associated with the current point and, as such, this routine would only be called during WM_MOUSEMOVE or WM_SENSOR_MOVE processing. Calling this function when processing other messages will retrieve the auxiliary data from the last WM_MOUSEMOVE or WM_SENSOR_MOVE received. Before querying auxiliary point data, the cbStructSize field must be initialized. Because this function may be called up to 200 times per second, no exception handling is performed to keep execution time to a minimum. Therefore a nonzero, invalid address will result in a Trap D addressing exception. ═══ 14.9. WrtQueryEventData ═══ Syntax rc = WrtQueryEventData (PWRTEVENTDATA pedInfo); Purpose This function returns the event data associated with current point. A call to WrtQueryLocatorCaps will determine which fields in the structure are supported by the device and are valid. Parameters pedInfo (PWRTEVENTDATA) - output Pointer to an event data structure. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid structure pointer. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. WRTERR_INVALID_MOUSE_EVENT Mouse event not generated by pointing device. Remarks The structure returned contains data pertinent to the current mouse event. This function would be called only during the processing of a PM mouse message (such as messages between WM_MOUSEFIRST and WM_MOUSELAST). After returning from a mouse message, the event data is invalid. Before querying event data, the cbStructSize field must be initialized. Mouse messages that are generated by PM will not have associated event data because the message was not generated by the pointing device. A WRTERR_INVALID_MOUSE_EVENT error is returned in this case. Because this function may be called up to 200 times per second, no exception handling is performed to keep execution time to a minimum. Therefore a nonzero, invalid address will result in a Trap D addressing exception. ═══ 14.10. WrtSetStrictEmulation ═══ Syntax rc = WrtSetStrictEmulation (HWND hwnd, ULONG option); Purpose This function sets the calling application in a mouse emulation mode. Parameters hwnd (HWND) - input Handle of the frame window. option (ULONG) - input Contains one of the following values: SSE_RESET Reset strict mouse emulation. SSE_SET Set strict mouse emulation. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_INVALID_HWND Invalid window handle. WRTERR_INVALID_OPTION Invalid option. WRTERR_INVALID_PARM Invalid parameter. Remarks This API effectively removes all Pen for OS/2 system extension functionality and only mouse emulation is performed. This function is applied to all windows on a program or object (or both) basis. The intended purpose of this interface is to provide a very fast interface with minimum delay. The application trades off unneeded Pen for OS/2 functionality, such as gestures, for quick response time. An example application would be a Pop-Up Keyboard Tool that wants to maximize keystrokes per second processing. ═══ 14.11. WrtControlDisplayBacklight ═══ Syntax rc = WrtControlDisplayBacklight (ULONG option, ULONG displayID); Purpose This function is called by an application to control the state of the display backlight. Parameters option (ULONG) - input Controls display backlight. CDB_LIGHT_ON Turn backlight on. This option will also restart the blanking timer period if blanking is enabled. CDB_LIGHT_OFF Turn backlight off. displayID (ULONG) - input ID of the target display. If 0, the command will be sent to all configured displays that support backlight blanking. If there are no configured displays, an WRTERR_NO_DEVICE_CAPABILITY error is returned. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_PARM CDB_RESET_TIMER and CDB_LIGHT_OFF are mutually exclusive. WRTERR_INVALID_DISPLAY_ID Invalid display ID. WRTERR_NO_DEVICE_CAPABILITY Device does not support option. Remarks This routine is called by an application to control the state of the display backlight. If the CDB_LIGHT_ON option is specified, the backlight will be turned on if it is off. If backlight blanking is enabled, the blanking timer will also be reset. If the CDB_LIGHT_ON option is specified and the backlight is already on and backlight blanking is disabled, the command has no effect. If the CDB_LIGHT_OFF option is specified and the backlight is already off, the command has no effect. ═══ 14.12. WrtEnumInputDrivers ═══ Syntax rc = WrtEnumInputDrivers (PULONG pulNumDrivers, PSTR_32 aDriverNames); Purpose This function lists all the configured Pen for OS/2 input drivers. Parameters pulNumDrivers (PULONG) - input/output Maximum number of driver names that can be returned. If the ULONG pointed to by pulNumDrivers is: Zero The number of drivers will be calculated and returned in the ULONG. aDriverNames will not be updated. Nonzero The ULONG is updated to reflect the actual number of driver names returned in aDriverNames. aDRiverNames (PSTR_32) - output Array of null-terminated strings, each of which identifies an input driver. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_MORE_NAMES_AVAIL More names are available. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid buffer pointer. Remarks On the first call, if the ULONG pointed to by pulNumDrivers is set to 0, the number of drivers will be calculated and returned in the ULONG. The output buffer will contain an array of structures in the following format. (example - "ABC Color Tablet\0 WACOM SD-510C\0 MOUSE\0 ") ═══ 14.13. WrtQueryInputDeviceNames ═══ Syntax rc = WrtQueryInputDeviceNames (PSZ pszDriverName, PULONG pulNumDevices, PSTR_32 aDeviceName, PULONG aDeviceType, PULONG aDeviceID); Purpose This function lists all the devices registered by an input driver. Parameters pszDriverName (PSZ) - input Pointer to a null-terminated string containing the name of the input driver. pulNumDevices (PULONG) - input/output Number of device names and descriptions. If the ULONG pointed to by pulNumDevices is: Zero The number of names and descriptions supported is returned in the ULONG and the arrays parameters are not updated. Nonzero The ULONG is updated to reflect the number of names and descriptions returned and the arrays are updated. aDeviceName (PSTR_32) - output Device name array. aDeviceType (PULONG) - output Device type array. aDeviceID (PULONG) - output Device ID array. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_MORE_NAMES_AVAIL More names are available. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid buffer pointer. WRTERR_INVALID_DRIVER_NAME Invalid driver name. Remarks On the first call, if the ULONG pointed to by pulNumDevices is set to 0, the number of drivers are calculated and returned in the ULONG. The output buffer will contain an array of structures in the following format: Driver Name - "ABC Color Tablet" Device Name - "Pen" "Touch" "BezelButton" "ColorLCD" Device Type - DT_LOCATOR DT_LOCATOR DT_BUTTON DT_DISPLAY Device ID - 1 2 1 1 Driver Name - "WACOM SD-510C" Device Name - "Pen" "BarrelButton" Device Type - DT_LOCATOR DT_BUTTON Device ID - 3 2 Driver Name - "MOUSE" Device Name - "StockMouse" Device Type - DT_LOCATOR Device ID - 4 ═══ 14.14. WrtQuerySystemCaps ═══ Syntax rc = WrtQuerySystemCaps (PWRTSYSTEMINFO psiInfo); Purpose This function returns Pen for OS/2 system capabilities. Parameters psiInfo (PWRTSYSTEMINFO) - input/output Pointer to WRTSYSTEMINFO structure. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_BUFFER Invalid structure pointer. WRTERR_INVALID_PARM Invalid parameter. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. Remarks This function returns a structure that provides pertinent information about devices attached to the system. Before querying the system capabilities structure, the cbStructSize field must be initialized. ═══ 14.15. WrtQueryLocatorCaps ═══ Syntax rc = WrtQueryLocatorCaps (PULONG pulLocatorID, PWRTLOCATORDEVINFO pldiInfo); Purpose This function returns device capabilities for locator devices. Parameters pulLocatorID (PULONG) - input/output If pointing to a value of 0, the number of configured locators will be returned. If pointing to a nonzero value, it is the ID of the locator to be queried. pldiInfo (PWRTLOCATORDEVINFO) - input/output Pointer to WRTLOCATORDEVINFO structure. If pulLocatorID is pointing to a nonzero value, pldiInfo must contain a valid structure pointer. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 system extension is not active. WRTERR_INVALID_LOCATOR_ID Invalid locator ID. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid locatorID pointer. WRTERR_INVALID_BUFFER Invalid structure pointer. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. Remarks This function returns device capabilities for registered locator devices. If the function is called with pulLocatorID pointing to a value of 0, the number of configured locator devices is calculated and returned in the ULONG. Locator IDs are numbered 1 to N. If the value 3 is returned in the ULONG, the valid locator IDs are 1, 2, and 3. Before querying the locator capabilities structure, the cbStructSize field must be initialized. Examples In this code example, the application queries up to 5 registered pointing devices and maintains the configuration data for use at touchdown, mousemove, and liftoff time. Having more than 5 registered pointing devices would be highly unusual. ULONG i, ulLocatorID; APIRET apirc; PWRTEVENTDATA ped; #define MAX_DEVICES 5 static WRTLOCATORDEVINFO ldiInfo[MAX_DEVICES]; case WM_CREATE: /* Query configuration data for up to 5 pointing devices */ /* for use at touch down and lift off */ ulLocatorID = 0; ldiInfo[0].cbStructSize = sizeof (WRTLOCATORDEVINFO); apirc = WrtQueryLocatorCaps(&ulLocatorID, &ldiInfo[0]); for (i=1 ; i <= ulLocatorID && i <= MAX_DEVICES ; i++) { ldiInfo[i-1].cbStructSize = sizeof (WRTLOCATORDEVINFO); apirc = WrtQueryLocatorCaps(&i, &ldiInfo[i-1]); } break; case WM_LIFTOFF: ped = (PWRTEVENTDATA) mp2; if (!(ped->flEventStatus & WRT_STROKE_AVAIL) || /* No stroke buffer avail */ !(ped->flEventStatus & WRT_TD_LO_SAME_HWND) || { /* Not our Stroke */ ped->ulLocatorID > MAX_DEVICES) /* Or unknown device */ return (MRESULT) FALSE; /* Do not process it */ } /* Determine type of pointing device */ switch (ldiInfo[ped->ulLocatorID-1].ulLocatorType) { case LT_PEN: break; case LT_TOUCH: break; case LT_MOUSE: break; default: break; } /* endswitch */ ═══ 14.16. WrtQueryButtonCaps ═══ Syntax rc = WrtQueryButtonCaps (PULONG pulButtonID, PWRTBUTTONDEVINFO pbdiInfo); Purpose This function returns device capabilities for button devices. Parameters pulButtonID (PULONG) - input/output If pointing to a value of 0, the number of configured button devices will be returned. If pointing to a nonzero value, it is the ID of the button device to be queried. pbdiInfo (PWRTBUTTOBDEVINFO) - input/output Pointer to WRTBUTTONDEVINFO structure. If the ULONG pointed to by pulButtonIDis nonzero, pbdiInfo must contain a valid structure pointer. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_BUTTON_ID Invalid button ID. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid buttonID pointer. WRTERR_INVALID_BUFFER Invalid structure pointer. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. Remarks This function returns device capabilities for registered button devices. If the function is called with the ULONG pointed to by pulButtonID set to 0, the number of configured button devices is calculated and returned in the ULONG. Button device IDs are numbered 1 to N. If the value 3 is returned in the ULONG, the valid button device IDs are 1, 2, and 3. Before you query WrtQueryButtonCaps, the cbStructSize field must be initialized. ═══ 14.17. WrtWrtQueryDisplayCaps ═══ Syntax rc = WrtWrtQueryDisplayCaps (PULONG pulDisplayID, PWRTDISPLAYDEVINFO pddiInfo); Purpose This function returns device capabilities for display devices. Parameters pulDisplayID (PULONG) - input/output If pointing to a value of 0, the number of configured display devices will be returned. If pointing to a nonzero value, it is the ID of the display device to be queried. pddiInfo (PWRTDISPLAYDEVINFO) - input/output Pointer to WRTDISPLAYDEVINFO structure. If the ULONG pointed to by pulDisplayID is nonzero, pddiInfo must contain a valid structure pointer. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 subsystem is not active. WRTERR_INVALID_BUTTON_ID Invalid button ID. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid displayID pointer. WRTERR_INVALID_BUFFER Invalid structure pointer. WRTERR_STRUCT_NOT_INIT cbStructSize field not initialized. Remarks This function returns device capabilities for registered display devices. If the function is called with the ULONG pointed to by pulDisplayID set to 0, the number of configured display devices is calculated and returned in the ULONG. Display device IDs are numbered 1 to N. If the value 2 is returned in the ULONG, the valid display device IDs are 1 and 2. Before you query WrtWrtQueryDisplayCaps, the cbStructSize field must be initialized. ═══ 14.18. WrtSetInputDeviceVariable ═══ Syntax rc = WrtSetInputDeviceVariable (PSZ pszDriverName, PSZ pszDeviceName, ULONG ulValueID, LONG lValue, ULONG ulDatalen, PVOID pData); Purpose Sets a Pen for OS/2 input device variable. This function is called by the Workplace Shell Setup objects that control the Pen for OS/2 input devices. Parameters pszDriverName (PSZ) - input Pointer to a null-terminated string containing the driver name. pszDeviceName (PSZ) - input Pointer to a null-terminated string containing the device name. When setting a driver specific parameter such as PPMID_DEVICE_PARMS, pszDeviceName should be "Driver". ulValueId (ULONG) - input Input device variable ID. Contains none or some of the following flags: PPMID_MOTION_STOP Stops motion filter. PPMID_MOTION_START Starts motion filter. PPMID_MINGESTURELENGTH Minimum gesture size. PPMID_DISABLE_PROXIMITY Disables proximity events. PPMID_POINT_RATE Maximum point rate. PPMID_DIVIDE_RATE Divide rate. PPMID_BACKLIGHTBLANK Blanking enable. PPMID_BACKLIGHTBLANK_INT Blanking timer interval. PPMID_TOUCHOFFSET_X Displays offset between fingertip and the screen's pointer icon (X). PPMID_TOUCHOFFSET_Y Displays offset between fingertip and the screen's pointer icon (Y). PPMID_DEVICE_PARMS Device specific data. lValue (LONG) - input New value of variable. ulDatalen (ULONG) - input The length of the binary calibration data when option PPMID_DEVICE_PARMS is specified. Otherwise, this parameter is ignored. The length of the calibration data cannot exceed 512 bytes. pData (PVOID) - input A pointer to the binary calibration data when option PPMID_DEVICE_PARMS is specified. Otherwise, this parameter is ignored. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen subsystem is not active. WRTERR_INVALID_DRIVER_NAME Invalid driver name. WRTERR_INVALID_DEVICE_NAME Invalid device name. WRTERR_INVALID_ID Invalid valueid. WRTERR_PARM_OUT_OF_RANGE Parameter out of range. WRTERR_INVALID_BUFFER Faulty buffer pointer, buffer is too small, or buffer is too large. WRTERR_INVALID_PARM Invalid parameter. WRTERR_VALUEID_DEVICE_MISMATCH Value/device mismatch. WRTERR_NO_DEVICE_CAPABILITY Device does not support option. Remarks This function sets an input device variable for the specified device. The variable is passed to the associated device driver and is written to the profile. A WRTERR_VALUEID_DEVICE_MISMATCH error is a result of trying to set a parameter like PPMID_BACKLIGHTBLANK for a "Pen" device. A WRTERR_NO_DEVICE_CAPABILITY is a result of trying to set a parameter such as PPMID_BACKLIGHTBLANK for a "Display" device that does not support backlight blanking. ═══ 14.19. WrtQueryInputDeviceVariable ═══ Syntax rc = WrtQueryInputDeviceVariable (PSZ pszDriverName, PSZ pszDeviceName, ULONG ulValueID, PLONG plValue, PULONG pulDatalen, PVOID pData); Purpose Queries a Pen for OS/2 input device variable. This function is called by Workplace Shell Setup objects that control the associated device. Parameters pszDriverName (PSZ) - input Pointer to a null-terminated string containing the driver name. pszDeviceName (PSZ) - input Pointer to a null-terminated string containing the device name. When setting a driver specific parameter such as PPMID_DEVICE_PARMS, pszDeviceName should be "Driver". ulValueId (ULONG) - input Input device variable ID. Contains none or some of the following flags: PPMID_MOTION_STOP Stops motion filter. PPMID_MOTION_START Starts motion filter. PPMID_MINGESTURELENGTH Minimum gesture size. PPMID_DISABLE_PROXIMITY Disables proximity events. PPMID_POINT_RATE Maximum point rate. PPMID_DIVIDE_RATE Divide rate. PPMID_BACKLIGHTBLANK Blanking enable. PPMID_BACKLIGHTBLANK_INT Blanking timer interval. PPMID_TOUCHOFFSET_X Displays offset between fingertip and the screen's pointer icon (X). PPMID_TOUCHOFFSET_Y Displays offset between fingertip and the screen's pointer icon (Y). PPMID_DEVICE_PARMS Device specific data. plValue (PLONG) - output Pointer to a LONG to receive the current value of the variable. pulDatalen (PULONG) - input/output Pointer to the length of the binary calibration data when option PPMID_DEVICE_PARMS is specified. Otherwise, this parameter is ignored. The length of the device data can range from 1 to 512 bytes. Programs may query the size of the device data by specifying a length of 0. When the ULONG pointed to by pulDatalen is 0, the pData parameter is ignored and the ULONG is updated with the actual size of the device data. When retrieving device data, the ULONG pointed to by pulDatalen must be greater than or equal to the size of the device data. pData (PVOID) - input/output A pointer to the buffer in which to receive the device data when PPMID_DEVICE_PARMS is specified. Otherwise, this parameter is ignored. This parameter is also ignored when querying the size of of the device data. rc (APIRET) - return Returns Return codes indicating success or type of failure: WRT_NO_ERROR Successful. WRTERR_NOT_ACTIVE Pen for OS/2 writing input subsystem is not active. WRTERR_INVALID_DRIVER_NAME Invalid driver name. WRTERR_INVALID_DEVICE_NAME Invalid device name. WRTERR_INVALID_ID Invalid valueID. WRTERR_INVALID_PARM Invalid parameter. WRTERR_INVALID_POINTER Invalid plValue pointer. WRTERR_INVALID_BUFFER Faulty buffer pointer or buffer is too small. WRTERR_VALUEID_DEVICE_MISMATCH Value/device mismatch. WRTERR_NO_DEVICE_CAPABILITY Device does not support option. Remarks This function queries an input device variable for the specified device. Input device variables are maintained for each configured device. During device initialization, the default values are set, unless a profile entry exists for that device. Input device variables will exist only in the profile if the associated Workplace Shell Setup Object made an entry at installation or if a user modified the value. A WRTERR_VALUEID_DEVICE_MISMATCH error is a result of trying to query a parameter like PPMID_BACKLIGHTBLANK for a "Pen" device. A WRTERR_NO_DEVICE_CAPABILITY is a result of trying to query a parameter such as PPMID_BACKLIGHTBLANK for a "Display" device that does not support backlight blanking. ═══ 15. Pen for OS/2 Writing Subsystem Messages ═══ The messages in this chapter include notification messages that report various asynchronous events and device proximity events that report changes in state. ═══ 15.1. WM_TOUCHDOWN ═══ This message indicates that the user has made contact with the surface, using either the pen, finger, or mouse. The message is sent to the window under the point of contact through WinSendMsg. The application is provided with the status of the configured bezel buttons and whether the stroke is going to be inked by default. It is at this time that the application might specify: o The delay between the touch-down point and the mouse-button-down event message o Whether to override the default inking o The options to receive coordinate data at full bandwidth An example message follows and the associated parameters are explained: WM_TOUCHDOWN -- User has made contact with the surface DelayCode = WinSendMsg(hwnd, WM_TOUCHDOWN, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes DelayCode (MRESULT) Delay between WM_TOUCHDOWN and WM_BUTTONxDOWN: Contains one of the following flags: TDN_DEFAULT_DELAY Use the default delay. TDN_IMMEDIATE No delay. The application will receive the WM_BUTTONxDOWN message immediately. Note that a stroke buffer is not built when this option is specified. TDN_INFINITE Infinite delay. The application will not receive a WM_BUTTONxDOWN message. Inking options: Contains one of the following flags: TDN_INK_STROKE Ink the stroke. TDN_NO_INK_STROKE Do not ink stroke. TDN_LEAVE_INK Do not de-ink the stroke at the lift-off point. The stroke will remain inked except if the stroke contained points that were outside the touch-down window. In this case, the stroke will be de-inked. Contains one of the following flags: TDN_HIFREQ_MOUSEMOVE Pass all received points as WM_MOUSEMOVE messages. These messages are sent at the hardware sampling rate through WinSendMsg. Receiving high frequency WM_MOUSEMOVEs does not prevent the user from retrieving the stroke buffer at the lift-off point. TDN_SENSOR_MOVE Pass all received points as WM_SENSOR_MOVE messages. See WM_SENSOR_MOVE message. ═══ 15.2. WM_LIFTOFF ═══ The WM_LIFTOFF message indicates that the user has broken contact with the surface. The message is sent through WinSendMsg to the window that normally would have received the WM_BUTTONxUP message so that the subsequent processing, including mouse emulation, can be specified. If another window had captured the mouse, the message would have been routed to that window. If the user moved the pointer device and lifted off before the delay timeout, a stroke might be available. If the WRT_STROKE_AVAIL flag is set in the flEventStatus field of the WRTEVENTDATA structure pointed to by mp2, the application may query the size of the stroke buffer and retrieve it (obtain a copy of its contents) through WrtQueryStrokeData. The stroke will be made invalid subsequent to the handling of this message, so the application must retrieve it before returning from this call. When gestures are drawn, an application will not receive WM_LIFTOFF messages because the message is rerouted to the gesture-compatibility window, which collects strokes and performs gesture recognition on behalf of the window. When LO_EMULATE_MOUSE is returned from WM_LIFTOFF, WM_BUTTONxDOWN and WM_BUTTONxUP events are generated to perform mouse emulation. If the application returns LO_STROKE_PROCESSED, the application has performed all processing of the message and no further action is taken. When LO_DEFAULT is returned, A WM_STROKE message is generated and sent to the application. An example message follows and the associated parameters are explained: WM_LIFTOFF -- User has broken contact with the surface fProcessed = WinSendMsg(hwnd, WM_LIFTOFF, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes fProcessed (MRESULT) Contains none or some of the following flags: LO_DEFAULT Continue with gesture recognition. LO_EMULATE_MOUSE Skip gesture recognition and do mouse emulation. LO_STROKE_PROCESSED Application handle stroke. Do no further processing. ═══ 15.3. WM_STROKE ═══ This message is always sent through WinSendMsg. The WM_STROKE message indicates that a stroke is available because the the liftoff window did not handle the stroke during WM_LIFTOFF processing. The format is exactly the same as the WM_LIFTOFF message except that mp1 contains the sequence number of the stroke so that an application can later reference that stroke in the doodle object. An example message follows and the associated parameters are explained: WM_STROKE -- Stroke is available fProcessed = WinSendMsg(hwnd, WM_STROKE, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes fProcessed (MRESULT) Contains none or some of the following flags: STK_DEFAULT Send WM_TAP message, if appropriate; then do mouse emulation. STK_STROKE_PROCESSED Application handled stroke. Do no further processing. ═══ 15.4. WM_SENSOR_MOVE ═══ This message indicates the movement of the pen or finger. It is sent through WinSendMsg upon receiving a WM_TOUCHDOWN return from an application with the TDN_SENSOR_MOVE flag set. The coordinates contained in mp1 are high resolution and the WrtMapPointLong routine must be called to convert them to screen coordinates and map them to the application's window if they are to be inked. WM_SENSOR_MOVE messages are generated at the digitizer-sampling rate and provide the application with the digitizer-coordinate data real time as opposed to the standard method of collecting the buffered coordinate data at the lift-off point. Given the arrival rate of WM_SENSOR_MOVES, applications should keep WM_SENSOR_MOVE processing to a minimum, preferably under 2 milliseconds of execution time. If the application falls behind in the processing of WM_SENSOR_MOVE messages, subsequent WM_SENSOR_MOVE messages will not be discarded or coalesced. The messages will remain buffered in the Pen for OS/2 Writing Subsystem until they can be dequeued and sent to the application. Note that coordinates will be relative when reported by relative devices, which means the coordinates will be expressed as on offset from the last location instead of as an absolute X/Y location. An example message follows and the associated parameters are explained: WM_SENSOR_MOVE -- Change of touch or pen position WinSendMsg(hwnd, WM_SENSOR_MOVE, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes None. ═══ 15.5. WM_TAP ═══ This message is sent through WinSendMsg and will be sent to the capture window, if any. If no window has the capture, then the window under the cursor gets the message. Position is always relative to the window receiving this message. This message indicates that the user tapped on the surface where a tap is defined as touching down and lifting off before a pause timeout occurs. An example message follows and the associated parameters are explained: WM_TAP -- Tap fProcessed = WinSendMsg(hwnd, WM_TAP, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes fProcessed (MRESULT) Contains none or some of the following flags: TP_TAP_PROCESSED Program processed tap message. Take no other action. TP_DEFAULT Perform mouse emulation, except when you are processing the touch-down message. ═══ 15.6. WM_DBL_TAP ═══ This message is sent through WinSendMsg and will be sent to the capture window, if any. If no window has the capture, then the window under the cursor gets the message. Position is always relative to the window receiving this message. This message indicates that the user tapped twice on the digitizer where the second tap occurred within a period of time less than the double-click time. The second WM_TAP message is converted to a WM_DBL_TAP message before it is sent to the application. An example message follows and the associated parameters are explained: WM_DBL_TAP -- Double Tap fProcessed = WinSendMsg(hwnd, WM_DOUBLE_TAP, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes fProcessed (MRESULT) Contains none or some of the following flags: TP_TAP_PROCESSED Program processed tap message. Take no other action. TP_DEFAULT Perform mouse emulation, except when you are processing the touch-down message. ═══ 15.7. WM_PAUSE_TIMEOUT ═══ This message is sent through WinSendMsg and will be sent to the capture window, if any. If no window has the capture, then the window under the cursor gets the message. Position is always relative to the window receiving this message. This message indicates that the pause timer expired during a gesture and mouse emulation mode was entered. An example message follows and the associated parameters are explained: WM_PAUSE_TIMEOUT -- Pause Timeout fProcessed = WinSendMsg(hwnd, WM_PAUSE_TIMEOUT, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes fProcessed (MRESULT) Indicates success or failure of the operation. PTO_DEFAULT A WM_BUTTONxDOWN message will be generated and routed to the target application. PTO_CONTINUE The pause timeout is ignored and no mouse emulation is performed. The building of the stroke buffer continues. ═══ 15.8. WM_EXIT_PROXIMITY ═══ This message is sent through WinSendMsg and will be sent to the capture window, if any. If no window has the capture, then the window under the cursor gets the message. Position is always relative to the window receiving this message. This message indicates that the pen has exited the proximity region of the digitizer. This message can be used as a stimulus to process strokes data as leaving the proximity region. It is an indication of a temporary cessation of pen input. Not all digitizers provide proximity capability. An application can determine this through a call to WrtQueryLocatorCaps. An example message follows and the associated parameters are explained: WM_EXIT_PROXIMITY -- Pen Exit Proximity fProcessed = WinSendMsg(hwnd, WM_EXIT_PROXIMITY, mp1, mp2) Parameters mp1 ptsPointerPos (POINTS) Pointer position. The pointer position is in window coordinates relative to the bottom-left corner of the window. Note: mp1 can be addressed through PM MOUSEMSG macro. mp2 pedEventData (PWRTEVENTDATA) Pointer to an event data assigned with the current pointer. Return Codes None. ═══ 15.9. WM_WRT_DEV_CAPS_CHANGE ═══ This message is posted through WinBroadcastMsg to all frame windows whenever there has been a change in device capabilities. Pen drivers notify Pen for OS/2 Writing Subsystem whenever there has been a change in device capabilities and Pen for OS/2 Writing Subsystem in turn notifies applications. An example of a device capability change would be a change in calibration, the enabling/disabling of hardware such as bezel or barrel buttons, or the reduction in point rate. Applications that have intimate knowledge of device capabilities or rely heavily on certain hardware features should call Pen for OS/2 Writing Subsystem function WrtQuery*Caps to determine the new device capabilities when handling this message. An example message follows and the associated parameters are explained: WM_WRT_DEV_CAPS_CHANGE - Device Capabilities Change Notification WinBroadcastMsg(hwnd, WM_WRT_DEV_CAPS_CHANGE, mp1, mp2); Parameters mp1 deviceID (USHORT) The ID of the device reporting a change in device capabilities. devicetype (USHORT) Device type. (See DT_* values that follow.) DT_* values for mp1 of the WM_WRT_DEV_CAPS_CHANGE message. #define DT_LOCATOR 0x03 /* locator device */ #define DT_BUTTON 0x04 /* button device */ #define DT_DISPLAY 0x05 /* display device */ mp2 NULL (MPARAM) Return Codes None. ═══ 15.10. WM_WRT_SYSVALUECHANGED ═══ This message is posted through WinBroadcastMsg to all windows whenever a Pen for OS/2 system value has changed. It is the responsibility of the application changing the system value to broadcast the message. Applications sensitive to changes in Pen for OS/2 system variables should examine mp1 and mp2 to determine the changed variables and call Pen for OS/2 Writing Subsystem function WrtQuerySysValue or WrtQueryInputDeviceVariable to retrieve the new value. An example message follows and the associated parameters are explained: WM_WRT_SYSVALUECHANGED - Pen for OS/2 System Value Change Notification WinBroadcastMsg(hwnd, WM_WRT_SYSVALUECHANGED, mp1, mp2); Parameters mp1 Type of Pen for OS/2 program variable that changed. Contains none or some of the following flags: VT_PPMSV Pen for OS/2 system variable (see "Using System Variables" for information on PPMSV_*) VT_PPMID Pen for OS/2 input device variable (see "Using Device Drivers" for information on PPMID_*) mp2 PPMID_* values for mp2 of WM_WRT_SYSVALUECHANGED. mp2 might also contain PPMSV_* values defined elsewhere. PPMID_MOTION_STOP Amount of movement in thousandths of an inch to determine cessation of motion PPMID_MOTION_START Amount of movement in .001" to determine start of motion PPMID_MINGESTURELENGTH Minimum gesture length in .001" PPMID_DISABLE_PROXIMITY Disable proximity event reporting PPMID_TOUCHOFFSET_X X offset of cursor relative to finger PPMID_TOUCHOFFSET_Y Y offset of cursor relative to finger PPMID_BACKLIGHTBLANK Enable blanking of backlight PPMID_BACKLIGHTBLANK_INT Timer value to blank backlight PPMID_POINT_RATE Number of points generated per second PPMID_DIVIDE_RATE Divide rate for points passed to OS/2 PPMID_DEVICE_PARMS Device specific data. Usually calibration data Return Codes None. ═══ 16. Pen for OS/2 Writing Subsystem Data Structures ═══ This section contains the data structures used within the Pen for OS/2 system extension writing subsystem. ═══ 16.1. Stroke Data ═══ A stroke buffer is built in real time as points are passed to the system from the digitizer. The Pen for OS/2 subsystem buffers all points so that none are lost due to the coalescing of mouse moves by the PM system. The user is notified of the availability of a stroke buffer through the WM_LIFTOFF or WM_STROKE message. It is at this time that the application can retrieve it. After WM_LIFTOFF and WM_STROKE processing, the stroke buffer is marked invalid and can no longer be retrieved. To retrieve the stroke buffer, the application must first query the size (WrtQueryStrokeData) to allocate sufficient storage in which to store it. It then obtains the stroke buffer through the WrtQueryStrokeData function. The stroke buffer may be retrieved multiple times, each time specifying different parameters. For example, an application might request the stroke in high-resolution coordinates to ink the stroke in a high-resolution bit map. It then might request the stroke in window coordinates to ink it on the display. Coordinate data is passed as a POINTL array to accommodate the standard GPI functions. The Pen for OS/2 writing subsystem currently limits the size of the stroke buffer to a maximum 1000 points or a stroke 9 seconds in length. After 1000 points have been buffered, subsequent points are discarded and the WRT_BUFFER_OVERRUN flag is set in the ulEventStatus field of the WRTEVENTDATA structure. The flag is also set in the stroke buffer header field flStrokeFlags. The Pen for OS/2 stroke data format will accommodate the increased data delivered by original equipment manufacturer device drivers. typedef struct _STROKEDATA { ULONG cbStructSize; // Size of stroke data header ULONG ulSource; // See Wrt Event Sources ULONG ulSeq; // Sequence number wraps at 4G ULONG ulResolution; // Points per inch ULONG ulSampleRate; // Points per second RECTL rclCell; // Bounding box around stroke ULONG ulNumPoints; // Number of points in stroke ULONG flStrokeFlags; // Stroke flags (See SBF_*) ULONG ulXExtent; // X extent used to scale coords. ULONG ulYExtent; // Y extent used to scale coords. ULONG ulSensorResolution; // Resolution of digitizer ULONG ulSensorXExtent; // Extent of digitizer X-axis ULONG ulSensorYExtent; // Extent of digitizer Y-axis ULONG ulTimestamp; // Time stamp of button-down ULONG ulDevTimestampRes; // Resolution of device TS in usecs PPOINTL pXY; // Pointer to X/Y POINTL array PAUXDATAINFO pAuxInfo; // Pointer to AUXDATAINFO PAUXSTROKEDATA pAuxData; // Pointer to AUXPOINTDATA ULONG ulUser1; // For program use ULONG ulUser2; // For program use struct _STROKEDATA *psdFwd; // Use: Forward chain pointer struct _STROKEDATA *psdBack; // Use: Backward chain pointer } STROKEDATA; // Note: ulSensorResolution, ulSensorXExtent and ulSensorYExtent // are only meaningful if the QSD_STANDARDIZED_RES option // was specified. This is so the original resolution information // can be recovered at a later time. // // pAuxInfo and pAuxData are only meaningful if option auxiliary // data was requested. // /* Stroke Buffer Flags */ #define SBF_SCREEN 0x00000001 // 1=Screen coords 0=hi res coord #define SBF_SCALE 0x00000001 // 1=Scaled coords 0=hi res coord #define SBF_INKED 0x00000002 // Stroke was inked #define SBF_INK_NOT_REMOVED 0x00000004 // Stroke left inked #define SBF_TD_LO_SAME_HWND 0x00000008 // Touchdown/liftoff in same hwnd #define SBF_STROKE_OUTSIDE_HWND 0x00000010 // Stroke left the boundaries #define SBF_POINTS_LOST 0x00000040 // Points were lost (HW overrun) #define SBF_BUFFER_OVERRUN 0x00000080 // Points were lost (SB overrun) #define SBF_MBUTTON_MASK 0x00001C00 // Mask for isolating mouse button #define SBF_TAP 0x00002000 // Stroke was a tap #define SBF_DBLTAP 0x00004000 // Stroke was a double tap #define SBF_NEGATIVE_COORDS 0x80000000 // Contains negative window coord Stroke Data Format ═══ 16.2. Auxiliary Digitizer Data ═══ An application may request additional point-stream data associated with the stroke when retrieving the stroke buffer. This device-dependent data provides Z-axis data and time stamps for application use. The auxiliary data may be queried either on a stroke or point basis. Since the auxiliary data of a stroke can consume large amounts of storage, a dynamic format is used so that an application can retrieve only those fields that are needed. When the data is retrieved on a point-by-point basis, a complete auxiliary data structure is passed to the application and the application is free to retain the data fields of interest. ═══ 16.2.1. Auxiliary Stroke Data Structure ═══ To accommodate applications needing device-specific data and reduce storage requirements for applications needing only partial device data, the auxiliary stroke data structure is defined as a dynamic structure whose format is controlled by the requesting application. Example Stroke Buffer Auxiliary Data Description Array 00000048 Size of AuxDataInfo ┌───────────────┐ . 00000003 Number of elements │ Stroke Data │ . 00000008 Size of auxiliary data packet │ Header │ . 00000000 Description (Time stamp) │ │ . 00000000 Offset ├───────────────┤ . 00000004 Size │ X/Y │ . 00000001 Description (Flags) │ Coordinate │ . 00000004 Offset │ Array │ . 00000002 Size ├───────────────┤ 00000008 Description (User) │ Auxiliary │ . . . 00000006 Offset │ Data │ . 00000002 Size │ Information │ . . . . ├───────────────┤ . . . . Auxiliary Data Array (for each X/Y coordinate) │ │ . │ Auxiliary │ . . . 000348F8 AuxData[0] │ Data │ 0022 │ Array │ 0000 │ │ 00034919 AuxData[1] └───────────────┘ . 0022 . 0000 . 0003493A AuxData[2] . 0022 . 0000 . 0003495B AuxData[3] . 0022 . 0000 * Example Auxiliary Stroke Data Description Format typedef struct _AUXDATADESC //add { ULONG id; // Auxiliary data type identity (See ADT_*) ULONG offset; // Field offset ULONG cb; // Auxiliary data type byte count } AUXDATADESC; typedef AUXDATADESC *PAUXDATADESC; /* AUXDATADESC.id Equates */ #define ADT_TIMESTAMP 0 // Point time stamp #define ADT_FLAGS 1 // Point flags #define ADT_SCREENZ 2 // Normalized Z-axis value #define ADT_DEVZ 3 // Device Z-axis value #define ADT_ANGLE 4 // Stylus angle to XY #define ADT_ROTATION 5 // Stylus rotation #define ADT_BUTTON 6 // Button status #define ADT_USER 7 // For program use #define ADT_OEM 16 // OEM specific data typedef struct _AUXDATAINFO // adi { ULONG cbAuxDesc; // Size of auxiliary // description structure ULONG ulNumElements; // Number of data elements in // auxiliary data packet ULONG ulAuxSize; // Length of auxiliary data packet // Size of auxiliary // description structure AUXDATADESC addAuxDesc[1]; // Array of descriptors } AUXDATAINFO; typedef AUXDATAINFO *PAUXDATAINFO; // padi typedef struct _AUXSTROKEDATA // asd { UCHAR bAuxData[1][1]; // Auxiliary stroke data } AUXSTROKEDATA; typedef AUXSTROKEDATA *PAUXSTROKEDATA; // pasd Auxiliary Stroke Data Format ═══ 16.2.2. Auxiliary Point Data Structure ═══ Auxiliary data may also be queried point-by-point in real time while processing WM_MOUSEMOVE or WM_SENSOR_MOVE messages in the window procedure. To expedite the retrieval of point auxiliary data, the data is presented as a fixed structure instead of a dynamic structure as when retrieved by strokes. A call to WrtQueryLocatorCaps will tell your application which fields are valid and supported by the device. Before querying point data, the cbStructSize field must be initialized. typedef struct _AUXPOINTDATA // apd { USHORT cbStructSize; // Structure size ULONG ulTimestamp; // Point time stamp USHORT usFlags; // Point flags USHORT usUser; // For program use SHORT sScrZ; // Normalize Z-axis value // (4K to -4k) // Height 0 to 4096 // Pressure 0 to -4096 SHORT sDevZ; // Device Z-axis value is // device dependent. See // locator caps structure. SHORT sAngle; // Pen angle to XY SHORT sRotation; // Pen rotation USHORT usButton; // Button status UCHAR OEM[8]; // Original equipment // manufacturer specific data } AUXPOINTDATA; typedef AUXPOINTDATA *PAUXPOINTDATA; // papd /* AUXPOINTDATA.usFlags Equates */ #define APD_MODEMASK 0x0003 Mode mask (see below) #define APD_IDLEMODE 0 Stylus is idle #define APD_PROXMODE 1 Stylus is in proximity #define APD_CONTACTMODE 2 Stylus is in contact #define APD_FILTERED 0x0004 Mouse event not passed to PM Auxiliary Point Data Format ═══ 16.3. WRT Event Data Structure ═══ This data structure is built on every mouse-button transition and exit-proximity event. The structure is passed to the target window through a pointer in qmsg.mp2 for the following messages: o WM_TOUCHDOWN o WM_LIFTOFF o WM_STROKE o WM_TAP o WM_DTAP o WM_PAUSE_TIMEOUT o WM_EXIT_PROXIMITY o WM_SENSOR_MOVE This information can also be retrieved during WM_MOUSEMOVE processing by calling WrtQueryEventData. typedef struct _WRTEVENTDATA // ed { ULONG cbStructSize; // Structure size USHORT usKCFlags; // KC flags from mouse button event // (See PM's KC_* flags) USHORT usHitTest; // Hit test from mouse-button event ULONG flEventStatus; // Event status (See WRT_*) POINTL ptlDisplay; // Display X/Y coordinate POINTL ptlSensor; // Digitizer X/Y coordinate POINTL ptlStandard; // Standard X/Y coordinate ULONG ulStrokeSeq; // Stroke seq (Only on liftoff) ULONG ulStrokeSize; // Stroke size (Only on liftoff) ULONG ulLocatorID; // Locator device ID ULONG ulLocatorType; // Locator Type (See LT_*) ULONG ulLocatorFlags; // Locator Flags (See LTYPE_*) ULONG ulValidityFlags; // Aux data validity flags (See ADF_*) ULONG ulButtonStatus; // Button status HWND hwndUnderPtr; // Hwnd under pointer } WRTEVENTDATA; typedef WRTEVENTDATA *PWRTEVENTDATA; // ped /* WRTEVENTDATA.ulEventStatus Values */ #define WRT_STROKE_AVAIL 0x00000001 // Stroke is avail for retrieval #define WRT_INKING 0x00000002 // Stroke was inked // Note: The next three flags // are only valid if the Stroke // Avail bit is set. #define WRT_INK_NOT_REMOVED 0x00000004 // Stroke left inked as requested #define WRT_TD_LO_SAME_HWND 0x00000008 // Touchdown/liftoff in same hwnd #define WRT_STROKE_OUTSIDE_HWND 0x00000010 // Stroke left the boundaries // of the TD window's hwnd. #define WRT_POINTS_LOST 0x00000040 // Points were lost (HW overrun) #define WRT_BUFFER_OVERRUN 0x00000080 // Points lost (Stroke buffer overrun) #define WRT_NON_DEVICE_EVENT 0x00000100 // Mouse event not generated by device #define WRT_MBUTTON_MASK 0x00001C00 // Mask for isolating mouse button #define WRT_MBUTTON1 0x00000400 // Mouse button 1 #define WRT_MBUTTON2 0x00000800 // Mouse button 2 #define WRT_MBUTTON3 0x00001000 // Mouse button 3 #define WRT_TAP 0x00002000 // Stroke is a tap #define WRT_DBLTAP 0x00004000 // Stroke is a double tap Event Data Structure Format ═══ 16.4. System Capabilities Data Structure ═══ This data structure provides to the aware application pertinent information on devices attached to the system. It may be queried through the function WrtQuerySystemCaps. typedef struct _WRTSYSTEMINFO // si { ULONG cbStructSize; // Structure size ULONG ulDisplayXPels; // Number of display X pixels ULONG ulDisplayYPels; // Number of display Y pixels ULONG ulDisplayXRes; // Display pels per inch X-axis ULONG ulDisplayYRes; // Display pels per inch Y-axis ULONG ulStandardXRes; // Standardized dots per inch X-axis ULONG ulStandardYRes; // Standardized dots per inch Y-axis ULONG ulNumDrivers; // Number of registered pen drivers ULONG ulNumLocators; // Number of registered pointing devices ULONG ulNumButtons; // Number of registered button devices ULONG ulNumDisplays; // Number of registered display devices } WRTSYSTEMINFO; typedef WRTSYSTEMINFO *PWRTSYSTEMINFO; //psi System Capabilities Information Format ═══ 16.5. Locator Device Capabilities Data Structure ═══ This data structure provides to the aware application pertinent information on locator devices. It may be queried through the function WrtQueryLocatorCaps. typedef struct _WRTLOCATORDEVINFO // ldi { ULONG cbStructSize; // Structure size ULONG ulLocatorID; // ID of pointing device ULONG ulLocatorType; // Type of pointing device ULONG ulLocatorFlags; // Pointing device flags ULONG ulValidityFlags; // Auxiliary data validity flags ULONG ulOEMValidityCnt; // Count of valid original equipment // manufacturer bytes ULONG ulSensorHeight; // Digitizer height in thousandths of inches ULONG ulSensorWidth; // Digitizer width in thousandths of inches ULONG ulNumMouButtons; // Number of mouse buttons emulated ULONG ulNumButtons; // Number of buttons on pointing device ULONG ulButtonMask; // Mask giving IDs of barrel buttons ULONG ulSensorXpts; // Number of digitizer X-axis units ULONG ulSensorYpts; // Number of digitizer Y-axis units ULONG ulSensorZptsP; // Number of digitizer Z-axis pressure units ULONG ulSensorZptsH; // Number of digitizer Z-axis height units ULONG ulSensorXres; // Digitizer X resolution (points/inch) ULONG ulSensorYres; // Digitizer Y resolution (points/inch) ULONG ulStandardXpts; // Number of standardized X-axis units ULONG ulStandardYpts; // Number of Standardized Y-axis units ULONG ulSampleRate; // Sample rate of pen ULONG ulMaxSampleRate; // Maximum possible point rate supported ULONG ulTimestampRes; // Device time stamp resolution in microsecs UCHAR pszDriverName[32]; // Name of controlling device driver UCHAR pszDeviceName[32]; // Name of pointing device } WRTLOCATORDEVINFO; typedef WRTLOCATORDEVINFO *PWRTLOCATORDEVINFO; //pldi Locator Device Capabilities Information Structure /* WRTLOCATORDEVINFO.ulLocatorType Values */ #define LT_MOUSE 0x00000001 // Mouse #define LT_PEN 0x00000002 // Stylus #define LT_TOUCH 0x00000003 // Finger touch #define LT_OTHER 0x00000004 // Other misc pointing device /* WRTLOCATORDEVINFO.ulLocatorFlags Values */ #define LTYPE_TETHERED 0x00000001 // Stylus is tethered #define LTYPE_PROXIMITY_EVENT 0x00000002 // Proximity events reported #define LTYPE_TILT 0x00000004 // Device reports angle to XY #define LTYPE_ROTATION 0x00000008 // Device reports rotation #define LTYPE_OEMDATA 0x00000010 // Device reports extra OEM data #define LTYPE_TIMESTAMP 0x00000020 // Device reports hi-res time stamp #define LTYPE_PRESSURE 0x00000040 // Device reports pressure #define LTYPE_HEIGHT 0x00000080 // Device reports height #define LTYPE_PIN 0x00000100 // Pen contains PIN #define LTYPE_BATTERY 0x00000800 // Pen contains battery #define LTYPE_ERASURE 0x00000200 // Erasure end of stylus reported #define LTYPE_INTEG_SENSOR 0x00000400 // Sensor integrated in display #define LTYPE_RELATIVE 0x00001000 // Relative pointing device // Sensor coords from relative // devices are offsets from // last reported point #define LTYPE_ABSOLUTE 0x00002000 // Absolute pointing device /* WRTLOCATORDEVINFO.ulValidityFlags Values */ #define ADF_TIMESTAMP 0x00000001 // Point time stamp #define ADF_FLAGS 0x00000002 // Point flags #define ADF_SCREENZ 0x00000004 // Normalized Z-axis #define ADF_DEVZ 0x00000008 // Device Z #define ADF_ANGLE 0x00000010 // Stylus angle to XY #define ADF_ROTATION 0x00000020 // Stylus barrel rotation #define ADF_BUTTON 0x00000040 // Button status #define ADF_OEM 0x00000080 // OEM specific data byte count #define ADF_OEM_COUNT_MASK 0x000F0000 // OEM valid count #define ADF_USER 0x00000100 // This bit is not HW related and // is always set. For appl use. #define ADF_ALL 0X000001FF // All fields WRTLOCATORDEVINFO ═══ 16.6. Button Device Capabilities Data Structure ═══ This data structure provides information on buttons that are part of locator or digitizer devices. The function WrtQueryButtonCaps will provide the structure with the pertinent information. typedef struct _WRTBUTTONDEVINFO // bdi { ULONG cbStructSize; // Structure size ULONG ulButtonID; // ID of button device ULONG ulNumButtons; // Number of configured buttons ULONG ulButtonMask; // 1=barrel, 0=nonbarrel button UCHAR pszDriverName[32]; // Name of controlling device driver UCHAR pszDeviceName[32]; // Name of button device } WRTBUTTONDEVINFO; typedef WRTBUTTONDEVINFO *PWRTBUTTONDEVINFO; //pbdi Button Device Capabilities Information Structure ═══ 16.7. Display Device Capabilities Data Structure ═══ This data structure provides information on displays that are part of digitizer devices. The function WrtQueryDisplayCaps will provide the structure with the pertinent information. typedef struct _WRTDISPLAYDEVINFO // ddi { ULONG cbStructSize; // Structure size ULONG ulDisplayID; // ID of display device ULONG ulDisplayType; // Type of display ULONG ulDisplayXPels; // Number of display X pixels ULONG ulDisplayYPels; // Number of display Y pixels ULONG ulDisplayXRes; // Display pels per inch X-axis ULONG ulDisplayYRes; // Display pels per inch Y-axis ULONG ulDisplayHeight; // Height of display in thousandths ULONG ulDisplayWidth; // Width of display in thousandths UCHAR pszDriverName[32]; // Name of controlling device driver UCHAR pszDeviceName[32]; // Name of display device } WRTDISPLAYINFO; typedef WRTDISPLAYDEVINFO *PWRTDISPLAYDEVINFO; //pddi /* WRTDISPLAYDEVINFO.ulDisplayType Values */ #define DISPTYPE_LCD 0x0001 // 1 - LCD, 0 - not LCD #define DISPTYPE_CRT 0x0002 // 1 - CRT, 0 - not CRT #define DISPTYPE_BLANKING 0x0004 // Display performs 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 integrated #define DISPTYPE_MICROPHONE 0x0100 // 1 - Microphone integrated Display Device Capabilities Information Structure ═══ 17. Recognition Event Delivery Subsystem API ═══ This section contains the APIs used to help control the delivery of recognition events to applications. The following is a list of the available APIs: o RedDeregisterRecoCommand o RedQueryRecoCommand o RedQueryRecoHandle o RedQueryRecoSubsystem o RedReadObjectEventMap o RedRecoDataFromEnv o RedRecoIDFromName o RedRecoNameFromID o RedRegisterRecoCommand o RedWriteObjectEventMap ═══ 17.1. RedDeregisterRecoCommand ═══ Syntax rc = RedDeregisterRecoCommand(HWND cmdhwnd); Purpose This function deregisters a recognition command handler that was registered through RedRegisterRecoCommand. Parameters cmdhwnd (HWND) - input The window handle of the command handler to be deregistered. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NOT_FOUND The command handler registration was not found. Remarks This function does not need to be called from the same process that registered the command handler. ═══ 17.2. RedQueryRecoCommand ═══ Syntax cmdhwnd = RedQueryRecoCommand(PSZ cmdnamep); Purpose This function is used to query the window handle of a registered command handler. Parameters cmdnamep (PSZ) - input A pointer to the null-terminated string giving the name of the recognition command handler being queried. cmdhwnd (HWND) - return The window handle of the registered command handler to be deregistered. Returns The window handle the command handler named by cmdnamep registered through RedRegisterRecoCommand is returned. If there is no registered command handler for cmdnamep, NULLHANDLE is returned. Remarks The primary use of this function is to give a recognition command handler a way to determine if there is a copy of the command handler already running and if there is, a way to communicate with the previously running copy. If the name of a built-in command is given, NULLHANDLE is returned. ═══ 17.3. RedQueryRecoHandle ═══ Syntax rc = RedQueryRecoHandle(PSZ pszRecoSubsystem, PHRECO hReco, ULONG * pEventCount); Purpose This function is used to query the handle of a registered recognition subsystem. Parameters pszRecoSubsystem (PSZ) - input Pointer to the buffer that contains the recognition subsystem name. The name is case sensitive. hReco (PHRECO) - output Recognition subsystem handle. pEventCount (ULONG *) - output Pointer to the ULONG that will receive the count of registered events for the subsystem. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDERR_NOT_ACTIVE RED subsystem is not active. REDERR_RECO_NAME_TOO_LONG Name longer than 12 characters REDERR_INVALID_RECO_NAME Name was null string REDERR_RECO_SUBSYS_NOT_REQ Subsystem not registered. Remarks This call maps a recognition subsystem name to the subsystem handle. The returned handle will be zero if an error occurs. The number of registered events is also returned. The handle for the Gesture subsystem is retrieved by having the pszRecoSubsystem parameter point to a string whose value is "Gesture". ═══ 17.4. RedQueryRecoSubsystem ═══ Syntax rc = RedQueryRecoSubsystem(HRECO hReco, PSZ pszRecoSubsystem, ULONG pEventCount); Purpose This function is used to query the name of a registered recognition subsystem from a recognition handle. Parameters hReco (HRECO) - input Recognition subsystem handle. pszRecoSubsystem (PSZ) - output Pointer to the buffer that will be filled in with the name. This buffer must be at least 13 bytes long. pEventCount (ULONG) - output Pointer to the ULONG that will receive the count of registered events for the subsystem. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDEER_NOT_ACTIVE RED subsystem is not active. REDERR_RECO_SUBSYS_NOT_REG Subsystem not registered. Remarks This call maps a recognition handle to the name of the subsystem. The number of registered events is also returned in the call. ═══ 17.5. RedReadObjectEventMap ═══ Syntax rc = RedReadObjectEventMap(HOBJECT hobj, PSZ fnamep); Purpose This function reads recognition event mappings from a disk file located by RedReadObjectEventMap and merges it with the current set of mappings for the object. If the file and current mappings contain a mapping for the same object, the mapping from the file will overwrite the current mapping. Parameters hobj (HOBJECT) - input The (persistent) object handle of the object that will receive the object mappings stored in the file given by fnamep. fnamep (PSZ) - input Pointer to the name of the file from which the object mappings should be read. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. Other A base OS/2 error. If an I/O error occurs, the appropriate base OS/2 error will be returned. Remarks This function will do no handling of critical or disk change errors. The default OS/2 handling of these errors will be used by this function. ═══ 17.6. RedRecoDataFromEnv ═══ Syntax rc = RedRecoDataFromEnv(PRECODATA prdEnv, PULONG pulDataLen); Purpose This function builds a recognition data block from the Pen for OS/2 environment variables. Parameters prdEnv (PRECODATA) - input/output Pointer to RECODATA structure to contain the data. pulDataLen (PULONG) - input/output Pointer to a ULONG that on: input Holds the size of the buffer pointed to by prdEnv output The ULONG pointed to by pulDataLen contains the size in bytes of the data copied into prdEnv or the size of the buffer needed to retrieve the RECODATA structure and the strings pointed to by the RECODATA fields: pszCommand, pszCmdArgs, and pszPrefixCmd if rc is REDERR_BUF_TOO_SMALL. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDERR_NOT_PENPM_ENV Pen for OS/2 environment variables not found. REDERR_BUF_TOO_SMALL Buffer is not large enough to contain full RECODATA structure. Remarks An unsuccessful return code from this function indicates that the program was not started through a recognition event. This function is generally used by programs that are aware of the Pen for OS/2 environment, but that were not previously started and registered through RedRegisterRecoCommand. The returned data is equivalent to the RECODATA structure whose pointer is passed in mp2 parameter of a WM_RECO_COMMAND message. Note: If the prdEnv parameter is NULL, then no error will be returned and the ULONG pointed to by the pulDataLen parameter will contain the size of the buffer needed to retrieve the RECODATA structure and the three strings pointed to be the RECODATA fields: pszCommand, pszCmdArgs, and pszPrefixCmd. ═══ 17.7. RedRecoIDFromName ═══ Syntax rc = RedRecoIDFromName(HRECO hReco, PSZ pszEventName, PRECOID peventID); Purpose This function is used to query a recognition event ID from a recognition event name. Parameters hReco (HRECO) - input Recognition subsystem handle. pszEventName (PSZ) - input Pointer to the buffer that contains the event name. The event name is case sensitive. peventID (PRECOID) - output Event ID. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDEER_NOT_ACTIVE RED subsystem is not active. REDERR_RECO_SUBSYS_NOT_REG Subsystem not registered. REDEER_EVENT_NAME_TOO_LONG Event name longer than 12 characters. REDEER_INVALID_EVENT_NAME Event name was null string. REDEER_EVENT_NAME_NOT_REG Event name not registered. Remarks This call translates an event name into the event ID. ═══ 17.8. RedRecoNameFromID ═══ Syntax rc = RedRecoNameFromID(HRECO hReco, RECOID eventID, PSZ pszEventID); Purpose This function is used to query a recognition event name from a recognition event ID. Parameters hReco (HRECO) - input Recognition subsystem handle. eventID (RECOID) - input Event ID. pszEventID (PSZ) - output Pointer to the buffer that receives the event name. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDEER_NOT_ACTIVE RED subsystem is not active. REDERR_INVALID_EVENT_ID Event ID is not registered. REDEER_RECO_SUBSYS_NOT_REG Subsystem is not registered. Remarks This call translates an event ID into the event name. ═══ 17.9. RedRegisterRecoCommand ═══ Syntax rc = RedRegisterRecoCommand(PSZ pszCommand, ULONG id, HWND hwnd); Purpose This function is used to register a recognition command handler. Parameters pszCommand (PSZ) - input Pointer to recognition command verb to be registered. See Remarks below for special processing applied to the recognition command verb. id (ULONG) - input An ID that will be placed in the WM_RECO_COMMAND message. hwnd (HWND) - input The window that will receive the WM_RECO_COMMAND message. This is the window that is being registered to handle the pszCommand processing. NULL will deregister a handler. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_TOO_MANY_MAPPERS Too many registered handlers. REDERR_NOT_ACTIVE RED subsystem is not active. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. REDERR_CMD_IS_BUILTIN The command verb is the same as one of the Pen for OS/2 built-in commands. The command was not registered. Remarks This call registers a handler of a particular recognition-command verb. If the command is already registered, this call supersedes the previous registration. Only one registered handler per recognition command is allowed. Registration of a command handler that would replace one of the Pen for OS/2 built-in command handlers is not allowed and results in a return code of REDERR_CMD_IS_BUILTIN. When checking for previous registrations, the given command will replace any command that has the name portion of a file specification equivalent to the command. For example, if D:\PENPM\HWRITING.EXE is already registered and this function was called with an pszCommand of HWRITING, the registration for D:\PENPM\HWRITING.EXE would be superseded. This is to allow for the specification of path information in the initial gesture-mapping profile. When a recognition event results in mapping to a registered recognition command verb (through profile processing), the registered window will receive a WM_RECO_COMMAND message. ═══ 17.10. RedWriteObjectEventMap ═══ Syntax rc = RedWriteObjectEventMap(HOBJECT hobj, PSZ fnamep); Purpose This function writes an object's event mapping to disk file. Parameters hobj (HOBJECT) - input The (persistent) object handle of the object whose event mapping is to be written. fnamep (PSZ) - input Pointer to the null-terminated name of the file the mappings will be written to. rc (APIRET) - return Returns Return codes indicating success or type of failure: RED_NO_ERROR Successful. REDERR_NOT_FOUND There were no event mappings for the object handle given. REDERR_NO_MEMORY There was insufficient memory available to process the request. REDERR_INVALID_PARM One or more of the parameters passed is invalid. Other A base OS/2 error. If an I/O error occurs, the appropriate base OS/2 error will be returned. Remarks This function will do no handling of critical or disk-change errors. The default OS/2 handling of these errors will be used by this function. ═══ 18. Recognition Event Delivery Subsystem Messages ═══ This section contains the Recognition Event Delivery subsystem messages that are used to indicate that a recognition event has occurred, and to supply additional information about the event. ═══ 18.1. WM_RECO ═══ This message is sent through WinSendMsg to the window under the hot spot. Position in mp1 is relative to the window receiving this message. This message indicates that a recognition event has occurred. An application can obtain the full set of recognition information from the PRECODATA pointer in the mp2 parameter. The receiver of this message can control subsequent processing of the event through the return parameter. The following is an example of how this message is entered: fProcessed = WinSendMsg(hwnd, WM_RECO, mp1, mp2) Parameters mp1 xPosition (SHORT) x position in window coordinates. yPosition (SHORT) y position in window coordinates. Note: mp1 can be addressed with the PM MOUSEMSG macro. This is the position of the hot spot. mp2 prdReco (PRECODATA) This is the pointer to a RECODATA structure. The command argument and prefix command strings must be copied to your application's memory before your application returns control. Also, while processing this message, do not invoke any dialog or message box because a deadlock might occur since this is a sent message. Note: The data pointed to by mp2 is only valid for the duration of the message. If the receiver requires the information after returning from this message, then make a copy of the data. Return Codes fProcessed (MRESULT) Contains none or some of the following flags. RECO_PROCESSED The application has processed the event. No further analysis or processing will be done. RECO_MAP Continue with Recognition mapping. If mapping is successful, further Recognition messages may result. ═══ 18.2. WM_RECO_COMMAND ═══ This message is SENT to a registered recognition command handler upon a successful recognition event resulting in an action that is registered for that handler (window). Applications may register application unique recognition commands by calling RedRegisterRecoCommand. Upon receiving a WM_RECO_COMMAND message, the mp2 parameter can be used to obtain more information about the recognition and mapping events. The following is an example of how this message is entered: WinSendMsg(hwnd, WM_RECO_COMMAND, mp1, mp2); Parameters mp1 ID (ULONG) This is the command ID, originally passed by RedRegistedRecoCommand. Note: This is not the recognition event ID. mp2 prdRecoCmd (PRECODATA) This is the pointer to a RECODATA structure. Note: The command argument and prefix command strings must be copied to your application's memory before before your application returns control. Also, while processing this message, do not invoke any dialog or message box because a deadlock might occur. Return Codes NULL (MRESULT) ═══ 19. Recognition Event Delivery Subsystem Data Structure ═══ This section contains the data structure used within the Recognition Event Delivery subsystem. ═══ 19.1. RECODATA - Recognition Data Block (RDB) Structure ═══ This data structure is built for every recognition event passed to the Pen for OS/2 subsystem by a recognition subsystem (for example: voice, button, gesture). The target application is then informed of the recognition event through a WM_RECO message and the recognition data block is made available. The recognition data block is retrieved through the RedRecoFromEnv function and from the mp2 parameter of the WM_RECO and WM_RECO_COMMAND messages. typedef struct _RECODATA { ULONG cbSize; /* Size of structure */ RECOID id; /* ID if recognition event */ HRECO hReco; /* Recognition subsystem handle */ ULONG virtual_id; /* Virtual ID of event */ ULONG char_code; /* Character code of event */ RECTL bound_box; /* Bounding box of gesture */ POINTL ptlHotSpot; /* Hot spot, X/Y screen coordinate */ HWND hwnd; /* Hwnd under hot spot */ HWND hwndActive; /* Active window */ HWND hwndFocus; /* Window that has the focus */ PSZ pszCommand; /* Command assigned to gesture */ PSZ pszCmdArgs; /* Argument of command */ PSZ pszPrefixCard; /* Prefix assigned to gesture */ } RECODATA; typedef RECODATA *PRECODATA; RECODATA Data Format ═══ 20. Sketch Control Programming Interface ═══ Setup and modification of a sketch control follows the standard OS/2 PM methods for controls. The initial display attributes are controlled by a word of style bits. Subsequent modification of the operation of the control is accomplished through control messages. When the control needs to notify its parent of some event, the control sends the parent a notification message. Through the messages, the stroke database will be externalized for the control, with each control having its own private database. The database exists for the life of the control, so strokes can be retrieved from the control until it is destroyed. During the shell initialization of the OS/2 operating system, the .DLL file for the sketch-entry control is loaded and initialized. The class of the control is publicly registered and has a value of WC_SKETCH. ═══ 20.1. Control Style Bits ═══ The following standard PM dialog manager and sketch control style bits can be specified in the creation of a sketch input control. ═══ 20.1.1. Standard PM Window Styles Bits ═══ WS_VISIBLE Makes the window visible. OS/2 draws the window on the screen unless overlapping windows completely obscure it. By default, the WinCreateWindow function creates invisible windows unless the WS_VISIBLE style is given. WS_DISABLED Disables mouse and keyboard input to the window. This style is used to temporarily prevent the user from using the window. If the window is already imbedded, the control will repaint the stroke half-tone. The pointer will remain unchanged. WS_CLIPCHILDREN Prevents a window from painting over its child window. Standard PM meaning, with no effect on control. WS_CLIPSIBLINGS Prevents a window from painting over its sibling windows. Standard PM meaning, with no effect on control. WS_PARENTCLIP Prevents a window from painting over its parent window. Standard PM meaning, with no effect on control. WS_SAVEBITS Saves the image under the window as a bit map. When the window is moved or hidden, the system restores the image by copying the bits. Standard PM meaning, with no effect on control. WS_SYNCPAINT Causes the window to receive WM_PAINT messages immediately after a part of the window becomes invalid, instead of receiving WM_PAINT messages only if no other message is waiting to be processed. Standard PM meaning, with no effect on control. WS_MINIMIZED Reduces the window to the minimum size. Standard PM meaning, with no effect on control. WS_MAXIMIZED Enlarges the window to the maximum size. Standard PM meaning, with no effect on control. ═══ 20.1.2. Dialog Manager Styles Bits ═══ WS_GROUP Specifies the first control of a group of controls in which the user can move from one control to another using the ARROW key. Standard PM meaning, with no effect on control. WS_TABSTOP Specifies one of any number of controls through which the user can move by tabbing. Standard PM meaning, with no effect on control. WS_MULTISELECT Standard PM meaning, with no effect on control. ═══ 20.1.3. Sketch Control Style Bits ═══ SKS_BORDER The control displays a border around its input area. SKS_3DBORDER The control displays a 3-dimensional border around its input area. ═══ 20.2. Control Messages ═══ Control messages are sent to the sketch entry control to alter its processing characteristics. These message are sent in the following manner: WinSendMsg(hWndSiCtl, MessageID, mp1, mp2); Where: hWndSiCtl = The handle of the sketch entry control window. MessageID = The ID of the control message. mp1 = Message data as defined by the control message. mp2 = Message data as defined by the control message. The owner of a sketch entry control sends these messages to the window to query, set, or change the state of the window. The messages should be sent by the owner to the sketch entry control as follows: mRc = (MRESULT) WinSendMsg(hWndSiCtl, SKM_xxx, mp1, mp2); The following control messages are sent to the sketch entry control to alter the controls processing characteristic: o SKM_DELETE_ALL_STROKES o SKM_GET_BITMAP o SKM_UNDO_LAST_STROKE o SKM_QUERY_BITMAP_SIZE o SKM_RENDER_TO_CLIPBOARD o SKM_QUERY_CTL_DRAW_POINTER o SKM_QUERY_CTL_INK_COLOR o SKM_QUERY_CTL_INK_WIDTH o SKM_QUERY_CTL_INVISIBLE_MODE o SKM_QUERY_CTL_STROKE_COUNT o SKM_QUERY_STROKE_DATA o SKM_QUERY_STROKE_INK_COLOR o SKM_QUERY_STROKE_INK_WIDTH o SKM_QUERY_STROKE_LENGTH o SKM_SET_CTL_AUXDATA_MODE o SKM_SET_CTL_DRAW_POINTER o SKM_SET_CTL_INK_COLOR o SKM_SET_CTL_INK_WIDTH o SKM_SET_CTL_INVISIBLE_MODE o SKM_SET_STROKE_INK_COLOR o SKM_SET_STROKE_INK_WIDTH o SKM_ADD_STROKE ═══ 20.3. SKM_DELETE_ALL_STROKES ═══ This messages is sent to the control to request deletion of all strokes in the stroke database. If the delete was successful TRUE will be returned in response to the message; otherwise, FALSE will be returned. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE The clear operation was successfully performed. FALSE An error occurred. For example, there is no stroke available. ═══ 20.4. SKM_GET_BITMAP ═══ This message creates a screen resolution bit map image from the sketch control and returns its handle. The sketch control responds to this message by rendering the screen resolution image to a bit map and returning the bit map handle to the application. The bit map will use the format of the display screen. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes hBitMap (HBITMAP) Handle of the bit map. NULL The operation failed or an error occurred. ═══ 20.5. SKM_UNDO_LAST_STROKE ═══ This message tells the sketch control to clear the ink of the last stroke and to delete it from the database. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE The clear operation was successfully performed. FALSE An error occurred. For example, there is no stroke available. ═══ 20.6. SKM_QUERY_BITMAP_SIZE ═══ This message returns the size of the bit map that could be returned with the SKM_GET_BITMAP or the SKM_RENDER_TO_CLIPBOARD messages. The returned values are dependent on whether the control has a border. If the control does not contain a border, the bit map's size is the same size as the control's window. If the control does contain a border, the bit map's size will be reduced by 2 pixels in the X and Y directions. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes size (ULONG) Indicates the size of the bit map or failure of the operation. LOUSHORT Size in pixels of the bit map in the X direction. HIUSHORT Size in pixels of the bit map in the Y direction. FALSE An error occurred. ═══ 20.7. SKM_RENDER_TO_CLIPBOARD ═══ This message renders the screen resolution bit map image from the sketch control to the clipboard. The bit map is copied to the clipboard in the bit count format corresponding to the capabilities of the screen device. The size of the bit map is the size of sketch input control window. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of the operation. TRUE The operation was successful. FALSE The operation failed or an error occurred. ═══ 20.8. SKM_QUERY_CTL_DRAW_POINTER ═══ This message returns the handle of the current drawing pointer. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes hptrDrawPointer (HPOINTER) Drawing pointer handle. Note: The drawing pointer might have been set to NULL. ═══ 20.9. SKM_QUERY_CTL_INK_COLOR ═══ This message queries the control's current ink color. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes lInkColor (LONG) Indicates the color of the control ink as follows: CLR_DEFAULT CLR_WHITE CLR_BLACK CLR_BACKGROUND CLR_BLUE CLR_RED CLR_PINK CLR_GREEN CLR_CYAN CLR_YELLOW CLR_NEUTRAL CLR_DARKGRAY CLR_DARKBLUE CLR_DARKRED CLR_DARKPINK CLR_DARKGREEN CLR_DARKCYAN CLR_BROWN CLR_PALEGRAY CLR_ERROR An error occurred. ═══ 20.10. SKM_QUERY_CTL_INK_WIDTH ═══ This message returns the control's current ink width. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes ulInkWidth (ULONG) Control ink width. NULL An error occurred. ═══ 20.11. SKM_QUERY_CTL_INVISIBLE_MODE ═══ This message returns the value of the invisible mode flag. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes ulInvisibleMode (BOOL) Indicates if the color of the ink is invisible. TRUE Invisible mode is On, all strokes are invisible. FALSE Invisible mode is Off, all strokes are visible. ═══ 20.12. SKM_QUERY_CTL_STROKE_COUNT ═══ This message is used to get the count of strokes in the stroke control. Parameters param1 (ULONG) 0, reserved value. param2 (ULONG) 0, reserved value. Return Codes count (ULONG) Reports the count of strokes. ═══ 20.13. SKM_QUERY_STROKE_DATA ═══ This message is used to retrieve stroke(i) from the control: o mp1 specifies the stroke (1...n). o mp2 is a pointer to a buffer to hold the contents of the stroke, including any auxiliary data. The buffer size is determined by sending the message SKM_QUERY_STROKE_LENGTH to the control. The memory buffer layout for Ptr->SKTCTRLSTROKEDEF is as follows: SKTCTRLSTROKEDEF STROKEDATA ARRAY OF POINTL AUXDATAINFO AUXPOINTDATA The structure used to retrieve stroke(i) from the stroke database is described in the toolkit file, SKETCH.H. . ------------------------------- . 1 . . . SKTCTRLSTROKEDEF . . . . PSTROKEDATA . -> 2 . ------------------------------- . Note: The application must 2 . . adjust the pointers indicated . STROKEDATA . here, if the data is moved to a . . different buffer or read from . PPOINTL . -> 3 a control file. . . . PAUXDATAINFO . -> 4 . PAUXSTROKEDATA . -> 5 . . . struct _STROKEDATA * . -> NULL . struct _STROKEDATA * . -> NULL . ------------------------------- . 3 . . . X/Y POINTL array . . . . ------------------------------- . 4 . . . AUXDATAINFO . . . . ------------------------------- . 5 . . . AUXPOINTDATA . . . . ------------------------------- . Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (PVOID) pSktCtrlStrokeDef(PSKTCTLSTROKEDEF) Memory buffer. typedef struct _SktCtrlStrokeDef { ULONG ulStrokeColor; ULONG ulStrokeWidth; ULONG reserved; PSTROKEDATA pStroke; }SKTCTRLSTROKEDEF; typedef SKTCTRLSTROKEDEF *PSKTCTRLSTROKEDEF; // Ptr->SKTCTRLSTROKEDEF typedef PSKTCTRLSTROKEDEF *PPSKTCTRLSTROKEDEF; // Ptr->Ptr->SKTCTRLSTROKEDEF Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE Success. FALSE An error occurred. ═══ 20.14. SKM_QUERY_STROKE_INK_COLOR ═══ This message returns the color attribute of stroke(i) in the stroke database. o mp1 specifies the stroke (1...n) to query. Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (ULONG) 0, reserved value. Return Codes lInkColor (LONG) Indicates the color of the stroke (1...n) ink as follows: CLR_DEFAULT CLR_WHITE CLR_BLACK CLR_BACKGROUND CLR_BLUE CLR_RED CLR_PINK CLR_GREEN CLR_CYAN CLR_YELLOW CLR_NEUTRAL CLR_DARKGRAY CLR_DARKBLUE CLR_DARKRED CLR_DARKPINK CLR_DARKGREEN CLR_DARKCYAN CLR_BROWN CLR_PALEGRAY CLR_ERROR An error occurred. ═══ 20.15. SKM_QUERY_STROKE_INK_WIDTH ═══ This message returns the width attribute of stroke(i) in the stroke database. o mp1 specifies the stroke (1...n) to query. Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (ULONG) 0, reserved value. Return Codes ulInkWidth (ULONG) Stroke ink width. NULL An error occurred. ═══ 20.16. SKM_QUERY_STROKE_LENGTH ═══ This message is used to retrieve the size in bytes of stroke(i). A return code of 0 signals an error, such as stroke not available. The size consists of the following structures: SKTCTRLSTROKEDEF STROKEDATA ARRAY OF POINTL AUXDATAINFO AUXPOINTDATA Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (ULONG) 0, reserved value. Return Codes size (ULONG) Indicates size of the stroke. If the length is 0, then an error occurred. ═══ 20.17. SKM_SET_CTL_AUXDATA_MODE ═══ This message informs the control that subsequent strokes will retrieve the specified pen stroke auxiliary data, if the data can be returned by the device (pen, touch, mouse). The flags ADF_* are defined in the header file PENPM.H. A value of 0 results in no auxiliary data being returned. Parameters param1 (ULONG) /* WRTLOCATORDEVINFO.ulValidityFlags Values */ ADF_TIMESTAMP 0x00000001 /* Point time stamp */ ADF_FLAGS 0x00000002 /* Point flags */ ADF_SCREENZ 0x00000004 /* Display Z-axis value */ /* The Z value is 0-4096 for height */ /* and 0 to -4096 for pressure */ ADF_ANGLE 0x00000008 /* Device angle */ ADF_ROTATION 0x00000010 /* Device rotation */ ADF_BUTTON 0x00000020 /* Button status */ ADF_OEM 0x00000040 /* OEM specific data byte count */ ADF_OEM_COUNT_MASK 0x000F0000 /* OEM valid count */ ADF_USER 0x00000080 /* For program use */ ADF_ALL 0x000000FF /* All fields */ param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE Success. FALSE An error occurred. ═══ 20.18. SKM_SET_CTL_DRAW_POINTER ═══ This message sets the drawing pointer handle and returns the previous pointer. The sketch control responds to this message by using a new drawing pointer specified on mp1 to replace the current drawing pointer. Parameters param1 (HPOINTER) hptrDrawPointer Drawing pointer handle. param2 (HPOINTER) 0, reserved value. Return Codes hptrPrevious (HPOINTER) The handle of the previous drawing pointer. Note: The previous drawing pointer might have been set to NULL. ═══ 20.19. SKM_SET_CTL_INK_COLOR ═══ This message sets the drawing stroke color for the control. Strokes created after this message will have the newly set color. Parameters param1 (ULONG) lInkColor (LONG) Indicates the color of the ink as follows: CLR_DEFAULT CLR_WHITE CLR_BLACK CLR_BACKGROUND CLR_BLUE CLR_RED CLR_PINK CLR_GREEN CLR_CYAN CLR_YELLOW CLR_NEUTRAL CLR_DARKGRAY CLR_DARKBLUE CLR_DARKRED CLR_DARKPINK CLR_DARKGREEN CLR_DARKCYAN CLR_BROWN CLR_PALEGRAY param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of the operation. TRUE The ink color was set successfully. FALSE The ink color cannot be set or an error occurred. ═══ 20.20. SKM_SET_CTL_INK_WIDTH ═══ This message sets the drawing stroke ink width for the control. Strokes created after this message will have the newly set width. Parameters param1 (ULONG) ulInkWidth Ink width in pels. The choices are 1 or 2 pels. The default is 1 pel. param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of the operation. TRUE The ink width was set successfully. FALSE The ink width cannot be set or an error occurred. ═══ 20.21. SKM_SET_CTL_INVISIBLE_MODE ═══ This message turns On or Off the invisible mode of the control. This lets an application hide a signature or password entered by a user. Parameters param1 (BOOL) Selects visible or invisible ink. TRUE Turn invisible mode On. All current and new strokes in the control will be invisible. FALSE Turn invisible mode Off. All current and new strokes in the control will be visible. param2 (ULONG) 0, reserved value. Return Codes fSuccess (BOOL) Indicates success or failure of the operation. TRUE The mode was successfully set. FALSE An error occurred setting the mode. ═══ 20.22. SKM_SET_STROKE_INK_COLOR ═══ This message is used to reset the color attribute of stroke(i) in the stroke database: o mp1 specifies the stroke (1...n). o mp2 is the stroke ink color. Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (LONG) lInkColor Stroke ink color CLR_DEFAULT CLR_WHITE CLR_BLACK CLR_BACKGROUND CLR_BLUE CLR_RED CLR_PINK CLR_GREEN CLR_CYAN CLR_YELLOW CLR_NEUTRAL CLR_DARKGRAY CLR_DARKBLUE CLR_DARKRED CLR_DARKPINK CLR_DARKGREEN CLR_DARKCYAN CLR_BROWN CLR_PALEGRAY Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE Success. FALSE An error occurred. ═══ 20.23. SKM_SET_STROKE_INK_WIDTH ═══ This message is used to reset the ink width attribute of stroke(i) in the stroke database: o mp1 specifies the stroke (1...n). o mp2 is the stroke ink width. Parameters param1 (ULONG) target (ULONG) Stroke target number. param2 (ULONG) ulInkWidth Ink width units (pels). The choices are 1 or 2 pels. The default ink width is 1 pel. Return Codes fSuccess (BOOL) Indicates success or failure of operation. TRUE Success. FALSE An error occurred. ═══ 20.24. SKM_ADD_STROKE ═══ This message is used to add a stroke to the control: o mp2 is a pointer to a buffer to hold the contents of the stroke, including any auxiliary data. The buffer size is determined by sending the message SKM_QUERY_STROKE_LENGTH to the control. The memory buffer layout for Ptr->SKTCTRLSTROKEDEF is as follows: SKTCTRLSTROKEDEF STROKEDATA ARRAY OF POINTL AUXDATAINFO AUXPOINTDATA The structure used to retrieve stroke(i) from the stroke database is described in the toolkit file, SKETCH.H. . ------------------------------- . 1 . . . SKTCTRLSTROKEDEF . . . . PSTROKEDATA . -> 2 . ------------------------------- . Note: The application must 2 . . adjust the pointers indicated . STROKEDATA . here, if the data is from a . . different buffer than the one . PPOINTL . -> 3 given by SKM_QUERY_STROKE_DATA. . . . PAUXDATAINFO . -> 4 . PAUXSTROKEDATA . -> 5 . . . struct _STROKEDATA * . -> NULL . struct _STROKEDATA * . -> NULL . ------------------------------- . 3 . . . X/Y POINTL array . . . . ------------------------------- . 4 . . . AUXDATAINFO . . . . ------------------------------- . 5 . . . AUXPOINTDATA . . . . ------------------------------- . Parameters param1 (ULONG) Reserved. param2 (PVOID) pSktCtrlStrokeDef (PSKTCTLSTROKEDEF) Memory buffer. typedef struct _SktCtrlStrokeDef { ULONG ulStrokeColor; ULONG ulStrokeWidth; ULONG reserved; PSTROKEDATA pStroke; }SKTCTRLSTROKEDEF; typedef SKTCTRLSTROKEDEF *PSKTCTRLSTROKEDEF; // Ptr->SKTCTRLSTROKEDEF typedef PSKTCTRLSTROKEDEF *PPSKTCTRLSTROKEDEF; // Ptr->Ptr->SKTCTRLSTROKEDEF Return Codes fSuccess (ULONG) Indicates success or failure of operation. TRUE Success. FALSE An error occurred. ═══ 20.25. Notification Messages ═══ Notification messages are initiated by the sketch control window to notify its owner of significant events. These messages are sent by the control to the owner as follows: WinSendMsg(hWndOwner, WM_CONTROL, MPFROM2SHORT(ID, NotifyCode), mp2); Where: hWndOwner = The owner of the sketch control window. ID = The ID assigned to the control at creation. NotifyCode = An event notification code. mp2 = Notify code specific information. The following notification messages are defined for the sketch control: o SKN_FOCUS_ACTIVATE o SKN_FOCUS_DEACTIVATE o SKN_STROKE_ADD o SKN_STROKE_UNDO o SKN_CONTROL_CLEARED o SKN_INK_COLOR_CHANGE o SKN_INK_WIDTH_CHANGE ═══ 20.26. SKN_FOCUS_ACTIVATE ═══ Informs the parent the control has been given input focus. Parameters mp2 (ULONG) 0, reserved value. Return Codes None. ═══ 20.27. SKN_FOCUS_DEACTIVATE ═══ Informs the parent the control has lost input focus. Parameters mp2 (ULONG) 0, reserved value. Return Codes None. ═══ 20.28. SKN_STROKE_ADD ═══ Sent to the parent when a stroke is about to be added to the stroke database. If the parent returns TRUE to the message, the stroke will not be added. If the parent returns FALSE, the stroke will be added. Parameters mp2 (ULONG) count (ULONG) Stroke number to add. Return Codes None. ═══ 20.29. SKN_STROKE_UNDO ═══ Sent to the parent when a stroke is about to be deleted from the stroke database. If the parent returns TRUE to the message, the stroke will not be deleted. If the parent returns FALSE, the stroke will be deleted. Parameters mp2 (ULONG) count (ULONG) Stroke number to undo. Return Codes None. ═══ 20.30. SKN_CONTROL_CLEARED ═══ Sent to the parent whenever the stroke database is about to be cleared of all strokes. If the parent returns TRUE to the message, the strokes will not be deleted. If the parent returns FALSE, all strokes will be deleted from the stroke database. Parameters mp2 (ULONG) count (ULONG) Number of strokes in the database. Return Codes None. ═══ 20.31. SKN_INK_COLOR_CHANGE ═══ Sent to the parent whenever the ink color for the drawing stroke is changed. Parameters mp2 (LONG) lInkColor Drawing stroke ink. Return Codes None. ═══ 20.32. SKN_INK_WIDTH_CHANGE ═══ Sent to the parent whenever the width for the ink is changed. Parameters mp2 (ULONG) ulInkWidth Drawing stroke width. Return Codes None. ═══ 21. Handwriting Input Control Programming Interface ═══ Setup and modification of a handwriting input control follows the standard OS/2 PM paradigm for controls. The initial display attributes are controlled by a word of style bits. Subsequent modification of the operation of the control is accomplished through control messages. When the control needs to notify its parent of an event, the control sends the parent a notification message. During the shell initialization of the OS/2 operating system, the DLL for the handwriting entry control will be loaded and initialized. The class of the control will be publicly registered and will have the value HWXENTRY. ═══ 21.1. Handwriting Input Control Style Bits ═══ The following control style bits are specific to the handwriting input control: HX_3DBORDER The control displays a three-dimensional border around the edge of its client area. The three-dimensional effect is created by painting white lines on the top and left edges of the control's client area and black lines on the bottom and right edges of the control. This makes the control appear to be raised above its parent. HX_BORDER The control displays a black border around the edge of its client area. Note: If both border style bits are set, HX_BORDER takes precedence. ═══ 21.2. Notification Messages ═══ Notification messages are initiated by the handwriting control window to notify its owner of significant events. These messages are sent by the control to the owner as follows: WinSendMsg(hOwnerWnd, WM_CONTROL, MPFROM2SHORT(ID, NotifyCode), mp2); Where: hOwnerWnd = The parent of the handwriting control window. ID = The ID assigned to the control at creation. mp1 = An event notification code. mp2 = Notify code specific information. The following notification message ID's are defined for the handwriting control: HXN_OVERFLOW Informs the owner of the control that the current operation has caused the text area of the control to overflow. The text limit for a handwriting control is 300 characters. Overflow text is lost. HXN_SETFOCUS Informs the owner of the control that the control has gained the focus. HXN_KILLFOCUS Informs the owner of the control that the control has lost focus. HXN_CONTENTS_CHANGED Sent to the control when the text contents of the control has changed. HXN_STROKE_ADDED Informs the owner that the control has received a pen stroke that is destined to be sent to the recognition system. If the owner returns TRUE to the message, the control takes no further action. If the owner returns FALSE, the control sends the pen stroke to the recognition system. HXN_DELETE_PENDING Informs the owner the control intends to delete a range of characters due to a user gesture. If the owner returns TRUE to the message, the control takes no further action. If the owner returns FALSE to the message, the control deletes the characters in the range. Message parameter 2 (mp2) contains two 16-byte fields to denote the range as follows: o HIUSHORT (mp2) - Start of range of deleted characters. o LOUSHORT (mp2) - End of range of deleted characters. HXN_INSERT_PENDING Informs the owner the control intends to insert spaces into the control. If the owner returns TRUE to the message, the spaces are not inserted. If the owner returns FALSE to the message, the spaces are inserted. Message parameter 2 (mp2) contains the following values: o usPosition (USHORT) - Position in the current text where spaces will be inserted. o usCount (USHORT) - Number of spaces that will be inserted. HXN_GESTURE_PENDING Informs the owner of the control that the user has just entered a gesture in the control. If the owner returns TRUE to the message, the gesture is not executed. If the owner returns FALSE to the message, the gesture is executed. Message parameter 2 (mp2) contains the gesture ID. Possible values for mp2 are: o VE_SPACE o VE_SCRATCHOUT o VE_DELETECHAR ═══ 21.2.1. Mouse Pointer Notification Message ═══ A WM_CONTROLPOINTER message is sent to the owner of the control, when the pointing-device pointer moves over the control's window. This message allows the owner to set the pointing device pointer. Parameters mp1 usControlID (USHORT) Control identifier. hCurrPointer (HPOINTER) Handle to pointer currently used by the control. mp2 NULL (USHORT) Unused hNewPointer (HPOINTER) Handle to new pointer used by the control. This message also allows the owner of the control to change the mouse pointer. The mouse pointer is changed if a valid handler to a mouse pointer resource is returned on completion of the processing of the message. If the mouse pointer is changed, the window procedure would pass this message to the default window procedure. ═══ 21.2.2. Help Notification Message ═══ A WM_HELP message is posted to the owner of the control when a help gesture is drawn on the control. The gesture must be drawn larger than a character cell, so that it will be interpreted as a gesture instead of recognition data. Parameters mp1 usControlID (USHORT) Control identifier. NULL (USHORT) Unused. mp2 usSource (USHORT) Command source, always CMDSRC_OTHER. usPointer (USHORT) Pointer Device indicator, always TRUE. If the owner passes this message to the default window procedure, the help notification message is passed to the owner's parent window, if it exists and is not the desktop. Otherwise, the help notification message sets the return value to FALSE. ═══ 21.3. Handwriting Input Control Display Colors ═══ The following four colors can be used to display a handwriting input control: Control Background Color This color is used by the control to paint its background. This color is derived from the OS/2 PM system color SYSCLR_BACKGROUND. Control Character Grid Color This color is used by the control to paint the character grid. This color is derived from the OS/2 PM system color CLR_DARKGRAY. Control Text Color This color is used by the control to paint the text. This color is derived from the OS/2 PM system color SYSCLR_WINDOWTEXT. Control Error Text Color This color is used by the control to paint the characters which are in error or not recognized. This color is derived from the OS/2 PM system color CLR_DARKGARY. ═══ 22. Virtual Keyboard Playback API ═══ Pop-Up Keyboard provides a set of Virtual Keyboard Playback (Vkp) API functions to let other PM applications control the Pop-Up Keyboard tool. The following is a list of available APIs. o VkpDeleteKeyboard o VkpHideKeyboard o VkpIsKbHidden o VkpIsKbRunning o VkpLoadKeyboard o VkpCloseKb o VkpQueryKbPos o VkpSetKbPos ═══ 22.1. VkpDeleteKeyboard ═══ Syntax rc = VkpDeleteKeyboard (PSZ pszKbd, HWND hwnd); Purpose This function deletes a keyboard data file from within the Pop-Up Keyboard's memory. The supplied name must match a keyboard data file kept within the Pop-Up Keyboard. If the requested keyboard data file is the current keyboard being shown, then the default keyboard will be used to replace the one being deleted. Parameters pszKbd (PSZ) - input A null-terminated string indicating the name of the keyboard data file to be deleted and unloaded. The file name must be a valid keyboard data file previously loaded into the Pop-Up Keyboard. hwnd (HWND) - input The window handle of the window requesting the deletion of a keyboard from the Pop-Up Keyboard. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.2. VkpHideKeyboard ═══ Syntax rc = VkpHideKeyboard (HWND hwnd); Purpose This function places the Pop-Up Keyboard in a hidden mode if it is currently visible. Parameters hwnd (HWND) - input The window handle of the window requesting the Pop-Up Keyboard to hide itself. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.3. VkpIsKbHidden ═══ Syntax rc = VkpIsKbHidden (PBOOL fHidden); Purpose This function determines if the Pop-up Keyboard is currently hidden from view. Parameters fHidden (PBOOL) - output Pointer to a BOOL which on output contains one of the two following values: True Indicates that the Pop-Up Keyboard is in a hidden mode. False Indicates that the Pop-Up Keyboard is currently visible. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_WQWP_FAILED Cannot determine window position. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.4. VkpIsKbRunning ═══ Syntax rc = VkpIsKbRunning (PBOOL fRunning); Purpose This function determines if the Pop-Up Keyboard is currently active. Parameters fRunning (PBOOL) - output Pointer to a BOOL which on output contains one of the two following values: True Indicates that the Pop-Up Keyboard is active. False Indicates that the Pop-Up Keyboard is not available for use. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.5. VkpLoadKeyboard ═══ Syntax rc = VkpLoadKeyboard (PSZ pszKbdFname, HWND hwnd); Purpose This function displays the new keyboard from the input name. The given keyboard data file will be loaded from disk if needed. Parameters pszKbdFname (PSZ) - input An ASCIIZ string that contains the file name of the keyboard data file to be set as the current keyboard of the Pop-Up Keyboard. The location of the keyboard data file must be either given explicitly in the supplied file name or in the subdirectories assigned to the environment variable DPATH. A NULL value will indicate that the default keyboard should be set as the current keyboard. hwnd (HWND) - input Window handle whose frame should be considered the owner of the Pop-Up Keyboard. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_KBD_LOAD_FAILED The keyboard load failed. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.6. VkpCloseKb ═══ Syntax rc = VkpCloseKb (HWND hwnd); Purpose This function enables an application to close the Pop-Up Keyboard tool. Parameters hwnd (HWND) - input Window handle of the window requesting the closure of the Pop-Up Keyboard. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_INVALID_OWNER The HWND is not the current owner of the Pop-Up Keyboard. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.7. VkpQueryKbPos ═══ Syntax rc = VkpQueryKbPos (PSWP pswp); Purpose This function returns the current position of the Pop-Up Keyboard frame in DESKTOP coordinates. Parameters pswp (PSWP) - output A pointer to a data structure of type SWP, that will receive the current position and size of the Pop-Up Keyboard window. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_WQWP_FAILED Cannot determine window position. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 22.8. VkpSetKbPos ═══ Syntax rc = VkpSetKbPos (LONG x, LONG y, LONG cx, LONG cy, ULONG fs, HWND hwnd); Purpose This function sets the Pop-Up Keyboard's position on the Desktop based on the value passed. Parameters x (LONG) - input This value specifies the x position of the Pop-Up Keyboard relative to its lower-left corner. This value is valid only if the SWP_MOVE flag is specified in the fs parameter. y (LONG) - input This value specifies the y position of the Pop-Up Keyboard relative to its lower-left corner. This value is valid only if the SWP_MOVE flag is specified in the fs parameter. cx (LONG) - input This value specifies the horizontal size of the Pop-Up Keyboard. If the given size is less that the set minimal size of the keyboard, the minimal size will be used. This value is valid only if the SWP_SIZE flag is specified in the fs parameter. cy (LONG) - input This value specifies the vertical size of the Pop-Up Keyboard. If the given size is less that the set minimal size of the keyboard, the minimal size will be used. This value is valid only if the SWP_SIZE flag is specified in the fs parameter. fs (ULONG) - input This parameter specifies the Pop-Up Keyboard positioning options. A subset of the flags specified by the Developer's Toolkit for OS/2 is used. Any combination of the following can be used: SWP_HIDE SWP_MINIMIZE SWP_MOVE SWP_RESTORE SWP_SHOW SWP_SIZE hwnd (HWND) - input The window handle of the window which is requesting to change the appearance of the Pop-Up Keyboard. rc (APIRET) - return Returns Return codes indicating success or type of failure: VKP_NO_ERROR Successful. VKPERR_VKB_NOT_READY Pop-Up Keyboard is not active. VKPERR_INVALID_PARM Invalid parameter passed to function. Remarks None. ═══ 23. Pen for OS/2 Setup Objects ═══ Several Workplace Shell objects make up the Pen for OS/2 system extension Setup Objects. The interface to the Writing Subsystem consists of several objects in the System Setup folder and Pen for OS/2 folder. These objects provide access to device-specific settings. Also, the Pen Object class provides the user with the ability to edit the gesture mappings and overrides by program object. ═══ 23.1. Overview of the Pen for OS/2 Setup Objects ═══ The current System Setup folder contains two objects representing the system input devices: sound and mouse. These objects allow the user to adjust certain device-specific parameters. In the Pen for OS/2 system extension, the current sound and mouse objects are replaced by subclasses of themselves (PenSound and PenMouse). The new sound and mouse objects have an additional Settings page that allows the user to set Writing Subsystem parameters that are specific to the mouse and sound devices. Also in Pen for OS/2, the PenPenSubSystem object class allows the user to set Writing Subsystem and Recognition Subsystem parameters that globally affect the Pen for OS/2 subsystem, which means that all devices are affected. The relationship of the PenPenSubsystem class to the Pen for OS/2 system extension is analogous to the relationship between the wpSystem class to the OS/2 system. The following five additional object classes are provided to allow the user to set device-specific settings, such as button assignments and tap rates: o PenButtonDevice o PenLocator o PenLocatorPen o PenLocatorFinger o PenDisplay Finally, the PenObject class (which replaces the WPObject class) allows for information to be associated with all object instances of the WPProgram and WPProgramFile classes. This data represents the user assignments of gestures and the Writing Subsystem overrides to be used for any program object. 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. For more information, see Pen for OS/2 Device Driver Reference. ═══ 23.2. Programming Interfaces ═══ The programming interface to the new objects will be through Workplace Shell published methods. The following documentation on the methods and overrides for these new methods is provided for the application programmer. Refer to the OS/2 System Object Model Guide and Reference (SOM) for more information on how to subclass SOM and WPS objects. The Pen for OS/2 program introduces the following new classes into the OS/2 Workplace Shell class hierarchy. SOMObject │ └─ WPObject (replaced by PenObject) │ └─ WPAbstract │ ├─ WPSound (replaced by PenSound) │ ├─ WPMouse (replaced by PenMouse) │ ├─ PenButtonDevice │ │ │ ├─ PenLocator │ │ │ │ │ ├─ PenLocatorPen │ │ │ │ │ └─ PenLocatorFinger │ │ │ └─ PenDisplay │ └─ PenPenSubSystem Pen for OS/2 Classes Into OS/2 Workplace Shell Class Hierarchy This document describes the programming interface to the following Pen for OS/2 classes: o PenObject o PenSound o PenMouse o PenPenSubSystem Refer to the Pen for OS/2 Device Driver Reference, for programming information regarding the following Pen for OS/2 classes: o PenButtonDevice o PenLocator o PenLocatorPen o PenLocatorFinger o PenDisplay The following files are provided with the Pen for OS/2 Developer's Toolkit: o PENOBJ.H and PENOBJ.SC for the WPObject object replacement class. o PENSOUND.H and PENSOUND.SC for the WPSound object replacement class. o WPMOUSEP.H and WPMOUSEP.SC for the WPMouse object replacement class. o WPPENSYS.H and WPPENSYS.SC for the Customization object class. o PENBTNDV.H and PENBTNDV.SC for the button device object class. o WPDISPLAY.H and WPDISPLAY.SC for the display object class. o WPLOCATR.H and WPLOCATR.SC for the locator object class. o WPLOCPEN.H and WPLOCPEN.SC for the locator pen object class. o WPLOCFGR.H and WPLOCFGR.SC for the locator finger object class. ═══ 23.3. PenObject Object Class ═══ The PenObject object class will include these published methods and overrides: The penAddObjectEventPage method This method is called to allow the object to add the Gesture page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddObjectEventPage method is overridden to replace or remove the Gesture page. The penAddOverridesPage method This method is called to allow the object to add the Overrides page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddOverridesPage method is overridden to replace or remove the Overrides page. The penInvokeGestureHelp method This method is called to cause the Settings notebook to be opened to the Gesture page. This method must be overridden if the penAddObjectEventPage method is overridden to remove the Gesture page, because the penInvokeGestureHelp method refers to the Gesture page. Override to the wpAddSettingsPages method This method is overridden to insert the additional Settings pages. When overriding, use the BKA_* notebook flags. Override to the wpInitData method This method is overridden to initialize the object for the Pen for OS/2 system extension. When overriding, call the parent first. Override to the wpUnInitData method This method is overridden to uninitialize (remove settings) the object for the Pen for OS/2 system extension. When overriding, call the parent last. Override to the wpCreateAnother method This method is overridden to initialize the object for the Pen for OS/2 system extension. When overriding, call the parent first. Override to the wpSaveState method This method is overridden to save Pen for OS/2 system information for the object. When overriding, call the parent last. Override to the wpRestoreState method This method is overridden to restore Pen for OS/2 system information for the object. When overriding, call the parent first. parent .* last. Override to the wpFree method This method is overridden to deallocate Pen for OS/2 system information for the object. When overriding, call the parent last. ═══ 23.4. penAddObjectEventPage ═══ Syntax ULONG penAddObjectEventPage (PenObject * self, HWND hwndNotebook, PVOID pReserved), name lookup Purpose The penAddObjectEventPage method is called to allow the object to add the first Gesture page to its Settings notebook. Parameters self (PenObject *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. pReserved (PVOID) - input Reserved. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the first Gesture page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods o penInvokeGestureHelp ═══ 23.5. penInvokeGestureHelp ═══ Syntax ULONG penInvokeGestureHelp (PenObject * self), name lookup Purpose The penInvokeGestureHelp method is called to cause the Settings notebook to be opened to the Gesture page. Parameters self (PenObject *) - input The pointer to the instance object. Returns Success indicator: 1 Successful completion. 0 Error occurred. Remarks None. Usage This method may be called at any time. Override If the Gesture page is removed from the object, this method should be overridden also. This will prevent the Gesture page from being invoked through gesturing. Related Methods o penAddObjectEventPage ═══ 23.6. penAddOverridesPage ═══ Syntax ULONG penAddOverridesPage (PenObject * self, HWND hwndNotebook) Purpose The penAddOverridesPage method is called to allow the object to add the Overrides page to its Settings notebook. Parameters self (PenObject *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Overrides page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 23.7. PenSound Object Class ═══ The PenSound object class will include these published methods and overrides: The penAddPenPauseBeepPage method This method is called to allow the object to add the Pause Beep page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddPenPauseBeepPage method is overridden to replace or remove the Pause Beep page. Override to the wpAddSettingsPages method This method is overridden to insert the additional Settings pages. When overriding, call the parent first to insert pages added at the top of the notebook, or call the parent last to insert pages added at the bottom of the notebook. Override to the wpInitData method This method is overridden to initialize Pen for OS/2 system information. When overriding, call the parent first. Override to the wpSaveState method This method is overridden to save Pen for OS/2 system information. When overriding, call the parent last. Override to the wpRestoreState method This method is overridden to restore Pen for OS/2 system information. When overriding, call the parent first. ═══ 23.8. penAddPenPauseBeepPage ═══ Syntax ULONG penAddPenPauseBeepPage (PenSound * self, HWND hwndNotebook) Purpose The penAddPenPauseBeepPage method is called to allow the object to add the Pause Beep page to its Settings notebook. Parameters self (PenSound *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Pause Beep page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 23.9. PenMouse Object Class ═══ The PenMouse object class will include these published methods and overrides: The penAddMousePenTimingPage method This method is called to allow the object to add the Pen Timing page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddMousePenTimingPage method is overridden to replace or remove the Pen Timing page. Override to the wpAddSettingsPages method This method is overridden to insert the additional Settings pages. When overriding, call the parent first to insert pages added at the top of the notebook, or call the parent last to insert pages added at the bottom of the notebook. Override to the wpAddMouseTimingPage method This method is overridden to add the Pen Timing page as page 2 of the Timing page. When overriding, call the parent last. Override to the wpInsertSettingsPage method This method is overridden to add the page number to the Timing page. When overriding, call the parent first. ═══ 23.10. penAddMousePenTimingPage ═══ Syntax ULONG penAddMousePenTimingPage (PenMouse * self, HWND hwndNotebook) Purpose The penAddMousePenTimingPage method is called to allow the object to add the Pen Timing page to its Settings notebook. Parameters self (PenMouse *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Pen Timing page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 23.11. PenPenSubSystem Object Class ═══ The PenPenSubSystem object is a new class and is a child of the WPAbstract class. It will have these published methods and overrides: The penAddPenFeedback2Page method This method is called to allow the object to add the Feedback page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddPenFeedback2Page method is overridden to replace or remove the Feedback page. The penAddPenTimeouts1Page method This method is called to allow the object to add the Timeouts page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddPenTimeouts1Page method is overridden to replace or remove the Timeouts page. The penAddObjectEventPage method This method is called to allow the object to add the first Gesture page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddObjectEventPage method is overridden to replace or remove the first Gesture page. The penAddObjectEventPage2 method This method is called to allow the object to add the second through the fourth Gesture pages to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddObjectEventPage2 method is overridden to replace or remove the second through the fourth Gesture pages. If the penAddObjectEventPage method is overridden to remove the first Gesture page, then to complete the procedure you would override this method to remove the second through the fourth Gesture pages. The penInvokeGestureHelp method This method is called to cause the Settings notebook to be opened to the Gesture page. This method must be overridden if the penAddObjectEventPage method is overridden to remove the Gesture page, because the penAddObjectEventPage method refers to the Gesture page. The penAddTrainingPage method This method is called to allow the object to add the Training page to its Settings notebook. This method can be called only from within an override of the wpAddSettingsPages method. The penAddTrainingPage method is overridden to replace or remove the Training page. Override to the wpAddSettingsPages method This method is overridden in order to insert the additional Settings pages. When overriding, call the parent first to insert pages added at the top of the notebook, or call the parent last to insert pages added at the bottom of the notebook. Override to the wpAddObjectWindowPage method This method is overridden in order to remove the Window page from the Settings notebook. It returns SETTINGS_PAGE_REMOVED, without calling the parent. Override to the wpFilterPopupMenu method This method is overridden to filter out unwanted menu options. When overriding, call the parent first. Override to the wpclsQueryDefaultHelp class method This method is overridden in order to set the help library for the class. Override to the wpclsQueryDefaultView class method This method is overridden in order to set the default view for the class to OPEN_SETTINGS. When overriding, return a valid view. Override to the wpclsQueryIconData class method This method is overridden to set the icon for the class. When overriding, the correct size of the ICONINFO structure must be returned. Override to the wpclsQueryStyle class method This method is overridden in order to set the default object style for the class. When overriding, call the parent first. Override to the wpclsQueryTitle class method This method is overridden in order to set the default title for the class. When overriding, return a pointer of a valid string. ═══ 23.12. penAddFeedback2Page ═══ Syntax ULONG penAddFeedBack2Page (PenPenSubSystem * self, HWND hwndNotebook) Purpose The penAddPenFeedback2Page method is called to allow the object to add the Feedback page to its Settings notebook. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Feedback page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 23.13. penAddTimeouts1Page ═══ Syntax ULONG penAddTimeouts1Page (PenPenSubSystem * self, HWND hwndNotebook) Purpose The penAddPenTimeouts1Page method is called to allow the object to add the Timeouts page to its Settings notebook. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Timeouts page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 23.14. penAddObjectEventPage ═══ Syntax ULONG penAddObjectEventPage (PenPenSubSystem * self, HWND hwndNotebook, PVOID pReserved), name lookup Purpose The penAddObjectEventPage method is called to allow the object to add the first Gesture page to its Settings notebook. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. pReserved (PVOID) - input Reserved. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the first Gesture page. If this method is overridden to remove the first Gesture page, then to complete the procedure you would override the penAddObjectEventPage2 method to remove the second through the fourth Gesture pages. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. The penInvokeGestureHelp method must also be overridden if this page is removed. Related Methods o penAddObjectEventPage2 o penInvokeGestureHelp ═══ 23.15. penAddObjectEventPage2 ═══ Syntax ULONG penAddObjectEventPage2 (PenPenSubSystem * self, HWND hwndNotebook, PVOID pReserved), name lookup Purpose The penAddObjectEventPage method is called to allow the object to add the second through the fourth Gesture pages to its Settings notebook. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. pReserved (PVOID) - input Reserved. Returns Page identifier: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the second through the fourth Gesture pages. If the penAddObjectEventPage method is overridden to remove the first Gesture page, then to complete the procedure you would override the penAddObjectEventPage2 method to remove the second through the fourth Gesture pages. To remove the pages, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods o penAddObjectEventPage ═══ 23.16. penInvokeGestureHelp ═══ Syntax ULONG penInvokeGestureHelp (PenPenSubSystem* self, HOBJECT hObject), name lookup The penInvokeGestureHelp method is called to cause the Settings notebook to be opened to the Gesture page. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hObject (HOBJECT) - input Contains one of the following values: REBHOBJ_OS2 REDHOBJ_WIN REDHOBJ_DOS REDHOBJ_PM Returns Success indicator: 1 Successful completion. 0 Error occurred. Remarks None. Usage This method may be called at any time. Override If the Gesture page is removed from the object, then this method should be overridden to prevent Gesture from being invoked. Return the value 1, without calling the parent. Related Methods o penAddObjectEventPage ═══ 23.17. penAddTrainingPage ═══ Syntax ULONG penAddTrainingPage (PenPenSubSystem * self, HWND hwndNotebook) Purpose The penAddTrainingPage method is called to allow the object to add the Training page to its Settings notebook. Parameters self (PenPenSubSystem *) - input The pointer to the instance object. hwndNoteBook (HWND) - input The handle of the notebook in which to insert the page. Returns Success indicator: 0 Error occurred. PageId Identifier for the inserted page. Remarks None. Usage This method can be called only from within an override of the wpAddSettingsPages method. Override This method is overridden to replace or remove the Training page. To remove the page, return SETTINGS_PAGE_REMOVED, without calling the parent. Related Methods None. ═══ 24. Appendix A. Pen for OS/2 Libraries and Header Files ═══ The Pen for OS/2 system extension libraries and header files are described in this section. ═══ 24.1. Toolkit Installation ═══ The Pen for OS/2 Toolkit installation provides the header files, the import library files and the class definitions files. ═══ 24.2. Compiler Options ═══ Pen for OS/2 declares structures as packed on a word boundary. The application needs to use the same pack definition in the compile statement or pack on a byte boundary. ═══ 24.3. Header Files ═══ Pen for OS/2 header files are listed and a brief description is provided: PENPM.H This header file is included in all modules that use Pen for OS/2. PENPMORD.H This header contains a list of ordinal entry points for the different functions of Pen for OS/2. ═══ 24.4. Pen for OS/2 Object Class Hierarchy ═══ The following diagram lists a portion of the predefined object classes in a hierarchical order. ──SOMObject └─WPObject ├─PenObject └─WPAbstract ├─PenPenSubSystem ├─PenButtonDevice │ ├─PenLocator │ │ ├─PenLocatorPen │ │ └─PenLocatorFinger │ └─PenDisplay ├─WPSound │ └─PenSound └─WPMouse └─PenMouse The following table provides the class branch, the file extensions, the file class, and the parent. ┌────────────┬─────────────────┬──────────────────┬──────────────────┐ │ CLASS-STEM │ FILE EXTENSIONS │ CLASS │ PARENT │ ├────────────┼────────┬────────┼──────────────────┼──────────────────┤ │ PENOBJ │ .H │ .SC │ PenObject │ WPObject │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPPENSYS │ .H │ .SC │ PenPenSubSystem │ WPAbstract │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ PENBTNDV │ .H │ .SC │ PenButtonDevice │ WPAbstract │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPMOUSEP │ .H │ .SC │ PenMouse │ WPMouse │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ PENSOUND │ .H │ .SC │ PenSound │ WPSound │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPLOCPEN │ .H │ .SC │ PenLocatorPen │ PenLocator │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPLOCFGR │ .H │ .SC │ PenLocatorFinger │ PenLocator │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPLOCATR │ .H │ .SC │ PenLocator │ PenButtonDevice │ ├────────────┼────────┼────────┼──────────────────┼──────────────────┤ │ WPDISPLY │ .H │ .SC │ PenDisplay │ PenButtonDevice │ └────────────┴────────┴────────┴──────────────────┴──────────────────┘ ═══ 24.5. Library Support ═══ The Pen for OS/2 library provides libraries for your application to link to Pen for OS/2. ═══ 24.5.1. Stub Linkage ═══ The stub linkage provided is PENPMST.LIB. This stub library maps all Pen for OS/2 entry points for the Wrtxxx, Redxxx, and Vkpxxx calls defined in PENPM.DLL. The stub library checks if Pen for OS/2 is installed and jumps to the dynamically loaded function code or returns an error, WRTERR_PEN_NOT_INSTALLED, to the caller if Pen for OS/2 is not installed. ═══ 24.5.2. Load-Time Linkage ═══ The load-time linkage provided is PENPM.LIB. This import library is used on load-time linkage for any module making use of Pen for OS/2 defined in PENPM.DLL. The APIs provided are Pen Writing Subsystem (Wrtxxx), Recognition Event Delivery (Redxxx), Virtual Keyboard Playback (Vkpxxx), and Workplace Methods (M_Penxxx and Penxxx). ═══ 24.5.3. Run-Time Linkage ═══ Run-time linking allows an application to load PENPM.DLL when it is required. The application uses the DosLoadModule function to load the DLL and uses the DosQueryProcAddr function to obtain a pointer to the desired Pen for OS/2 function. The function can also be referenced by its ordinal value defined in PENPMORD.H. ═══ 24.6. Library Usage ═══ This section provides instruction on linking the Pen for OS/2 libraries dependent on your system. ═══ 24.6.1. Mixed Mode Applications ═══ A pen-aware application that supports Pen for OS/2 that also needs to run when Pen for OS/2 is not installed should link with the static-stub library PENPMST.LIB and should issue the function call WrtWaitActive to determine if Pen for OS/2 is up and running. If Pen for OS/2 is not installed, the function call WrtWaitActive with a timeout of a few seconds, (for example, 15 seconds) will return WRTERR_PEN_NOT_INSTALLED and any other function call defined in the static-stub library PENPMST.LIB will return an error. The application could, for example, grey out pen-aware menu controls when Pen for OS/2 is not installed and take other appropriate actions. If Pen for OS/2 is installed, the function call WrtWaitActive (ulTimeout) with a timeout of a few seconds, (for example, 15 seconds) will return immediately and any other function call defined in the static-stub library PENPMST.LIB will call the appropriate API. ═══ 24.6.2. Pen-aware Applications ═══ A pen-aware application that requires Pen for OS/2 in order to run should link with PENPM.LIB. The application should also issue the function call WrtWaitActive to determine if Pen for OS/2 is up and running. If Pen for OS/2 is installed, the function call WrtWaitActive (ulTimeout) with a timeout of a few seconds, (for example, 15 seconds) will return immediately and any other function call defined in the library PENPM.LIB will be available to the application. An attempt to run a program that has been linked with PENPM.LIB on a system without Pen for OS/2 will result in the OS/2 loader failing to load the program. ═══ 25. Appendix B. Notices ═══ 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 IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577. ═══ 25.1. 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 The following terms, denoted by a double asterisk (**) in this publication are trademarks of other companies as follows: WACOM Wacom Co., Ltd. Windows Microsoft Corporation ═══ 26. Glossary ═══ 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 ANSI/EIA Standard-440-A: Fiber Optic Terminology. Copies may be purchased from the Electronic Industries Association, 2001 Pennsylvania Avenue, N.W., Washington DC 20006. Definitions are identified by the symbol (E) 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. A accelerator. A key or combination of keys that invokes an application-defined function. active window. The window that a user is currently interacting with. The window that is active has a highlighted border and title bar. Contrast with inactive window. 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. array. (1) An arrangement of data in one or more dimensions: a list, a table, or a multidimensional arrangement of items. (2) In programming languages, an aggregate that consists of data objects, with identical attributes, each of which may be uniquely referenced by subscripting. (I) 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. attribute. A named property of an entity. B backlight. The fluorescent lighting on 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. bit map. A representation of an image by an array of bits. bounding box. The smallest rectangle that fully encloses a gesture. buffer. (1) A routine or storage used to compensate for a difference in rate of flow of data, or time of occurrence of events, when transferring data from one device to another. (A) (2) A portion of storage used to hold input or output data temporarily. 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. byte. A string that consists of a number of bits, usually 8, that are treated as a unit and represent a character. C cache. (1) A special-purpose buffer storage, smaller and faster than main storage, used to hold a copy of instructions and data obtained from main storage and likely to be needed next by the processor. (T) (2) A buffer storage that contains frequently accessed instructions and data; it is used to reduce access time. 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. child window. A window that appears within the border of its parent window (either a primary window or another child window). When the parent window is resized, moved or destroyed, the child window is also resized, moved or destroyed. However, the child window can be moved or resized independently from the parent window, within the boundries of the parent window. Contrast with parent window. 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. class object. The run-time implementation of a class. click. To press and release a mouse button without moving the pointer off the choice. See double-click. client area. The part of the window inside the border that is below the menu bar. It is the user's work space, where a user types information and selects choices from selection fields. In primary windows, it is where an application programmer presents the objects that a user works on. client window. The window in which the application displays output and receives input. This window is located inside the frame window, under the window title bar and any menu bar, and within any scroll bars. clipboard. An area of computer memory or storage that temporarily holds data. Date in the clipboard is available to other applications. coalesce. (1) To combine two or more sets of items into one set of any form. (I) (2) To combine two or more files into one file. composite window. A window composed of other windows (such as a frame window, frame-control windows, and a client window) that are kept together as a unit and that interact with each other. 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. copy. To place onto the clipboard a duplicate of what has been selected. CRT display. Cathode ray tube display. D database. A collection of data with a given structure for accepting, storing, and providing, on demand, data for multiple users. (T) DCB. Device control block. desktop. A folder that fills the entire screen and holds all the objects with which the user can interact to perform operations on the system. 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 ID. A unique identification 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. dialog. (1) The interaction between a user and a computer. (2) In an interactive system, a series of related inquiries and responses similar to a conversation between two people. dialog box. A movable window, fixed in size, containing controls that a user uses to provide information required by an application so that it can continue to process a user request. digitizer. An electronic device that transmits coordinate data to software running on a computer. DLL. Dynamic link library. double-click. To press and release a mouse button twice within a time frame defined by the user, without moving the pointer off the choice. See click. double-tap. To touch a touch-sensitive screen with a pointing device twice in rapid succession within a small area. drag. To use a pointing device to move an object. drop. To fix the position of an object that is being dragged by releasing the select button on the pointing device. 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. 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. Emulation is usually achieved by means of hardware or firmware. (T) 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. frame-control window. A control window, owned by the frame window, that accepts simple input from the user and notifies the frame window or client window when it receives input. frame window. The window used as a base when constructing a primary window or composite window. The frame window coordinates the action of frame controls and the client window, enabling them to act as a single unit. function. (1) A specific purpose of an entity, or its characteristic action. (A) (2) A machine action such as a carriage return or a line feed. (A) (3) A subroutine that returns the value of a single variable and that usually has a single exit; for example, subroutines that compute mathematical functions, such as sine, cosine, logarithm, or that compute the maximum of a set of numbers. (T) 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. gesture mode. An input mode in which the system interprets pen input as gestures. Contrast with mouse-emulation mode. H header. (1) System-defined control information that precedes user data. (2) The portion of a message that contains control information for the message such as one or more destination fields, name of originating station, input sequence number, character string indicating the type of message, and priority level for the message. hot key. (1) The key combination used to change from one session to another on the workstation. (2) To jump, or hot key, from a host session to an application on the workstation, or from the workstation to the host session. hot spot. The area of a display screen that is activated to accept user input. Synonymous with touch area. I inactive window. A window you that a user is not currently interacting with. 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 the 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. ink. The trail resulting from writing with the pen. J joy stick. In computer graphics, a lever that can pivot in all directions and that is used as a locator device. (T) K kernel. The part of an operating system that performs basic functions, such as allocating hardware resources. L LCD. Liquid crystal display. LED. Light-emitting diode. lift-off point. Location plotted by the digitizer where a pointing device is removed from a touch-sensitive surface. 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. M message. (1) A packet of data used for communication between the Presentation Manager interface and Presentation Manager applications. (2) Information not requested by a user but displayed in response to an unexpected event, or when something undesirable could occur. method. An action that can be performed on an object. mouse-emulation mode. An input mode in which the system interprets pen input as mouse input. O object. (1) A graphic symbol that a user works with to perform a task. (2) In System Object Model, a set of data and the actions that can be performed on that data. object definition. See class. OEM. Original equipment manufacturer. Original equipment manufacturer (OEM). A manufacturer of equipment that may be marketed by another manufacturer. P parent class. A class from which another another class inherits. See inheritance. parent process. A process that creates other processes. Contrast with child process. parent window. In the OS/2 operating system, a window that creates a child window. The child window is drawn within the parent window. If the parent window is moved, resized, or destroyed, the child window also will be moved, resized, or destroyed. However, the child window can be moved and resized independently from the parent window, within the boundaries of the parent window. 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). pause and drag. To pause and then move the pointing device so that the pointer travels to a different location on the screen. Dragging ends when the pointing device is removed from the touch-sensitive surface. See pause. 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 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. pointer. (1) A data element that indicates the location of another data element. (T) (2) In computer graphics, a manually operated functional unit used to specify an addressable point. A pointer may be used to conduct interactive graphic operations, such as selection of one member of a predetermined set of display elements, or indication of a position on a display space while generating coordinate data. (T) (3) An identifier that indicates the location of an item of data. (A) (4) The symbol displayed on the screen that a user moves with a pointing device, such as a mouse. (5) A physical or symbolic identifier of a unique target. (6) In the C language, a variable that holds the address of a data object or a function. pointing device. An instrument, such as a pen, mouse, track ball or joy stick, used to move a pointer on the screen. pop-up window. See dialog box. 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 group. Several programs that can be acted upon as a single entity. program object. An object representing the file that starts a program. You can change the settings for this object to specify the gesture assignments for the particular program. proximity zone. In pen environments, an area where pen action is sensed by a touch-sensitive device without the pen touching the touch-sensitive surface. The zone varies depending on the technology of the digitizer, but it is usually no more than 6.35 mm (0.25 in.) from the surface. puck. A device used to select a particular location on a tablet. Q query. (1) A request for data from a database, based on specified conditions; for example, a request for availability of a seat on a flight reservation system. (T) (2) The process by which a master station asks a slave station to identify itself and to give its status. (T) (3) A request for information from a file based on specific conditions; for example, a request for a list of all customers whose balance is greater than $1000. R resolution. In computer graphics, a measure of the sharpness of an image, expressed as the number of lines and columns on the display screen or the number of pels per unit of area. return code. (1) A code used to influence the execution of succeeding instructions. (A) (2) A value returned to a program to indicate the results of an operation requested by that program. ring level. See privilege level. S screen. The physical surface of a display device upon which information is shown to a user. scroll. To move a display image vertically or horizontally to view data that otherwise cannot be observed within the boundaries of the display screen. settings. Characteristics of objects that the user can view and sometimes alter. setup object. An object that provides a means of communication between a user and a piece of equipment or a system. 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 turning off the computer to ensure that data and configuration information are not lost. slider. A control that represents a quantity and its relationship to the range of possible values for that quantity. For example, a slider might indicate a time range from 0 to 10 minutes. See also slider arm. slider arm. The visual indicator in a slider that shows that the numerical value can be changed by manipulating it. See slider. SOM. System Object Model. source directory. The directory from which information is read. Contrast with target directory. spreadsheet. A worksheet arranged in rows and columns, in which a change in the contents of one cell can cause electronic recomputation of one or more cells, based on user defined relations among the cells. (A) string. (1) A sequence of elements of the same nature, such as characters considered as a whole. (T) (2) In programming languages, the form of data used for storing and manipulating text. 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 of the parent class and can define new methods or override existing methods to define new behavior not inherited from the parent class. See inheritance. syntax (1) The relationship among characters or groups of characters, independent of their meanings or the manner of their interpretation and use. (I) (A) (2) The structure of expressions in a language. (A) (3) The rules governing the structure of a language. (A) (4) The relationship among symbols. (A) (5) The rules for the construction of a statement. System Object Model. A mechanism for language-neutral, object-oriented programming in the OS/2 environment. T tablet. (1) A special flat surface with a mechanism for indicating positions thereon, normally used as a locator. (I) (2) See also puck. 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. template. A pattern to help the user identify the location of keys on a keyboard, functions assigned to keys on a keyboard, or switches and lights on a control panel. toggle. To switch between two modes; for example, to switch between selected and deselected mode. Tool Bar. A bar containing choices that represent tools. When you select a choice from the bar, the defined action for the choice occurs. touch area. Synonym for hot spot. touch-down point. Location plotted by a digitizer where contact is made with a touch-sensitive device. 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. touch screen. A display device that allows the user to interact with a computer system by touching an area on its screen. Syninymous with touch-sensitive screen. track ball. Synonym for control ball. U unit number. A number used by a device driver to select a specific logical device. A unit number is unique only within the scope of the driver. V VGA. Video graphics array. W window. An area of the screen with visible boundaries within which information is displayed. A window can be smaller than or the same size as the screen. Windows can appear to overlap on the screen. window class. The grouping of windows whose processing needs conform to the services provided by one window procedure. window class style. The set of properties that apply to every window in a window class. ═══ ═══ When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, choose the Bookmark option from the Services menu. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Select the Place radio button (or press the Up or Down Arrow key to select it). 5. Select OK. The bookmark is then added to the bookmark list. ═══ ═══ You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list. To search for a word or phrase in all topics, do the following: 1. Choose the Search option from the Services pull-down. 2. Type the word or words to be searched. 3. Select All sections. 4. Select Search to begin the search. 5. The list of topics where the word or phrase appears is displayed. ═══ ═══ You can print one or more topics. You can also print a set of topics by first marking the topics on the Contents list. To print the document Contents list, do the following: 1. Select Print from the Services menu. 2. Select Contents. 3. Select Print. 4. The Contents list is printed on your printer. ═══ ═══ You can copy a topic you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using an editor such as the System Editor. To copy a topic, do the following: 1. Expand the Contents list and select a topic. 2. When the topic appears, select Copy to file from the Services menu. The system copies the text pertaining to that topic into the temporary TEXT.TMP file. For information on any of the other choices in the Services menu, highlight the choice and press the F1 key. ═══ ═══ You can control the appearance of the Contents list. To expand the Contents and show all levels for all topics, select Expand all from the Options menu. For information on any of the other choices in the Options menu, highlight the choice and press the F1 key. ═══ ═══ Trademark of the IBM Corporation. ═══ ═══ Trademark of the Microsoft Corporation. ═══ ═══ WACOM is a trademark of Wacom Co., Ltd.