Microsoft Programmer's Library 1.3/Microsoft_Programmers_Library.7z/MPL/os2/prgmr2.txt

Text File | 2013-11-08 | 1.4 MB | 38,260 lines

 Microsoft Operating System/2: Programmer's Reference Volume 2


 ══════════════════════════════════════════════════════════════════════════


 Microsoft(R) Operating System/2: Programmer's Reference Volume 2

 Version 1.1


 ══════════════════════════════════════════════════════════════════════════


   Information in this document is subject to change without notice and does
   not represent a commitment on the part of Microsoft Corporation. The
   software and/or databases described in this document are furnished under a
   license agreement or nondisclosure agreement. The software and/or
   databases may be used or copied only in accordance with the terms of the
   agreement. The purchaser may make one copy of the software for backup
   purposes. No part of this manual and/or database may be reproduced or
   transmitted in any form or by any means, electronic or mechanical,
   including photocopying, recording, or information storage and retrieval
   systems, for any purpose other than the purchaser's personal use, without
   the written permission of Microsoft Corporation.

   PUBLISHED BY

   (C) Copyright Microsoft Corporation, 1989. All rights reserved.

   Printed in the United States of America.

   The character-set tables in this manual are reprinted by permission from
   the IBM Operating System/2 User's Reference, (C) 1987 by International
   Business Machines Corporation.

   Microsoft(R), MS(R), MS-DOS(R), and the Microsoft logo are registered
   trademarks of Microsoft Corporation.

   IBM(R), PC/AT(R), and Personal System/2(R) are registered trademarks
   of International Business Machines Corporation.

   Document No. LN0702B-110-I00-0289



 ────────────────────────────────────────────────────────────────────────────
 Contents


 Chapter 1  Introduction
        1.1     Overview
        1.2     How to Use This Manual
        1.3     Naming Conventions
        1.4     Notational Conventions

 Chapter 2  Functions Directory
        2.1     Introduction
        2.2     Functions

 Chapter 3  Messages Directory
        3.1     Introduction
        3.2     Messages

 Chapter 4  Types, Macros, Structures
        4.1     Introduction
        4.2     Types
        4.3     Macros
        4.4     Structures

 Chapter 5  File Formats
        5.1     Introduction
        5.2     Font-File Format
        5.3     Font Signature
        5.4     Font Metrics
        5.5     Font Character Definition
        5.6     Code-Page Font Support

 Appendix A  Error Values
        A.1     Introduction
        A.2     Errors

 Appendix B  Device Capabilities
        B.1     Introduction
        B.2     About Device Capabilities

 Figures
        Figure 1.1     Sample Reference Page

 Tables
        Table 5.1      Additional Glyphs



 ────────────────────────────────────────────────────────────────────────────
 Chapter 1  Introduction

        1.1     Overview
        1.2     How to Use This Manual
            1.2.1     C Format
            1.2.2     MS OS/2 Include Files
            1.2.3     MS OS/2 Calling Conventions
            1.2.4     Bit Masks in Function Parameters
            1.2.5     Structures
        1.3     Naming Conventions
            1.3.1     Parameter and Field Names
                1.3.1.1    Prefixes
                1.3.1.2    Base Types
            1.3.2     Constant Names
        1.4     Notational Conventions

 1.1  Overview

   This manual describes the Dev, Gpi, and Win system functions of
   Microsoft(R) Operating System/2 (MS(R) OS/2). These functions, also called
   the Presentation Manager functions, let programs use the window-management
   and graphics features of MS OS/2.

   MS OS/2 system functions are designed to be used in C, Pascal, and other
   high-level-language programs, as well as in assembly-language programs. In
   MS OS/2, all programs request operating-system services by calling system
   functions.

   This chapter, "Introduction," shows how to use this manual, provides a
   brief description of MS OS/2 calling conventions, illustrates function
   calls in various languages, and outlines MS OS/2 naming conventions.

   Chapter 2, "Functions Directory," is an alphabetical listing of MS OS/2
   Presentation Manager functions. This chapter defines each function's
   purpose, gives its syntax, describes the function parameters, and gives
   possible return values. Many functions also show simple program examples
   that illustrate how the function is used to carry out simple tasks.

   Chapter 3, "Messages Directory," lists the messages sent and received by
   MS OS/2 Presentation Manager functions.

   Chapter 4, "Types, Macros, Structures," describes the types, macros, and
   structures used by MS OS/2 Presentation Manager functions.

   Chapter 5, "File Formats," describes the format of font files. Font files
   contain bitmap or vector information that MS OS/2 needs for drawing
   characters using Gpi functions.

   Appendix A, "Error Values," lists error codes and their corresponding
   values.

   Appendix B, "Device Capabilities," lists the device capabilities that can
   be determined by using the DevQueryCaps function.

   This manual is intended to fully describe MS OS/2 Presentation Manager
   functions and the structures and file formats used with these functions.
   It does not show how to use these functions to carry out specific tasks.
   For more information on this topic, see the Microsoft Operating System/2
   Programmer's Reference, Volume 1. Also, this manual does not describe MS
   OS/2 base system functions. MS OS/2 base system functions let programs use
   the operating system to carry out tasks such as reading from and writing
   to disk files; allocating memory; starting other programs; and using the
   keyboard, mouse, and video screen. For more information on MS OS/2 base
   system functions, see the Microsoft Operating System/2 Programmer's
   Reference, Volume 3.


 1.2  How to Use This Manual

   This manual provides detailed information about each MS OS/2 Presentation
   Manager function, message, macro, and structure. Each description has the
   following format:

   ┌────────────────────────────────────────────────────────────────────────┐
   │ Figure 1.1 can be found in Section 1.2 of the printed manual.          │
   └────────────────────────────────────────────────────────────────────────┘

   Figure 1.1  Sample Reference Page

   These are the elements shown:

   1.  The function, message, macro, or structure name.

   2.  The function, message, macro, or structure syntax. The syntax
       specifies the number of parameters (or fields) and gives the type of
       each. It also gives the order (from left to right) that parameters
       must be pushed on the stack. Comments to the right briefly describe
       the purpose of the parameter (or field).

   3.  A description of the function, message, macro, or structure, including
       its purpose and details of operation.

   4.  A full description of each parameter (or field), including permitted
       values and related structures.

   5.  A description of the function return value, including possible error
       values.

   6.  An example showing how the function can be used to accomplish a simple
       task.

   7.  A list of related functions, structures, macros, and messages.

 1.2.1  C Format

   In this manual, the syntax for MS OS/2 functions is given in C-language
   format. In your C-language sources, the function name must be spelled
   exactly as given in the syntax and the parameters must be used in the
   order given in the syntax. This syntax also applies to Pascal program
   sources.

   The following example shows how to call the WinAlarm function in a
   C-language program:

   /* sound an alarm when an error occurs */

   WinAlarm(HWND_DESKTOP,       /* alarm for the desktop window */
            WA_ERROR);          /* tone for errors              */

 1.2.2  MS OS/2 Include Files

   This manual uses many types, structures, and constants that are not part
   of standard C language. These items, designed for MS OS/2, are defined in
   the MS OS/2 C-language include files provided with the Microsoft OS/2
   Presentation Manager Softset and the Microsoft OS/2 Presentation Manager
   Toolkit.

   In C-language programs, the #include directive specifying os2.h, the MS
   OS/2 C-language include file, can be placed at the beginning of the source
   file to include the definitions for the special types, structures, and
   constants. Although there are many MS OS/2 include files, the os2.h file
   contains the additional #include directives needed to process the basic MS
   OS/2 definitions.

   To speed up processing of the MS OS/2 C-language include files, many
   definitions are processed only if the C-language program explicitly
   defines a corresponding include constant. An include constant is simply a
   constant name, with the prefix INCL_, that controls a portion of the
   include files. If a constant is defined using the #define directive, the
   corresponding MS OS/2 definitions are processed. For a list of the include
   constants and a description of the MS OS/2 system functions they enable,
   see the Microsoft Operating System/2 Programmer's Reference, Volume 1.

 1.2.3  MS OS/2 Calling Conventions

   You must know MS OS/2 calling conventions to use MS OS/2 functions in
   other high-level languages or in assembly language. MS OS/2 functions use
   the Pascal (sometimes called the PLM) calling convention for passing
   parameters, and they apply some additional rules to support dynamic-link
   libraries. The following rules apply:

   ■  You must push the parameters on the stack. In this manual, each
      function description lists the parameters in the order they must be
      pushed. The left parameter must be pushed first, the right parameter
      last. If a parameter specifies an address, the address must be a far
      address; that is, it must have the form selector:offset. The selector
      must be pushed first, then the offset.

   ■  The function automatically removes the parameters from the stack as it
      returns. This means the function must have a fixed number of
      parameters.

   ■  You must use an intersegment call instruction to call the function.
      This is required for all dynamic-link-library functions.

   ■  The function returns a value, possibly an error value, in either the ax
      register or the dx:ax register pair. Only the di and si register values
      are guaranteed to be preserved by the function. MS OS/2 Presentation
      Manager functions may preserve other registers as well, but they do not
      preserve the flags register. The contents of the flags register are
      undefined; specifically, the direction flag in the register may be
      changed. However, if the direction flag was zero before the function
      was called, it will be zero after the function returns.

   The following example shows how MS OS/2 calling conventions apply to the
   WinCreateStdWindow function in an assembly-language program:

   EXTRN WINCREATESTDWINDOW:FAR

   hwndParent            dd      01H
   flCreateFlags         dd      0FH
   szClientClass         db     "MyClass", 0
   szTitle               db     "My Window", 0
   hwndClient            dd      01H

   push word ptr [hwndParent+2]     ; handle of the parent window
   push word ptr [hwnParent]
   push 0                           ; frame-window style
   push 0
   push ds                          ; creation flags
   push offset flCreateFlags
   push ds
   push offset szClientClass        ; client-window class name
   push ds                          ; address of title-bar text
   push offset szTitle
   push 0                           ; client-window style
   push 0                           ;
   push 0                           ; handle of the resource file
   push 1                           ; resource identifier
   push ds                          ; address of client-window handle
   push offset hwndClient
   call WINCREATESTDWINDOW

   The following example shows how to call the same WinCreateStdWindow
   function in a C-language program. In C, the WinCreateStdWindow function
   name, parameter types, and constant names are defined in os2.h, the MS
   OS/2 C-language include file.

   # include <os2.h>

   HWND hwndParent = HWND_DESKTOP;
   ULONG flCreateFlags =
       FCF_TITLEBAR | FCF_SYSMENU | FCF_MENU | FCF_SIZEBORDER;
   HWND hwndClient;

   WinCreateStdWindow(
       hwndParent,          /* handle of the parent window     */
       0L,                  /* frame-window style              */
       &flCreateFlags,      /* creation flags                  */
       "MyClass",           /* client-window class name        */
       "My Window",         /* address of title-bar text       */
       0L,                  /* client-window style             */
       0,                   /* handle of the resource file     */
       1,                   /* resource identifier             */
       &hwndClient);        /* address of client-window handle */


 1.2.4  Bit Masks in Function Parameters

   Many MS OS/2 system functions accept or return bit masks as part of their
   operation. A bit mask is a collection of two or more bit fields within a
   single byte, or a short or long value. Bit masks provide a way to pack
   many Boolean flags (flags whose values represent on/off or true/false
   values) into a single parameter or structure field. In assembly-language
   programming, it is easy to individually set, clear, or test the bits in a
   bit mask by using instructions that modify or examine bits within a byte
   or a word. In C-language programming, however, the programmer does not
   have direct access to these instructions, so the bitwise AND and OR
   operators typically are used to examine and modify the bit masks.

   Since this manual presents the syntax of MS OS/2 system functions in
   C-language syntax, it also defines bit masks in a way that is easiest to
   work with using the C language: as a set of constant values. When a
   function parameter is a bit mask, this manual provides a list of constants
   (named or numeric) that represent the correct values used to set, clear,
   or examine each field in the bit mask. For example, the fsSelection field
   of the FATTRS structure in the GpiCreateLogFont function specifies several
   values, such as FATTR_SEL_ITALIC and FATTR_SEL_UNDERSCORE. These represent
   the "set" values of the fields in the bit mask. Typically, the description
   associated with the value explains the result of the function if the given
   value is used; that is, when the corresponding bit is set. Generally, the
   opposite result is assumed when the value is not used. For example, using
   FATTR_SEL_ITALIC in the fsSelection field enables the italic font; not
   using it disables the italic font.

 1.2.5  Structures

   Many MS OS/2 system functions use structures as input and output
   parameters. This manual defines all structures and their fields using
   C-language syntax. In most cases, the structure definition presented is
   copied directly from the C-language include files provided with the
   Microsoft C Optimizing Compiler. Occasionally, an MS OS/2 function may
   have a structure that has no corresponding include-file definition. In
   such cases, this manual gives an incomplete form of the C-language
   structure definition to indicate that the structure is not already defined
   in an include file.


 1.3  Naming Conventions

   In this manual, all parameter, variable, structure, field, and constant
   names conform to MS OS/2 naming conventions. MS OS/2 naming conventions
   are rules that define how to create names that indicate both the purpose
   and data type of an item used with MS OS/2 system functions. These naming
   conventions are used in this manual to help you readily identify the
   purpose and type of the function parameters and structure fields. These
   conventions are also used in most MS OS/2 sample program sources to make
   the sources more readable and informative.

 1.3.1  Parameter and Field Names

   With MS OS/2 naming conventions, all parameter and field names consist of
   up to three elements: a prefix, a base type, and a qualifier. A name
   always consists of at least a base type or a qualifier. In most cases, the
   name also includes a prefix.

   The base type, always written in lowercase letters, identifies the data
   type of the item. The prefix, also written in lowercase letters, specifies
   additional information about the item, such as whether it is a pointer, an
   array, or a count of bytes. The qualifier, a short word or phrase written
   with the first letter of each word uppercase, specifies the purpose of the
   item.

   There are several standard prefixes and base types. These are used for the
   data types most frequently used with MS OS/2.

   1.3.1.1  Prefixes

   The following is a list of standard prefixes used in MS OS/2 naming
   conventions:

╓┌─┌───────┌─────────────────────────────────────────────────────────────────╖
   Prefix  Description
   ──────────────────────────────────────────────────────────────────────────
   p       Pointer. This prefix identifies a far, or 32-bit, pointer to a
   Prefix  Description
   ──────────────────────────────────────────────────────────────────────────
   p       Pointer. This prefix identifies a far, or 32-bit, pointer to a
           given item. For example, pch is a far pointer to a character.

   np      Near pointer. This prefix identifies a near, or 16-bit, pointer to
           a given item. For example, npch is a near pointer to a character.

   a       Array. This prefix identifies an array of two or more items of a
           given type. For example, ach is an array of characters.

   i       Index. This prefix identifies an index into an array. For example,
           ich is an index to one character in an array of characters.

   c       Count. This prefix identifies a count of items. It is usually
           combined with the base type of the items being counted instead of
           the base type of the actual parameter. For example, cch is a count
           of characters even though it may be declared with the type USHORT.

   h       Handle. This prefix is used for values that uniquely identify an
           object but that cannot be used to access the object directly. For
   Prefix  Description
   ──────────────────────────────────────────────────────────────────────────
          object but that cannot be used to access the object directly. For
           example, hfile is a handle of a file.

   off     Offset. This prefix is used for values that represent offsets from
           the beginning of a buffer or a structure. For example, off is the
           offset from the beginning of the given segment to the specified
           byte.

   id      Identifier. This prefix is used for values that identify an
           object. For example, idSession is a session identifier.
   ──────────────────────────────────────────────────────────────────────────


   1.3.1.2  Base Types

   The following is a list of standard base types used in MS OS/2 naming
   conventions:

╓┌─┌───────┌─────────────────────────────────────────────────────────────────╖
   Base    Type/Description
   type
   ──────────────────────────────────────────────────────────────────────────
   f       BOOL. A 16-bit flag or Boolean value. The qualifier should
           describe the condition associated with the flag when it is TRUE.
           For example, fSuccess is TRUE if successful, FALSE if not; fError
           is TRUE if an error occurs and FALSE if no error occurs. For
           objects of type BOOL, a zero value implies FALSE; a nonzero value
           implies TRUE.

   ch      CHAR. An 8-bit signed value.

   s       SHORT. A 16-bit signed value.

   l       LONG. A 32-bit signed value.

   uch     UCHAR. An 8-bit unsigned value.

   us      USHORT. A 16-bit unsigned value.

   ul      ULONG. A 32-bit unsigned value.
   Base    Type/Description
   type
   ──────────────────────────────────────────────────────────────────────────
  ul      ULONG. A 32-bit unsigned value.

   b       BYTE. An 8-bit unsigned value. Same as uch.

   sz      CHAR[ ]. Array of characters, terminated with a null character
           (the last byte is set to zero).

   fb      UCHAR. Array of flags in a byte. This base type is used when more
           than one flag is packed in an 8-bit value. Values for such an
           array are typically created by using the logical OR operator to
           combine two or more values.

   fs      USHORT. Array of flags in a short (16-bit unsigned value). This
           base type is used when more than one flag is packed in a 16-bit
           value. Values for such an array are typically created by using the
           logical OR operator to combine two or more values.

   fl      ULONG. Array of flags in a long (32-bit unsigned value). This base
   Base    Type/Description
   type
   ──────────────────────────────────────────────────────────────────────────
  fl      ULONG. Array of flags in a long (32-bit unsigned value). This base
           type is used when more than one flag is packed in a 32-bit value.
           Values for such an array are typically created by using the
           logical OR operator to combine two or more values.

   sel     SEL. A 16-bit value that is used to hold a segment selector.
   ──────────────────────────────────────────────────────────────────────────


   The base type for a structure is usually derived from the structure name.
   An MS OS/2 structure name, always written in uppercase letters, is a word
   or phrase that describes the size, purpose, and/or intended content
   associated with the type. The base type is typically an abbreviation of
   the structure name. The following list gives the base types for the
   structures described in this manual:

   acc             fcdata          ptl
   acct            fm              ptri
   arcp            gradl           qmsq
   bmi             hci             rcfx
   bmp             hpga            rcl
   btncd           ibmd            rgb
   cbnd            krnpr           rgnrc
   clsi            lbnd            sbcd
   crst            matlf           sizfx
   csri            mbhdr           sizl
   ctchbf          mbnd            smhs
   dde             mi              swctl
   ddei            mqi             swent
   dop             oi              swp
   dlgt            pbnd            ti
   dlgti           pib             ubtn
   driv            proge           wprm
   erri            progt           wywin
   fat             ptfx

 1.3.2  Constant Names

   A constant name is a descriptive name for a numeric value used with an MS
   OS/2 function. All constant names are written in uppercase letters and
   have a prefix derived from the name of the function, object, or idea
   associated with the constant. The prefix is followed by an underscore (_)
   and the rest of the constant name, which indicates the meaning of the
   constant and may specify a value, action, color, or condition. A few
   common constants do not have prefixes──for example, NULL is used for null
   pointers of all types, and TRUE and FALSE are used with the BOOL data
   type.


 1.4  Notational Conventions

   The following notational conventions are used throughout this manual:

   Convention      Meaning
   ──────────────────────────────────────────────────────────────────────────
   bold            Bold type is used for keywords──for example, the names of
                   functions, data types, structures, and macros. These names
                   are spelled exactly as they should appear in source
                   programs.

   italics         Italic type is used to indicate the name of an argument;
                   this name must be replaced by an actual argument. Italics
                   are also used to show emphasis in text.

   this type       This type is used for example program-code fragments.
   ──────────────────────────────────────────────────────────────────────────



 ────────────────────────────────────────────────────────────────────────────
 Chapter 2  Functions Directory

        2.1     Introduction
        2.2     Functions

 2.1  Introduction

   This chapter describes MS OS/2 Dev, Gpi, and Win functions. These
   functions, also called MS OS/2 Presentation Manager functions, provide the
   special Presentation Manager features of MS OS/2, such as windows, message
   queues, and device-independent graphics. The Dev, Gpi, and Win functions
   represent three distinct function groups. As described in the following
   list, programs use these function groups to carry out specific tasks:

╓┌─┌───────────┌─────────────────────────────────────────────────────────────╖
   Function    Usage
   group
   ──────────────────────────────────────────────────────────────────────────
   Dev         Use the Presentation Manager device (Dev) functions to open
               and control Presentation Manager device drivers. These
               functions let you create device contexts that you can
               associate with a presentation space and use with the Gpi
               functions to carry out device-independent graphics for
               displays, printers, and plotters.

   Gpi         Use the graphics programming interface (Gpi) functions to
               create graphics output for a display, printer, and other
               output devices. The Gpi functions give you a full range of
               graphics primitives, from lines to complex curves to bitmaps.
               You choose the attributes for the primitives, such as color,
               line width, and pattern, and then draw lines, text, and
               shapes. The retained-graphics capability lets you save the
   Function    Usage
   group
   ──────────────────────────────────────────────────────────────────────────
              shapes. The retained-graphics capability lets you save the
               drawing in segments and build complex pictures by drawing a
               chain of segments.

   Win         Use the window-manager (Win) functions to create and manage
               windows. Presentation Manager applications use windows as the
               main interface with the user. The Win functions let you create
               menus, scroll bars, and dialog windows that let the user
               choose commands and supply input. Your application receives
               all mouse and keyboard input as messages from the message
               queue. The Win functions let you retrieve messages from the
               queue and dispatch them to the window the input is intended
               for.
   ──────────────────────────────────────────────────────────────────────────


   This chapter gives complete syntax, purpose, and parameter descriptions
   for each function. Types, macros, and structures used by a function are
   given with the function; these are described more fully in Chapter 4,
   "Types, Macros, Structures." The numeric values for error values returned
   by the functions are listed in Appendix A, "Error Values."

   Many of the function descriptions in this chapter include examples. The
   examples show how to use the functions to accomplish simple tasks. In
   nearly all cases, the examples are code fragments, not complete programs.
   A code fragment is intended to show the context in which a function can be
   used, but often assumes that variables, structures, and constants used in
   the example have been defined and/or initialized. Also, a code fragment
   may use comments to represent a task instead of giving the actual
   statements.

   Although the examples are not complete, you can still use them in your
   programs if you take the following steps:

   ■  Include the os2.h file in your program.

   ■  Define the appropriate include constants for the functions, structures,
      and constants used in the example.

   ■  Define and initialize all variables.

   ■  Replace comments that represent tasks with appropriate statements.

   ■  Check return values for errors and take appropriate actions.


 2.2  Functions

   The following is a complete list, in alphabetical order, of the MS OS/2
   Dev, Gpi, and Win functions.

 ────────────────────────────────────────────────────────────────────────────
 DevCloseDC
 ────────────────────────────────────────────────────────────────────────────
   HMF DevCloseDC (hdc)
   HDC hdc;                /*device-context handle                         */

   The DevCloseDC function closes the specified device context. If the device
   context is associated with a presentation space or was created by using
   the WinOpenWindowDC function, an error occurs and the device context is
   not closed. This function decrements the use count (by one) of processes
   that have accessed the device context. The device context is deleted when
   the use count reaches zero.

 Parameters

   hdc  Identifies the device context. An error results if this parameter
   identifies a screen device context or is associated with a micro
   presentation space.

 Return Value

   The return value is DEV_OK if the function is successful and the device
   context is not a metafile device context. The return value is DEV_ERROR if
   an error occurs. Any other return value indicates that the function closed
   a metafile device context and returned its handle.

 See Also

   DevOpenDC, WinOpenWindowDC


 ────────────────────────────────────────────────────────────────────────────
 DevEscape
 ────────────────────────────────────────────────────────────────────────────
   LONG DevEscape (hdc, cmdCode, cbInData, pbInData, pcbOutData, pbOutData)
   HDC hdc;                /*device-context handle                         */
   LONG cmdCode;           /*escape function to perform                    */
   LONG cbInData;          /*size of input buffer                          */
   PBYTE pbInData;         /*pointer to input buffer                       */
   PLONG pcbOutData;       /*pointer to buffer for number of bytes         */
                           /*received                                      */
   PBYTE pbOutData;        /*pointer to output buffer                      */

   The DevEscape function allows applications to access facilities of a
   device not otherwise available through the applications programming
   interface (API). Calls to escape functions are, in general, sent to the
   device driver and must be understood by it.

 Parameters

   hdc  Identifies the device context.

   cmdCode  Specifies the escape function to perform. The following escape
   functions are currently defined:

         DEVESC_QUERYESCSUPPORT
         DEVESC_GETSCALINGFACTOR
         DEVESC_STARTDOC
         DEVESC_ENDDOC
         DEVESC_NEXTBAND
         DEVESC_ABORTDOC
         DEVESC_NEWFRAME
         DEVESC_DRAFTMODE
         DEVESC_FLUSHOUTPUT
         DEVESC_RAWDATA

   Devices can define additional escape functions by using other cmdCode
   values in the following ranges:

   Range       Meaning
   ──────────────────────────────────────────────────────────────────────────
   32768-40959 Not stored in a metafile and not recorded (passed to the
               device driver for PM_Q_STD).

   40960-49151 Stored in a metafile only (passed to the device driver for
               PM_Q_STD).

   49152-57343 Stored in a metafile and recorded (not passed to the device
               driver for PM_Q_STD).

   57344-65535 Recorded only (not passed to the device driver for PM_Q_STD).
   ──────────────────────────────────────────────────────────────────────────

   cbInData  Specifies the number of bytes of data in the buffer pointed to
   by the pbInData parameter.

   pbInData  Points to the buffer that contains the input data required for
   the escape function.

   pcbOutData  Points to the buffer that receives the number of bytes of data
   in the buffer pointed by the pbOutData parameter. If data is returned in
   the pbOutData parameter, pcbOutData is updated to the number of bytes of
   data returned.

   pbOutData  Points to the buffer that receives the output from this escape.
   If this parameter is NULL, no data is returned.

 Return Value

   The return value is DEV_OK if the function is successful, DEVESC_ERROR if
   an error occurs, or DEVESC_NOTIMPLEMENTED if the escape function is not
   implemented for the specified code.

 Comments

   The standard escape functions, or escapes, are listed as follows, with the
   contents of each DevEscape parameter:

   The DEVESC_QUERYESCSUPPORT escape determines whether the device driver has
   implemented a particular escape. The return value gives the result. This
   escape is not stored in a metafile or recorded.

   For DEVESC_QUERYESCSUPPORT, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Specifies the number of bytes pointed to by the pbInData
                   parameter.

   pbInData        Specifies the escape-code value of the escape function to
                   be checked.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_GETSCALINGFACTOR escape returns the scaling factors for the x
   and y axes of a printing device. For each scaling factor, an exponent of
   two is put in the pbOutData parameter. For example, the value 3 is used if
   the scaling factor is 8. Scaling factors are used by devices that cannot
   support graphics at the same resolution as the device resolution.

   For DEVESC_GETSCALINGFACTOR, the DevEscape parameters contain the
   following information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Points to the number of bytes of data pointed to by the
                   pbOutData parameter. Upon return, this parameter is
                   updated to the number of bytes returned.

   pbOutData       Points to the buffer that receives the output from this
                   escape. A structure is returned that specifies the scaling
                   factors for the x and y axes.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_STARTDOC escape allows an application to indicate that a new
   print job is starting and that all subsequent calls to DEVESC_NEWFRAME
   should be spooled under the same job, until DEVESC_ENDDOC is called. This
   ensures that documents longer than one page are not interspersed with
   other jobs.

   For DEVESC_STARTDOC, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Specifies the number of bytes pointed to by the pbInData
                   parameter.

   pbInData        Points to the null-terminated ASCII string that specifies
                   the name of the document.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_ENDDOC escape ends a print job started by the DEVESC_STARTDOC
   escape.

   For DEVESC_ENDDOC, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Points to the buffer that specifies the number of
                   characters in the string pointed to by the pbOutData
                   parameter. This parameter should be NULL if the number of
                   characters is zero.

   pbOutData       Points to the USHORT value that specifies the job
                   identifier if a spooler print job was created.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_NEXTBAND escape allows an application to signal that it has
   finished writing to a "band," or rectangle. The coordinates of the next
   band are returned. This escape is used by applications that perform handle
   banding ("for-printing") themselves.

   For DEVESC_NEXTBAND, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Points to the number of bytes of data pointed to by the
                   pbOutData parameter. Upon return, the escape updates this
                   parameter to the number of bytes returned.

   pbOutData       Points to the address of the buffer that receives the
                   output from this escape. A structure is returned that
                   specifies the device coordinates of the next band, which
                   is a rectangle.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_ABORTDOC escape stops the current job, erasing everything
   written by the application to the device since the DEVESC_ENDDOC escape
   was called.

   For DEVESC_ABORTDOC, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_NEWFRAME escape allows an application to signal when it has
   finished writing to a page. You usually use this escape with a printer
   device to advance to a new page. Calling this escape, which is similar to
   processing the GpiErase function for a screen device context, resets the
   screen attributes.

   For DEVESC_NEWFRAME, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_DRAFTMODE escape turns draft mode on or off. Turning draft mode
   on instructs the device driver to print faster and with lower quality. You
   can change the draft mode only at page boundaries──for example, after a
   call to the DEVESC_NEWFRAME escape.

   For DEVESC_DRAFTMODE, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Specifies the number of bytes pointed to by the pbInData
                   parameter.

   pbInData        Points to the SHORT value that specifies the draft mode; 1
                   for on, 0 for off.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_FLUSHOUTPUT escape removes any output from the device buffer.

   For DEVESC_FLUSHOUTPUT, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Not used; can be set to zero.

   pbInData        Not used; can be set to NULL.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

   The DEVESC_RAWDATA escape allows an application to send "raw," or binary,
   data directly to a device driver. For example, in the case of a printer
   device driver, the data could be a stream of printer data.

   If binary data is mixed with other data──for example, Gpi data──being sent
   to the same page of a device context, the results are unpredictable and
   depend upon the action taken by the Presentation Manager device driver,
   which, might even ignore the Gpi data completely. In general, you should
   send binary data either to a separate page, using the DEVESC_NEWFRAME
   escape to obtain a new page, or to a separate document, using the
   DEVESC_STARTDOC and DEVESC_ENDDOC escapes to create a new document.

   For DEVESC_RAWDATA, the DevEscape parameters contain the following
   information:

   Parameter       Description
   ──────────────────────────────────────────────────────────────────────────
   cbInData        Specifies the number of bytes pointed to by the pbInData
                   parameter.

   pbInData        Points to the binary data.

   pcbOutData      Not used; can be set to NULL.

   pbOutData       Not used; can be set to NULL.
   ──────────────────────────────────────────────────────────────────────────

 See Also

   GpiErase


 ────────────────────────────────────────────────────────────────────────────
 DevOpenDC
 ────────────────────────────────────────────────────────────────────────────
   HDC DevOpenDC (hab, type, pszToken, count, pbData, hdcComp)
   HAB hab;                /*anchor-block handle                           */
   LONG type;              /*type of device context                        */
   PSZ pszToken;           /*pointer to device-information token           */
   LONG count;             /*number of elements in structure               */
   PDEVOPENDATA pbData;    /*pointer to structure for device context       */
   HDC hdcComp;            /*handle of compatible device context           */

   The DevOpenDC function creates a device context. This function initializes
   the use count (to one) of the number of processes that have access to the
   device context.

 Parameters

   hab  Identifies the anchor block.

   type  Specifies the type of device context; it can be one of the
   following:

   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   OD_QUEUED       A device, such as a printer or plotter, for which to queue
                   output.

   OD_DIRECT       A device, such as a printer or plotter, for which to not
                   queue output.

   OD_INFO         Same as for OD_DIRECT, but used only to retrieve
                   information (for example, font metrics). You can draw to a
                   presentation space associated with such a device context,
                   but you cannot update any output.

   OD_METAFILE     A device context that is used to draw a metafile. The
                   graphics field defines the area of interest within the
                   metafile picture.

   OD_MEMORY       A device context that is used to contain a bitmap.
   ──────────────────────────────────────────────────────────────────────────

   pszToken  Points to the null-terminated string that contains the
   device-information token. This device information, which is held in the
   os2.ini file, is the same as that which may be pointed to by the pbData
   parameter; any information obtained from pbData overrides the information
   obtained by using this parameter. If you specify an asterisk (*) for
   pszToken, no device information is taken from the os2.ini file. MS OS/2
   version 1.1 acts as if "*" is specified but allows you to specify any
   string.

   count  Specifies the number of elements in the structure pointed to by the
   pbData parameter. This number may be less than the number of items in the
   full list if omitted items are irrelevant or are supplied from the
   pszToken parameter or elsewhere.

   pbData  Points to a data area that describes the output device. This area
   can be either an array of pointers or a DEVOPENSTRUC structure, which has
   the following form:

   typedef struct _DEVOPENSTRUC {
       PSZ        pszLogAddress;
       PSZ        pszDriverName;
       PDRIVDATA  pdriv;
       PSZ        pszDataType;
       PSZ        pszComment;
       PSZ        pszQueueProcName;
       PSZ        pszQueueProcParams;
       PSZ        pszSpoolerParams;
       PSZ        pszNetworkParams;
   } DEVOPENSTRUC;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   hdcComp  Identifies the compatible device context. When the type parameter
   is OD_MEMORY, this parameter identifies a device context that is
   compatible with the bitmaps to be used with it. If you do not supply this
   parameter or if it is NULL, the device context that MS OS/2 opens is
   compatible with the screen.

 Return Value

   The return value identifies the device context if the function is
   successful. The return value is DEV_ERROR if an error occurs.


 ────────────────────────────────────────────────────────────────────────────
 DevPostDeviceModes
 ────────────────────────────────────────────────────────────────────────────
   LONG DevPostDeviceModes (hab, pbDriverData, pszDriverName, achDeviceName,
   pszLogAddr)
   HAB hab;                /*anchor-block handle                           */
   PDRIVDATA pbDriverData; /*pointer to buffer for data                    */
   PSZ pszDriverName;      /*pointer to string for driver name             */
   PSZ achDeviceName;      /*pointer to device name                        */
   PSZ pszLogAddr;         /*pointer to string for name of output device   */

   The DevPostDeviceModes function causes a device driver to post a dialog
   box that allows the user to set options for the device──for example,
   resolution, font cartridges, and so forth.

   The application can call this function first with a NULL data pointer to
   find out how much storage is needed for the data buffer. Having allocated
   the storage, the application can then call the function a second time in
   order to have the buffer filled with data.

   Once the data has been returned, you can pass it to the DevOpenDC function
   as the buffer data pointed to by the pbDriverData parameter.

 Parameters

   hab  Identifies the anchor block.

   pbDriverData  Points to the data buffer that receives device data defined
   by the driver. If this parameter is NULL, the function returns the
   required size of the buffer. The format of the data is the same as for the
   pbData parameter of the DevOpenDC function.

   pszDriverName  Points to the null-terminated string that contains the name
   of the device driver.

   achDeviceName  Points to a null-terminated string that identifies the
   particular device (model number, etc.). This string must not exceed 32
   bytes. Valid names are defined by device drivers.

   pszLogAddr  Points to the null-terminated string that contains the logical
   address of the output device──for example, LPT1.

 Return Value

   The return value if the pbDriverData parameter is NULL is the size (in
   bytes) required for the data buffer, DPDM_NONE if there are no options
   that can be set, or DPDM_ERROR if an error occurs.

   The return value if pbDriverData is not NULL is DEV_OK if the function is
   successful, DPDM_NONE if there is no device mode, or DPDM_ERROR if an
   error occurs.

 See Also

   DevOpenDC


 ────────────────────────────────────────────────────────────────────────────
 DevQueryCaps
 ────────────────────────────────────────────────────────────────────────────
   BOOL DevQueryCaps (hdc, lStartitem, cItems, alItems)
   HDC hdc;                /*device-context handle                         */
   LONG lStartitem;        /*first item to retrieve                        */
   LONG cItems;            /*number of items to retrieve                   */
   PLONG alItems;          /*array for device characteristics              */

   The DevQueryCaps function queries the characteristics of the specified
   device.

 Parameters

   hdc  Identifies the device context.

   lStartitem  Specifies the first item of information to retrieve.

   cItems  Specifies the number of items of information to retrieve.

   alItems  Points to an array of device characteristics, starting with the
   item specified by the lStartitem parameter. For more information about
   device characteristics, see Appendix B, "Device Capabilities."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   DevOpenDC


 ────────────────────────────────────────────────────────────────────────────
 DevQueryDeviceNames
 ────────────────────────────────────────────────────────────────────────────
   BOOL DevQueryDeviceNames (hab, pszDriverName, pcMaxNames, achDeviceName,
   achDeviceDesc, pcMaxDataTypes, achDataType)
   HAB hab;                /*anchor-block handle                           */
   PSZ pszDriverName;      /*pointer to string for device name             */
   PLONG pcMaxNames;       /*maximum number of device drivers              */
   PSTR32 achDeviceName;   /*pointer to array of device names              */
   PSTR64 achDeviceDesc;   /*pointer to array of device descriptions       */
   PLONG pcMaxDataTypes;   /*maximum number of data types                  */
   PSTR16 achDataType;     /*pointer to array of data types                */

   The DevQueryDeviceNames function returns the device names, descriptions,
   and data types supported by the specified device driver.

   The application can call the function first with the pcMaxNames and
   pcMaxDataTypes parameters set to zero in order to find how much storage is
   needed for the data buffers. Having allocated the storage, the application
   then calls the function a second time in order to have the buffers filled
   with data for the data to be filled in.

 Parameters

   hab  Identifies the anchor block.

   pszDriverName  Points to the null-terminated string that contains the name
   of the device driver.

   pcMaxNames  Points to the maximum number of device names and descriptions
   that can be returned. If this parameter is zero, the number of device
   names and descriptions supported is returned and the arrays pointed to by
   the achDeviceName and achDeviceDesc parameters are not updated. If this
   parameter is nonzero, then its value is updated to the number returned in
   the arrays pointed to by achDeviceName and achDeviceDesc and the arrays
   are updated.

   achDeviceName  Points to an array of null-terminated strings, each element
   of which identifies a particular device (for example, model number). Valid
   names are defined by device drivers. IBM4201 is an example of a device
   name.

   achDeviceDesc  Points to an array of null-terminated strings, each element
   of which is a description of a particular device (for example, model
   name). Valid names are defined by device drivers. IBM 4201 Proprinter is
   an example of a device description.

   pcMaxDataTypes  Points to the maximum number of data types that can be
   returned. If this parameter is zero, the number of data types supported is
   returned and the array pointed to by the achDataType parameter is not
   updated. If this parameter is nonzero, then its value is updated to the
   number returned and the array is updated.

   achDataType  Points to an array of null-terminated strings, each element
   of which identifies a data type. Valid data types are defined by device
   drivers. PM_Q_STD is an example of a data type.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.


 ────────────────────────────────────────────────────────────────────────────
 DevQueryHardcopyCaps
 ────────────────────────────────────────────────────────────────────────────
   LONG DevQueryHardcopyCaps (hdc, iStartForm, cForms, phci)
   HDC hdc;                /*device-context handle                         */
   LONG iStartForm;        /*index of form code to start from              */
   LONG cForms;            /*number of forms to query                      */
   PHCINFO phci;           /*pointer to structure for results              */

   The DevQueryHardcopyCaps function returns information about the hardcopy
   capabilities of a device.

   You can use the iStartForm and cForms parameters together to enumerate all
   available form codes without having to allocate a buffer large enough to
   hold information on them all.

 Parameters

   hdc  Identifies the device context.

   iStartForm  Specifies the index of the form code from which to start the
   query. The first form code is specified by the value 0.

   cForms  Specifies the number of forms to query.

   phci  Points to the buffer that contains the results of the query. The
   result consists of cForms copies of the HCINFO structure. The HCINFO
   structure has the following form:

   typedef struct _HCINFO {
       CHAR szFormname[32];
       LONG cx;
       LONG cy;
       LONG xLeftClip;
       LONG yBottomClip;
       LONG xRightClip;
       LONG yTopClip;
       LONG xPels;
       LONG yPels;
       LONG flAttributes;
   } HCINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   If there are five form codes defined and the iStartForm parameter is 2 and
   the cForms parameter is 3, a query is performed for form codes 2, 3, and 4
   and the result is returned in the buffer pointed to by the phci parameter.

   The return value if cForms is zero is the number of available forms, or if
   cForms is nonzero, the number of forms returned. The return value is
   DQHC_ERROR if an error occurs.

 ────────────────────────────────────────────────────────────────────────────
 GpiAssociate
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiAssociate (hps, hdc)
   HPS hps;                /*presentation-space handle                     */
   HDC hdc;                /*device-context handle                         */

   The GpiAssociate function associates a presentation space with a device
   context and resets the presentation space. Once a device context is
   associated with a presentation space, all subsequent drawing in the
   presentation space is copied to the device.

   Only one device context can be associated with a presentation space at a
   time. GpiAssociate cannot associate a new device context with a
   presentation space until the current device context is released. The
   function releases the current device context from the presentation space
   if hdc is NULL.

 Parameters

   hps  Identifies a normal presentation space. Micro and cached presentation
   spaces cannot be used.

   hdc  Identifies the device context. Although any type of device context
   may be used, the device context must not be already associated with a
   presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_DC_IS_ASSOCIATED
         PMERR_INV_MICROPS_FUNCTION
         PMERR_PS_IS_ASSOCIATED

 Comments

   When GpiAssociate resets the presentation space, it sets all attributes to
   their default values, sets the model transform to unity, sets the current
   position to (0,0), closes any open path, area, or element brackets, closes
   any open segment, removes any clip path, viewing limits and clip region,
   and enables kerning if the device supports kerning.

   The GpiCreatePS function can also be used to associate a device context
   with a new presentation space.

 Example

   This example releases the current device context and associates a new
   device context with the presentation space.

   HPS hps;
   HDC hdcPrinter;
   GpiAssociate(hps, NULL);       /* release the current device context */
   GpiAssociate(hps, hdcPrinter); /* associate a printer device context */

 See Also

   GpiCreatePS, GpiResetPS


 ────────────────────────────────────────────────────────────────────────────
 GpiBeginArea
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiBeginArea (hps, flOptions)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOptions;        /*area-option flag                              */

   The GpiBeginArea function starts an area bracket, that is, it starts a
   sequence of functions that define the shape of an area. All subsequent
   drawing functions, up to the next GpiEndArea function, apply to the new
   area. The flOptions parameter specifies whether the figures in the area
   have boundary lines and which filling mode to use for constructing the
   interior of the area.

 Parameters

   hps  Identifies the presentation space.

   flOptions  Specifies the area options. It can be any combination of the
   following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   BA_ALTERNATE        Constructs the interior in alternate mode (default).

   BA_BOUNDARY         Boundary lines are drawn.

   BA_NOBOUNDARY       Boundary lines are not drawn (default).

   BA_WINDING          Constructs the interior in winding mode.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_ALREADY_IN_AREA
         PMERR_INV_AREA_CONTROL
         PMERR_INV_IN_PATH

 Example

   This example uses the GpiBeginArea function to draw an area. The area, an
   isosceles triangle, is drawn with boundary lines and filled using the
   alternate filling mode.

   HPS hps;
   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
   GpiMove(hps, &ptlStart);    /* move to starting point (0, 0)     */
   GpiBeginArea(hps,           /* start the area bracket            */
       BA_BOUNDARY |           /* draw boundary lines               */
       BA_ALTERNATE);          /* fill interior with alternate mode */
   GpiPolyLine(hps, 3L, ptlTriangle);       /* draw the triangle    */
   GpiEndArea(hps);                         /* end the area bracket */
                                            /* and fill the area    */

 See Also

   GpiEndArea


 ────────────────────────────────────────────────────────────────────────────
 GpiBeginElement
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiBeginElement (hps, lType, pszDesc)
   HPS hps;                /*presentation-space handle                     */
   LONG lType;             /*element type                                  */
   PSZ pszDesc;            /*pointer to element description                */

   The GpiBeginElement function starts an element bracket, that is, a
   sequence of functions that define the contents of an element. All
   subsequent graphics functions, up to the next GpiEndElement or
   GpiCloseSegment function, apply to the new element.

   The GpiBeginElement may only be used while creating a segment. The element
   type and element description, specified by the lType and pszDesc
   parameters, are values that the application supplies to distinguish one
   element from another within a segment.

 Parameters

   hps  Identifies the presentation space.

   lType  Specifies the element type. It can be any integer value.

   pszDesc  Points to a null-terminated string. If no description is needed,
   it may point to an empty string.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_ALREADY_IN_ELEMENT
         PMERR_INV_MICROPS_FUNCTION

 Comments

   The GpiBeginElement function cannot be used within an element bracket.

 Example

   This example uses the GpiBeginElement function to create an element in a
   segment. The element type is 1 and the element description is "Triangle".
   The application can use these later to identify the element.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
   GpiBeginElement(hps,                   /* start element bracket      */
       1L,                                /* element type is 1          */
       "Triangle");                       /* element description        */
   GpiMove(hps, &ptlStart);               /* move to start point (0, 0) */
   GpiPolyLine(hps, 3L, ptlTriangle);     /* draw triangle              */
   GpiEndElement(hps);                    /* end element bracket        */

 See Also

   GpiCloseSegment, GpiDeleteElement, GpiEndElement, GpiQueryElement,
   GpiQueryElementPointer, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiBeginPath
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiBeginPath (hps, idPath)
   HPS hps;                /*presentation-space handle                     */
   LONG idPath;            /*path identifier                               */

   The GpiBeginPath function starts a path bracket, that is, starts a
   sequence of functions that define the shape and size of a path.
   GpiBeginPath sets the path identifier and initializes the path, clearing
   any path created previously with this identifier. All subsequent drawing
   functions, up to the next GpiEndPath function, apply to the new path.

 Parameters

   hps  Identifies the presentation space.

   idPath  Specifies the path identifier; for MS OS/2 version 1.1, it must be
   1.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_ALREADY_IN_PATH
         PMERR_INV_PATH_ID

 Comments

   Since there is a limit to the size of a path, any line or curve drawing
   function within a path bracket that would exceed the limit returns the
   PMERR_PATH_TOO_BIG error value.

 Example

   This example uses the GpiBeginPath function to create a path. The path, an
   isosceles triangle, is given path identifier 1. After the path bracket is
   ended using GpiEndPath, a subsequent call to the GpiFillPath function
   draws and fills the path.

   HPS hps;
   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0 };
   GpiBeginPath(hps, 1L);                  /* start the path bracket */
   GpiMove(hps, &ptlStart);                /* move to starting point */
   GpiPolyLine(hps, 2L, ptlTriangle);      /* draw the three sides   */
   GpiCloseFigure(hps);                    /* close the triangle     */
   GpiEndPath(hps);                        /* end the path bracket   */
   GpiFillPath(hps, 1L, FPATH_ALTERNATE);  /* draw and fill the path */

 See Also

   GpiCloseFigure, GpiEndPath, GpiFillPath, GpiModifyPath,
   GpiSetClipPath, GpiSetLineWidthGeom, GpiStrokePath


 ────────────────────────────────────────────────────────────────────────────
 GpiBitBlt
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiBitBlt (hpsTarg, hpsSrc, cPoints, aptl, lRop, flOptions)
   HPS hpsTarg;            /*target presentation-space handle              */
   HPS hpsSrc;             /*source presentation-space handle              */
   LONG cPoints;           /*number of points in array                     */
   PPOINTL aptl;           /*pointer to array                              */
   LONG lRop;              /*mixing method                                 */
   ULONG flOptions;        /*line/column-compression flag                  */

   The GpiBitBlt function copies a bitmap from one presentation space to
   another. It can also modify the bitmap within a rectangle in a
   presentation space. The exact operation carried out by GpiBitBlt depends
   on the raster operation specified by the lRop parameter.

   If lRop directs GpiBitBlt to copy a bitmap, the function copies the bitmap
   from a source presentation space specified by hpsSrc to a target
   presentation space specified by hpsTarg. Each presentation space must be
   associated with a device context for the display, for memory, or for some
   other suitable raster device. The target and source presentation spaces
   can be the same if desired. The aptl parameter points to an array of
   points that specify the corners of a rectangle containing the bitmap in
   the source presentation space as well as the corners of the rectangle in
   the target presentation space to receive the bitmap. If the source and
   target rectangles are not the same, GpiBitBlt stretches or compresses the
   bitmap to fit the target rectangle.

   If lRop directs GpiBitBlt to modify a bitmap, the function uses the raster
   operation to determine how to alter the bits in a rectangle in the target
   presentation space. Raster operations include changes such as inverting
   target bits, replacing target bits with pattern bits, and mixing target
   and pattern bits to create new colors. For some raster operations, the
   function mixes the bits of a bitmap from a source presentation space with
   the target and/or pattern bits.

 Parameters

   hpsTarg  Identifies the target presentation space.

   hpsSrc  Identifies the source presentation space.

   cPoints  Specifies the number of points pointed to by the aptl parameter.
   It may be one of the following values:

   Value   Meaning
   ──────────────────────────────────────────────────────────────────────────
   2       The points specify the lower-left and upper-right corners of the
           target rectangle. If 2 is given, the raster operation specified by
           the lRop parameter must not include a source.

   3       The points specify the lower-left and upper-right corners of the
           target rectangle, and the lower-left corner of the source
           rectangle. The upper-right corner of the source rectangle is
           computed such that the target and source rectangles have equal
           width and height. Any raster operation may be used. If the
           operation does not include a source, the third point is ignored.

   4       The points specify the lower-left and upper-right corners of the
           target and the source rectangles. If the rectangles do not have
           equal width and height, the source bitmap is stretched or
           compressed to fit the target rectangle. GpiBitBlt uses the
           flOptions parameter to determine how the bitmap should be
           compressed. If the raster operation does not include a source, the
           source coordinates are ignored.
   ──────────────────────────────────────────────────────────────────────────

   aptl  Points to an array of POINTL structures containing the number of
   points specified in the cPoints parameter. The points must be given in the
   following order:

   Element index       Coordinate
   ──────────────────────────────────────────────────────────────────────────
   0                   Specifies the lower-left corner of the target
                       rectangle.

   1                   Specifies the upper-right corner of the target
                       rectangle.

   2                   Specifies the lower-left corner of the source
                       rectangle.

   3                   Specifies the upper-right corner of the source
                       rectangle.
   ──────────────────────────────────────────────────────────────────────────

   All points must be in device coordinates. The POINTL structure has the
   following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lRop  Specifies the raster operation for the function. It can be any value
   in the range 0 through 255 or one of the following values, which represent
   common raster operations:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   ROP_DSTINVERT       Inverts the target.

   ROP_MERGECOPY       Combines the source and the pattern using the bitwise
                       AND operator.

   ROP_MERGEPAINT      Combines the inverse of the source and the target
                       using the bitwise OR operator.

   ROP_NOTSRCCOPY      Copies the inverse of the source to the target.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  ROP_NOTSRCCOPY      Copies the inverse of the source to the target.

   ROP_NOTSRCERASE     Combines the inverse of the source and the inverse of
                       the target bitmaps using the bitwise AND operator.

   ROP_ONE             Sets all target pels to 1.

   ROP_PATCOPY         Copies the pattern to the target.

   ROP_PATINVERT       Combines the target and the pattern using the bitwise
                       exclusive XOR operator.

   ROP_PATPAINT        Combines the inverse of the source, the pattern, and
                       target using the bitwise OR operator.

   ROP_SRCAND          Combines the source and target bitmaps using the
                       bitwise AND operator.

   ROP_SRCCOPY         Copies the source bitmap to the target.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  ROP_SRCCOPY         Copies the source bitmap to the target.

   ROP_SRCERASE        Combines the source and the inverse of the target
                       bitmaps using the bitwise AND operator.

   ROP_SRCINVERT       Combines the source and target bitmaps using the
                       bitwise exclusive OR operator.

   ROP_SRCPAINT        Combines the source and target bitmaps using the
                       bitwise OR operator.

   ROP_ZERO            Sets all target pels to 0.
   ──────────────────────────────────────────────────────────────────────────


   flOptions  Specifies how to compress a bitmap if the target rectangle is
   smaller than the source. It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   BBO_AND           Compresses two rows or columns into one by combining
                     them with the bitwise AND operator. This value is useful
                     for compressing bitmaps

   BBO_IGNORE        Compresses two rows or columns by throwing one out. This
                     value is useful for compressing color bitmaps. that have
                     black images on a white background.

   BBO_OR            Compresses two rows or columns into one by combining
                     them with the bitwise OR operator. This value is the
                     default and is useful for compressing bitmaps that have
                     white images on a black background.
   ──────────────────────────────────────────────────────────────────────────

   All values in the range 0x0100 through 0xFF00 are reserved for privately
   supported modes for particular devices.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_BASE_ERROR
         PMERR_BITMAP_NOT_SELECTED
         PMERR_INCOMPATIBLE_BITMAP
         PMERR_INV_BITBLT_MIX
         PMERR_INV_BITBLT_STYLE
         PMERR_INV_COORDINATE
         PMERR_INV_DC_TYPE
         PMERR_INV_HBITMAP
         PMERR_INV_HDC
         PMERR_INV_IN_AREA
         PMERR_INV_IN_PATH
         PMERR_INV_LENGTH_OR_COUNT

 Comments

   The source and target presentation spaces may be associated with any
   device context having raster capabilities. Some raster devices, such as
   banded printers, can receive bitmaps but cannot supply them. These devices
   cannot be used as a source.

   GpiBitBlt does not affect the pels in the upper and right boundaries of
   the target rectangle. This means the function draws up to but does not
   include those pels.

   If lRop includes a pattern, GpiBitBlt uses the current area color, area
   background color, pattern set, and pattern symbol of the target
   presentation space. Although the function may stretch or compress the
   bitmap, it never stretches or compresses the pattern.

   If the target and source presentation spaces are associated with device
   contexts that have different color formats, GpiBitBlt converts the bitmap
   color format as it copies the bitmap. This applies to bitmaps copied to or
   from a device context having a monochrome format. To convert a monochrome
   bitmap to a color bitmap, GpiBitBlt converts 1 pels to the target's
   foreground color, and 0 pels to the current area background color. To
   convert a color bitmap to a monochrome bitmap, GpiBitBlt converts pels
   with the source's background color to the target's background color, and
   all other pels to the target's foreground color.

   The bitmap associated with a source presentation space is always a finite
   size. Although GpiBitBlt will copy a bitmap when given a source rectangle
   that is larger than the source bitmap or extends past the boundaries of
   the source bitmap, any pels not associated with the source bitmap are
   undefined.

 Example

   This example uses GpiBitBlt to copy and compress a bitmap in a
   presentation space. The function copies the bitmap that is 100 pels wide
   and 100 pels high into a 50-by-50-pel rectangle at the location (300,400).
   Since the raster operation is ROP_SRCCOPY, GpiBitBlt replaces the image
   previously in the target rectangle. The function compresses the bitmap to
   fit the new rectangle by discarding extra rows and columns as specified by
   the BBO_IGNORE option.

   HPS hps;
   POINTL aptl[4] = {
       300, 400,         /* lower-left corner of target    */
       350, 450,         /* upper-right corner of target   */
       0, 0,             /* lower-left corner of source    */
       100, 100 };       /* upper-right corner of source   */

   GpiBitBlt(hps,        /* target presentation space      */
       hps,              /* source presentation space      */
       4L,               /* four points needed to compress */
       aptl,             /* points to source and target    */
       ROP_SRCCOPY,      /* copy source replacing target   */
       BBO_IGNORE);      /* discard extra rows and columns */

 See Also

   DevOpenDC, GpiCreateBitmap, GpiLoadBitmap, GpiSetBitmap,
   GpiSetBitmapDimension, GpiSetBitmapId, GpiWCBitBlt


 ────────────────────────────────────────────────────────────────────────────
 GpiBox
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiBox (hps, cmdControl, pptl, lHRound, lVRound)
   HPS hps;                /*presentation-space handle                     */
   LONG cmdControl;        /*fill and outline indicator                    */
   PPOINTL pptl;           /*pointer to structure for box corners          */
   LONG lHRound;           /*horizontal length of rounding-ellipse axis    */
   LONG lVRound;           /*vertical length of rounding-ellipse axis      */

   The GpiBox function draws a rectangular box or a box with rounded corners.
   The function draws the box by drawing the outline of a rectangle. The
   current position specifies one corner and the point given by pptl
   specifies the other. The sides of the box are always parallel to the x and
   y axes. The function may fill the interior with the current fill pattern.
   If a rounded box is requested, the function rounds the corners of the
   rectangle using quarter ellipses. The lHRound and lVRound parameters
   specify the lengths of the major and minor axes for the ellipse. If either
   the lHRound or the lVRound parameter is zero, no rounding occurs.

   The current position is unchanged by this function.

 Parameters

   hps  Identifies the presentation space.

   cmdControl  Specifies whether to draw the box's interior and/or outline.
   It can be one of the following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   DRO_FILL            Fills the interior.

   DRO_OUTLINE         Draws the outline.

   DRO_OUTLINEFILL     Draws the outline and fills the interior.
   ──────────────────────────────────────────────────────────────────────────

   pptl  Points to the POINTL structure that contains the coordinates of a
   corner of the box. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lHRound  Specifies the horizontal length (in world coordinates) of the
   full axis of the ellipse used for rounding at each corner.

   lVRound  Specifies the vertical length (in world coordinates) of the full
   axis of the ellipse used for rounding at each corner.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following value:

         PMERR_INV_BOX_CONTROL

 Comments

   GpiBox can be used in an area bracket but only if DRO_OUTLINE is used. If
   the current position is (x0,y0), and pptl is set to (x1,y1), the box is
   drawn from (x0,y0) to (x1,y0) to (x1,y1) to (x0,y1) to (x0,y0). This can
   affect the way the box is filled when drawn in an area.

   When correlating a segment, a box drawn using GpiBox will be "hit" if the
   box boundary intersects in the pick aperture. If the pick aperture lies
   within the box, a hit occurs only if the interior is drawn, that is, only
   if the DRO_FILL or DRO_OUTLINEFILL option is used.

 Example

   This example calls GpiBox to draw a series of rounded boxes, one inside
   another.

   POINTL ptl = { 100, 100 };
   SHORT i;

   for (i = 0; i < 5; i++)
       GpiBox(hps,            /* handle to a ps        */
           DRO_OUTLINE,       /* fill the interior     */
           (PPOINTL) &ptl,    /* address of the corner */
           i * 10L,           /* horizontal length     */
           i * 10L);          /* vertical length       */

 See Also

   GpiBeginArea, GpiEndArea


 ────────────────────────────────────────────────────────────────────────────
 GpiCallSegmentMatrix
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCallSegmentMatrix (hps, idSegment, cElements, pmatlf, lType)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG cElements;         /*number of matrix elements to examine          */
   PMATRIXLF pmatlf;       /*pointer to structure for matrix               */
   LONG lType;             /*transformation modifier                       */

   The GpiCallSegmentMatrix function draws the specified segment using an
   instance transformation. The function combines the instance transformation
   pointed to by pmatlf with the current model transformation, then draws the
   segment as if calling the GpiDrawSegment function. The combined
   transformation applies only while the function draws the segment.
   GpiCallSegmentMatrix does not modify the current model transformation.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment to draw. This value must be greater than
   zero.

   cElements  Specifies the number of matrix elements pointed to by pmatlf.
   It can be any value from 0 through 9.

   pmatlf  Points to a MATRIXLF structure that contains the matrix for the
   instance transformation. Although a transformation requires nine matrix
   elements, the function copies from the structure only the number of matrix
   elements specified by cElements. If cElements is less than nine, the
   function supplies the remaining elements by substituting corresponding
   elements from the identity matrix. The MATRIXLF structure has the
   following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lType  Specifies how to combine the instance transformation with the model
   transformation. It can be one of the following values:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   TRANSFORM_ADD         Adds the model transformation to the instance
                         transformation (MODEL * INSTANCE).

   TRANSFORM_PREEMPT     Adds the instance transformation to the model
                         transformation (INSTANCE * MODEL).

   TRANSFORM_REPLACE     Replaces the model transform with the instance
                         transformation.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_CALLED_SEG_IS_CURRENT
         PMERR_CALLED_SEG_NOT_FOUND
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_INV_TRANSFORM_TYPE
         PMERR_SEG_CALL_RECURSIVE

 Example

   This example calls the GpiCallSegmentMatrix function to draw a segment
   three times. Each time the segment is drawn, the instance transformation
   doubles in size. The result is three triangles with the last triangle
   twice the size of the second, and the second twice the size of the first.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
   MATRIXLF matlfInstance = { 1, 0, 0, 0, 1, 0, 0, 0, 1 };

   GpiOpenSegment(hps, 1L);             /* open the segment           */
   GpiMove(hps, &ptlStart);             /* move to start point (0, 0) */
   GpiPolyLine(hps, 3L, ptlTriangle);   /* draw the triangle          */
   GpiCloseSegment(hps);                /* close the segment          */

   for (i = 0; i < 3; i++) {

       /*
        * Draw the segment after adding the matrix to the model
        * transformation.
        */

       GpiCallSegmentMatrix(hps, 1L, 9, &matlfInstance, TRANSFORM_ADD);
       matlfInstance.fxM11 *= 2;
       matlfInstance.fxM22 *= 2;
   }


 See Also

   GpiDrawSegment


 ────────────────────────────────────────────────────────────────────────────
 GpiCharString
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCharString (hps, cchString, pchString)
   HPS hps;                /*presentation-space handle                     */
   LONG cchString;         /*number of characters in string                */
   PCH pchString;          /*pointer to string to draw                     */

   The GpiCharString function draws a character string positioned at the
   current position. After the function draws the string, it sets the current
   position to the end of the character string.

 Parameters

   hps  Identifies the presentation space.

   cchString  Specifies the number of characters in the string pointed to by
   pchString.

   pchString  Points to the character string to be drawn.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiCharString function to draw the string "Hello".
   The GpiMove function moves the current position to (100,100) so that the
   string starts there.

   HPS hps;
   POINTL ptlStart;

   ptlStart.x = 100L;
   ptlStart.y = 100L;

   /* Start string at (100, 100). */

   GpiMove(hps, &ptlStart);

   /* Draw the 5-character string. */

   GpiCharString(hps, 5L, "Hello");

 See Also

   GpiCharStringAt, GpiCharStringPos


 ────────────────────────────────────────────────────────────────────────────
 GpiCharStringAt
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCharStringAt (hps, pptlStart, cchString, pchString)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlStart;      /*pointer to structure for starting position    */
   LONG cchString;         /*number of characters in string                */
   PCH pchString;          /*pointer to string to draw                     */

   The GpiCharStringAt function draws a character string starting at the
   specified position. After the function draws the string, it sets the
   current position to the end of the character string.

 Parameters

   hps  Identifies the presentation space.

   pptlStart  Points to the POINTL structure that contains the starting
   position in world coordinates. The POINTL structure has the following
   form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cchString  Specifies the number of characters pointed to by pchString.

   pchString  Points to the character string to be drawn.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   The example uses the GpiCharStringAt function to draw the string "Hello"
   starting at the position (100,100). It then uses the GpiMove and
   GpiCharString functions to draw the same string at exactly the same
   position.

   HPS hps;
   POINTL ptlStart;

   ptlStart.x = 100L;
   ptlStart.y = 100L;

   /* Draw the string "Hello" at (100, 100). */

   GpiCharStringAt(hps, &ptlStart, 5, "Hello");

   /* These two calls are identical to the one above. */

   GpiMove(hps, &ptlStart);
   GpiCharString(hps, 5L, "Hello");

 See Also

   GpiCharString, GpiMove


 ────────────────────────────────────────────────────────────────────────────
 GpiCharStringPos
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCharStringPos (hps, prcl, flOptions, cchString, pchString, adx)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to structure for rectangle            */
                           /*coordinates                                   */
   ULONG flOptions;        /*formatting flags                              */
   LONG cchString;         /*number of characters in string                */
   PCH pchString;          /*pointer to string to draw                     */
   PLONG adx;              /*pointer to array of increment values          */

   The GpiCharStringPos function draws a character string starting at the
   current position and using one or more formatting options. The options
   direct the function to draw a background for the string, clip the string
   to the given rectangle, or position the characters in the string using
   distances given in an array. After drawing the string, the function either
   leaves the current position at the end of the string or resets it to the
   beginning of the string.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to a RECTL structure that contains the lower-left and
   upper-right corners of a rectangle. The function draws the rectangle if
   the CHS_OPAQUE option is given. It uses the rectangle to clip the string
   if the CHS_CLIP option is given. Otherwise the rectangle is ignored. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies the formatting options. It can be one or more of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CHS_CLIP          Clips the string to the rectangle, omitting any portion
                     of any character outside the rectangle. The function
                     clips the string regardless of whether CHS_OPAQUE is
                     specified.

   CHS_LEAVEPOS      Resets the current position back to the start of the
                     string. If not given, GpiCharStringPos moves the current
                     position to the end of string.

   CHS_OPAQUE        Draws the rectangle whose lower-left and upper-right
                     corners are specified by prcl, then fills the rectangle
                     with the current background color. The string is drawn
                     after filling the rectangle.

   CHS_VECTOR        Advances the current position after each character is
                     drawn by using the next value in the array adx. The
                     current character direction defines which direction the
                     current position is advanced.
   ──────────────────────────────────────────────────────────────────────────

   All other values are reserved.

   cchString  Specifies the number of characters in the string pointed to by
   pchString.

   pchString  Points to the character string to be drawn.

   adx  Points to an array of increment values. Each value is a 4-byte,
   signed integer specifying the distance in world coordinates to advance the
   current position after drawing a character. There must be one value for
   each character in the string. The first element specifies the distance to
   advance after drawing the first character, the second element specifies
   the distance after the second character, and so on.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Comments

   If CHS_OPAQUE is specified and the drawing mode is DM_RETAIN,
   GpiCharStringPos uses the color mix mode BM_OVERPAINT to fill the
   rectangle. In other drawing modes, the function uses the BM_LEAVEALONE.
   GpiCharStringPos draws the rectangle using the coordinates specified in
   prcl. It does not use the start of the string to compute the rectangle's
   location.

 See Also

   GpiCharString, GpiCharStringAt, GpiCharStringPosAt


 ────────────────────────────────────────────────────────────────────────────
 GpiCharStringPosAt
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCharStringPosAt (hps, pptlStart, prcl, flOptions, cchString,
   pchString, adx)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlStart;      /*pointer to structure for starting position    */
   PRECTL prcl;            /*pointer to structure for rectangle            */
                           /*coordinates                                   */
   ULONG flOptions;        /*formatting flags                              */
   LONG cchString;         /*number of characters in string                */
   PCH pchString;          /*pointer to string to draw                     */
   PLONG adx;              /*increment vector                              */

   The GpiCharStringPosAt function draws a character string starting at the
   specified position and using one or more formatting options. The options
   direct the function to draw a background for the string, clip the string
   to the given rectangle, or position the characters in the string using
   distances given in an array. After drawing the string, the function either
   leaves the current position at the end of the string or resets it to the
   beginning of the string.

 Parameters

   hps  Identifies the presentation space.

   pptlStart  Points to a POINTL structure that contains the starting
   position in world coordinates. The POINTL structure has the following
   form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prcl  Points to a RECTL structure that contains the lower-left and
   upper-right corners of a rectangle. The function draws the rectangle if
   the CHS_OPAQUE option is given. It uses the rectangle to clip the string
   if the CHS_CLIP option is given. Otherwise the rectangle is ignored. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG xLeft;
       LONG yBottom;
       LONG xRight;
       LONG yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies the formatting options. It can be one or more of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CHS_CLIP          Clips the string to the rectangle, omitting any portion
                     of any character outside the rectangle. The function
                     clips the string regardless of whether CHS_OPAQUE is
                     specified.

   CHS_LEAVEPOS      Resets the current position back to the start of the
                     string. If not given, GpiCharStringPos moves the current
                     position to the end of string.

   CHS_OPAQUE        Draws the rectangle whose the lower-left and upper-right
                     corners are specified by prcl, then fills the rectangle
                     with the current background color. The string is drawn
                     after filling the rectangle.

   CHS_VECTOR        Advances the current position after each character is
                     drawn by using the next value in the array adx. The
                     current character direction defines which direction the
                     current position is advanced.
   ──────────────────────────────────────────────────────────────────────────

   All other values are reserved.

   cchString  Specifies the number of characters in the string pointed to by
   pchString.

   pchString  Points to the character string to be drawn.

   adx  Points to an array of increment values. Each value is a 4-byte,
   signed integer specifying the distance in world coordinates to advance the
   current position after drawing a character. There must be one value for
   each character in the string. The first element specifies the distance to
   advance after drawing the first character, the second element specifies
   the distance after the second character, and so on.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Comments

   If CHS_OPAQUE is specified and the drawing mode is DM_RETAIN,
   GpiCharStringPosAt uses the color mix mode BM_OVERPAINT to fill the
   rectangle. In other drawing modes, the function uses the BM_LEAVEALONE.
   GpiCharStringPos draws the rectangle using the coordinates specified in
   prcl. It does not use the start of the string to compute the rectangle's
   location.

 See Also

   GpiCharStringPos


 ────────────────────────────────────────────────────────────────────────────
 GpiCloseFigure
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiCloseFigure (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiCloseFigure function closes an open figure in a path bracket. A
   figure is open unless it is explicitly closed by using the GpiCloseFigure
   function. A figure can be open even if the current point and the starting
   point of the figure are equal.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiCloseFigure function to close a triangle drawn in
   a path bracket. The triangle starts at (0,0). Since the current position
   just before the GpiCloseFigure is (200,0), the function closes the
   triangle by drawing a line from (200,0) to (0,0).

   HPS hps;
   POINTL ptlStart = { 0, 0 };
   POINTL ptlPoints[] = { 100, 100, 200, 0 };

   GpiBeginPath(hps, 1L);                  /* start the path bracket */
   GpiMove(hps, &ptlStart);                /* move to starting point */
   GpiPolyLine(hps, 2L, ptlPoints);        /* draw the three sides   */
   GpiCloseFigure(hps);                    /* close the triangle     */
   GpiEndPath(hps);                        /* end the path bracket   */

 See Also

   GpiBeginPath, GpiEndPath


 ────────────────────────────────────────────────────────────────────────────
 GpiCloseSegment
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiCloseSegment (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiCloseSegment function closes the current segment. Closing a segment
   does not delete the segment or affect output on the current device. If any
   element bracket is open, GpiCloseSegment automatically closes it.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_MODE_FOR_REOPEN_SEG
         PMERR_PATH_INCOMPLETE

 Comments

   You must explicitly end any area or path bracket before closing the
   segment. Failing to end an area or path may invalidate the segment.

   GpiCloseSegment resets the current viewing transformation to identity.

 Example

   This example uses the GpiCloseSegment function to close a segment. The
   GpiOpenSegment opens the segment; GpiMove and GpiPolyLine draw a triangle.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100,100, 200,0, 0,0 };

   GpiOpenSegment(hps, 1L);             /* open the segment          */
   GpiMove(hps, &ptlStart);             /* move to start point (0,0) */
   GpiPolyLine(hps, 3L, ptlTriangle);   /* draw triangle             */
   GpiCloseSegment(hps);                /* close the segment         */

 See Also

   GpiOpenSegment


 ────────────────────────────────────────────────────────────────────────────
 GpiCombineRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCombineRegion (hps, hrgnDest, hrgnSrc1, hrgnSrc2, cmdMode)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgnDest;          /*handle of destination region                  */
   HRGN hrgnSrc1;          /*handle of first source region                 */
   HRGN hrgnSrc2;          /*handle of second source region                */
   LONG cmdMode;           /*combination method                            */

   The GpiCombineRegion function combines two source regions identified by
   hrgnSrc1 and hrgnSrc2. The new region replaces the destination region
   identified by hrgnDest. If one of the source regions is also given as the
   destination region, the function replaces that source region with the new
   region, but does not affect the other source region.

 Parameters

   hps  Identifies the presentation space. The presentation space must be
   associated with a device context.

   hrgnDest  Identifies the destination region.

   hrgnSrc1  Identifies the first source region.

   hrgnSrc2  Identifies the second source region.

   cmdMode  Specifies how to combine the source regions. It can be one of the
   following values:

   Value     Meaning
   ──────────────────────────────────────────────────────────────────────────
   CRGN_AND  Creates the intersection of the source regions (hrgnSrc1
             INTERSECT hrgnSrc2). The new region contains only the parts of
             the source regions that are common.

   CRGN_COPY Copies the first source region to the destination. The function
             does not use the hrgnSrc2 parameter.

   CRGN_DIFF Creates the difference of the source region (hrgnSrc1 INTERSECT
             NOT hrgnSrc2). The new region contains the parts of the first
             source region that are not also in the second region.

   CRGN_OR   Creates the union of the two source regions (hrgnSrc1 UNION
             hrgnSrc2). The new region contains all parts of both source
             regions.

   CRGN_XOR  Creates the "symmetric" difference of the source regions
             (hrgnSrc1 - hrgnSrc2). The new region contains only the parts of
             the source regions that are not common.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is RGN_NULL, RGN_RECT, or REGN_COMPLEX if the function is
   successful. The return value is RGN_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_REGION_MIX

 Comments

   The source and destination regions must belong to the same presentation
   space or to presentation spaces associated with a similar device context.

 Example

   This example uses the GpiCombineRegion function to create a complex region
   consisting of everything in two rectangles except where they overlap.

   HRGN hrgn1, hrgn2, hrgn3;
   RECTL rclRect1 = { 0, 0, 100, 100 };
   RECTL rclRect2 = { 50, 50, 200, 200 };

   hrgn1 = GpiCreateRegion(hps, 1L, &rclRect1); /* create first region  */
   hrgn2 = GpiCreateRegion(hps, 1L, &rclRect2); /* create second region */
   hrgn3 = GpiCreateRegion(hps, 0L, NULL);      /* create empty region  */

   /* Combine first and second regions, replacing the empty region. */

   GpiCombineRegion(hrgn3, hrgn1, hrgn2, CRGN_XOR);

 See Also

   GpiCreateRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiComment
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiComment (hps, cbData, pbData)
   HPS hps;                /*presentation-space handle                     */
   LONG cbData;            /*length of comment string                      */
   PBYTE pbData;           /*pointer to the comment string                 */

   The GpiComment function adds a comment string to a segment.

 Parameters

   hps  Identifies the presentation space.

   cbData  Specifies the length in bytes of the comment string pointed to by
   pbData.

   pbData  Points to the comment string. The string must not be longer than
   255 bytes.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiComment function to comment the contents of a
   segment.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 0L);                        /* open the segment  */
   GpiComment(hps, 18L, "Start point (0, 0)");
   GpiMove(hps, &ptlStart);
   GpiComment(hps, 13L, "Draw triangle");
   GpiPolyLine(hps, 3L, ptlTriangle);
   GpiCloseSegment(hps);                           /* close the segment */

 See Also

   GpiCloseSegment, GpiMove, GpiOpenSegment, GpiPolyLine


 ────────────────────────────────────────────────────────────────────────────
 GpiConvert
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiConvert (hps, lSrc, lTarg, cPoints, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG lSrc;              /*source coordinate space                       */
   LONG lTarg;             /*target coordinate space                       */
   LONG cPoints;           /*number of coordinate pairs in structure       */
   PPOINTL aptl;           /*pointer to structure for coordinate pairs     */

   The GpiConvert function converts one or more points from one coordinate
   space to another. For each POINTL structure in the array pointed to by
   aptl, the function replaces the original x- and y-coordinate values with
   the converted values.

 Parameters

   hps  Identifies the presentation space.

   lSrc  Specifies the source coordinate space. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CVTC_DEFAULTPAGE  Page space prior to default viewing transform

   CVTC_DEVICE       Device space

   CVTC_MODEL        Model space

   CVTC_PAGE         Page space after default viewing transform

   CVTC_WORLD        World coordinates
   ──────────────────────────────────────────────────────────────────────────

   lTarg  Specifies the target coordinate space. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CVTC_DEFAULTPAGE  Page space prior to default viewing transform

   CVTC_DEVICE       Device space

   CVTC_MODEL        Model space

   CVTC_PAGE         Page space after default viewing transform

   CVTC_WORLD        World coordinates
   ──────────────────────────────────────────────────────────────────────────

   cPoints  Specifies the number of coordinate pairs pointed to by aptl.

   aptl  Points to an array of POINTL structures containing the coordinate
   pairs. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiSetModelTransformMatrix, GpiSetPageViewport,
   GpiSetSegmentTransformMatrix, GpiSetViewingTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiCopyMetaFile
 ────────────────────────────────────────────────────────────────────────────
   HMF GpiCopyMetaFile (hmfSrc)
   HMF hmfSrc;             /*handle of source metafile                     */

   The GpiCopyMetaFile function creates a copy of the metafile identified by
   hmfSrc and returns a handle for the new metafile. The new metafile can be
   edited or deleted without affecting the original metafile.

 Parameters

   hmfSrc  Identifies the source metafile. The source metafile must have been
   loaded previously using the GpiLoadMetaFile function or created previously
   using the DevOpenDC and DevCloseDC functions.

 Return Value

   The return value is the handle of the new metafile if the function is
   successful, or it is GPI_ERROR if an error occurred.

 Example

   This example uses the GpiCopyMetaFile function to copy make a copy of the
   metafile loaded using the GpiLoadMetaFile function.

   HMF hmf1, hmf2;

   GpiLoadMetaFile(hmf1, "sample.met");  /* load the metafile from disk */
   hmf2 = GpiCopyMetaFile(hmf1);         /* copy the metafile           */

 See Also

   DevCloseDC, DevOpenDC, GpiLoadMetaFile


 ────────────────────────────────────────────────────────────────────────────
 GpiCorrelateChain
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCorrelateChain (hps, lType, pptl, lMaxHits, lMaxDepth, alSegTag)
   HPS hps;                /*presentation-space handle                     */
   LONG lType;             /*segment type                                  */
   PPOINTL pptl;           /*pointer to structure for aperture center      */
   LONG lMaxHits;          /*maximum number of hits                        */
   LONG lMaxDepth;         /*maximum number of segment/tag pairs to return */
   PLONG alSegTag;         /*pointer to array of segment and tag           */
                           /*identifiers                                   */

   The GpiCorrelateChain function correlates the segment chain, identifying
   each tagged primitive that intersects the current aperture, as set by the
   GpiSetPickApertureSize function.

   The GpiCorrelateChain function correlates a segment chain by searching for
   each tagged primitive in each segment that lies completely or partially
   within the aperture. Each instance of a tagged primitive in the aperture
   is called a "hit." The function records a hit by copying the identifier of
   the segment containing the primitive (along with the identifier for its
   tag) to the array pointed to by alSegTag. After searching all segments in
   the chain, GpiCorrelateChain returns the number of hits it located.

 Parameters

   hps  Identifies the presentation space.

   lType  Specifies the type of segment to correlate. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PICKSEL_ALL       Correlate all segments with nonzero identifiers
                     regardless of the detectability and visibility
                     attributes of the segments.

   PICKSEL_VISIBLE   Correlate visible and detectable segments with nonzero
                     identifiers.
   ──────────────────────────────────────────────────────────────────────────

   pptl  Points to the POINTL structure that contains the position (in
   presentation page units) of the center of the aperture. The POINTL
   structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lMaxHits  Specifies the maximum number of hits to record.

   lMaxDepth  Specifies the maximum number of segment/tag pairs to record for
   each hit.

   alSegTag  Points to the array to receive the segment/tag pairs. The array
   must be large enough to receive 8 x lMaxHits x lMaxDepth bytes.

 Return Value

   The return value is the number of hits that occurred if the function is
   successful or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_CORRELATE_DEPTH
         PMERR_INV_CORRELATE_TYPE
         PMERR_INV_MAX_HITS
         PMERR_INV_MICROPS_FUNCTION
         PMERR_PATH_INCOMPLETE

 Comments

   GpiCorrelateChain may record more than one segment for each hit. It first
   records the segment containing the hit, then the segment that called the
   first segment, and so on until the function either records the original
   segment in this chain or has recorded lMaxDepth segments. If the function
   finds less than lMaxDepth segments for the hit, the function records zeros
   so that exactly lMaxDepth records are copied for each hit. The function
   records all hits up to lMaxHits, then continues to count the hits even
   though it no longer records them. The return value specifies the complete
   number of hits, not just those recorded.

   The function searches only segments that have nonzero identifiers. If the
   function encounters a segment with a zero identifier, it stops the search
   even if subsequent segments in the chain have nonzero identifiers. During
   the search, the function ignores primitives that do not have nonzero
   identifiers. The function never records more than one hit for a tag in a
   segment even if that tag is used with many primitives.

 See Also

   GpiCorrelateFrom, GpiCorrelateSegment, GpiSetPickApertureSize


 ────────────────────────────────────────────────────────────────────────────
 GpiCorrelateFrom
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCorrelateFrom (hps, idFirstSegment, idLastSegment, lType, pptl,
   lMaxHits, lMaxDepth, alSegTag)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstSegment;    /*first segment to correlate                    */
   LONG idLastSegment;     /*last segment to correlate                     */
   LONG lType;             /*segment type                                  */
   PPOINTL pptl;           /*pointer to structure for aperture center      */
   LONG lMaxHits;          /*maximum number of hits                        */
   LONG lMaxDepth;         /*maximum number of segment/tag pairs to return */
   PLONG alSegTag;         /*pointer to array of segment and tag           */
                           /*identifiers                                   */

   The GpiCorrelateFrom function correlates a portion of the segment chain,
   identifying each tagged primitive that intersects the current aperture, as
   set by the GpiSetPickApertureSize function.

   The GpiCorrelateFrom function correlates a portion of the segment chain by
   searching for each tagged primitive that lies completely or partially
   within the aperture. Each instance of a tagged primitive in the aperture
   is called a "hit." The function records a hit by copying the identifier of
   the segment containing the primitive (along with the identifier for its
   tag) to the array pointed to by alSegTag. The function starts the search
   with the segment identified by idFirstSegment and includes chained and
   called segments up to, and including, the segment identified by
   idLastSegment. After searching these segments, GpiCorrelateFrom returns
   the number of hits it located.

 Parameters

   hps  Identifies the presentation space.

   idFirstSegment  Specifies the first segment to correlate. This value must
   be greater than zero.

   idLastSegment  Specifies the last segment to correlate. This value must be
   greater than zero.

   lType  Specifies the type of segment to correlate. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PICKSEL_ALL       Correlate all segments with nonzero identifiers
                     regardless of the detectability and visibility
                     attributes of the segments.

   PICKSEL_VISIBLE   Correlate visible and detectable segments with nonzero
                     identifiers.
   ──────────────────────────────────────────────────────────────────────────

   pptl  Points to the POINTL structure that contains the position (in
   presentation page units) of the center of the aperture. The POINTL
   structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lMaxHits  Specifies the maximum number of hits to record.

   lMaxDepth  Specifies the maximum number of segment/tag pairs to record.

   alSegTag  Points to the array to receive the segment/tag pairs. The array
   must be large enough to receive 8 x lMaxHits x lMaxDepth bytes.

 Return Value

   The return value is the number of hits that occurred if the function is
   successful or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_CORRELATE_DEPTH
         PMERR_INV_CORRELATE_TYPE
         PMERR_INV_MAX_HITS
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_PATH_INCOMPLETE

 Comments

   GpiCorrelateFrom may record more than one segment for each hit. It first
   records the segment containing the hit, then the segment that called the
   first segment, and so on until the function either records the original
   segment in this chain or has recorded lMaxDepth segments. If the function
   finds less than lMaxDepth segments for the hit, the function records zeros
   so that exactly lMaxDepth records are copied for each hit. The function
   records all hits up to lMaxHits, then continues to count the hits even
   though it no longer records them. The return value specifies the complete
   number of hits, not just those recorded.

   The function searches only segments that have nonzero identifiers. If the
   function encounters a segment with a zero identifier, it stops the search
   even if subsequently called segments have nonzero identifiers. During the
   search, the function ignores primitives that do not have nonzero
   identifiers. The function never records more than one hit for a tag in a
   segment even if that tag is used with many primitives.

   If the idFirstSegment parameter does not exist, or is not in the segment
   chain, the function returns an error. If the segment specified by
   idLastSegment does not exist, is not in the chain, or is chained before
   idFirstSegment, no error results and the function continues to the end of
   the chain.

 See Also

   GpiCorrelateChain, GpiCorrelateSegment


 ────────────────────────────────────────────────────────────────────────────
 GpiCorrelateSegment
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCorrelateSegment (hps, idSegment, lType, pptl, lMaxHits,
   lMaxDepth, alSegTag)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment to correlate                          */
   LONG lType;             /*segment type                                  */
   PPOINTL pptl;           /*pointer to structure for aperture center      */
   LONG lMaxHits;          /*maximum number of hits                        */
   LONG lMaxDepth;         /*maximum number of segment/tag pairs to return */
   PLONG alSegTag;         /*pointer to array of segment and tag           */
                           /*identifiers                                   */

   The GpiCorrelateSegment function correlates the specified segment,
   identifying each tagged primitive that intersects the current aperture, as
   set by the GpiSetPickApertureSize function.

   The GpiCorrelateSegment function correlates a segment by searching for
   each tagged primitive in the segment that lies completely or partially
   within the aperture. Each instance of a tagged primitive in the aperture
   is called a "hit." The function records a hit by copying the identifier of
   the segment containing the primitive (along with the identifier for its
   tag) to the array pointed to by alSegTag. The function also searches
   segments that are called by the specified segment. After searching all
   segments, GpiCorrelateSegment returns the number of hits it located.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment to correlate. This value must be greater
   than zero.

   lType  Specifies the type of segment to correlate. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PICKSEL_ALL       Correlate all segments with nonzero identifiers
                     regardless of the detectability and visibility
                     attributes of the segments.

   PICKSEL_VISIBLE   Correlate visible and detectable segments with nonzero
                     identifiers.
   ──────────────────────────────────────────────────────────────────────────

   pptl  Points to the POINTL structure that contains the position (in
   presentation page units) of the center of the aperture. The POINTL
   structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lMaxHits  Specifies the maximum number of hits to record.

   lMaxDepth  Specifies the maximum number of segment/tag pairs to record.

   alSegTag  Points to the array to receive the segment/tag pairs. The array
   must be large enough to receive 8 x lMaxHits x lMaxDepth bytes.

 Return Value

   The return value is the number of hits that occurred if the function is
   successful or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_CORRELATE_DEPTH
         PMERR_INV_CORRELATE_TYPE
         PMERR_INV_MAX_HITS
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_PATH_INCOMPLETE

 Comments

   GpiCorrelateSegment may record more than one segment for each hit. It
   first records the segment containing the hit, then the segment that called
   the first segment, and so on until the function either records the
   original segment in this chain or records lMaxDepth segments. If the
   function finds less than lMaxDepth segments for the hit, the function
   records zeros so that exactly lMaxDepth records are copied for each hit.
   The function records all hits up to lMaxHits, then continues to count the
   hits even though it no longer records them. The return value specifies the
   complete number of hits, not just those recorded.

   The function searches only segments that have nonzero identifiers. If the
   function encounters a segment with a zero identifier, it stops the search
   even if subsequently called segments have nonzero identifiers. During the
   search, the function ignores primitives that do not have nonzero
   identifiers. The function never records more than one hit for a tag in a
   segment even if that tag is used with many primitives.

 See Also

   GpiCorrelateChain, GpiCorrelateFrom


 ────────────────────────────────────────────────────────────────────────────
 GpiCreateBitmap
 ────────────────────────────────────────────────────────────────────────────
   HBITMAP GpiCreateBitmap (hps, pbmpFormat, flOptions, pbData, pbmiData)
   HPS hps;                /*presentation-space handle                     */
   PBITMAPINFOHEADER pbmpFormat;
                           /*pointer to structure for format data          */
   ULONG flOptions;        /*options                                       */
   PBYTE pbData;           /*pointer to buffer of image data               */
   PBITMAPINFO pbmiData;   /*pointer to structure for color and format     */

   The GpiCreateBitmap function creates a bitmap and returns a bitmap handle
   identifying the bitmap. The new bitmap has the width, height, and format
   specified by fields of the structure pointed to by pbmpFormat. The
   flOptions parameter specifies whether to initialize the bitmap color and
   image. If the parameter is CBM_INIT, the function uses the bitmap image
   data pointed to by pbData and the bitmap color data pointed to by pbmiData
   to initialize the bitmap. If CBM_INIT is not given, the bitmap's initial
   image and color are undefined.

   The bitmap handle can be used in subsequent functions that accept bitmap
   handles. In most cases, the bitmap is set to a memory presentation space
   using the GpiSetBitmap function, then copied to the screen or a printer
   using the GpiBitBlt function.

 Parameters

   hps  Identifies the presentation space.

   pbmpFormat  Points to the BITMAPINFOHEADER structure that contains the
   bitmap format data. The BITMAPINFOHEADER structure has the following form:

   typedef struct _BITMAPINFOHEADER {
       ULONG  cbFix;
       USHORT cx;
       USHORT cy;
       USHORT cPlanes;
       USHORT cBitCount;
   } BITMAPINFOHEADER;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies whether to initialize the bitmap. It can one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CBM_INIT          Initializes the bitmap, using the bitmap image and color
                     data specified by the pbData and pbmiData parameters.

   0x0000            Does not initialize the bitmap.
   ──────────────────────────────────────────────────────────────────────────

   pbData  Points to the buffer that contains bitmap image data. The image
   data defines the color of each pel in the bitmap. This parameter is
   ignored if CBM_INIT is not given.

   pbmiData  Points to a BITMAPINFO structure that contains the bitmap format
   and color data. The format data is identical to the data pointed to by the
   pbmpFormat parameter. The color data follows immediately after the format
   data, and consists of two or more RGB color values. The exact number
   depends on the bitmap format. This parameter is ignored if CBM_INIT is not
   given. The BITMAPINFO structure has the following form:

   typedef struct _BITMAPINFO {
       ULONG  cbFix;
       USHORT cx;
       USHORT cy;
       USHORT cPlanes;
       USHORT cBitCount;
       RGB    argbColor[1];
   } BITMAPINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value identifies the new bitmap if the function is successful,
   or is GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_USAGE

 Comments

   The full number of bitmap formats depends on what the associated device
   supports. However, most devices support the following standard bitmap
   formats:

   Format            Description
   ──────────────────────────────────────────────────────────────────────────
   Monochrome        1 bit per pel and 1 color plane

   16-color          4 bits per pel and 1 color plane

   256-color         8 bits per pel and 1 color plane

   Full-color        24 bits per pel and 1 color plane
   ──────────────────────────────────────────────────────────────────────────

   When initializing the bitmap, the bitmap color data must consist of an
   appropriate number of RGB color values. For monochrome format, it must
   have 2 values; for 16-color format, 16 values; and for 256-color format,
   256 values. No color values are required for the full-color format, since
   the image data for each pel fully specifies the pel color.

   When CBM_INIT is given, the function continues to copy data from the
   buffer until the entire bitmap is initialized. The function expects each
   row of image data to contain a multiple of 32 bits (4 bytes). Although the
   bitmap width does not have to be a multiple of 32, the image data must be.
   Any extra bits at the end of a row are ignored.

   The new bitmap belongs to the device context associated with the given
   presentation space. It can be set to any presentation space having the
   same device context or having a compatible device context.

 Example

   The following example loads a bitmap resource from memory and uses the
   GpiCreateBitmap function to create the bitmap. This is similar to using
   the GpiLoadBitmap function, except it gives the application the chance to
   modify the bitmap image data before creating the bitmap.

   SEL sel;          /* selector for segment containing bitmap resource */
   PBITMAPFILEHEADER pbfh;  /* bitmap resource header information       */
   PBYTE pb;                /* pointer to bitmap image data in resource */
   HBITMAP hbm;             /* bitmap handle                            */

   DosGetResource(NULL, RT_BITMAP, 1, &sel); /* load bitmap resource #1 */
   pbfh = MAKEP(sel, 0);              /* bitmap file header in resource */
   pb = MAKEP(sel, pbfh->offBits);    /* image data starts at offBits   */

   /* make any changes to bitmap image data here */

   hbm = GpiCreateBitmap(hps,             /* presentation space         */
       &(pbfh->bmp),                      /* bitmap information in file */
       CBM_INIT,                          /* initialize the bitmap      */
       pb,                                /* bitmap data                */
       &(pbfh->bmp));                     /* bitmap information in file */

   DosFreeSeg(sel);                       /* free bitmap resource       */

 See Also

   DosFreeSeg, DosGetResource, GpiDeleteBitmap, GpiLoadBitmap,
   GpiQueryDeviceBitmapFormats


 ────────────────────────────────────────────────────────────────────────────
 GpiCreateLogColorTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiCreateLogColorTable (hps, flOptions, lFormat, iStart, clTable,
   alTable)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOptions;        /*options                                       */
   LONG lFormat;           /*format of entries                             */
   LONG iStart;            /*starting index                                */
   LONG clTable;           /*number of entries in table                    */
   PLONG alTable;          /*pointer to array for table                    */

   The GpiCreateLogColorTable function creates a logical color table. The
   logical color table has the format specified by lFormat, with the initial
   value of each entry specified by the array alTable.

 Parameters

   hps  Identifies the presentation space.

   flOptions  Specifies whether the logical color table uses pure,
   realizable, or default color values. It can be one of the following
   values:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   0x0000            Creates a logical color table having the entries
                     specified by alTable. The logical color table entries
                     map to existing device colors in the physical palette or
                     to dithered colors if no matching device color is in the
                     palette. This means the table is not realized and does
                     not require pure colors.

   LCOL_PURECOLOR    Creates a logical color table whose entries map to pure
                     (nondithered) colors only. If not given, the function
                     creates a color table whose entries map to dithered
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    creates a color table whose entries map to dithered
                     colors if the physical palette does not contain matching
                     device colors.

   LCOL_REALIZABLE   Creates a logical color table that can be realized by
                     using the GpiRealizeColorTable function. Until the
                     logical color table is realized, colors in the table map
                     to the existing device colors in the physical palette.
                     This option is useful only for devices that permit
                     realization of logical color tables.

   LCOL_RESET        Resets all entries in the logical color table to default
                     values before initializing the entries specified by the
                     alTable parameter. This option is useful for quickly
                     initializing all entries without supplying initial
                     values for every element in alTable.
   ──────────────────────────────────────────────────────────────────────────


   lFormat  Specifies the logical color table format. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LCOLF_CONSECRGB   Creates a color table having consecutive entries. The
                     first entry has the index specified by iStart.

   LCOLF_INDRGB      Creates a color table. The entries are not required to
                     be consecutive. The alTable array specifies both the
                     index and RGB color value for each entry.

   LCOLF_RGB         Enables direct RGB color mapping. Applications use RGB
                     values instead of color indexes to specify the colors in
                     subsequent drawing functions.
   ──────────────────────────────────────────────────────────────────────────

   iStart  Specifies the color index of the first entry for a color table
   having LCOLF_CONSECRGB format. If LCOLF_CONSECRGB is not given, this
   parameter is ignored.

   clTable  Specifies the number of elements in the array alTable. If the
   format LCOLF_INDRGB is given, this parameter must be an even number (that
   is, two elements for each entry). If LCOL_RESET or LCOLF_RGB is given,
   this parameter can be zero.

   alTable  Specifies the start address of the array that contains the color
   table entries. The format depends on the value of lFormat, as follows:

   Value               Format
   ──────────────────────────────────────────────────────────────────────────
   LCOLF_CONSECRGB     Each element is a 4-byte RGB color value.

   LCOLF_INDRGB        Each pair of elements contains a 4-byte color index
                       and a 4-byte RGB color value, in that order.

   LCOLF_RGB           No elements required.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_COLOR_DATA
         PMERR_INV_COLOR_FORMAT
         PMERR_INV_COLOR_OPTIONS

 Comments

   Although GpiCreateLogColorTable can create a realizable color table, it
   does not realize the colors. Until the color table is realized by using
   the GpiRealizeColorTable function, the logical color table entries are
   mapped to the existing colors in the physical palette. Realizing the
   logical color table causes the physical palette colors to be replaced with
   the realized colors for the logical color table entries.

   The default physical palette contains at least the standard 16 PC colors
   (unless this is not physically possible). If a device supports more than
   16 colors, the physical palette may have additional colors, but there is
   no guarantee that these additional colors are the same on every device.

 Example

   This example uses the GpiCreateLogColorTable function to create a logical
   color table, using data from the previous logical color table:

   ULONG alTable[16];                       /* assume 16 entries        */

   /* retrieve the current table */

   GpiQueryLogColorTable(hps, 0L, 0L, 16L, alTable);

   alTable[1] = 0x000080;      /* change the second entry to light blue */

   GpiCreateLogColorTable(hps,              /* presentation space       */
       0L,                                  /* no special options       */
       LCOLF_CONSECRGB,                     /* consecutive RGB values   */
       0L,                                  /* start with color index 0 */
       16,                                  /* 16 entries               */
       alTable);                            /* RGB color values         */

 See Also

   DevQueryCaps, GpiErase, GpiQueryColorData, GpiQueryLogColorTable,
   GpiRealizeColorTable, GpiSetBitmapBits, WinSetSysColors


 ────────────────────────────────────────────────────────────────────────────
 GpiCreateLogFont
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiCreateLogFont (hps, pchName, lcid, pfat)
   HPS hps;                /*presentation-space handle                     */
   PSTR8 pchName;          /*pointer to logical-font name                  */
   LONG lcid;              /*local identifier                              */
   PFATTRS pfat;           /*pointer to structure for font attributes      */

   The GpiCreateLogFont function creates a logical font. A logical font is a
   list of font attributes, such as face name, average width, and maximum
   height, that an application uses to request a physical font. A physical
   font is the bitmap or vector information the system uses to draw
   characters on a device. Applications create logical fonts to specify the
   fonts they need, and the system maps the logical fonts to matching
   physical fonts.

   GpiCreateLogFont creates a logical font using the font attributes
   specified in the structure pointed to by the pfat parameter. Each logical
   font has a local identifier and logical font name, specified by the lcid
   and pchName parameters, to uniquely identify it. The local identifier can
   then be used in subsequent graphics functions to identify the font.

   Since a physical font that exactly matches the logical font may not be
   available, the system usually maps the logical font to the closest
   matching physical font. The system uses rules to map the font──for
   example, it chooses a font with a greater height if a font of the exact
   height is not available. An application can force the system to choose a
   particular font by setting the value of the lMatch field in the FATTRS
   structure to be that returned for the desired font by the GpiQueryFonts
   function. After GpiCreateLogFont chooses the physical font, this choice
   does not change for a particular logical font.

 Parameters

   hps  Identifies the presentation space.

   pchName  Points to an 8-character logical-font name. It can be NULL, if no
   logical font name is desired.

   lcid  Specifies the local identifier that the application uses to refer to
   this font. It must be in the range 1 through 254. It is an error if this
   parameter is already in use to refer to a font or bitmap.

   pfat  Points to a FATTRS structure that will contain the attributes of the
   logical font that is created. The FATTRS structure has the following form:

   typedef struct _FATTRS {
       USHORT  usRecordLength;
       USHORT  fsSelection;
       LONG    lMatch;
       CHAR    szFaceName[FACESIZE];
       USHORT  idRegistry;
       USHORT  usCodePage;
       LONG    lMaxBaselineExt;
       LONG    lAveCharWidth;
       USHORT  fsType;
       SHORT   sQuality;
       USHORT  fsFontUse;
   } FATTRS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is 2 if a matching font is found, 1 if a matching font
   could not be found, or zero if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_FONT_NOT_LOADED
         PMERR_INV_FONT_ATTRS

 Comments

   To choose the system default font, set the face name to NULL and all other
   attributes in the FATTR structure, except the code page, to zero.

   To use a font, the application sets the font for the presentation space by
   specifying the local identifier for the corresponding logical font with
   the GpiSetCharSet function. Once a font is set, the system uses the font
   for subsequent text output.

 Example

   This example uses the GpiCreateLogFont function to create a logical font
   with the local identifier 1. The logical font has the face name "Courier"
   and requested width and height of 12 pels. Once the font is created, the
   example sets the font using the local identifier and displays a string in
   the font at the point (100,100).

   USHORT i;
   POINTL ptl = { 100, 100 };
   FATTRS fat;

   fat.usRecordLength = sizeof(FATTRS); /* set size of structure        */
   fat.fsSelection = 0;            /* use default selection             */
   fat.lMatch = 0L;                /* do not force match                */
   fat.idRegistry = 0;             /* use default registry              */
   fat.usCodePage = 850;           /* code page 850                     */
   fat.lMaxBaselineExt = 12L;      /* requested font height is 12 pels  */
   fat.lAveCharWidth = 12L;        /* requested font width is 12 pels   */
   fat.fsType = FATTR_TYPE_FIXED;  /* fixed-spacing font                */
   fat.fsFontUse = FATTR_FONTUSE_NOMIX; /* do not mix with graphics     */

   /* copy Courier to szFacename field */

   for (i=0; fat.szFacename[i] = "Courier"[i]; i++);


   GpiCreateLogFont(hps,           /* presentation space                */
                    NULL,          /* do not use logical font name      */
                    1L,            /* local identifier                  */
                    &fat);         /* structure with font attributes    */

   GpiSetCharSet(hps, 1L);           /* set font for presentation space */
   GpiCharStringAt(hps, &ptl, 5L, "Hello"); /* display a string         */

 See Also

   GpiCharStringAt, GpiCreateLogFont, GpiQueryFonts, GpiSetCharSet


 ────────────────────────────────────────────────────────────────────────────
 GpiCreatePS
 ────────────────────────────────────────────────────────────────────────────
   HPS GpiCreatePS (hab, hdc, psizl, flOptions)
   HAB hab;                /*anchor-block handle                           */
   HDC hdc;                /*device-context handle                         */
   PSIZEL psizl;           /*pointer to structure for page size            */
   ULONG flOptions;        /*presentation-space options                    */

   The GpiCreatePS function creates a presentation space. The presentation
   space has the presentation type, page size, page unit, and storage format
   specified by psizl and flOptions. The function also associates the device
   context specified by hdc with the presentation space if a device context
   is given. The presentation space, identified by the handle returned by
   GpiCreatePS, can be used in subsequent Gpi functions to draw to the
   associated device.

 Parameters

   hab  Identifies the anchor block.

   hdc  Identifies a device context. It is required only if the GPIA_ASSOC
   option is given in flOptions. It must be a handle to a device context if
   the GPIT_MICRO option is given. Otherwise, it can be NULL.

   psizl  Points to a SIZEL structure that contains the width and height of
   the presentation page. The width and height can be zero if the GPIA_ASSOC
   option is given. The width and height must be non-zero if the PU_ARBITRARY
   option is given. The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies the presentation-space options. The options define
   the page unit, storage format, and presentation type for the presentation
   space, as well as specifying whether to associate a device context with
   the new presentation space. The flOptions parameter must include exactly
   one of the following page unit options combined with no more than one each
   of the following storage format, presentation type, and association
   options:

   Page unit         Meaning
   ──────────────────────────────────────────────────────────────────────────
   PU_ARBITRARY      Sets units initially to pels but permits the units to be
                     modified later using the GpiSetPageViewport function.

   PU_HIENGLISH      Sets units to 0.001 inch.

   PU_HIMETRIC       Sets units to 0.01 millimeter.

   PU_LOENGLISH      Sets units to 0.01 inch.

   PU_LOMETRIC       Sets units to 0.1 millimeter.

   PU_PELS           Sets units to pels.

   PU_TWIPS          Sets units to 1/1440 inch (1/20 point).
   ──────────────────────────────────────────────────────────────────────────

   Storage format    Meaning
   ──────────────────────────────────────────────────────────────────────────
   GPIF_DEFAULT      Stores coordinates as 2-byte integers. GPIF_DEFAULT is
                     the default if no storage format is given.

   GPIF_LONG         Stores coordinates as 4-byte integers.

   GPIF_SHORT        Stores coordinates as 2-byte integers.
   ──────────────────────────────────────────────────────────────────────────

   Presentation type Meaning
   ──────────────────────────────────────────────────────────────────────────
   GPIT_MICRO        Creates a micro presentation space. The presentation
                     space must be associated with a screen device context.
                     The GPIA_ASSOC option and a device context must also be
                     given.

   GPIT_NORMAL       Creates a normal presentation space. The presentation
                     space can be associated with any device context and used
                     with retained graphics. If a presentation-space type is
                     not given, the default is GPIT_NORMAL.
   ──────────────────────────────────────────────────────────────────────────

   Association       Meaning
   ──────────────────────────────────────────────────────────────────────────
   GPIA_ASSOC        Associates the device context specified by hdc with the
                     new presentation space. If hdc identifies a memory
                     device context, GPIT_MICRO must be set or the system
                     will issue a warning.

   GPIA_NOASSOC      Creates presentation space without associating a device
                     context. GPIA_NOASSOC is the default if an association
                     option is not given.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is the handle of the presentation space if the function
   is successful or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_OR_INCOMPAT_OPTIONS

 Comments

   The presentation type can be normal or micro. Normal presentation spaces
   can be associated with any device context and can be used for retained
   graphics. Micro presentation spaces can be associated with any device, but
   only when they are created. They can never be reassociated. The GPIA_ASSOC
   and GPIA_NOASSOC options specify whether the new presentation space is to
   be associated with the device context identified by hdc. If not
   associated, the GpiAssociate function must be used to associate a device
   context. A presentation space can not be used without an associated
   device.

   The page unit specifies the unit of measure used to draw to the device.
   For example, if the page unit is pels, a line 100 units long in world
   space coordinates is 100 pels long on the device.

   The presentation page size specifies the width and height of the
   presentation page. The presentation page and page viewport define how
   points in the presentation page space are mapped to the pels in the device
   space. This is important for programs that need to change the page unit
   without recreating the presentation space.

   The storage format specifies the internal format for coordinate values
   stored in the segments. This is important for applications that edit
   segments.

 Example

   This example uses the GpiCreatePS function to create a micro presentation
   space for a memory device context. The function associates the
   presentation space with the device context and sets the page units to
   pels. By default, the presentation space is a normal presentation space
   that uses local storage format.

   HDC hdc;
   HPS hps;
   SIZEL sizl = { 0, 0 };    /* use same page size as device */
   DEVOPENSTRUC dop;

   dop.pszLogAddress = NULL;
   dop.pszDriverName = (PSZ) "DISPLAY";
   dop.pdriv = NULL;
   dop.pszDataType = NULL;

   /* Create the memory device context. */

   hdc = DevOpenDC(hab, OD_MEMORY, "*", 4L, &dop, NULL);

   /* Create the presentation and associate the memory device context. */

   hps = GpiCreatePS(hab, hdc, &sizl, PU_PELS | GPIT_MICRO | GPIA_ASSOC);

 See Also

   GpiDestroyPS, GpiSetPageViewport


 ────────────────────────────────────────────────────────────────────────────
 GpiCreateRegion
 ────────────────────────────────────────────────────────────────────────────
   HRGN GpiCreateRegion (hps, crcl, prcl)
   HPS hps;                /*presentation-space handle                     */
   LONG crcl;              /*number of rectangles                          */
   PRECTL prcl;            /*pointer to structure for rectangles           */

   The GpiCreateRegion function creates a region for the device associated
   with the specified presentation space. The region is the union of the
   rectangles specified by the prcl parameter.

 Parameters

   hps  Identifies the presentation space.

   crcl  Specifies the number of rectangles specified in the prcl parameter.
   If the crcl parameter is equal to zero, an empty region is created, and
   prcl is ignored.

   prcl  Points to an array of RECTL structures. The RECTL structure has the
   following form:

   typedef struct _RECTL {
       LONG xLeft;
       LONG yBottom;
       LONG xRight;
       LONG yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is a handle to the region if the function is successful
   or zero if an error occurred. It is an error if this function is issued
   when there is no device context associated with the presentation space.

 Example

   This example uses the GpiCreateRegion function to create a region
   consisting of the union of three rectangles:

   HRGN hrgn;                                      /* handle for region */
   RECTL arcl[3] = { 100, 100, 200, 200,           /* 1st rectangle     */
                     150, 150, 250, 250,           /* 2nd rectangle     */
                     200, 200, 300, 300 };         /* 3rd rectangle     */

   hrgn = GpiCreateRegion(hps,                    /* presentation space */
                          3L,                     /* three rectangles   */
                          arcl);      /* pointer to array of rectangles */

 See Also

   GpiCombineRegion, GpiDestroyRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteBitmap
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteBitmap (hbm)
   HBITMAP hbm;            /*bitmap handle                                 */

   The GpiDeleteBitmap function deletes the bitmap specified by hbm.

 Parameters

   hbm  Identifies the bitmap to delete.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_BITMAP_IS_SELECTED

 Example

   This example uses the GpiDeleteBitmap function to delete a bitmap. The
   GpiSetBitmap function releases the bitmap from the presentation space
   before deleting it. This is needed only if the bitmap is set in the
   presentation space.

   HBITMAP hbm, hbmPrevious;

   hbm = GpiLoadBitmap(hps, NULL, 1, 0L, 0L); /* load the bitmap        */
   hbmPrevious = GpiSetBitmap(hps, hbm);      /* set bitmap for PS      */

   /* use GpiBitBlt to display bitmap */

   GpiSetBitmap(hps, hbmPrevious);            /* release bitmap from PS */
   GpiDeleteBitmap(hbm);                      /* delete the bitmap      */

 See Also

   GpiCreateBitmap, GpiLoadBitmap, GpiQueryDeviceBitmapFormats,
   GpiSetBitmap


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteElement
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteElement (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiDeleteElement function deletes an element from the currently open
   segment. The function deletes the element pointed to by the element
   pointer, then moves the element pointer to the preceding element (if any).
   The segment containing the element must be open and the drawing mode must
   be DM_RETAIN.

   GpiDeleteElement cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Example

   This example uses the GpiDeleteElement function to delete the third
   element from the previously created segment 2:

   GpiOpenSegment(hps, 2L);           /* open segment #2       */
   GpiSetElementPointer(hps, 3L);     /* move to third element */
   GpiDeleteElement(hps);             /* delete element        */
   GpiCloseSegment(hps);              /* close the segment     */

 See Also

   GpiBeginElement, GpiEndElement, GpiQueryElement,
   GpiQueryElementPointer, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteElementRange
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteElementRange (hps, idFirstElement, idLastElement)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstElement;    /*first element                                 */
   LONG idLastElement;     /*last element                                  */

   The GpiDeleteElementRange function deletes one or more elements from the
   currently open segment. The function deletes all elements between and
   including the elements specified by idFirstElement and idLastElement, then
   moves the element pointer to the preceding element (if any). The function
   rounds idFirstElement or idLastElement to a valid element-pointer position
   if the given position does not point to an element. The segment containing
   the element must be open and the drawing mode must be DM_RETAIN.

   GpiDeleteElementRange cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   idFirstElement  Specifies the element-pointer position of the first
   element to delete.

   idLastElement  Specifies the element-pointer position of the last element
   to delete.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Example

   This example uses the GpiDeleteElementRange function to delete the second
   through fifth elements in the previously created segment 2:

   GpiOpenSegment(hps, 2L);            /* open segment # 2            */
   GpiDeleteElementRange(hps, 2L, 5L); /* delete elements 2 through 5 */
   GpiCloseSegment(hps);               /* close the segment           */

 See Also

   GpiOffsetElementPointer, GpiQueryElementPointer, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteElementsBetweenLabels
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteElementsBetweenLabels (hps, idFirstLabel, idLastLabel)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstLabel;      /*label of first element                        */
   LONG idLastLabel;       /*label of last element                         */

   The GpiDeleteElementsBetweenLabels function deletes one or more elements
   from the currently open segment. The function deletes all elements between
   but not including the elements having the labels specified by the
   idFirstLabel and idLastLabel parameters, then moves the element pointer to
   the element preceding the deleted elements (if any). If either label
   cannot be found between the current element-pointer position and the end
   of the segment, the function deletes no elements and returns an error
   value. The segment containing the element must be open and the drawing
   mode must be DM_RETAIN.

   GpiDeleteElementBetweenLabels cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   idFirstLabel  Specifies the label that marks the start of the elements to
   delete.

   idLastLabel  Specifies the label that marks the end of the elements to
   delete.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_LABEL_NOT_FOUND

 Example

   This example uses the GpiDeleteElementsBetweenLabels function to delete
   the elements between but not including the elements having the labels 1
   and 2:

   GpiOpenSegment(hps, 2L);            /* open segment #2   */

   /* delete elements between 1 and 2 */

   GpiDeleteElementsBetweenLabels(hps, 1L, 2L);
   GpiCloseSegment(hps);               /* close the segment */

 See Also

   GpiLabel, GpiSetElementPointerAtLabel


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteMetaFile
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteMetaFile (hmf)
   HMF hmf;                /*metafile handle                               */

   The GpiDeleteMetaFile function deletes the metafile specified by hmf.

 Parameters

   hmf  Identifies the metafile.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   DevCloseDC, DevOpenDC, GpiLoadMetaFile


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteSegment
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteSegment (hps, idSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*identifier of segment to delete               */

   The GpiDeleteSegment function deletes the segment specified by idSegment.
   If the segment is open, the function automatically closes the segment
   before deleting it. If the segment is in the picture chain, the function
   removes it from the chain.

   This function deletes only segments created using the GpiOpenSegment
   function.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment to delete; it must be greater than zero.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 Example

   This example uses the GpiDeleteSegment function to delete segment 4:

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 4L);               /* open the segment           */
   GpiMove(hps, &ptlStart);               /* move to start point (0, 0) */
   GpiPolyLine(hps, 3L, ptlTriangle);     /* draw triangle              */
   GpiCloseSegment(hps);                  /* close the segment          */
       .
       .
       .
   GpiDeleteSegment(hps, 4L);             /* delete segment #4          */

 See Also

   GpiCloseSegment, GpiDeleteSegments, GpiOpenSegment,
   GpiQuerySegmentNames


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteSegments
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteSegments (hps, idFirstSegment, idLastSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstSegment;    /*identifier of first segment                   */
   LONG idLastSegment;     /*identifier of last segment                    */

   The GpiDeleteSegments function deletes the segments between and including
   the segments specified by the idFirstSegment and idLastSegment parameters.
   If idFirstSegment and idLastSegment are equal, the function deletes only
   that segment. If idFirstSegment is greater than idLastSegment, the
   function deletes only the segment specified by idFirstSegment. If any of
   the segments is open, the function closes the segment before deleting it.
   If any of the segments is in the picture chain, the function removes the
   segment from the chain.

   This function deletes only segments created using the GpiOpenSegment
   function.

 Parameters

   hps  Identifies the presentation space.

   idFirstSegment  Specifies the identifier of the first segment to delete.
   This parameter must be greater than zero.

   idLastSegment  Specifies the identifier of the last segment to delete.
   This parameter must be greater than zero.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 See Also

   GpiCloseSegment, GpiDeleteSegment, GpiOpenSegment,
   GpiQuerySegmentNames

 Example

   This example uses the GpiDeleteSegments function to delete segments 4
   through 6:

   GpiDeleteSegments(hps, 4L, 6L);       /* delete segments 4 through 6 */


 ────────────────────────────────────────────────────────────────────────────
 GpiDeleteSetId
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDeleteSetId (hps, lcid)
   HPS hps;                /*presentation-space handle                     */
   LONG lcid;              /*local identifier for font or bitmap           */

   The GpiDeleteSetId function deletes a logical font or removes the tag from
   a tagged bitmap, depending on the object identified by local identifier
   lcid. If the object is a logical font, the function deletes it, making it
   no longer available for use. If the object is a bitmap, the function
   removes the tag, but the bitmap handle remains valid. In either case, the
   function frees the local identifier for use with another object.

 Parameters

   hps  Identifies the presentation space.

   lcid  Specifies the local identifier for the object. If this parameter is
   set to LCID_ALL, the function deletes all logical fonts and removes the
   tags from all tagged bitmaps.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiDeleteSetId function to delete a logical font.
   The GpiSetCharSet function is required only if the logical font is the
   current font for the presentation space.

   FATTRS fat;

   /* create and set the font */

   GpiCreateLogFont(hps, NULL, 1L, &fat);
   GpiSetCharSet(hps, 1L);
       .
       .
       .
   GpiSetCharSet(hps, 0L);          /* release the font before deleting */
   GpiDeleteSetId(hps, 1L);         /* delete the logical font          */

 See Also

   GpiSetBitmapId, GpiSetCharSet


 ────────────────────────────────────────────────────────────────────────────
 GpiDestroyPS
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDestroyPS (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiDestroyPS function destroys the presentation space and releases all
   resources owned by the presentation space. This function should only be
   used to destroy presentation spaces created by the GpiCreatePS function.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiDestroyPS function to destroy the presentation
   space associated with a memory device context:

   HDC hdc;
   HPS hps;
   SIZEL page = { 0, 0 };

   /* create the memory device context and presentation space */

   hdc = DevOpenDC(hab, OD_MEMORY, "*", 0L, NULL, NULL);
   hps = GpiCreatePS(hab, hdc, &page, PU_PELS | GPIT_MICRO | GPIA_ASSOC);
       .
       .
       .
   GpiDestroyPS(hps);    /* destroy the presentation space */
   DevCloseDC(hdc);      /* close the device context       */

 See Also

   GpiCreatePS


 ────────────────────────────────────────────────────────────────────────────
 GpiDestroyRegion
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDestroyRegion (hps, hrgn)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*handle of region to destroy                   */

   The GpiDestroyRegion function destroys the region specified by hrgn. The
   function destroys the region only if the device context containing the
   region is associated with the given presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region to destroy.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiDestroyRegion function to destroy a region after
   drawing a complex figure:

   HRGN hrgn;
   RECTL arcl[3] = { 10, 10, 20, 20, 15, 15, 25, 25, 20, 20, 30, 30 };

   hrgn = GpiCreateRegion(hps, 3L, arcl); /* use 3 rectangles   */
   GpiPaintRegion(hps, hrgn);             /* paint the region   */
   GpiDestroyRegion(hps, hrgn);           /* destroy the region */

 See Also

   GpiCreateRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiDrawChain
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDrawChain (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiDrawChain function draws the picture chain. The function draws all
   segments in the picture chain, including called segments. GpiDrawChain
   draws the segments using the current draw controls (except correlation
   control), as set by the GpiSetDrawControl function. The function does not
   affect drawing modes or open segments.

   The function cannot be used in an area, path, or element bracket.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_PATH_INCOMPLETE
         PMERR_STOP_DRAW_OCCURRED

 See Also

   GpiCloseSegment, GpiDrawDynamics, GpiDrawFrom, GpiDrawSegment,
   GpiQuerySegmentNames, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiDrawDynamics
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDrawDynamics (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiDrawDynamics function draws the dynamic segments in the picture
   chain. The function draws all dynamic segments unless a previous call to
   the GpiRemoveDynamics function restricts the drawing to a selected range.
   The function draws the segments using the current draw controls (except
   correlation control), as set by the GpiSetDrawControl function.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_PATH_INCOMPLETE
         PMERR_STOP_DRAW_OCCURRED

 See Also

   GpiCloseSegment, GpiDrawChain, GpiDrawFrom, GpiDrawSegment,
   GpiQuerySegmentNames, GpiRemoveDynamics, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiDrawFrom
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDrawFrom (hps, idFirstSegment, idLastSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstSegment;    /*first chain segment to draw                   */
   LONG idLastSegment;     /*last chain segment to draw                    */

   The GpiDrawFrom function draws one or more segments in the picture chain.
   The function draws all chained and called segments between and including
   the segments identified by the idFirstSegment and idLastSegment
   parameters. Although idFirstSegment must identify an existing segment,
   idLastSegment need not. If idLastSegment does not specify an existing
   segment, the function draws to the end of the picture chain.

   GpiDrawFrom draws the segments using the current draw controls (except
   correlation control), as set by the GpiSetDrawControl function. The
   function does not affect drawing modes or open segments. Also, GpiDrawFrom
   cannot be used in an area, path, or element bracket.

 Parameters

   hps  Identifies the presentation space.

   idFirstSegment  Specifies the identifier of the first segment to draw.
   This parameter must be greater than zero.

   idLastSegment  Specifies the identifier of the last segment to draw. This
   parameter must be greater than zero.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_PATH_INCOMPLETE
         PMERR_STOP_DRAW_OCCURRED

 Example

   This example uses the GpiDrawFrom function to draw all segments in the
   picture chain between and including the segments 1 and 4:

   GpiDrawFrom(hps, 1L, 4L);

 See Also

   GpiCloseSegment, GpiDrawChain, GpiDrawDynamics, GpiDrawSegment,
   GpiQuerySegmentNames, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiDrawSegment
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiDrawSegment (hps, idSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*identifier of segment to draw                 */

   The GpiDrawSegment function draws the specified segment. The function
   draws the segments using the current draw controls (except correlation
   control), as set by the GpiSetDrawControl function. The function does not
   affect drawing modes or open segments.

   GpiDrawSegment cannot be used in an area, path, or element bracket.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Identifies the segment to draw. This parameter must be greater
   than zero.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_PATH_INCOMPLETE
         PMERR_STOP_DRAW_OCCURRED

 Example

   This example uses the GpiDrawSegment function to draw segment 4:

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 4L);               /* open the segment           */
   GpiMove(hps, &ptlStart);               /* move to start point (0, 0) */
   GpiPolyLine(hps, 3L, ptlTriangle);     /* draw triangle              */
   GpiCloseSegment(hps);                  /* close the segment          */
       .
       .
       .
   GpiDrawSegment(hps, 4L);               /* draw segment #4            */



 See Also

   GpiCloseSegment, GpiDrawChain, GpiDrawDynamics, GpiDrawFrom,
   GpiQuerySegmentNames, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiElement
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiElement (hps, lType, psz, cb, pb)
   HPS hps;                /*presentation-space handle                     */
   LONG lType;             /*element type                                  */
   PSZ psz;                /*pointer to element descriptor                 */
   LONG cb;                /*length in bytes of buffer for graphics orders */
   PBYTE pb;               /*pointer to buffer for graphics orders         */

   The GpiElement function draws an element. The element consists of one or
   more graphics orders in the buffer pointed to by pb. The function executes
   each order as if it were the corresponding Gpi function.

   The function adds the element to the current open segment if the drawing
   mode is DM_RETAIN or DM_DRAWANDRETAIN. Otherwise, it just draws the
   element. The element must not contain graphics orders for an element
   bracket. Similarly, the function cannot be used in an element bracket.

   The function sets the type and descriptor for the element to the values
   given by lType and psz. The type and descriptor are a useful way of
   uniquely identifying the element when it is added to a segment. The type
   and descriptor can be retrieved at any time by using the
   GpiQueryElementType function.

 Parameters

   hps  Identifies the presentation space.

   lType  Specifies the integer value to use for the element type.

   psz  Points to the null-terminated string to use for the element
   descriptor.

   cb  Specifies the length of graphics order data for the element.

   pb  Points to the buffer that contains the graphics orders for the
   element. The buffer must not exceed 63K.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful. (It
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs.) The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_DATA_TOO_LONG
         PMERR_INV_LENGTH
         PMERR_INV_MICROPS_FUNCTION

 Comments

   GpiElement does not convert coordinates. This may affect drawing the
   element if the format for the coordinates in the graphics orders is not
   the correct format for the presentation space.

 See Also

   GpiBeginElement, GpiDeleteElement, GpiEndElement, GpiQueryElement,
   GpiQueryElementPointer, GpiQueryElementType, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiEndArea
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiEndArea (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiEndArea function ends an area bracket──that is, it ends the
   sequence of functions (starting with the GpiBeginArea function) that
   define the outline of an area. The function automatically closes any open
   figure in the area, if necessary, by drawing a line from the current
   position to the starting point of the figure, then draws the area using
   the filling mode specified by the GpiBeginArea function that started the
   area bracket.

   The GpiEndArea function does not change the current position unless it
   must draw a line to close a figure in the area. In this case the new
   position is the last point in the line.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful. (It
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs.) The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiEndArea function to end an area bracket. The
   function draws the area (a triangle) by filling the outline with the
   current fill pattern.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiBeginArea(hps, BA_NOBOUNDARY | BA_ALTERNATE);
   GpiMove(hps, &ptlStart);
   GpiPolyLine(hps, 3L, ptlTriangle);
   GpiEndArea(hps);

 See Also

   GpiBeginArea


 ────────────────────────────────────────────────────────────────────────────
 GpiEndElement
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiEndElement (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiEndElement function ends an element bracket──that is, it ends the
   sequence of functions (starting with the GpiBeginElement function) that
   define the contents of an element. The GpiEndElement function may only be
   used while creating a segment.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Example

   This example uses the GpiEndElement function to end an element bracket:

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
       .
       .
       .
   GpiBeginElement(hps, 1L, "Triangle");  /* begin the element bracket  */
   GpiMove(hps, &ptlStart);               /* move to start point (0, 0) */
   GpiPolyLine(hps, 3L, ptlTriangle);     /* draw triangle              */
   GpiEndElement(hps);                    /* end element bracket        */

 See Also

   GpiBeginElement, GpiDeleteElement, GpiQueryElement,
   GpiQueryElementPointer, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiEndPath
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiEndPath (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiEndPath function ends a path bracket──that is, it ends the sequence
   of functions (starting with the GpiBeginPath function) that define the
   outline of a path.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiEndPath function to end a path bracket. When the
   path bracket is ended, a subsequent call to the GpiFillPath function draws
   and fills the path.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0 };

   GpiBeginPath(hps, 1L);                  /* start the path bracket */
   GpiMove(hps, &ptlStart);                /* move to starting point */
   GpiPolyLine(hps, 2L, ptlTriangle);      /* draw the three sides   */
   GpiCloseFigure(hps);                    /* close the triangle     */
   GpiEndPath(hps);                        /* end the path bracket   */
   GpiFillPath(hps, 1L, FPATH_ALTERNATE);  /* draw and fill the path */

 See Also

   GpiBeginPath


 ────────────────────────────────────────────────────────────────────────────
 GpiEqualRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiEqualRegion (hps, hrgn1, hrgn2)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn1;             /*handle of the first region                    */
   HRGN hrgn2;             /*handle of the second region                   */

   The GpiEqualRegion function checks two regions for equality. Regions are
   equal if the difference between the two regions is an empty region. The
   function compares the regions only if the device context containing the
   regions is associated with the given presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn1  Identifies the first region.

   hrgn2  Identifies the second region.

 Return Value

   The return value is EQRGN_NOTEQUAL or EQRGN_EQUAL if the function is
   successful, or EQRGN_ERROR if an error occurred.

 See Also

   WinEqualRect


 ────────────────────────────────────────────────────────────────────────────
 GpiErase
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiErase (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiErase function clears the display associated with the specified
   presentation space. The function clears the display by filling it with the
   color specified by the CLR_BACKGROUND color index for the presentation
   space. The function clips the output to the current clipping region,
   graphics field, and visual region (if any), but does not clip to the
   current viewing limits and clipping path. Also, the function ignores the
   the current draw controls (as set by the GpiSetDrawControl function).

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiErase function to clear the display before
   drawing:

   GpiErase(hps);                        /* clear the display */
   GpiMove(hps, &ptlStart);              /* draw a triangle   */
   GpiPolyLine(hps, 3L, ptlTriangle);

 See Also

   GpiCloseSegment, GpiSetColor, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiErrorSegmentData
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiErrorSegmentData (hps, pidSegment, plContext)
   HPS hps;                /*presentation-space handle                     */
   PLONG pidSegment;       /*pointer to segment identifier                 */
   PLONG plContext;        /*pointer to variable for error type            */

   The GpiErrorSegmentData function returns information about the last error
   that occurred while drawing a segment. The function copies the segment
   identifier and error type to the variables pointed to by pidSegment and
   plContext, then returns either a byte offset or an element pointer
   position, depending on the type of error.

 Parameters

   hps  Identifies the presentation space.

   pidSegment  Points to a variable to receive the identifier of the segment
   causing the error.

   plContext  Points to a variable to receive the error type. It can be one
   of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   GPIE_DATA         A graphics order in the buffer for the GpiPutData
                     function caused an error. The return value is the byte
                     offset from the beginning of the buffer to this graphics
                     order.

   GPIE_ELEMENT      A graphics order in the buffer for the GpiElement
                     function caused an error. The return value is the byte
                     offset from the beginning of the buffer to this graphics
                     order.

   GPIE_SEGMENT      An element in the given segment caused an error. The
                     return value is the position of the element pointer for
                     this element.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is either a byte offset or an element pointer position if
   the function is successful. Otherwise, it is GPI_ALTERROR.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiCloseSegment, GpiElement, GpiOpenSegment, GpiPutData


 ────────────────────────────────────────────────────────────────────────────
 GpiExcludeClipRectangle
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiExcludeClipRectangle (hps, prcl)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to structure for rectangle            */
                           /*coordinates                                   */

   The GpiExcludeClipRectangle function excludes a rectangle from the clip
   region. The function excludes all points in the rectangle except points on
   the top and right boundary.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to a RECTL structure containing the rectangle. The RECTL
   structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RGN_COMPLEX, RGN_NULL, or RGN_RECT if the function is
   successful or RGN_ERROR if an error occurred.

 See Also

   GpiIntersectClipRectangle, WinExcludeUpdateRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiFillPath
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiFillPath (hps, idPath, flFill)
   HPS hps;                /*presentation-space handle                     */
   LONG idPath;            /*identifier of path                            */
   LONG flFill;            /*fill mode                                     */

   The GpiFillPath function draws the interior of the path specified by
   idPath by filling it with the current fill pattern. The function first
   closes any open figures in the path, then fills the closed figures using
   the filling mode specified by flFill. Finally, the function deletes the
   path.

 Parameters

   hps  Identifies the presentation space.

   idPath  Specifies the path whose interior is to be drawn; it must equal 1.

   flFill  Specifies the fill option. It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   FPATH_ALTERNATE   Fills the path using the alternate (even/odd) rule.

   FPATH_WINDING     Fills the path using the winding rule.
   ──────────────────────────────────────────────────────────────────────────

   The default is FPATH_ALTERNATE.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful. (It
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs.) The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_PATH_ID
         PMERR_PATH_UNKNOWN

 Example

   This example uses the GpiFillPath function to draw the interior of the
   given path. The path, an isosceles triangle, is not closed when it is
   created, so the GpiFillPath function closes it before filling.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiBeginPath(hps, 1L);                  /* create a path */
   GpiMove(hps, &ptlStart);
   GpiPolyLine(hps, 3L, ptlTriangle);
   GpiEndPath(hps);

   GpiFillPath(hps, 1L, FPATH_ALTERNATE);  /* fill the path */

 See Also

   GpiBeginPath, GpiEndPath

 ────────────────────────────────────────────────────────────────────────────
 GpiFullArc
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiFullArc (hps, flFlags, fxMultiplier)
   HPS hps;                /*presentation-space handle                     */
   LONG flFlags;           /*fill and outline indicator                    */
   FIXED fxMultiplier;     /*arc-size multiplier                           */

   The GpiFullArc function creates a full arc. A full arc is a complete
   circle or ellipse, drawn by using the current arc parameters. The function
   first scales the width and height of the arc by using the multipier
   specified by the fxMultiplier parameter, then draws either the outline of
   the arc, the interior of the arc, or both, depending on the flags
   specified by the flFlags parameter.

   The function uses the current position as the center of the arc but does
   not change the current position. The function uses the arc parameters to
   determine whether to draw the full arc clockwise or counterclockwise. When
   an arc is used as part of an area or path, the direction in which the arc
   is drawn can affect how it is filled.

 Parameters

   hps  Identifies the presentation space.

   flFlags  Specifies whether to fill and/or outline the arc. It can be one
   of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   DRO_FILL          Fills the interior of the arc with the current fill
                     pattern.

   DRO_OUTLINE       Draws the outline of the arc by using the current line
                     style and color.

   DRO_OUTLINEFILL   Draws the outline and fills the arc interior.
   ──────────────────────────────────────────────────────────────────────────

   Do not use DRO_FILL or DRO_OUTLINEFILL when using GpiFullArc in an area
   bracket.

   fxMultiplier  Specifies how much to scale the width and height of the arc.
   It must be a fixed-point value in the range 1 through 255 (or in the range
   0x10000 through 0xFF0000 if expressed as 32-bit values). This means the
   function can scale the arc from 1 to 255 times the current arc-parameter
   dimensions.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_ARC_CONTROL
         PMERR_INV_MULTIPLIER

 Comments

   When correlating an arc, the system generates a hit if the arc boundary
   intersects the pick aperture. If the pick aperture is inside the arc, the
   system generates a hit only if the interior of the arc has been filled.

 Example

   This example uses GpiFullArc to draw five concentric circles. The arc
   parameters are set before drawing the arc. Only the outline is drawn for
   the arc.

   SHORT i;
   ARCPARAMS arcp = { 1, 1, 0, 0 };

   GpiSetArcParams(hps, &arcp);

   for (i = 5; i > 0; i --)
       GpiFullArc(hps,             /* presentation-space handle       */
           DRO_OUTLINE,            /* outline                         */
           MAKEFIXED(i, 0));       /* converts integer to fixed point */

 See Also

   GpiMove, GpiPointArc, GpiQueryArcParams, GpiSetArcParams,
   GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiGetData
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiGetData (hps, idSegment, off, pcmdFormat, cb, pb)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   PLONG off;              /*pointer to variable for segment offset        */
   LONG pcmdFormat;        /*conversion type                               */
   LONG cb;                /*length in bytes of the data buffer            */
   PBYTE pb;               /*pointer to buffer for data                    */

   The GpiGetData function copies graphics orders from the specified segment
   to the specified buffer. The function continues to copy the graphics
   orders from the segment to the buffer until all orders in the segment have
   been copied or the number of bytes specified by the cb parameter have been
   copied. If the function fills the buffer, the last order in the buffer may
   not be complete since the function does not stop on an order boundary when
   copying to the buffer. In any case, the function returns the number of
   bytes copied to the buffer.

   The function starts copying graphics-order data from the location
   specified by the off parameter. If this parameter is zero, the function
   copies from the beginning of the segment. After copying the data, the
   function replaces the value in off with the offset to the next byte of
   data to copy from the segment (if any). This value can be used to specify
   the next location to copy.

   The GpiGetData function cannot be used to copy data from an open segment,
   but it can be used to copy data while some other segment is open.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment identifier.

   off  Specifies the offset from the beginning of the segment to the next
   byte of graphics order data to copy. If this parameter is zero, the
   function copies from the beginning of the segment.

   pcmdFormat  Points to the variable that contains the coordinate conversion
   type. The variable can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   DFORM_NOCONV      Copies coordinates without converting. The coordinates
                     are in the format used by the presentation space.

   DFORM_PCLONG      Converts coordinates to PC-format long (4-byte)
                     integers.

   DFORM_PCSHORT     Converts coordinates to PC-format short (2-byte)
                     integers.

   DFORM_S370SHORT   Converts coordinates to S/370-format short (2-byte)
                     integers.
   ──────────────────────────────────────────────────────────────────────────

   cb  Specifies the length in bytes of the buffer to receive the graphics
   orders.

   pb  Points to the buffer that receives the graphics-order data.

 Return Value

   The return value is the number of graphics-order bytes copied if the
   function is successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_DATA_TOO_LONG
         PMERR_INV_GETDATA_CONTROL
         PMERR_INV_LENGTH
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_OFFSET
         PMERR_SEG_NOT_FOUND

 Example

   This example uses the GpiGetData function to copy data from one segment to
   another:

   LONG fFormat = DFORM_NOCONV;    /* do not convert coordinates        */
   LONG offSegment = 0L;           /* offset in segment                 */
   LONG offNextElement = 0L;       /* offset in segment to next element */
   LONG cb = 0L;                   /* bytes retrieved                   */
   BYTE abBuffer[512];

   GpiOpenSegment(hps, 3L);        /* open segment to receive the data  */
   do {
       offSegment += cb;
       offNextElement = offSegment;
       cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, abBuffer);
       /* put data in other segment */

       if (cb > 0L) GpiPutData(hps,  /* presentation-space handle        */
           fFormat,                  /* format of coordinates            */
           &cb,                      /* number of bytes in buffer        */
           abBuffer);                /* buffer with graphics-order data  */

   } while (cb > 0);
   GpiCloseSegment(hps);         /* close segment that received the data */

 See Also

   GpiPutData


 ────────────────────────────────────────────────────────────────────────────
 GpiImage
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiImage (hps, lFormat, psizl, cbData, pbData)
   HPS hps;                /*presentation-space handle                     */
   LONG lFormat;           /*image data format                             */
   PSIZEL psizl;           /*pointer to structure for image width and      */
                           /*height                                        */
   LONG cbData;            /*length in bytes of the image data             */
   PBYTE pbData;           /*pointer to image data                         */

   The GpiImage function draws an image. An image is a rectangular array of
   pels, each pel having either the current foreground or background color.
   Each image has a width and height specified by the psizl parameter. The
   width and height determines how many pels there are in the horizontal and
   vertical directions.

   GpiImage draws the image by using the image data pointed to by the pbData
   parameter to set the color of each pel in the image. Each pel is
   represented by one bit in the image data. If the bit is 1, the pel has the
   foreground color; if the bit is 0, the pel has the background color. The
   function combines each pel with the color already on the display by using
   the foreground mix mode for foreground pels and the background mix mode
   for background pels. The function places the upper-left corner of the
   image at the current position but does not change the current position.

 Parameters

   hps  Identifies the presentation space.

   lFormat  Specifies the format of the image data. This is a reserved field;
   it must be set to zero.

   psizl  Points to a SIZEL structure containing the width and height of the
   image in pels. The maximum width allowed is 2040 pixels. The SIZEL
   structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cbData  Specifies the length in bytes of the image data.

   pbData  Points to the image data. The pels must be given, row by row,
   starting at the top and running from left to right within each row.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_IMAGE_DATA_LENGTH
         PMERR_INV_IMAGE_DIMENSION
         PMERR_INV_IMAGE_FORMAT

 Comments

   The image data is an array of bytes. Each byte in the array represents
   eight pels, with the high bit representing the leftmost pel. The function
   draws the image from left to right and top to bottom. For each row of the
   image, the function continues to read bytes from the array until all pels
   in the row are set. If the image width is not a multiple of 8, any
   remaining bits in the last byte for the row are ignored. The function
   continues until all rows are set. This means the number of bytes in the
   image data (and the length specified for the data) must be equal to the
   height in pels multiplied by the width in bytes.

 Example

   This example uses GpiImage to draw an 8-by-8 image. The image data is
   specified as an array of bytes.

   SIZEL sizl = { 8, 8 };        /* image is 8 pels wide by 8 pels high */
   BYTE abImage[] = { 0x00, 0x18, 0x3c, 0x7e, 0xff,
       0xff, 0x7e, 0x3c, 0x18, 0x00 };

   GpiImage(hps, 0L, &sizl, 8L, abImage);            /* draws the image */

 See Also

   GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiIntersectClipRectangle
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiIntersectClipRectangle (hps, prcl)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to structure for rectangle            */
                           /*coordinates                                   */

   The GpiIntersectClipRectangle function sets the new clip region (in device
   coordinates) to the intersection of the current clip region and the
   specified rectangle.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to a RECTL structure. The RECTL structure has the following
   form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is
   successful, or RGN_ERROR if an error occurred.

 See Also

   GpiExcludeClipRectangle


 ────────────────────────────────────────────────────────────────────────────
 GpiLabel
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiLabel (hps, idLabel)
   HPS hps;                /*presentation-space handle                     */
   LONG idLabel;           /*label                                         */

   The GpiLabel function creates a label element. A label element is an
   element in a segment that contains nothing more than a 32-bit value. The
   function creates a label for an element in the current open segment. If no
   segment is open, no label is created.

   The GpiLabel function cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   idLabel  Specifies the label. It can be any value in the range 0x00000000
   through 0xFFFFFFFF.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Comments

   The GpiLabel function is intended to be used to uniquely identify elements
   in a segment that may be edited. Label elements are typically placed near
   elements to be edited. The label can be used with the
   GpiSetElementPointerAtLabel function to move the element pointer to the
   given element.

 Example

   This example uses the GpiLabel function to create label elements in a
   segment. If the segment is subsequently edited, the label elements can
   still be used to locate the elements near it.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 4L);          /* creates a segment */
   GpiLabel(hps, 5L);                /* creates label 5   */
   GpiLabel(hps, 10L);               /* creates label 10  */
   GpiMove(hps, &ptlStart);
   GpiCloseSegment(hps);
   GpiPolyLine(hps, 3L, ptlTriangle);

 See Also

   GpiSetElementPointerAtLabel


 ────────────────────────────────────────────────────────────────────────────
 GpiLine
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiLine (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for the end point        */

   The GpiLine function draws a straight line from the current position to
   the specified end point. The function then moves the current position to
   the end point.

   The function draws the line by using the current values of the line-color,
   line-mix, line-width, and line-type attributes. These values are set by
   using the GpiSetAttrs function.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that contains the end point of the
   line. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses GpiLine to draw an X.

   POINTL ptl[4] = { 0, 0, 100, 100, 0, 100, 100, 0 };

   GpiMove(hps, &ptl[0]);
   GpiLine(hps, &ptl[1]);
   GpiMove(hps, &ptl[2]);
   GpiLine(hps, &ptl[3]);

 See Also

   GpiMove, GpiPolyLine, GpiSetAttrs, GpiSetColor,
   GpiSetCurrentPosition, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiLoadBitmap
 ────────────────────────────────────────────────────────────────────────────
   HBITMAP GpiLoadBitmap (hps, hmod, idBitmap, lWidth, lHeight)
   HPS hps;                /*presentation-space handle                     */
   HMODULE hmod;           /*module handle                                 */
   USHORT idBitmap;        /*bitmap identifier                             */
   LONG lWidth;            /*width in pels of the bitmap                   */
   LONG lHeight;           /*height in pels of the bitmap                  */

   The GpiLoadBitmap function loads a bitmap resource from the specified
   module and uses it to create a bitmap having the specified width and
   height. The function uses the image data in the bitmap resource to
   initialize the bitmap image. If the lWidth or lHeight parameter is zero,
   the function creates a bitmap having the width or height given in the
   bitmap resource. If lWidth or lHeight is not zero, the function stretches
   or compresses the bitmap image to the specified width or height.

   The bitmap handle can be used in subsequent functions that accept bitmap
   handles. In most cases, the bitmap is set to a memory presentation space
   by using the GpiSetBitmap function then copied to the screen or a printer
   by using the GpiBitBlt function.

 Parameters

   hps  Identifies the presentation space.

   hmod  Specifies the module handle of the dynamic-link library containing
   the bitmap resource. If this parameter is NULL, the function loads the
   bitmap from the application's executable file.

   idBitmap  Specifies the identifier of the bitmap within the resource file.

   lWidth  Specifies the width in pels of the bitmap.

   lHeight  Specifies the height in pels of the bitmap.

 Return Value

   The return value is a handle to the bitmap if the function is successful
   or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_BITMAP_DIMENSION

 Example

   This example uses the GpiLoadBitmap function to create a bitmap by using
   the bitmap resource in the application's executable file. The bitmap must
   have been added to the executable file by using Resource Compiler.

   HBITMAP hbm;                     /* handle of the bitmap          */

   hbm = GpiLoadBitmap(hps,         /* presentation-space handle     */
       NULL,                        /* loads from application's file */
       1,                           /* bitmap resource #1            */
       64L,                         /* sets width to 64 pels         */
       64L);                        /* sets height to 64 pels        */

 See Also

   GpiCreateBitmap, GpiDeleteBitmap, GpiSetBitmap, GpiSetBitmapBits,
   GpiSetBitmapDimension, GpiSetBitmapId, WinGetSysBitmap


 ────────────────────────────────────────────────────────────────────────────
 GpiLoadFonts
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiLoadFonts (hab, pszModName)
   HAB hab;                /*anchor-block handle                           */
   PSZ pszModName;         /*pointer to module name                        */

   The GpiLoadFonts function loads fonts from the specified resource file.
   Once loaded, the fonts are private fonts and can be used by any thread in
   the process. Any other process can use the fonts but only if it also loads
   the font by using the GpiLoadFonts. The function loads a copy of the fonts
   once only. Any subsequent call to the function by another process for the
   same fonts simply increments the use count for the resource and gives that
   process access.

 Parameters

   hab  Identifies the anchor block.

   pszModName  Points to a null-terminated string. This string must be a
   valid MS OS/2 filename. If it does not specify a path and the filename
   extension, the function appends the default extension (.dll) and searches
   for the font resource file in the directories specified by the libpath
   command in the config.sys file.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiLoadFonts function to load all fonts from the
   font resource file helv.fon. The GpiQueryFonts function retrieves the
   number of fonts loaded.

   LONG cFonts = 0L;

   GpiLoadFonts(hab, "helv");
   cFonts = GpiQueryFonts(hps, QF_PRIVATE, NULL, &cFonts, 0L, NULL);

 See Also

   GpiCreateLogFont, GpiDeleteSetId, GpiQueryFonts, GpiUnloadFonts


 ────────────────────────────────────────────────────────────────────────────
 GpiLoadMetaFile
 ────────────────────────────────────────────────────────────────────────────
   HMF GpiLoadMetaFile (hab, pszFilename)
   HAB hab;                /*anchor-block handle                           */
   PSZ pszFilename;        /*pointer to filename of metafile               */

   The GpiLoadMetaFile function loads data from a file into a metafile. The
   function first creates the metafile, then copies the data and returns the
   metafile handle. The metafile handle can be used in subsequent calls to
   the GpiPlayMetaFile or GpiDeleteMetaFile function.

 Parameters

   hab  Identifies the anchor block.

   pszFilename  Points to a null-terminated string. This string must be a
   valid MS OS/2 filename that specifies the path and filename of the file to
   load into a metafile.

 Return Value

   The return value is a handle to the metafile if the function is successful
   or GPI_ERROR if an error occurred.

 Example

   This example uses the GpiLoadMetaFile function to load a metafile with
   data from the file sample.met. Later, the metafile is deleted by using the
   GpiDeleteMetaFile function.

   HMF hmf;

   GpiLoadMetaFile(hmf, "sample.met"); /* loads metafile from disk */
       .
       .
       .
   GpiDeleteMetaFile(hmf);             /* deletes metafile         */

 See Also

   GpiCopyMetaFile, GpiDeleteMetaFile, GpiPlayMetaFile, GpiSaveMetaFile,
   GpiSetMetaFileBits


 ────────────────────────────────────────────────────────────────────────────
 GpiMarker
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiMarker (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for marker position      */

   The GpiMarker function draws a marker, placing the center of the marker at
   the point specified by the pptl parameter. The current marker set and
   marker symbol attributes specify the marker to draw.

   The function moves the current position to the specified point.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that contains the position of the
   marker. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, and Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiMarker function to draw a marker at the point
   (10,10).

   POINTL ptl = { 10, 10 };

   GpiMarker(hps, &ptl);

 See Also

   GpiMove, GpiPolyMarker, GpiSetAttrs, GpiSetCurrentPosition,
   GpiSetMarkerBox, GpiSetMarkerSet


 ────────────────────────────────────────────────────────────────────────────
 GpiModifyPath
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiModifyPath (hps, idPath, cmdMode)
   HPS hps;                /*presentation-space handle                     */
   LONG idPath;            /*path identifier                               */
   LONG cmdMode;           /*modification options                          */

   The GpiModifyPath function modifies a path. Modifying a path affects the
   way the GpiFillPath function draws the path. For example, a modified path
   can be used to draw a wide line; that is, a line having a width specified
   by the current geometric-line width. The function modifies the path as
   specified by the cmdMode parameter.

   The GpiModifyPath can modify the path for drawing as a wide line. In this
   case, the GpiFillPath function draws a line that follows the path. The
   line has the current geometric-line width and is filled with the current
   fill pattern. Furthermore, the current line-join attribute defines how to
   draw the intersection of two lines at their end points and the current
   line-end attribute defines how to draw the end of a line, respectively.
   GpiModifyPath prevents GpiFillPath from closing open figures in the path.
   The line-end attribute applies to the start and end points of open
   figures. If a figure is closed by using the GpiCloseFigure function, the
   line-join attribute applies to the start and end points. If a line is
   joined to an arc, the line-join attribute applies to the intersection at
   the end points. If two lines intersect at any place other than their end
   points, the GpiFillPath function draws the wide line so that the
   intersection is filled despite the fill mode.

 Parameters

   hps  Identifies the presentation space.

   idPath  Specifies the identifier of the path to modify; it must be 1.

   cmdMode  Specifies how to modify the path. It can be the following value:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   MPATH_STROKE      Converts the path to a wide line. The line width is the
                     current geometric-line width set by using the
                     GpiSetLineWidthGeom function.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_PATH_ID
         PMERR_PATH_UNKNOWN

 Example

   This example uses the GpiModifyPath function to modify the given path. The
   GpiFillPath function then draws the path.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiBeginPath(hps, 1L);                       /* creates path    */
   GpiMove(hps, &ptlStart);
   GpiPolyLine(hps, 3L, ptlTriangle);
   GpiEndPath(hps);

   GpiModifyPath(hps,
                 1L,
                 MPATH_STROKE);     /* modifies path for wide line */
   GpiFillPath(hps, 1L, FPATH_ALTERNATE);   /* draws the wide line */

 See Also

   GpiBeginPath, GpiCloseFigure, GpiEndPath, GpiSetLineEnd,
   GpiSetLineJoin, GpiSetLineWidthGeom


 ────────────────────────────────────────────────────────────────────────────
 GpiMove
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiMove (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for new position         */

   The GpiMove function moves the current position to the specified point.
   When used in an area bracket, the function closes the current open figure
   (if any) and marks the start of a new figure.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure containing the position to move to. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiMove function to draw an X. The function moves
   the current position to the starting point of each leg of the character.

   POINTL ptl[4] = { 0, 0, 100, 100, 0, 100, 100, 0 };

   GpiMove(hps, &ptl[0]);    /* move to (0,0)   */
   GpiLine(hps, &ptl[1]);
   GpiMove(hps, &ptl[2]);    /* move to (0,100) */
   GpiLine(hps, &ptl[3]);

 See Also

   GpiSetCurrentPosition


 ────────────────────────────────────────────────────────────────────────────
 GpiOffsetClipRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiOffsetClipRegion (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for offset increments    */

   The GpiOffsetClipRegion function moves the clip region. The function moves
   the clip region by adding the x- and y-coordinates in the point specified
   by the pptl parameter to the region's current position. The x- and
   y-coordinates may be either positive or negative, so the region can move
   in any direction.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that contains the offset increments in
   world coordinates. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is
   successful, or RGN_ERROR if an error occurred.

 See Also

   GpiSetClipRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiOffsetElementPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiOffsetElementPointer (hps, off)
   HPS hps;                /*presentation-space handle                     */
   LONG off;               /*offset to add to element pointer              */

   The GpiOffsetElementPointer function moves the element pointer by the
   number of elements specified by the off parameter. The function starts the
   move at the current element-pointer position, and moves the element
   pointer either toward the beginning or end of the segment, depending on
   whether off is negative or positive. If off specifies more elements than
   actually exist between the current position and the beginning or end, the
   function sets the element pointer to zero or to the last element in the
   segment, depending on the direction of the move.

   The GpiOffsetElementPointer function affects the current open segment. If
   no segment is open, the function is ignored. Also, the function cannot be
   used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   off  Specifies the offset to be added to the element pointer.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Example

   This example uses the GpiOffsetElementPointer function to move to the
   element associated with a label element. Combining the
   GpiSetElementPointerAtLabel and GpiOffsetElementPointer functions is a
   convenient way to locate elements in segments that have been edited.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 4L);         /* creates a segment with labels */
   GpiLabel(hps, 5L);   GpiMove(hps, &ptlStart);
   GpiLabel(hps, 10L);  GpiPolyLine(hps, 3L, ptlTriangle);
   GpiCloseSegment(hps);
       .
       .
       .
   GpiOpenSegment(hps, 4L);
   GpiSetElementPointerAtLabel(hps, 10L) /* move to label 10         */
   GpiOffsetElementPointer(hps, 1L);     /* move to polyline element */

 See Also

   GpiSetEditMode, GpiSetElementPointer, GpiSetElementPointerAtLabel


 ────────────────────────────────────────────────────────────────────────────
 GpiOffsetRegion
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiOffsetRegion (hps, hrgn, pptl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PPOINTL pptl;           /*pointer to structure for offset increments    */

   The GpiOffsetRegion function moves a region. The function moves the region
   by adding the x- and y-coordinates in the point specified by the pptl
   parameter to the region's current position. The x- and y-coordinates may
   be either positive or negative, so the region can move in any direction.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region to move. The region must belong to the device
   context associated with the presentation space.

   pptl  Points to a POINTL structure that contains the offset increments for
   the move. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCreateRegion, GpiDestroyRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiOpenSegment
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiOpenSegment (hps, idSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */

   The GpiOpenSegment function opens the segment specified by the idSegment
   parameter. The function creates a new segment if a segment having the
   specified identifier does not already exist. Otherwise, it opens the
   segment. Once a segment is opened or created, the system stores an element
   in the segment for each subsequent primitive and attribute function, up to
   the next call to the GpiCloseSegment function. If the segment previously
   existed, the system either replaces the old elements with the new or
   inserts the new elements, depending on the segment editing mode.

   The function can create a segment when the drawing mode is set to either
   DM_RETAIN or DM_DRAWANDRETAIN but can open an existing segment only when
   the drawing mode is DM_RETAIN. (The GpiOpenSegment function can also
   create a segment when the drawing mode is DM_DRAW, but subsequent elements
   are not stored.)

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment identifier. The segment identifier must
   be a positive integer. If the identifier is unique──that is, has not been
   used before with the presentation space──the function creates a new
   segment. Zero is reserved for unnamed segments.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_DYNAMIC_SEG_ZERO_INV
         PMERR_IMAGE_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_MODE_FOR_OPEN_DYN
         PMERR_INV_MODE_FOR_REOPEN_SEG
         PMERR_PATH_INCOMPLETE

 Comments

   If the segment identifier is zero, the function creates an unnamed
   segment. An unnamed segment is like any other segment except it cannot be
   referenced by identifiers in subsequent segment functions. For example, an
   unnamed segment cannot be drawn directly since the GpiDrawSegment function
   requires a segment identifier, but the unnamed segment can be drawn if it
   is added to the picture chain. GpiOpenSegment creates a new unnamed
   segment for each call specifying the zero identifier. Any number of
   unnamed segments can be created, and the unnamed segments continue to
   exist until all segments are deleted.

   The GpiOpenSegment function assigns segment attributes to each new
   segment. The initial segment attributes are set by the
   GpiSetInitialSegmentAttrs function. If the initial attributes specify a
   dynamic segment, the segment can be created only in DM_RETAIN drawing
   mode.

   Only one segment per presentation space can be open at a time.

 Example

   This example uses the GpiOpenSegment to create a new segment. The segment
   is subsequently drawn by using the GpiDrawSegment function.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   GpiOpenSegment(hps, 1L);            /* opens the segment             */
   GpiMove(hps, &ptlStart);            /* moves to starting point (0,0) */
   GpiPolyLine(hps, 3L, ptlTriangle);  /* draws triangle                */
   GpiCloseSegment(hps);               /* closes the segment            */

   GpiDrawSegment(hps, 1L);

 See Also

   GpiCloseSegment, GpiErrorSegmentData, GpiSetInitialSegmentAttrs,
   GpiSetSegmentAttrs, GpiSetViewingTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiPaintRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPaintRegion (hps, hrgn)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */

   The GpiPaintRegion function paints the region specified by the hrgn
   parameter. The function paints a region by filling it with the current
   fill pattern, applying the current area colors and mix modes as it fills
   the region.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiPaintRegion function to fill a complex region
   consisting of three, intersecting rectangles. The region is filled with a
   red, diagonal pattern.

   HRGN hrgn;                               /* handle for region */
   RECTL arcl[3] = { 100, 100, 200, 200,    /* 1st rectangle     */
       150, 150, 250, 250,                  /* 2nd rectangle     */
       200, 200, 300, 300 };                /* 3rd rectangle     */

   hrgn = GpiCreateRegion(hps, 3L, arcl);
   GpiSetColor(hps, CLR_RED);
   GpiSetPattern(hps, PATSYM_DIAG1);
   GpiPaintRegion(hps, hrgn);

 See Also

   GpiCreateRegion, GpiSetAttrs, GpiSetColor, GpiSetPattern,
   GpiSetPatternRefPoint, GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiPartialArc
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPartialArc (hps, pptl, fxMultiplier, fxStartAngle, fxSweepAngle)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for center point         */
   FIXED fxMultiplier;     /*arc-size multiplier                           */
   FIXED fxStartAngle;     /*start angle of arc                            */
   FIXED fxSweepAngle;     /*sweep angle of arc                            */

   The GpiPartialArc function draws a partial arc. The function actually
   draws two figures: a straight line, from the current position to the start
   point of an arc; and the arc itself, with its center at the specified
   point. The function determines the start and end points of the arc by
   using the start and sweep angles specified by the fxStartAngle and
   fxSweepAngle functions.

   The GpiPartialArc function moves the current position to the end point on
   the partial arc.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that contains the center point. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   fxMultiplier  Specifies the amount to scale the width and height of the
   arc. It must be a fixed-point value in the range 1 through 255 (or in the
   range 0x10000 to 0xFF0000 if expressed as a 32-bit value). This means the
   function can scale the arc from 1 to 255 times the current arc-parameter
   dimensions.

   fxStartAngle  Specifies the start angle in degrees. It must be a positive,
   fixed-point value.

   fxSweepAngle  Specifies the sweep angle in degrees. It must be a positive,
   fixed-point value.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MULTIPLIER

 Comments

   To draw the arc, the GpiPartialArc function first constructs an imaginary
   unit circle at the specified center point. The function locates the start
   point of the arc by measuring counterclockwise from the x-axis of the
   circle by the number of degrees in the start angle. It then locates the
   end point of the arc by measuring counterclockwise from the start point by
   the number of degrees in the sweep angle. Finally, the function draws the
   arc by applying the current arc parameters and the arc-size multiplier.
   The direction in which the function draws the arc depends on the arc
   parameters. The direction may affect the way a closed figure containing an
   arc is filled.

   If the sweep angle is greater than 360 degrees, the function draws one or
   more complete circles or ellipses (depending on the original sweep-angle
   value) followed by an arc. The sweep angle of the final arc is the
   remainder after dividing the original sweep angle by 360.

 Example

   This example uses the GpiPartialArc function to draw a chord. A chord is
   an arc whose end points are connected by a straight line.

   POINTL ptl = { 100, 100 };             /* center point for arc */

   GpiSetLineType(hps, LINETYPE_INVISIBLE);
   GpiPartialArc(hps, &ptl, MAKEFIXED(50, 0), MAKEFIXED(0, 0),
       MAKEFIXED(180, 0));
   GpiSetLineType(hps, LINETYPE_SOLID);
   GpiPartialArc(hps, &ptl, MAKEFIXED(50, 0), MAKEFIXED(0, 0),
       MAKEFIXED(180, 0));

 See Also

   GpiFullArc, GpiLine, GpiMove, GpiPointArc, GpiQueryArcParams,
   GpiSetArcParams, GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition,
   GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPlayMetaFile
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPlayMetaFile (hps, hmf, cOptions, alOptions, pcSegments, cchDesc,
   pszDesc)
   HPS hps;                /*presentation-space handle                     */
   HMF hmf;                /*metafile handle                               */
   LONG cOptions;          /*number of elements in array                   */
   PLONG alOptions;        /*pointer to array of load options              */
   PLONG pcSegments;       /*pointer to count of renumbered segments       */
   LONG cchDesc;           /*number of bytes in record                     */
   PSZ pszDesc;            /*pointer to buffer for descriptive record      */

   The GpiPlayMetaFile function plays the metafile specified by the hmf
   parameter. The function plays the metafile file by converting the graphics
   data in the file to graphics operations for the given presentation space.
   The function uses the load options specified by the alOptions parameter to
   determine how to prepare the presentation space for playing the metafile.
   This may include resetting the presentation space, replacing tagged
   bitmaps and logical fonts, and replacing the logical color table.

   Since the metafile may create segments, the application must close any
   open segment before calling GpiPlayMetaFile. If the metafile creates
   segments, the function retains the segments only if the current drawing
   mode is DM_RETAIN or DM_DRAWANDRETAIN. If chained segments are retained,
   the function adds them to the end of the existing segment chain.

   The GpiPlayMetaFile function can play a metafile any number of times.

 Parameters

   hps  Identifies a presentation space.

   hmf  Identifies the metafile to play. It must have been created or loaded
   previously by using the DevOpenDC or GpiLoadMetaFile function.

   cOptions  Specifies the number of elements in the array pointed to by the
   alOptions parameter.

   alOptions  Points to the array specifying the load options. For a full
   description, see the following "Comments" section.

   pcSegments  Points to a variable for the count of renumbered segments.
   This parameter is reserved and is set to zero.

   cchDesc  Specifies the number of bytes in the buffer pointed to by the
   pszDesc parameter.

   pszDesc  Points to the buffer that receives the null-terminated string
   describing the metafile. This descriptive record is the record set by the
   DevOpenDC function for the metafile. If the buffer is smaller than the
   record, the function truncates the record.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INCOMPATIBLE_METAFILE
         PMERR_INV_LENGTH
         PMERR_INV_PLAY_METAFILE_OPTION
         PMERR_STOP_DRAW_OCCURRED

 Comments

   The GpiPlayMetaFile function uses several options to control how a
   metafile is played. The options are specified in an array passed to the
   function by using the alOptions parameter. The array has at most ten
   elements, and there are eight predefined array indexes that can be used to
   access these elements. The following list describes the purpose and
   possible values for each element:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Index             Meaning
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PMF_SEGBASE       Specifies a reserved element. It must be zero.

   PMF_LOADTYPE      Specifies the transformation to use when playing the
                     metafile. It can be one of the following:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     LT_DEFAULT        Default; same as LT_NOMODIFY.
                     LT_NOMODIFY       Use the current viewing transformation
                                       as set by the application by using the
                                       GpiSetViewingTransformMatrix function.
                                       This is the default action.
                     LT_ORIGINALVIEW   Use the viewing transformations
                                       defined in the metafile.

   PMF_RESOLVE       Specifies a reserved element. It must be RS_DEFAULT or
                     RS_NODISCARD.

   PMF_LCIDS         Specifies whether to use tagged bitmaps and logical
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
  PMF_LCIDS         Specifies whether to use tagged bitmaps and logical
                     fonts from the metafile or from the application. It can
                     be one of the following:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     LC_DEFAULT        Default; same as LC_NOLOAD.
                     LC_NOLOAD         Use the tagged bitmaps and logical
                                       fonts defined by the application. The
                                       application must define the
                                       appropriate objects and local
                                       identifiers before playing the
                                       metafile. This is the default.
                     LC_LOADDISC       Use the tagged bitmaps and logical
                                       fonts defined in the metafile. The
                                       function loads the object from the
                                       metafile and assigns a local
                                       identifier. If the local identifier is
                                       already defined by the application,
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
                                      already defined by the application,
                                       the function deletes the identifier
                                       before creating the new object.

   PMF_RESET         Specifies whether the presentation space should be reset
                     before playing the metafile, with the page units and
                     size being set as defined in the metafile. It can be one
                     of the following:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     RES_DEFAULT       Default; same as RES_NORESET.
                     RES_NORESET       Does not reset the presentation space.
                     RES_RESET         Resets the presentation space. The
                                       function resets the page units and
                                       page size to the values specified by
                                       the metafile. It then sets up default
                                       transformations, based on page units
                                       and size, as if the presentation space
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
                                      and size, as if the presentation space
                                       had just been created with these
                                       values, and modifies the device
                                       transformation (if necessary) to
                                       ensure that the physical size of the
                                       metafile picture is preserved.
                                       Finally, it resets the presentation
                                       space as if calling the GpiResetPS
                                       function with the GRES_ALL option.

   PMF_SUPPRESS      Specifies whether to continue playing the metafile after
                     resetting the presentation space. It can be one of the
                     following values:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     SUP_DEFAULT       Default; same as SUP_NOSUPPRESS.
                     SUP_NOSUPPRESS    Does not suppress the metafile.
                     SUP_SUPPRESS      Suppresses the metafile after the
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    SUP_SUPPRESS      Suppresses the metafile after the
                                       presentation space is reset as
                                       specified by the PMF_RESET option. All
                                       other options are ignored.

   PMF_COLORTABLES   Specifies whether to use logical color tables from the
                     metafile or from the application. It can be one of the
                     following:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     CTAB_DEFAULT      Default; same as CTAB_NOMODIFY.
                     CTAB_NOMODIFY     Uses the logical color table defined
                                       by the application. This is the
                                       default.
                     CTAB_REPLACE      Uses the logical color tables implied
                                       by or given in the metafile. The
                                       application's existing logical color
                                       table is overwritten.
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
                                      table is overwritten.

   PMF_COLORREALIZAB Specifies whether the logical color tables defined by
   LE                the metafile should be realizable. It can be one of the
                     following values:

                     Value             Meaning
                     ────────────────────────────────────────────────────────
                     CREA_DEFAULT      Default; same as CREA_REALIZE.
                     CREA_REALIZE      Creates realizable color tables. This
                                       is the default.
                     CREA_NOREALIZE    Does not create realizable color
                                       tables.

   PMF_PATHBASE      Specifies a reserved element. It must be zero.

   PMF_RESOLVEPATH   Specifies a reserved element. It must be RSP_DEFAULT or
                     RSP_NODISCARD.
   ──────────────────────────────────────────────────────────────────────────
   Index             Meaning
   ──────────────────────────────────────────────────────────────────────────
  ──────────────────────────────────────────────────────────────────────────


 Example

   This example uses the GpiPlayMetaFile function to play the given metafile.
   The function uses all the default actions for playing the metafile.

   HMF hmf;
   LONG cSegments;
   CHAR szBuffer[80];

   hmf = GpiLoadMetafile(hab, "sample.met");
   GpiPlayMetafile(hps, hmf, 0L, NULL, &cSegments, 80L, szBuffer);

 See Also

   DevCloseDC, DevOpenDC, GpiCreateLogColorTable, GpiCreateLogFont,
   GpiLoadMetaFile, GpiResetPS, GpiSetDrawingMode,
   GpiSetViewingTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiPointArc
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPointArc (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for points               */

   The GpiPointArc function draws an arc through three points. The function
   uses the current arc parameters to determine the shape of the arc, then
   starts the arc at the current position, draws it through the first point
   specified by pptl, and ends the arc at the second point specified by pptl.

   The GpiPointArc function moves the current position to the end point of
   the point arc.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that contains intermediate and end
   points. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiPointArc function to draw an arc through the
   three points of a triangle. The GpiPolyLine function then draws the
   triangle:

   POINTL ptlTriangle[] = { 0, 0, 100, 100, 200, 0 };

   GpiMove(hps, &ptlTriangle[0]);      /* moves to start point (0, 0) */
   GpiPointArc(hps, &ptlTriangle[1]);  /* draws the arc               */
   GpiMove(hps, &ptlTriangle[0]);      /* moves to start point (0, 0) */
   GpiPolyLine(hps, &ptlTriangle[1]);  /* draws the triangle          */

 See Also

   GpiFullArc, GpiMove, GpiQueryArcParams, GpiSetArcParams, GpiSetAttrs,
   GpiSetColor, GpiSetCurrentPosition, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPolyFillet
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPolyFillet (hps, cptl, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG cptl;              /*number of points in array                     */
   PPOINTL aptl;           /*pointer to array of structures for points     */

   The GpiPolyFillet function draws one or more fillets. The function draws
   the fillets by using the points specified by the aptl parameter. The
   function needs at least two points to draw a fillet. If exactly two points
   are specified, the function draws the fillet from the current position to
   the second point, using the first point as a control point. If more than
   two points are given, the function uses each point (except the last) as a
   control point, computing the end point of each fillet as needed. The
   function draws each fillet by using the current line-color, line-mix,
   line-width, and line-type attributes.

   The GpiPolyFillet function moves the current position to the end point of
   the last fillet.

 Parameters

   hps  Identifies the presentation space.

   cptl  Specifies the number of points.

   aptl  Points to an array of POINTL structures that contain the points. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Comments

   A fillet is a smooth curve whose path is controlled by three points: a
   start point, an end point, and a control point.

   When given two points, the GpiPolyFillet function draws a fillet by first
   constructing two imaginary straight lines, one from the current position
   to the control point (the first point) and another from the control point
   to the end point (the second point). The function then draws the curve
   from the current position to the end point. The curve is drawn so that the
   first imaginary line is tangent to the curve at the current position and
   the second imaginary line is tangent to the curve at the second point.
   Only the curve is drawn, never the imaginary lines.

   When given more than two points, the function constructs a series of
   imaginary straight lines, then draws a series of curves. The function
   draws the first curve from the current position to the midpoint of the
   second imaginary line, the second curve from the midpoint of the second
   line to the midpoint of the third, and so on until it draws the last curve
   from a midpoint to the last point specified.

   The maximum number of fillets allowed in the polyfillet depends on the
   length of coordinates, but is at least 4000.

 Example

   This example uses the GpiPolyFillet function to draw a curve with a loop.
   The four points are the four points of a rectangle. The curve is drawn
   from the lower-left corner, through the midpoint of the top edge, and back
   to the lower-right corner.

   POINTL ptlStart = { 0, 0 };
   POINTL aptl[3] = { 200, 100, 0, 100, 200, 0 };

   GpiMove(hps, &ptlStart);        /* move to the lower-left corner */
   GpiPolyFillet(hps, 3L, aptl};   /* draw the curve                */

 See Also

   GpiMove, GpiPolyFilletSharp, GpiPolyLine, GpiSetAttrs, GpiSetColor,
   GpiSetCurrentPosition, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPolyFilletSharp
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPolyFilletSharp (hps, cptl, aptl, afxSharpness)
   HPS hps;                /*presentation-space handle                     */
   LONG cptl;              /*number of points                              */
   PPOINTL aptl;           /*pointer to array of structures for points     */
   PFIXED afxSharpness;    /*pointer of array of structures for            */
                           /*sharpness values                              */

   The GpiPolyFilletSharp function creates one or more fillets. The function
   draws the fillets by using the control and end points specified by the
   aptl parameter and the fillet sharpness values specified by the
   afxSharpness parameter. The function draws the first fillet from the
   current position to the first end point, by using the first control point
   and first sharpness value to construct the path of the fillet. The second
   fillet is drawn from the first end point to the second end point using the
   second control point and sharpness values. The function continues with
   each successive point, using the last end point as the starting point for
   the next fillet, until the function draws one fillet for each control and
   end-point pair.

   For each fillet, the array pointed to by aptl contains a control and
   end-point pair. The first pair of points is the control and end points for
   the first fillet, with the control point given first. The array pointed to
   by afxSharpness contains the sharpness values for each fillet, with the
   sharpness value for the first fillet given first.

   The GpiPolyFilletSharp function moves the current position to the end
   point of the last fillet.

 Parameters

   hps  Identifies the presentation space.

   cptl  Specifies the number of points in the array pointed to by aptl. This
   must be twice the number of fillets since each fillet requires a control
   and end-point pair.

   aptl  Points to an array of POINTL structures that contain the points. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   afxSharpness  Points to an array of sharpness values giving the sharpness
   of successive fillets. Each value must be a fixed-point value. Each value
   controls the type of curve drawn for the fillet. If this value is greater
   than 1.0, the curve is a hyperbola. If the value is 1.0, the curve is a
   parabola. If the value is less than 1.0, the curve is an ellipse.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Comments

   A fillet is a smooth curve whose path is controlled by three points: a
   start point, an end point, and a control point. The smoothness of the
   fillet is controlled by a sharpness value.

   The GpiPolyFilletSharp function draws a fillet by first constructing two
   imaginary straight lines, one from the start point to the control point
   and another from the control point to the end point. The function then
   draws the fillet from the start to end point, such that the first
   imaginary line is tangent to the fillet at the current position and the
   second imaginary line is tangent to the fillet at the end point.

   GpiPolyFilletSharp uses the control point and the sharpness value to
   determine the path of the curve. The function always draws the curve
   through a fourth point. It locates the point by constructing two more
   imaginary straight lines, one from the start to end point, and another
   from the control point to the midpoint of this first line. The fourth
   point lies on the imaginary line drawn from the control point to the
   midpoint. It is placed such that the ratio of the lengths of the bottom
   and top pieces of this line is equal to the sharpness value.

   The maximum number of fillets allowed depends upon the length of
   coordinates and is not less than 2000.

 Example

   This example uses the GpiPolyFilletSharp function to draw a curve with a
   loop. The curve is drawn within a rectangle. The sharpness values are
   chosen to draw the curve close to the control points.

   POINTL ptlStart = { 0, 0 };
   POINTL aptl[4] = { 100, 100, 200, 100, 0, 100, 200, 0 };
   FIXED afx[2] = { MAKEFIXED(4, 0), MAKEFIXED(4, 0) };

   GpiMove(hps, &ptlStart);   /* move to first starting point         */
   GpiPolyFilletSharp(hps,    /* presentation-space handle            */
       4L,                    /* 4 points in the array                */
       aptl,                  /* pointer to array of points           */
       afx);                  /* pointer to array of sharpness values */

 See Also

   GpiMove, GpiPolyFillet, GpiPolyLine, GpiSetAttrs, GpiSetColor,
   GpiSetCurrentPosition, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPolyLine
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPolyLine (hps, cptl, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG cptl;              /*number of points in array                     */
   PPOINTL aptl;           /*pointer to array of structures for points     */

   The GpiPolyLine function draws one or more straight lines. The function
   draws the lines by using the points specified by the aptl parameter. The
   function needs at least one point to draw a line. If a point is specified,
   the function draws the line from the current position to the point. For
   each additional line, the function needs exactly one more point, and uses
   the end point of the last line as the starting point for the next. The
   function draws the lines by using the current values of the line-color,
   line-mix, line-width, and line-type attributes.

   The GpiPolyLine function moves the current position to the end point of
   the last line.

 Parameters

   hps  Identifies a presentation space.

   cptl  Specifies the number of points. This parameter must be greater than
   or equal to zero.

   aptl  Points to an array of POINTL structures that contains the points.
   The POINTL structure has the following form:

   typedef struct _POINTL {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiPolyLine function to draw a triangle:

   POINTL ptlTriangle[] = { 0, 0, 100, 100, 200, 0 };

   GpiMove(hps, &ptlTriangle[0]);       /* moves to start point (0, 0) */
   GpiPolyLine(hps, &ptlTriangle[1]);   /* draws the triangle          */

 See Also

   GpiLine, GpiMove, GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition,
   GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPolyMarker
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPolyMarker (hps, cptl, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG cptl;              /*number of points                              */
   PPOINTL aptl;           /*pointer to array of structures for point      */

   The GpiPolyMarker function draws a marker at each point specified by the
   aptl parameter. The function places the center of each marker at the given
   point. The current marker set and marker-symbol attributes specify the
   marker to draw.

   The function moves the current position to the point of the last marker.

 Parameters

   hps  Identifies a presentation space.

   cptl  Specifies the number of points.

   aptl  Points to an array of POINTL structures that contain the points. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiPolyMarker function to draw a series of markers.
   It then uses the GpiPolyLine function to connect to markers with lines.

   POINTL ptlStart = { 0, 0 };
   POINTL aptl[5] = { 10, 8, 20, 17, 30, 28, 40, 51, 50, 46 };

   GpiPolyMarker(hps, 5l, aptl);
   GpiMove(hps, &ptlStart);
   GpiPolyLine(hps, 5L, aptl);

 See Also

   GpiMarker, GpiMove, GpiSetAttrs, GpiSetCurrentPosition,
   GpiSetMarkerBox, GpiSetMarkerSet


 ────────────────────────────────────────────────────────────────────────────
 GpiPolySpline
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPolySpline (hps, cptl, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG cptl;              /*number of points in array                     */
   PPOINTL aptl;           /*pointer to array of structures for points     */

   The GpiPolySpline function creates one or more Bezier splines. The
   function draws the Bezier splines by using the points specified by the
   aptl parameter. The function needs at least three points to draw a spline.
   If exactly three points are specified, the function draws the spline from
   the current position to the third point, by using the first and second
   points as control points. For each additional spline, the function needs
   exactly three more points, and uses the end point of the last spline as
   the next starting point. The function draws each fillet by using the
   current line-color, line-mix, line-width, and line-type attributes.

   For each Bezier spline, the array pointed to by aptl contains two control
   points and an end point. The first triplet of points are the control and
   end points for the first spline, with the control points given first.

   The GpiPolySpline function moves the current position to the last
   specified point.

 Parameters

   hps  Identifies a presentation space.

   cptl  Specifies the number of points in the array pointed to by aptl. This
   must be three times the number of splines since each spline requires two
   control points and an end point.

   aptl  Points to an array of POINTL structures that contains the points.
   The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Comments

   A Bezier spline is a smooth curve whose path is controlled by four points:
   a start point, an end point, and two control points.

   As the GpiPolySpline function draws a spline, all points contribute to the
   direction of the path, with one point having the greatest amount of
   control. The point with the greatest control tends to pull the path toward
   it. Greatest control moves from the start point, to the first control
   point, to the second control point, and finally to the end point as the
   path progresses.

   If the function draws more than one spline, it does not automatically
   ensure continuity of the curve at the end points. If an application wants
   a smooth transition from one curve to the next, it must supply the
   appropriate end and control points.

 Example

   This example uses the GpiPolySpline function to draw a curve. The curve is
   drawn within a skewed rectangle, with the bottom corners being the start
   and end points and the top corners being the control points.

   POINTL ptlStart = { 0, 0 };
   POINTL aptl[3] = { 0, 100, 200, 150, 200, 50 };

   GpiMove(hps, &ptlStart);         /* moves to start point       */
   GpiPolySpline(hps,               /* presentation-space handle  */
       3L,                          /* 3 points in the array      */
       aptl);                       /* pointer to array of points */

 See Also

   GpiMove, GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition,
   GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiPop
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiPop (hps, cAttrs)
   HPS hps;                /*presentation-space handle                     */
   LONG cAttrs;            /*number of attributes to restore               */

   The GpiPop function restores one or more primitive attributes by popping
   the previous attribute values from the attribute stack. The system saves
   the previous value of a primitive attribute, such as color, line type, and
   fill pattern, on the attribute stack whenever an application changes an
   attribute while the attribute mode is AM_PRESERVE. The function pops the
   number of attributes specified by cAttrs from the stack in last-in,
   first-out order.

 Parameters

   hps  Identifies a presentation space.

   cAttrs  Specifies the number of attributes to restore.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_PRIMITIVE_STACK_EMPTY

 Comments

   Although GpiPop can be used in an area or path bracket, an application
   must ensure that the attribute to be restored is valid within the bracket.
   Once an attribute is on the stack, there is no way to check it for
   validity.

   The attribute stack is especially useful when you are drawing segments.
   Any attributes changed by the segment can be quickly restored by popping
   the stack. Note that a segment automatically pops the stack when it
   returns, so a call to the GpiPop function is not required.

 Example

   This example uses the GpiPop function to restore the fill pattern and
   color attribute after painting a path:

   GpiSetAttrMode(hps, AM_PRESERVE);   /* preserves attributes on stack */
       .
       .
       .
   GpiSetColor(hps, CLR_RED);          /* sets color to red             */
   GpiSetPattern(hps, PATSYM_DIAG1);   /* sets pattern to a diagonal    */
   GpiPaintRegion(hps, 3L);
   GpiPop(hps, 2L);       /* restores values of last two attributes set */

 See Also

   GpiRestorePS, GpiSavePS


 ────────────────────────────────────────────────────────────────────────────
 GpiPtInRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPtInRegion (hps, hrgn, pptl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PPOINTL pptl;           /*pointer to structure for point                */

   The GpiPtInRegion function checks whether a point lies in the region
   specified by the hrgn parameter. The function checks the region only if
   the device context containing the region is associated with the given
   presentation space.

 Parameters

   hps  Identifies a presentation space.

   hrgn  Identifies a region.

   pptl  Points to a POINTL data structure that contains the coordinates of
   the point. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is PRGN_OUTSIDE or PRGN_INSIDE if the function is
   successful, or PRGN_ERROR if an error occurs.

 See Also

   GpiRectInRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiPtVisible
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPtVisible (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for point                */

   The GpiPtVisible function checks whether a point is visible on the device
   associated with the specified presentation space. A point is visible if it
   lies within the intersection of the current graphics field, viewing limit,
   clip path, clip region, and visible region (if any).

 Parameters

   hps  Identifies a presentation space.

   pptl  Points to a POINTL data structure that contains the coordinates of
   the point. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is PVIS_VISIBLE or PVIS_INVISIBLE if the function is
   successful or PVIS_ERROR if an error occurred.

 See Also

   GpiConvert, GpiQueryPel


 ────────────────────────────────────────────────────────────────────────────
 GpiPutData
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiPutData (hps, cmdFormat, pcb, pb)
   HPS hps;                /*presentation-space handle                     */
   LONG cmdFormat;         /*coordinate type                               */
   PLONG pcb;              /*pointer to variable for length of order data  */
   PBYTE pb;               /*pointer to buffer for order data              */

   The GpiPutData function draws the graphics orders given in the buffer
   pointed to by the pb parameter. The function carries out the graphics
   operation specified by each graphics order. The buffer can contain any
   number of graphics orders as long as the buffer does not exceed 63K. The
   pcb parameter specifies the number of bytes of graphics-order data in the
   buffer. The function converts the coordinates in the graphics orders if
   the format specified by the cmdFormat parameter is not the same as the
   format used by the presentation space.

   The GpiPutData function is used typically with the GpiGetData function to
   copy graphics orders from one segment to another. For convenience, the
   last order in the buffer does not have to be complete. If the order is not
   complete, the function does not copy the order. Instead, it replaces the
   count in pcb with the count of bytes copied. This count can be used to
   locate the incomplete order in the buffer.

 Parameters

   hps  Identifies a presentation space.

   cmdFormat  Specifies the type of coordinates used in the graphics orders.
   It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   DFORM_S370SHORT   Uses S/370-format short (2-byte) integers.

   DFORM_PCSHORT     Uses PC-format short (2-byte) integers.

   DFORM_PCLONG      Uses PC-format long (4-byte) integers.
   ──────────────────────────────────────────────────────────────────────────

   pcb  Points to the count of bytes in the buffer pointed to by the pb
   parameter. After copying the data, the function replaces the count with
   the number of bytes copied.

   pb  Points to the buffer that contains the graphics-order data. It must
   not contain more than 63K of data.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_DATA_TOO_LONG
         PMERR_INV_EDIT_MODE
         PMERR_INV_ELEMENT_POINTER
         PMERR_INV_LENGTH_OR_COUNT
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_ORDER_LENGTH

 Comments

   The current drawing mode determines whether the function draws the
   graphics orders or copies them to a segment. To copy the graphics orders
   to the currently open segment, an application must set the current segment
   editing mode to SEGEM_INSERT and move the element pointer to the last
   element in the segment. The function can be used in an element bracket if
   the graphics-order data does not contain an element bracket.

 Example

   This example uses the GpiPutData function to copy graphics orders from one
   segment to another:

   LONG fFormat = DFORM_NOCONV;   /* do not convert coordinates        */
   LONG offSegment = 0L;          /* offset in segment                 */
   LONG offNextElement = 0L;      /* offset in segment to next element */
   LONG cb = 0L;                  /* bytes retrieved                   */
   BYTE abBuffer[512];

   GpiOpenSegment(hps, 3L);       /* open segment to receive the data  */
   do {
       offSegment += cb;
       offNextElement = offSegment;
       cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, abBuffer);

       /* Put data in other segment. */

       if (cb > 0L) GpiPutData(hps, /* presentation-space handle        */
           fFormat,                 /* format of coordinates            */
           &cb,                     /* number of bytes in buffer        */
           abBuffer);               /* buffer with graphics-order data  */

   } while (cb > 0L);
   GpiCloseSegment(hps);            /* close segment that received data */

 See Also

   GpiBeginElement, GpiEndElement, GpiGetData, GpiSetDrawingMode,
   GpiSetEditMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryArcParams
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryArcParams (hps, parcp)
   HPS hps;                /*presentation-space handle                     */
   PARCPARAMS parcp;       /*pointer to structure for arc parameters       */

   The GpiQueryArcParams function retrieves the current arc parameters used
   to draw arcs, circles, and ellipses. The function cannot be used in an
   open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   parcp  Points to the ARCPARAMS structure that receives the current arc
   parameters. The ARCPARAMS structure has the following form:

   typedef struct _ARCPARAMS {
       LONG lP;
       LONG lQ;
       LONG lR;
       LONG lS;
   } ARCPARAMS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiSetArcParams, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryAttrMode
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryAttrMode (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryAttrMode function retrieves the current value of the attribute
   mode, as set by the GpiSetAttrMode function.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current attribute mode if the function is
   successful or AM_ERROR if an error occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryAttrs
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryAttrs (hps, lPrimType, flAttrsMask, pbunAttrs)
   HPS hps;                /*presentation-space handle                     */
   LONG lPrimType;         /*primitive type                                */
   ULONG flAttrsMask;      /*attribute mask                                */
   PBUNDLE pbunAttrs;      /*pointer to buffer for nondefault attributes   */

   The GpiQueryAttrs function retrieves the current attributes for the
   specified primitive type. The function copies the attribute values
   specified by the flAttrsMask parameter to the buffer pointed to by the
   pbunAttrs parameter, then returns a mask that specifies which attributes
   have the default values. The function sets the bit in the mask if the
   corresponding attribute has its default value.

   The GpiQueryAttrs function cannot be used in an open segment when the
   drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   lPrimType  Specifies which primitive type to retrieve attributes for. It
   can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA         Area primitives

   PRIM_CHAR         Character primitives

   PRIM_IMAGE        Image primitives

   PRIM_LINE         Line and arc primitives

   PRIM_MARKER       Marker primitives
   ──────────────────────────────────────────────────────────────────────────

   flAttrsMask  Specifies which attributes to retrieve. The values for this
   parameter depend on the primitive type specified by the lPrimType
   parameter. This parameter can be any combination of the following values
   for a specific type:

   Type          Values
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA     ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE, ABB_BACK_MIX_MODE,
                 ABB_SET, ABB_SYMBOL, ABB_REF_POINT

   PRIM_CHAR     CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE, CBB_BACK_MIX_MODE,
                 CBB_SET, CBB_MODE, CBB_BOX, CBB_ANGLE, CBB_SHEAR,
                 CBB_DIRECTION

   PRIM_IMAGE    IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE, IBB_BACK_MIX_MODE

   PRIM_LINE     LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH, LBB_GEOM_WIDTH,
                 LBB_TYPE, LBB_END, LBB_JOIN

   PRIM_MARKER   MBB_COLOR, MBB_BACK_COLOR, MBB_MIX_MODE, MBB_BACK_MIX_MODE,
                 MBB_SET, MBB_SYMBOL, MBB_BOX
   ──────────────────────────────────────────────────────────────────────────

   If this parameter is zero, the function does not retrieve attributes but
   still returns a mask specifying the attributes with default values.

   pbunAttrs  Points to the buffer that receives the attribute values
   specified by the flAttrsMask parameter. The buffer format depends on the
   primitive type specified by the lPrimType parameter. The following
   structures can be used for the specified primitive types:

   Type                Structure
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA           AREABUNDLE

   PRIM_CHAR           CHARBUNDLE

   PRIM_IMAGE          IMAGEBUNDLE

   PRIM_LINE           LINEBUNDLE

   PRIM_MARKER         MARKERBUNDLE
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is the default mask if the function is successful or
   GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_PRIMITIVE_TYPE

 Example

   This example uses the GpiQueryAttrs function to retrieve the current
   attributes for the line primitive:

   LINEBUNDLE lbnd;
   LONG flDefMask;

   flDefMask = GpiQueryAttrs(hps,  /* presentation-space handle */
       PRIM_LINE,                  /* line primitive            */
       LBB_COLOR |                 /* line color                */
       LBB_MIX_MODE |              /* color-mix mode            */
       LBB_WIDTH |                 /* line width                */
       LBB_GEOM_WIDTH |            /* geometric-line width      */
       LBB_TYPE |                  /* line style                */
       LBB_END |                   /* line-end style            */
       LBB_JOIN,                   /* line-join style           */
       &lbnd);                     /* buffer for attributes     */

   if (flDefMask & LBB_COLOR)

       /* The line color has the default value. */

 See Also

   GpiSetAttrs, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBackColor
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryBackColor (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryBackColor function retrieves the current value of the line
   background-color attribute, as set by the GpiSetBackColor function. The
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the background color if the function is successful or
   CLR_ERROR if an error occurred.

 See Also

   GpiQueryBackMix, GpiQueryColor, GpiSetBackColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBackMix
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryBackMix (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryBackMix function retrieves the current value of the line
   background-color mix mode, as set by the GpiSetBackMix function.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the background-color mix mode if the function is
   successful or BM_ERROR if an error occurred.

 See Also

   GpiQueryBackColor, GpiQueryMix, GpiSetBackMix


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBitmapBits
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryBitmapBits (hps, lScanStart, cScan, pbBuffer, pbmi)
   HPS hps;                /*presentation-space handle                     */
   LONG lScanStart;        /*number for first scan line to retrieve        */
   LONG cScan;             /*number of scan lines to retrieve              */
   PBYTE pbBuffer;         /*pointer to buffer for bitmap image data       */
   PBITMAPINFO pbmi;       /*pointer to structure for bitmap info          */

   The GpiQueryBitmapBits function copies image data from a bitmap to the
   buffer pointed to by the pbBuffer parameter. The function copies the image
   data from the bitmap currently set for the presentation space. The
   presentation space must be associated with a memory device context.

   To copy the image data, the function needs the count of planes and
   adjacent color bits specified in the fields of the structure pointed to by
   the pbmi parameter. That is, the cPlanes and cBitCount fields must be set
   before you call the function. Also, the cbFix field must be set to 12. The
   function then copies the image data to the buffer. The buffer must have
   sufficient space to hold all the bytes of image data being copied. The
   number of bytes for the buffer is equal to the number of scan lines to
   copy, multiplied by the width of the bitmap in bytes (rounded up to the
   next multiple of 4), multiplied by the number of color planes. The width
   has to be a multiple of 4, since the function rounds the length of each
   scan line to a multiple of 4 bytes before copying. Also, the width must be
   multiplied by the number of adjacent color bits before rounding.

   After copying the image data, the GpiQueryBitmapBits function fills the
   remaining fields in the structure pointed to by pbmi. These fields are the
   width and height of the bitmap and the array of RGB color values for the
   bitmap pels. An application must make sure there is sufficient space in
   the structure to receive all elements of the array of RGB color values.
   The number of elements in the array depends on the format of the bitmap.

 Parameters

   hps  Identifies the presentation space.

   lScanStart  Specifies the number of the first scan line to copy to the
   buffer. If this parameter is zero, the function copies the first scan line
   in the bitmap.

   cScan  Specifies the number of scan lines to copy.

   pbBuffer  Points to the buffer that receives the bitmap image data. It
   must be large enough to hold all the bytes of the image data, from the
   scan line specified by the lScanStart parameter to the end of the bitmap.

   pbmi  Points to the BITMAPINFO structure that receives the bitmap
   information table. The BITMAPINFO structure has the following form:

   typedef struct _BITMAPINFO {
       ULONG  cbFix;
       USHORT cx;
       USHORT cy;
       USHORT cPlanes;
       USHORT cBitCount;
       RGB    argbColor[1];
   } BITMAPINFO;

   Depending on the format of the given bitmap, an application may need to
   allocate extra bytes for the structure to hold the additional elements for
   the argbColor field. For a full description, see Chapter 4, "Types,
   Macros, Structures."

 Return Value

   The return value is the number of scan lines retrieved if the function is
   successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_DC_TYPE
         PMERR_INV_INFO_TABLE

 Comments

   If the requested color format is not the same as the bitmap's color
   format, the function converts the bitmap image data to the requested
   format.

 Example

   This example uses the GpiQueryBitmapBits to copy the image data of a
   bitmap from a presentation space associated with a memory device context.

   BITMAPINFOHEADER bmp = { 12, 640, 350, 1, 1 };
   LONG cbBuffer, cbBitmapInfo;
   SEL selBuffer, selBitmapInfo;
   PBYTE pbBuffer;
   PBITMAPINFO pbmi;

   /*
    * Compute the size of the image-data buffer
    * and the bitmap information structure.
    */

   cbBuffer = (((bmp.cBitCount * bmp.cx) + 31) / 32)
       * 4 * bmp.cy * bmp.cPlanes;
   cbBitmapInfo = sizeof(BITMAPINFO) +
       (sizeof(RGB) * (1 << bmp.cBitCount));

   /* Allocate memory for the image data-buffer
    * and the bitmap information structure.
    */

   DosAllocSeg(cbBuffer, &selBuffer, SEG_NONSHARED);
   pbBuffer = MAKEP(selBuffer, 0);
   DosAllocSeg(cbBitmapInfo, &selBitmapInfo, SEG_NONSHARED);
   pbmi = MAKEP(selBitmapInfo, 0);
   /* Copy the image data. */

   pbmi->cbFix = 12; pbmi->cPlanes = 1; pbmi->cBitCount = 1;
   GpiQueryBitmapBits(hps, 0L, (LONG) bmp.cy, pbBuffer, pbmi);

 See Also

   GpiLoadBitmap, GpiQueryBitmapParameters, GpiSetBitmapBits


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBitmapDimension
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryBitmapDimension (hbm, psizl)
   HBITMAP hbm;            /*bitmap handle                                 */
   PSIZEL psizl;           /*pointer to structure for bitmap size info     */

   The GpiQueryBitmapDimension function retrieves the width and height of a
   bitmap, as specified by a previous call to the GpiSetBitmapDimension
   function. If the bitmap dimensions have not been set by
   GpiSetBitmapDimension, the width and height are zero.

 Parameters

   hbm  Identifies the bitmap.

   psizl  Points to the SIZEL structure that receives the width and height of
   the bitmap in 0.1 millimeter units. The SIZEL structure has the following
   form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryBitmapParameters, GpiSetBitmapDimension


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBitmapHandle
 ────────────────────────────────────────────────────────────────────────────
   HBITMAP GpiQueryBitmapHandle (hps, lcid)
   HPS hps;                /*presentation-space handle                     */
   LONG lcid;              /*local identifier                              */

   The GpiQueryBitmapHandle function retrieves the handle of the bitmap
   currently tagged with the specified local identifier. The function returns
   a null handle if a bitmap is not currently tagged with the specified local
   identifier.

 Parameters

   hps  Identifies the presentation space.

   lcid  Specifies the local identifier.

 Return Value

   The return value is a handle to the bitmap if the function is successful
   or GPI_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_BITMAP_NOT_FOUND

 See Also

   GpiSetBitmapId


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBitmapParameters
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryBitmapParameters (hbm, pbmp)
   HBITMAP hbm;            /*bitmap handle                                 */
   PBITMAPINFOHEADER pbmp; /*pointer to structure for bitmap info          */

   The GpiQueryBitmapParameters function retrieves information about the
   bitmap identified by the hbm parameter. The function copies the bitmap
   width, height, and number of color planes and adjacent color bits to the
   structure pointed to by the pbmp parameter.

 Parameters

   hbm  Identifies the bitmap.

   pbmp  Points to the BITMAPINFOHEADER structure that receives the
   information for the specified bitmap. The BITMAPINFOHEADER structure has
   the following form:

   typedef struct _BITMAPINFOHEADER {
       ULONG  cbFix;
       USHORT cx;
       USHORT cy;
       USHORT cPlanes;
       USHORT cBitCount;
   } BITMAPINFOHEADER;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCreateBitmap, GpiLoadBitmap, GpiQueryBitmapDimension


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryBoundaryData
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryBoundaryData (hps, prcl)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to structure for boundary data        */

   The GpiQueryBoundaryData function retrieves the current boundary data.
   Boundary data is the smallest rectangle in model space that encloses
   previous graphics output. The previous output includes all output since
   the application reset the boundary data by using the GpiResetBoundaryData
   function or started accumulating boundary data by using the DCTL_BOUNDARY
   option of the GpiSetDrawControl function.

   The boundary data is inclusive, meaning some output may lie on one or more
   edges of the given rectangle. If there has been no output, the boundary
   data is empty. In this case, the values for the upper-right corner in the
   given rectangle will be less than the values for the lower-left corner.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to the RECTL structure that receives the boundary data. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Example

   This example uses the GpiQueryBoundaryData function to retrieve the
   rectangle enclosing the output. The boundary data is then used to draw a
   border around the output.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[3] = { 100, 100, 200, 0, 0, 0 };
   RECTL rcl;

   GpiSetDrawControl(hps,
       DCTL_BOUNDARY, DCTL_ON);          /* accumulate boundary data   */

   GpiMove(hps, &ptlStart);              /* produce output             */
   GpiPolyLine(hps, 3L, &ptlTriangle);

   GpiQueryBoundaryData(hps, &rcl);      /* copy boundary data to rcl  */
   if (rcl.xLeft < rcl.xRight) {         /* verify output exists       */
       ptlStart.x = rcl.xLeft; ptlStart.y = rcl.yBottom;
       GpiMove(hps, &ptlStart);          /* move to lower-right corner */
       ptlStart.x = rcl.xRight; ptlStart.y = rcl.yTop;
       GpiBox(hps, DRO_OUTLINE, &ptlStart, 0L, 0L);     /* draw border */
   }

 See Also

   GpiResetBoundaryData, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharAngle
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCharAngle (hps, pgradlAngle)
   HPS hps;                /*presentation-space handle                     */
   PGRADIENTL pgradlAngle; /*pointer to structure for baseline-angle point */

   The GpiQueryCharAngle function retrieves the current value of the
   character-baseline angle. The character-baseline angle is set by the
   GpiSetCharAngle function.

   The GpiQueryCharAngle function cannot be used in an open segment when the
   drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   pgradlAngle  Points to the GRADIENTL structure that receives a point that
   specifies the end of a vector defining the baseline angle. The GRADIENTL
   structure has the following form:

   typedef struct _GRADIENTL {
       LONG x;
       LONG y;
   } GRADIENTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryAttrs, GpiQueryCharMode, GpiQueryCharShear, GpiSetCharAngle


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCharBox (hps, psizfxBox)
   HPS hps;                /*presentation-space handle                     */
   PSIZEF psizfxBox;       /*pointer to structure for character-box size   */

   The GpiQueryCharBox function retrieves the current value of the
   character-box attribute, as set by the GpiSetCharBox function. This
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   psizfxBox  Points to the SIZEF structure that receives the character-box
   size. The SIZEF structure has the following form:

   typedef struct _SIZEF {
       FIXED cx;
       FIXED cy;
   } SIZEF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryAttrs, GpiQueryCharMode, GpiQueryDefCharBox, GpiSetCharBox,
   GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharDirection
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryCharDirection (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryCharDirection function retrieves the current value of the
   character-direction attribute. This function cannot be used in an open
   segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current character-direction attribute if the
   function is successful or CHDIRN_ERROR if an error occurred.

 Comments

   Under MS OS/2 version 1.1, the only character directions available are
   CHDIRN_DEFAULT and CHDIRN_LEFTRIGHT.

 See Also

   GpiSetCharDirection, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharMode
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryCharMode (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryCharMode function retrieves the current value of the
   character-mode attribute, as set by the GpiSetCharMode function. This
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current character-mode attribute if the function
   is successful or CM_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiQueryCharAngle, GpiQueryCharShear, GpiSetCharMode,
   GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharSet
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryCharSet (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryCharSet function retrieves the character-set local identifier.
   This function cannot be used in an open segment when the drawing mode is
   set to DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the local identifier for the current character set if
   the function is successful or LCID_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetCharSet, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharShear
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCharShear (hps, pptlShear)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlShear;      /*pointer to structure for shear-vector point   */

   The GpiQueryCharShear function retrieves the value of the current
   character-shear angle. This function cannot be used in an open segment
   when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   pptlShear  Points to the POINTL structure that receives the point defining
   the character-shear vector. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryAttrs, GpiQueryCharAngle, GpiQueryCharMode, GpiSetCharShear,
   GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharStringPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCharStringPos (hps, flOptions, cchString, pchString, adx,
   aptl)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOptions;        /*option flags                                  */
   LONG cchString;         /*length of the string                          */
   PCH pchString;          /*pointer to string to examine                  */
   PLONG adx;              /*pointer to array for increment values         */
   PPOINTL aptl;           /*pointer to array of structures for points     */

   The GpiQueryCharStringPos function determines a position for each
   character in the string pointed to by the pchString parameter. Each
   position is the position of the character in world coordinates as if it
   were drawn by using the GpiCharStringPos function.

   The GpiQueryCharStringPos function copies the character positions to the
   array of structures pointed to by the aptl parameter. It uses the current
   character attributes or the array of vector increments specified by the
   adx parameter to determine the positions. The function cannot be used in
   an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   flOptions  Specifies whether to use the vector increments specified by the
   adx parameter. It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   0                 Advances the current position after each character by
                     using the width of the character. The adx parameter is
                     ignored.

   CHS_VECTOR        Advances the current position after each character by
                     using the next value in the array adx. The current
                     character direction defines the direction in which the
                     current position is advanced.
   ──────────────────────────────────────────────────────────────────────────

   cchString  Specifies the length of the string pointed to by the pchString
   parameter.

   pchString  Points to the character string to examine.

   adx  Points to an array of increment values. Each value is a 4-byte signed
   integer specifying the distance (in world coordinates) to advance the
   current position for each character. There must be one value for each
   character in the string. The first element specifies the distance for the
   first character, the second element for the second character, and so on.

   aptl  Points to the array of POINTL structures that receives the position
   (in world coordinates) of each character in the string. The POINTL
   structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryCharStringPos function to determine the
   location of each character in the string. Vector increments are not used.

   POINTL aptl[11];

   GpiQueryCharStringPos(hps,     /* presentation-space handle      */
       0L,                        /* do not use vector increments   */
       11L,                       /* 11 characters in string        */
       "This string",             /* character string               */
       NULL,                      /* no vector increments           */
       aptl);                     /* array of structures for points */

 See Also

   GpiCharStringPos, GpiQueryCharStringPosAt, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCharStringPosAt
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCharStringPosAt (hps, pptlStart, flOptions, cchString,
   pchString, adx, aptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlStart;      /*pointer to structure for starting point       */
   ULONG flOptions;        /*option flag                                   */
   LONG cchString;         /*length of the string                          */
   PCH pchString;          /*pointer to string to examine                  */
   PLONG adx;              /*pointer to array for increment values         */
   PPOINTL aptl;           /*pointer to array of structures for points     */

   The GpiQueryCharStringPosAt function determines a position for each
   character in the character string pointed to by the pchString parameter.
   The positions are determined as if the application had called the
   GpiCharStringPosAt function and are specified in world coordinates.

   The GpiQueryCharStringPosAt function copies the character positions to the
   array of structures pointed to by the aptl parameter. It uses the current
   character attributes or the array of vector increments specified by the
   adx parameter to determine the positions. The function cannot be used in
   an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   pptlStart  Points to the POINTL structure that specifies the starting
   point (in world coordinates) of the character string. The POINTL structure
   has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies whether to use the vector increments specified by the
   adx parameter. It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   0                 Advances the current position after each character by
                     using the width of the character. The adx parameter is
                     ignored.

   CHS_VECTOR        Advances the current position after each character by
                     using the next value in the array adx. The current
                     character direction defines the direction in which the
                     current position is advanced.
   ──────────────────────────────────────────────────────────────────────────

   cchString  Specifies the length (in bytes) of the string pointed to by the
   pchString parameter.

   pchString  Points to the character string to examine.

   adx  Points to an array of increment values. Each value is a 4-byte signed
   integer specifying the distance (in world coordinates) to advance the
   current position for each character. There must be one value for each
   character in the string. The first element specifies the distance for the
   first character, the second element for the second character, and so on.

   aptl  Points to the array of POINTL structures that receives the position
   (in world coordinates) of each character in the string.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryCharStringPosAt function to determine the
   location of each character in the string. Vector increments are not used.

   POINTL ptlStart = { 100, 100 };
   POINTL aptl[11];

   GpiQueryCharStringPosAt(hps,    /* presentation-space handle      */
       &ptlStart,                  /* starting point for string      */
       0L,                         /* do not use vector increments   */
       11L,                        /* 11 characters in string        */
       "This string",              /* character string               */
       NULL,                       /* no vector increments           */
       aptl);                      /* array of structures for points */

 See Also

   GpiCharStringPosAt, GpiQueryCharStringPos, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryClipBox
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryClipBox (hps, prcl)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to structure for clip box             */

   The GpiQueryClipBox function retrieves the world coordinates of the
   smallest rectangle that encloses the intersection of the current graphics
   field, viewing limit, clip path, clip region, and visible region (if any).
   If the clip box is empty, the function sets the left and right sides of
   the rectangle to equal values.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to the RECTL structure that receives the coordinates of the
   clip box. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is
   successful or RGN_ERROR if an error occurred.

 See Also

   GpiQueryClipRegion, GpiQueryGraphicsField, GpiQueryRegionBox,
   GpiQueryViewingLimits


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryClipRegion
 ────────────────────────────────────────────────────────────────────────────
   HRGN GpiQueryClipRegion (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryClipRegion function retrieves the handle of the currently
   selected clip region.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the handle of the clip region, if one is selected, or
   NULL if no clip region is selected. The return value is HRGN_ERROR if an
   error occurred.

 See Also

   GpiQueryClipBox, GpiQueryGraphicsField, GpiQueryViewingLimits,
   GpiSetClipRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryColor
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryColor (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryColor function returns the current value of the line-color
   attribute, as set by the GpiSetColor function. The function cannot be used
   in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current line-color attribute if the function is
   successful or CLR_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryColorData
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryColorData (hps, clData, alData)
   HPS hps;                /*presentation-space handle                     */
   LONG clData;            /*number of elements                            */
   PLONG alData;           /*three-element array                           */

   The GpiQueryColorData function retrieves the format flag and index-value
   range for the current logical color table. The format flag specifies
   whether the color table has the default, indexed-RGB, or RGB format. The
   index-value range specifies the first and last indexes in the table.
   (These apply to color tables having the default or indexed RGB formats.)

   The function typically copies the format flags and the first and last
   index values to the array pointed to by the alData parameter; however, the
   function uses the clData parameter to determine the number of values to
   copy. The clData parameter must be set to 3 in order to copy all values.

 Parameters

   hps  Identifies the presentation space.

   clData  Specifies the number of values to copy to the array pointed to by
   the alData parameter.

   alData  Points to the array that receives the format flag and index-value
   range. The elements of the array have the following meanings:

   Element index           Meaning
   ──────────────────────────────────────────────────────────────────────────
   QCD_LCT_FORMAT          Specifies the format of color table. It is
                           LCOLF_DEFAULT if the current color table is the
                           default color table; LCOLF_INDRGB if the color
                           table translates indices to RGB color values; or
                           LCOLF_RGB if the color-table indices and RGB color
                           values are equal.

   QCD_LCT_LOINDEX         Specifies the smallest color index. For the
                           default color table, the smallest index is zero.

   QCD_LCT_HIINDEX         Specifies the largest color index. For the default
                           color table, the largest index is one less than
                           the maximum number of entries in the table.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryColorData function to retrieve the smallest
   color-table index. The GpiQueryLogColorTable function is then used to
   retrieve the RGB color value for this index.

   LONG alData[3];
   LONG alColor[1];

   GpiQueryColorData(hps, 3L, alData);
   GpiQueryLogColorTable(hps, 0L, alData[QCD_LCT_LOINDEX], 1L, alColor);

 See Also

   GpiQueryLogColorTable, GpiQueryNearestColor, GpiQueryRealColors,
   GpiQueryRGBColor

 ────────────────────────────────────────────────────────────────────────────
 GpiQueryColorIndex
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryColorIndex (hps, flClrType, lRgbColor)
   HPS hps;                /*presentation-space handle                     */
   ULONG flClrType;        /*color type                                    */
   LONG lRgbColor;         /*RGB color value                               */

   The GpiQueryColorIndex function returns a color index for the specified
   RGB color value. The function maps the RGB color value to the closest
   match in the physical palette for the device associated with the
   presentation space. It then returns the index in the current logical color
   table that corresponds to this physical-palette color.

   If the current logical color table is realizable but has not been
   realized, the LCOLOPT_REALIZED option maps the RGB color value as if the
   logical color table has been realized. Since realizing a logical color
   table affects the contents of the physical palette, the color index value
   returned with this option may be different than the value returned without
   the option.

 Parameters

   hps  Identifies the presentation space.

   flClrType  Specifies whether the color index is based on realized colors.
   If it is LCOLOPT_REALIZED, the function returns a color index based on the
   colors in the physical palette after the current logical color table is
   realized. If the parameter is zero, the function returns a color index
   based on the colors in the current physical palette.

   lRgbColor  Specifies the RGB color value.

 Return Value

   The return value is a color index that is the closest possible match of
   the specified color if the function is successful, or QLCT_ERROR if an
   error occurred.

 See Also

   GpiQueryLogColorTable, GpiQueryRGBColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCp
 ────────────────────────────────────────────────────────────────────────────
   USHORT GpiQueryCp (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryCp function returns the identifier of the current graphics
   code page, as set by the GpiSetCp function. The system uses the current
   graphics code-page identifier as the default code-page identifier when the
   GpiCreateLogFont function selects fonts.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the currently selected graphics code-page identifier
   if the function is successful, or GPI_ERROR if an error occurred.

 See Also

   GpiCreateLogFont, GpiQueryFontMetrics, GpiSetCp


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryCurrentPosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryCurrentPosition (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for current position     */

   The GpiQueryCurrentPosition function returns the value of the current
   position. The function cannot be used in an open segment when the drawing
   mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure that receives the current position. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiMove, GpiSetCurrentPosition


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDefaultViewMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryDefaultViewMatrix (hps, cElements, pmatlf)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure for transformation       */
                           /*matrix                                        */

   The GpiQueryDefaultViewMatrix function retrieves the current default
   viewing transformation.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements in the transformation to
   retrieve. It must be an integer in the range 0 through 9.

   pmatlf  Points to a MATRIXLF structure that receives the elements of the
   default viewing transformation matrix. The MATRIXLF structure has the
   following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiSetDefaultViewMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDefCharBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryDefCharBox (hps, psizl)
   HPS hps;                /*presentation-space handle                     */
   PSIZEL psizl;           /*pointer to structure for character-box size   */

   The GpiQueryDefCharBox function retrieves the size of the default
   graphics-character box in world coordinates.

 Parameters

   hps  Identifies the presentation space.

   psizl  Points to a SIZEL structure that receives the default character-box
   size. The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryCharBox


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDevice
 ────────────────────────────────────────────────────────────────────────────
   HDC GpiQueryDevice (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryDevice function retrieves a device-context handle for the
   currently associated presentation space.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is a handle to a device context if the function is
   successful or NULL if no device context is currently associated with the
   presentation space. The return value is HDC_ERROR if an error occurred.

 Example

   This example uses the GpiQueryDevice function to retrieve a device-context
   handle for the presentation space of the desktop window. The handle is
   used in the DevQueryCaps function to determine the width and height of the
   Presentation Manager screen.

   HPS hps;
   HDC hdc;
   LONG lWidth, lHeight;
   hps = WinGetScreenPS(HWND_DESKTOP);
   hdc = GpiQueryDevice(hps);
   DevQueryCaps(hdc, CAPS_WIDTH, 1L, &lWidth);
   DevQueryCaps(hdc, CAPS_HEIGHT, 1L, &lHeight);

 See Also

   DevOpenDC, GpiAssociate, WinQueryWindowDC


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDeviceBitmapFormats
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryDeviceBitmapFormats (hps, clData, alData)
   HPS hps;                /*presentation-space handle                     */
   LONG clData;            /*number of elements                            */
   PLONG alData;           /*array of elements                             */

   The GpiQueryDeviceBitmapFormats function retrieves the bitmap formats for
   the raster or memory device associated with the given presentation space.
   The function copies the formats to the array pointed to by the alData
   parameter. A bitmap format consists of two 32-bit values, the first
   specifying the number of color planes, and the second specifying the
   number of color bits per pel. The first format copied to the array is the
   format that most closely matches the device.

   The GpiQueryDeviceBitmapFormats function uses the clData parameter to
   determine how many formats to return. Since each format fills two elements
   in the array, the clData must be a multiple of 2. Although there are
   several standard bitmap formats, most devices use just a few. If clData
   specifies more formats than the device supports, the functions fills the
   extra elements with zero. The DevQueryCaps function can be used to
   retrieve the actual number of bitmap formats for the device.

 Parameters

   hps  Identifies the presentation space.

   clData  Specifies the number of elements to copy to the array. Since each
   bitmap format fills two elements, this parameter must be a multiple of 2.

   alData  Points to the array to receive the bitmap formats.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryDeviceBitmapFormats function to retrieve a
   bitmap format for the given device. The format is then used to create a
   bitmap that is compatible with the device.

   LONG alFormats[2];
   BITMAPINFOHEADER bmp;
   HBITMAP hbm;

   /* Retrieve the format that most closely matches the device. */

   GpiQueryDeviceBitmapFormats(hps, 2L, alFormats);

   /* Set the bitmap dimensions and format and create the bitmap. */

   bmp.cbFix = 12;
   bmp.cx = 100;
   bmp.cy = 100;
   bmp.cPlanes = alFormats[0];
   bmp.cBitCount = alFormats[1];
   hbm = GpiCreateBitmap(hps, &bmp, 0L, NULL, NULL);

 See Also

   DevQueryCaps, GpiBitBlt, GpiCreateBitmap, GpiLoadBitmap


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDrawControl
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryDrawControl (hps, flDraw)
   HPS hps;                /*presentation-space handle                     */
   LONG flDraw;            /*drawing-control flag                          */

   The GpiQueryDrawControl function checks the state of the drawing control
   specified by flDraw. The function returns DCTL_ON or DCTL_OFF to specify
   whether the control is on or off.

 Parameters

   hps  Identifies the presentation space.

   flDraw  Specifies the drawing control to check. It can be one of the
   following values:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   DCTL_BOUNDARY         Accumulates boundary data.

   DCTL_CORRELATE        Correlates output with pick aperture.

   DCTL_DISPLAY          Allows drawing to occur on the output medium.

   DCTL_DYNAMIC          Draws dynamic segments.

   DCTL_ERASE            Erases before drawing.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is DCTL_ON or DCTL_OFF if the function is successful, or
   a negative number if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_DRAW_CONTROL
         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiDrawDynamics, GpiRemoveDynamics, GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryDrawingMode
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryDrawingMode (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryDrawingMode function returns the drawing mode, as set by
   GpiSetDrawingMode.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current drawing mode if the function is
   successful, or DM_ERROR if an error occurred.

 See Also

   GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryEditMode
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryEditMode (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryEditMode function returns the current editing mode.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is SEGEM_INSERT or SEGEM_REPLACE if the function is
   successful, or SEGEM_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiQueryElementPointer, GpiQueryElementType, GpiSetEditMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryElement
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryElement (hps, off, cbMax, pb)
   HPS hps;                /*presentation-space handle                     */
   LONG off;               /*offset to first byte to copy                  */
   LONG cbMax;             /*size of the buffer                            */
   PBYTE pb;               /*pointer to buffer for graphics-order data     */

   The GpiQueryElement function retrieves the graphics-order data for an
   element in the currently open segment. The element pointer must point to
   the element to retrieve. The function copies the data to the buffer
   pointed to by the pb parameter, copying all bytes in the current element
   or the number of bytes specified by cbMax, whichever is smaller. If off is
   not zero, the function uses this parameter as an offset from the beginning
   of the element to the first byte to copy to the buffer.

   The function can be used only in an open segment and only when the drawing
   mode is DM_RETAIN. It cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   off  Specifies the offset from the beginning of the segment to the first
   byte of graphics-order data for the element.

   cbMax  Specifies the size in bytes of the pb buffer.

   pb  Points to a buffer that receives the graphics-order data for the
   element.

 Return Value

   The return value specifies the number of bytes returned if the function is
   successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_LENGTH
         PMERR_INV_MICROPS_FUNCTION
         PMERR_NO_CURRENT_ELEMENT
         PMERR_NOT_IN_RETAIN_MODE

 Example

   This example uses the GpiQueryElement function to retrieve the
   graphics-order data for an element.

   BYTE abElement[512];

   /* Move pointer to first element in segment. */

   GpiSetElementPointer(hps, 1L);
   GpiQueryElement(hps,         /* presentation space               */
       0L,                      /* start with first byte in element */
       512L,                    /* copy no more than 512 bytes      */
       abElement);              /* buffer to receive data           */

 See Also

   GpiBeginElement, GpiDeleteElement, GpiEndElement,
   GpiQueryElementPointer, GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryElementPointer
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryElementPointer (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryElementPointer function retrieves the current element pointer.
   The function can be used only in an open segment and only when the drawing
   mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current element pointer if the function is
   successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_NOT_IN_RETAIN_MODE

 See Also

   GpiBeginElement, GpiDeleteElement, GpiEndElement, GpiQueryElement,
   GpiSetElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryElementType
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryElementType (hps, plType, cbDesc, pszDesc)
   HPS hps;                /*presentation-space handle                     */
   PLONG plType;           /*pointer to variable for type                  */
   LONG cbDesc;            /*length in bytes of buffer                     */
   PSZ pszDesc;            /*pointer to buffer for description             */

   The GpiQueryElementType function retrieves the type and description for an
   element in current open segment. It also returns the size in bytes of the
   element. The element pointer must point to the element to retrieve. The
   function copies the type to the variable pointed to by the plType
   parameter, and copies the description, up to the number of bytes specified
   by cbDesc, to the buffer pointed to by the pszDesc parameter.

   The function can be used only in an open segment and only when the drawing
   mode is DM_RETAIN. It cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   plType  Points to the variable that receives the element type.

   cbDesc  Specifies the maximum number of bytes of description to copy to
   the buffer specified by the pszDesc parameter.

   pszDesc  Points to the buffer that receives the description, a
   null-terminated string, for the element. The buffer must have the number
   of bytes specified by cbDesc. If the description is longer than the
   buffer, it is truncated.

 Return Value

   The return value is the size of the data required to hold the element if
   the function is successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_LENGTH
         PMERR_INV_MICROPS_FUNCTION
         PMERR_NO_CURRENT_ELEMENT
         PMERR_NOT_IN_RETAIN_MODE

 Example

   This example uses the GpiQueryElementType function to retrieve the size of
   the current element. The size is used to retrieve the graphics-order data
   in the element.

   BYTE abElement[512];
   LONG cbElement;
   LONG lType;

   /* move pointer to first element in segment */

   GpiSetElementPointer(hps, 1L);
   cbElement = GpiQueryElementType(
       hps,      /* presentation space             */
       &lType,   /* variable to receive type       */
       0L,       /* copy zero bytes of description */
       NULL);    /* no buffer for description      */

   GpiQueryElement(hps, 0L, cbElement, abElement);

 See Also

   GpiBeginElement, GpiElement, GpiQueryElement, GpiQueryElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryFontFileDescriptions
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryFontFileDescriptions (hab, pszFileName, pcFonts, pffdescs)
   HAB hab;                /*anchor-block handle                           */
   PSZ pszFileName;        /*pointer to the font-resource filename         */
   PLONG pcFonts;          /*pointer to variable with number of fonts      */
   PFFDESCS pffdescs;      /*array of names                                */

   The GpiQueryFontFileDescriptions function retrieves the typeface family
   and names contained in the specified file if the file is a font-resource
   file. The function copies the names to the array pointed to by the
   pffdescs parameter. Each name is a null-terminated string up to 32
   characters long. The function copies all names in the file up to the
   number of names specified by the pcFonts parameter.

 Parameters

   hab  Identifies the anchor block.

   pszFileName  Points to a null-terminated string. This string must be a
   valid MS OS/2 filename. If it does not specify a path and the .fon
   filename extension, the function appends the default extension (.dll) and
   looks for the font-resource file in the directories specified by the
   libpath command in the config.sys file.

   pcFonts  Points to a variable specifying the maximum number of typeface
   family and name pairs to retrieve. The function copies the actual number
   of descriptions it retrieved to this variable.

   pffdescs  Points to the array to receive the typeface family and names for
   each font. Each array element is itself a two-element array of type
   FFDESCS.

 Return Value

   The return value is the number of fonts for which details were not
   returned if the function is successful, or GPI_ALTERROR if an error
   occurred.

 Example

   This example uses the GpiQueryFontFileDescriptions to retrieve the
   typeface family and names for the fonts in the helv.fon file. The function
   is called twice, once to determine the actual number of fonts in the file,
   and again to retrieve the descriptions.

   PFFDESCS pffdescs;
   SEL sel;
   LONG cFonts;

   /* Retrieve a count of all fonts in the file. */

   cFonts = GpiQueryFontFileDescriptions(hab, "helv", &cFonts, NULL);

   /* Allocate space for the descriptions. */

   DosAllocSeg((USHORT) (cFonts * sizeof(FFDESCS)), &sel, SEG_NONSHARED);
   pffdescs = MAKEP(sel, 0);

   /* Retrieve the descriptions. */

   GpiQueryFontFileDescriptions(hab, "helv", &cFonts, pffdescs);

 See Also

   GpiQueryFonts


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryFontMetrics
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryFontMetrics (hps, cbMetrics, pfm)
   HPS hps;                /*presentation-space handle                     */
   LONG cbMetrics;         /*length of the structure                       */
   PFONTMETRICS pfm;       /*pointer to structure for font metrics         */

   The GpiQueryFontMetrics function retrieves the font metrics for the
   currently selected logical font. The font metrics describe the typeface
   family, name, maximum height, average width, and other information about
   the font. All sizes the function retrieves are in world coordinates.

 Parameters

   hps  Identifies the presentation space.

   cbMetrics  Specifies the length of the font metrics.

   pfm  Points to a FONTMETRICS structure that receives font metrics for the
   logical font. This FONTMETRICS structure has the following form:

   typedef struct _FONTMETRICS {
       CHAR    szFamilyname[FACESIZE];
       CHAR    szFacename[FACESIZE];
       SHORT   idRegistry;
       SHORT   usCodePage;
       LONG    lEmHeight;
       LONG    lXHeight;
       LONG    lMaxAscender;
       LONG    lMaxDescender;
       LONG    lLowerCaseAscent;
       LONG    lLowerCaseDescent;
       LONG    lInternalLeading;
       LONG    lExternalLeading;
       LONG    lAveCharWidth;
       LONG    lMaxCharInc;
       LONG    lEmInc;
       LONG    lMaxBaselineExt;
       SHORT   sCharSlope;
       SHORT   sInlineDir;
       SHORT   sCharRot;
       USHORT  usWeightClass;
       USHORT  usWidthClass;
       SHORT   sXDeviceRes;
       SHORT   sYDeviceRes;
       SHORT   sFirstChar;
       SHORT   sLastChar;
       SHORT   sDefaultChar;
       SHORT   sBreakChar;
       SHORT   sNominalPointSize;
       SHORT   sMinimumPointSize;
       SHORT   sMaximumPointSize;
       USHORT  fsType;
       USHORT  fsDefn;
       USHORT  fsSelection;
       USHORT  fsCapabilities;
       LONG    lSubscriptXSize;
       LONG    lSubscriptYSize;
       LONG    lSubscriptXOffset;
       LONG    lSubscriptYOffset;
       LONG    lSuperscriptXSize;
       LONG    lSuperscriptYSize;
       LONG    lSuperscriptXOffset;
       LONG    lSuperscriptYOffset;
       LONG    lUnderscoreSize;
       LONG    lUnderscorePosition;
       LONG    lStrikeoutSize;
       LONG    lStrikeoutPosition;
       SHORT   sKerningPairs;
       SHORT   sReserved;
       LONG    lMatch;
   } FONTMETRICS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ALTERROR
   if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_LENGTH

 Example

   This example uses the GpiQueryFontMetrics function to retrieve the font
   metrics for the current font.

   FONTMETRICS fm;

   GpiQueryFontMetrics(hps, sizeof(FONTMETRICS), &fm);

 See Also

   GpiQueryCp, GpiQueryFonts, GpiQueryKerningPairs


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryFonts
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryFonts (hps, flOptions, pszFacename, pcFonts, cbMetrics, pfm)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOptions;        /*type of fonts to retrieve                     */
   PSZ pszFacename;        /*pointer to typeface name of the fonts         */
   PLONG pcFonts;          /*number of fonts to retrieve                   */
   LONG cbMetrics;         /*length of the structure                       */
   PFONTMETRICS pfm;       /*pointer to structure(s) for font metrics      */

   The GpiQueryFonts function retrieves the font metrics for loaded fonts.
   The function copies the font metrics for the fonts that have the typeface
   name specified by the pszFacename parameter to the structure or array of
   structures pointed to by the pfm parameter. The function retrieves font
   metrics for all fonts up to the number specified by the pcFonts
   parameters. If the function does not retrieve font metrics for all the
   fonts, it returns the number of remaining fonts.

   All sizes retrieved by the function are in world coordinates.

 Parameters

   hps  Identifies the presentation space.

   flOptions  Specifies the type of fonts to retrieve. It can be a
   combination of the following values:

   Value         Meaning
   ──────────────────────────────────────────────────────────────────────────
   QF_PUBLIC     Retrieve public fonts. Public fonts were loaded by the
                 system and are available to all applications.

   QF_PRIVATE    Retrieve private fonts. Private fonts were loaded by the
                 application and are available only to it.
   ──────────────────────────────────────────────────────────────────────────

   pszFacename  Points to the typeface name of the fonts. If the pszFacename
   parameter is a NULL pointer, the function retrieves metrics for all
   available fonts regardless of their typeface names.

   pcFonts  Points to a variable containing the number of fonts for which to
   retrieve metrics. The function copies to this variable the actual number
   of fonts it retrieved.

   cbMetrics  Specifies the length of one FONTMETRICS structure.

   pfm  Points to one or more FONTMETRICS structures that receive the metrics
   of the fonts. The number of structure required is specified by the pcFonts
   parameter. This FONTMETRICS structure has the following form:

   typedef struct _FONTMETRICS {
       CHAR    szFamilyname[FACESIZE];
       CHAR    szFacename[FACESIZE];
       USHORT  idRegistry;
       USHORT  usCodePage;
       LONG    lEmHeight;
       LONG    lXHeight;
       LONG    lMaxAscender;
       LONG    lMaxDescender;
       LONG    lLowerCaseAscent;
       LONG    lLowerCaseDescent;
       LONG    lInternalLeading;
       LONG    lExternalLeading;
       LONG    lAveCharWidth;
       LONG    lMaxCharInc;
       LONG    lEmInc;
       LONG    lMaxBaselineExt;
       SHORT   sCharSlope;
       SHORT   sInlineDir;
       SHORT   sCharRot;
       USHORT  usWeightClass;
       USHORT  usWidthClass;
       SHORT   sXDeviceRes;
       SHORT   sYDeviceRes;
       SHORT   sFirstChar;
       SHORT   sLastChar;
       SHORT   sDefaultChar;
       SHORT   sBreakChar;
       SHORT   sNominalPointSize;
       SHORT   sMinimumPointSize;
       SHORT   sMaximumPointSize;
       USHORT  fsType;
       USHORT  fsDefn;
       USHORT  fsSelection;
       USHORT  fsCapabilities;
       LONG    lSubscriptXSize;
       LONG    lSubscriptYSize;
       LONG    lSubscriptXOffset;
       LONG    lSubscriptYOffset;
       LONG    lSuperscriptXSize;
       LONG    lSuperscriptYSize;
       LONG    lSuperscriptXOffset;
       LONG    lSuperscriptYOffset;
       LONG    lUnderscoreSize;
       LONG    lUnderscorePosition;
       LONG    lStrikeoutSize;
       LONG    lStrikeoutPosition;
       SHORT   sKerningPairs;
       SHORT   sReserved;
       LONG    lMatch;
   } FONTMETRICS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is the number of fonts not returned if the function is
   successful, or GPI_ALTERROR if an error occurred.

 Example

   This example uses the GpiQueryFonts function to retrieve the font metrics
   for all private fonts having the "Helv" typeface name. The function is
   called twice, once to determine the number of fonts available, again to
   retrieve the font metrics for all the fonts.

   LONG cFonts, lTemp = 0L;
   SEL sel;
   PFONTMETRICS pfm;

   /* Determine the number of fonts. */

   cFonts = GpiQueryFonts(hps, QF_PRIVATE, "Helv", &lTemp,
       (ULONG) sizeof(FONTMETRICS), NULL);

   /* Allocate space for the font metrics. */

   DosAllocSeg((USHORT) (sizeof(FONTMETRICS) * cFonts),
       &sel, SEG_NONSHARED);
   pfm = MAKEP(sel, 0);

   /* Retrieve the font metrics. */

   cFonts = GpiQueryFonts(hps, QF_PRIVATE, "Helv", &cFonts,
       (ULONG) sizeof(FONTMETRICS), pfm);

 See Also

   GpiCreateLogFont, GpiQueryFontMetrics


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryGraphicsField
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryGraphicsField (hps, prclField)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclField;       /*pointer to structure for the graphics field   */

   The GpiQueryGraphicsField function retrieves the coordinates, in
   presentation-page units, of the graphics field. The function copies the
   coordinates of the lower-left and upper-right corners of the field to the
   structure pointed to by the prclField parameter.

 Parameters

   hps  Identifies the presentation space.

   prclField  Points to the RECTL structure that receives the graphics field.
   This RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryClipBox, GpiQueryClipRegion, GpiQueryGraphicsField,
   GpiQueryViewingLimits, GpiSetGraphicsField


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryInitialSegmentAttrs
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryInitialSegmentAttrs (hps, lAttribute)
   HPS hps;                /*presentation-space handle                     */
   LONG lAttribute;        /*attribute                                     */

   The GpiQueryDrawControl function checks whether the initial segment attri-
   bute specified by lAttribute is enabled. The function returns ATTR_ON or
   ATTR_OFF to specify whether the given attribute is enabled or disabled.

 Parameters

   hps  Identifies the presentation space.

   lAttribute  Specifies the attributes to check. It can be one of the
   following values:

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   ATTR_CHAINED            Chained

   ATTR_DETECTABLE         Detectability

   ATTR_DYNAMIC            Dynamic

   ATTR_FASTCHAIN          Fast chaining

   ATTR_PROP_DETECTABLE    Propagate detectability

   ATTR_PROP_VISIBLE       Propagate visibility

   ATTR_VISIBLE            Visibility
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is ATTR_ON or ATTR_OFF if the function is successful, or
   ATTR_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetInitialSegmentAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryKerningPairs
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryKerningPairs (hps, ckrnpr, akrnpr)
   HPS hps;                /*presentation-space handle                     */
   LONG ckrnpr;            /*number of kerning pairs                       */
   PKERNINGPAIRS akrnpr;   /*pointer to array of kerning-pair structures   */

   The GpiQueryKerningPairs function retrieves kerning-pair information for
   the current font for the presentation space. The kerning-pair information
   specifies the characters to be kerned and the amount of space in world
   coordinates to kern. The number of kerned pairs for a given font is
   specified in the font metrics for that font.

 Parameters

   hps  Identifies the presentation space.

   ckrnpr  Specifies the number of kerning pairs to retrieve.

   akrnpr  Points to the array of KERNINGPAIRS structures that receives the
   kerning-pair information. The array must have the number of elements
   specified by the ckrnpr parameter. The KERNINGPAIRS structure has the
   following form:

   typedef struct _KERNINGPAIRS {
       SHORT sFirstChar;
       SHORT sSecondChar;
       SHORT sKerningAmount;
   } KERNINGPAIRS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryKerningPairs function to retrieve the
   kerning information for the current font.

   FONTMETRICS fm;
   SEL sel;
   PKERNINGPAIRS akrnpr;

   GpiQueryFontMetrics(hps, (LONG) sizeof(FONTMETRICS), &fm);
   DosAllocSeg(fm.sKerningPairs * sizeof(KERNINGPAIRS), &sel,
       SEG_NONSHARED);
   akrnpr = MAKEP(sel, 0);
   GpiQueryKerningPairs(hps, (LONG) fm.sKerningPairs, akrnpr);

 See Also

   GpiQueryFontMetrics


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLineEnd
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryLineEnd (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryLineEnd function returns the current line-end attribute. The
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current line-end attribute if the function is
   successful, or LINEEND_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetLineEnd


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLineJoin
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryLineJoin (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryLineJoin function returns the current line-join attribute. The
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current line-join attribute if the function is
   successful, or LINEJOIN_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetLineJoin


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLineType
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryLineType (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryLineType function returns the current cosmetic line-type
   attribute, as set by the GpiSetLineType function. The function cannot be
   used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current cosmetic line-type attribute if the
   function is successful, or LINETYPE_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetLineType


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLineWidth
 ────────────────────────────────────────────────────────────────────────────
   FIXED GpiQueryLineWidth (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryLineWidth function returns the current value of the cosmetic
   line-width attribute, as set by the GpiSetLineWidth function. The function
   cannot be used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current value of the cosmetic line-width attribute
   if the function is successful, or LINEWIDTH_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetLineWidth


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLineWidthGeom
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryLineWidthGeom (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryLineWidthGeom function returns the current geometric
   line-width attribute. The function cannot be used in an open segment when
   the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current geometric line-width attribute if the
   function is successful, or LINEWIDTHGEOM_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetLineWidthGeom


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryLogColorTable
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryLogColorTable (hps, flOptions, iStart, clTable, alTable)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOptions;        /*color type to retrieve                        */
   LONG iStart;            /*starting index                                */
   LONG clTable;           /*maximum number of values to copy              */
   PLONG alTable;          /*pointer to array for elements                 */

   The GpiQueryLogColorTable function retrieves the current
   logical-color-table entries. This function copies the RGB color values
   from the current logical color table to the array pointed to by alTable.
   It may also copy the color-table index values for each RGB color value,
   depending on the value of flOptions.

   GpiQueryLogColorTable uses iStart as the index of the first color table
   entry to copy. It continues to copy subsequent entries until it reaches
   the end of the table or it has copied the number of values specified by
   clTable. If a logical color-table entry has no corresponding RGB color
   value, the function either copies -1 to the array or skips the entry,
   depending on the value of flOptions. It skips the entry only if it is
   copying both the color-table index and the RGB value to the array.

 Parameters

   hps  Identifies the presentation space.

   flOptions  Specifies whether to retrieve indexes and RGB color values or
   just RGB values. If flOptions is LCOLOPT_INDEX, the function retrieves
   indexes and RGB color values. If it is 0x0000, the function retrieves RGB
   color values only.

   iStart  Specifies the color-table index for the first entry to copy. The
   function copies this entry and all subsequent entries up to the number of
   values specified by clTable or the end of the logical color table.

   clTable  Specifies the maximum number of values to copy to the array
   pointed to by alTable. If flOptions is 0x0000, this parameter specifies
   the number of RGB color values to retrieve. If flOptions is LCOLOPT_INDEX,
   this parameter specifies the combined total of index and RGB values to
   retrieve and must be an even value.

   alTable  Points to the array to receive the color-table entries. If
   flOptions is equal to 0x0000, each element in the array receives an RGB
   color value. If flOptions is LCOLOPT_INDEX, each pair of array elements
   receives an index and a corresponding RGB value, with the first element in
   the pair receiving the index.

 Return Value

   The return value is the number of values copied to the array if the
   function is successful. The return value is QLCT_ERROR if an error
   occurred. The function returns QLCT_RGB if flOptions is LCOLOPT_INDEX and
   the current logical color table does not use indexes.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_COLOR_OPTIONS

 Example

   This example uses the GpiQueryLogColorTable function to retrieve all the
   entries in the current logical color table.

   LONG cColors;
   SEL sel;
   PLONG alColor;

   /* Find out how many colors are in the color table. */

   DevQueryCaps(GpiQueryDevice(hps), CAPS_COLORS, 1L, &cColors);

   /* Allocate space for the color values and indexes. */

   DosAllocSeg((USHORT)(cColors * 2 * sizeof (LONG)), &sel, SEG_NONSHARED);
   alColor = MAKEP(sel, 0);

   /* Retrieve the values. */

   GpiQueryLogColorTable(hps,   /* presentation space              */
       LCOLOPT_INDEX,           /* retrieve indexes and RGB values */
       0L,                      /* start with first entry          */
       cColors * 2,             /* copy 2 values for each entry    */
       alColor);                /* array to receive values         */

 See Also

   GpiCreateLogColorTable, GpiQueryColorData, GpiQueryNearestColor,
   GpiQueryRealColors, GpiQueryRGBColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMarker
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryMarker (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryMarker function returns the current value of the marker-symbol
   attribute. The function cannot be used in an open segment when the drawing
   mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current marker symbol if the function is
   successful, or MARKSYM_ERROR if an error occurred.

 See Also

   GpiMarker, GpiPolyMarker, GpiQueryAttrs, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMarkerBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryMarkerBox (hps, psizfxBox)
   HPS hps;                /*presentation-space handle                     */
   PSIZEF psizfxBox;       /*pointer to structure for marker-box size      */

   The GpiQueryMarkerBox function retrieves the current value of the
   marker-box attribute, set by the GpiSetMarkerBox function. The function
   cannot be used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   psizfxBox  Points to the SIZEF structure that receives the size of the
   marker box. The SIZEF structure has the following form:

   typedef struct _SIZEF {
       FIXED cx;
       FIXED cy;
   } SIZEF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetMarkerBox


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMarkerSet
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryMarkerSet (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryMarkerSet function returns the current value of the marker-set
   attribute, as set by the GpiSetMarkerSet function. The function cannot be
   used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the local identifier for the marker set if the
   function is successful, or LCID_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiSetDrawingMode, GpiSetMarkerSet


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMetaFileBits
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryMetaFileBits (hmf, off, cbBuffer, pbBuffer)
   HMF hmf;                /*metafile handle                               */
   LONG off;               /*offset to the first metafile byte to copy     */
   LONG cbBuffer;          /*length in bytes of buffer                     */
   PBYTE pbBuffer;         /*pointer to buffer for metafile data           */

   The GpiQueryMetaFileBits function copies data from the metafile specified
   by hmf to the buffer pointed to by the pbBuffer parameter. The function
   copies the bytes of the metafile, up to the number of bytes specified by
   cbBuffer, starting at the byte whose offset from the beginning of the
   metafile is specified by the off parameter.

 Parameters

   hmf  Identifies the memory metafile.

   off  Specifies the offset in bytes from the beginning of the metafile to
   the first byte to copy.

   cbBuffer  Specifies the number of bytes of metafile data to copy.

   pbBuffer  Points to the buffer to receive the metafile data. It must have
   the number of bytes specified by the cbBuffer parameter.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_METAFILE_LENGTH
         PMERR_INV_METAFILE_OFFSET

 Example

   This example uses the GpiQueryMetaFileBits function to retrieve the
   graphics-order data from the specified metafile. The
   GpiQueryMetaFileLength function returns the length of the metafile.

   HMF hmf;
   LONG cBytes;
   SEL sel;
   LONG off;

   hmf = GpiLoadMetaFile(hps, "sample.met");

   /* Allocate the buffer for the metafile data. */

   DosAllocSeg(0, &sel, SEG_NONSHARED);
   pbBuffer = MAKEP(sel, 0);

   cBytes = GpiQueryMetaFileLength(hmf);  /* get length of metafile */

   /* Continue to retrieve data in 64K blocks. */

   for (off = 0L; off < cBytes; off += 65536L)
       GpiQueryMetaFileBits(
           hps,          /* presentation space              */
           off,          /* offset of next byte to retrieve */
           65536L,       /* retrieve as much as possible    */
           pbBuffer);    /* buffer to receive metafile data */

 See Also

   GpiQueryMetaFileLength, GpiSetMetaFileBits


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMetaFileLength
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryMetaFileLength (hmf)
   HMF hmf;                /*metafile handle                               */

   The GpiQueryMetaFileLength function returns the total length, in bytes, of
   the metafile specified by hmf. The function is typically used to determine
   the number of bytes of data to retrieve using the GpiQueryMetaFileBits
   function.

 Parameters

   hmf  Identifies the metafile.

 Return Value

   The return value is the metafile length if the function is successful, or
   GPI_ALTERROR if an error occurred.

 See Also

   GpiQueryMetaFileBits, GpiSetMetaFileBits


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryMix
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryMix (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryMix function returns the current value of the (line)
   foreground color-mixing mode, as set by the GpiSetMix function. The
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current foreground mix mode if the function is
   successful, or FM_ERROR if an error occurred.

 See Also

   GpiQueryAttrs, GpiQueryBackMix, GpiSetDrawingMode, GpiSetMix


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryModelTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryModelTransformMatrix (hps, cElements, pmatlf)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure for transformation       */
                           /*matrix                                        */

   The GpiQueryModelTransformMatrix function retrieves the matrix for the
   current model transformation. The function cannot be used in an open
   segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements of the matrix to retrieve. It
   must be an integer in the range 0 through 9.

   pmatlf  Points to the MATRIXLF structure the receives the model
   transformation matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiSetDrawingMode, GpiSetModelTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryNearestColor
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryNearestColor (hps, flOptions, lRgbColorIn)
   HPS hps;                /*presentation-space handle                     */
   ULONG flClrType;        /*color type                                    */
   LONG lRgbColorIn;       /*RGB color value                               */

   The GpiQueryColorIndex function returns the RGB color value from the
   physical palette that most closely matches the RGB color value specified
   by the lRgbColorIn parameter. The function uses the physical palette of
   the device associated with the given presentation space.

   If the current logical color table is realizable but has not been
   realized, the LCOLOPT_REALIZED option maps the RGB color value as if the
   logical color table has been realized. Since realizing a logical color
   table affects the contents of the physical palette, the RGB color value
   returned with this option may be different than the value returned without
   the option.

 Parameters

   hps  Identifies the presentation space.

   flClrType  Specifies whether the RGB color value is based on realized
   colors. If it is LCOLOPT_REALIZED, the function returns a RGB color based
   on the colors in the physical palette after the current logical color
   table is realized. If the parameter is zero, the function returns a RGB
   color based on the colors in the current physical palette.

   lRgbColorIn  Specifies a RGB color value.

 Return Value

   The return value is the nearest available color if the function is
   successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_COLOR_OPTIONS
         PMERR_INV_RGBCOLOR

 See Also

   GpiCreateLogColorTable, GpiQueryColorData, GpiQueryRealColors,
   GpiQueryRGBColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryNumberSetIds
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryNumberSetIds (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryNumberSetIds function returns the number of local identifiers
   currently in use that refer to fonts or bitmaps. The function is typically
   used before calling the GpiQuerySetIds function.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the number of local identifiers in use if the function
   is successful or GPI_ALTERROR if an error occurred.

 See Also

   GpiQuerySetIds, GpiSetBitmapId, GpiSetCharSet


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPageViewport
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryPageViewport (hps, prclViewport)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclViewport;    /*pointer to structure for viewport             */

   The GpiQueryPageViewport function retrieves the page viewport. The
   function cannot be used if no device context is associated with the
   presentation space.

 Parameters

   hps  Identifies the presentation space.

   prclViewport  Points to the RECTL structure that receives the page
   viewport. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCreatePS, GpiSetPageViewport


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPattern
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryPattern (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryPattern function returns the current value of the
   shading-pattern symbol, as set by the GpiSetPattern function. The function
   cannot be used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current shading-pattern symbol if the function is
   successful or PATSYM_ERROR if an error occurred.

 See Also

   GpiQueryPatternRefPoint, GpiQueryPatternSet, GpiSetDrawingMode,
   GpiSetPattern


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPatternRefPoint
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryPatternRefPoint (hps, pptlRefPoint)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlRefPoint;   /*pointer to structure for                      */
                           /*pattern-reference point                       */

   The GpiQueryPatternRefPoint function retrieves the current
   pattern-reference point. The function cannot be used in an open segment
   when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   pptlRefPoint  Points to the POINTL structure that receives the
   pattern-reference point. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryPattern, GpiQueryPatternSet, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPatternSet
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryPatternSet (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryPatternSet function returns the current value of the
   pattern-set identifier, as set by the GpiSetPatternSet function. The
   function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is the current pattern-set identifier if the function is
   successful or LCID_ERROR if an error occurred.

 See Also

   GpiQueryPattern, GpiQueryPatternRefPoint, GpiSetDrawingMode,
   GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPel
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryPel (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure with point to query      */

   The GpiQueryPel function returns the color of a pel at the specified
   point. The point, given in world coordinates, must be in any of the
   current clipping objects: clip path, viewing limits, graphics field, clip
   region, or visible region.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to the POINTL structure that contains the world coordinates
   of the point. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is the color index of the pel if the function is
   successful or GPI_ALTERROR if an error occurred.

 See Also

   GpiPtVisible, GpiSetPel


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPickAperturePosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryPickAperturePosition (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure for center point         */

   The GpiQueryPickAperturePosition function retrieves the position of the
   center of the pick aperture.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to the POINTL structure that receives the coordinates, in
   presentation page units, of the center. The POINTL structure has the
   following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryPickApertureSize, GpiSetPickAperturePosition


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPickApertureSize
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryPickApertureSize (hps, psizl)
   HPS hps;                /*presentation-space handle                     */
   PSIZEL psizl;           /*pointer to structure for pick-aperture size   */

   The GpiQueryPickApertureSize function retrieves the width and height of
   the the pick aperture. The pick aperture is set using the
   GpiSetPickApertureSize function.

 Parameters

   hps  Identifies the presentation space.

   psizl  Points to a SIZEL structure that receives the pick-aperture size.
   The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryPickAperturePosition, GpiSetPickApertureSize


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryPS
 ────────────────────────────────────────────────────────────────────────────
   ULONG GpiQueryPS (hps, psizlPage)
   HPS hps;                /*presentation-space handle                     */
   PSIZEL psizlPage;       /*pointer to structure for page size            */

   The GpiQueryPS function retrieves the page parameters and returns the
   presentation-space options for the presentation space. The page parameters
   specify the dimensions of the presentation page. The presentation-space
   options specify the page unit, storage format, and presentation type for
   the presentation space. These are the values set for the presentation
   space when it is created using the GpiCreatePS function.

 Parameters

   hps  Identifies the presentation space.

   psizlPage  Points to a SIZEL structure that receives the presentation-page
   size. The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is the presentation-space options if the function is
   successful or GPI_ERROR if an error occurred.

 Comment

   The individual presentation-space options can be extracted from the return
   value by using the bitwise AND operator and the constants defined for the
   flOptions parameter of the GpiCreatePS function.

 See Also

   GpiCreatePS, GpiQueryPageViewport


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryRealColors
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryRealColors (hps, flClrType, lStart, cclr, aclr)
   HPS hps;                /*presentation-space handle                     */
   ULONG flClrType;        /*color options                                 */
   LONG lStart;            /*ordinal number of first color                 */
   LONG cclr;              /*number of colors                              */
   PLONG aclr;             /*pointer to array of colors                    */

   The GpiQueryRealColors function retrieves the RGB values in the physical
   palette of the device associated with the presentation space. These colors
   represent the only device colors currently available to the application.
   The function copies the RGB color values, up to the number specified by
   the cclr parameter, to the array pointed to by the aclr parameter. The
   function uses the lStart parameter to determine which physical palette
   color to start copying. If this parameter is zero, the function copies
   from the start of the physical palette. The function returns the number of
   colors actually retrieved.

   An application can change the contents of the physical palette by
   realizing a color table, for devices that permit realizable color tables.
   If the current logical color table is realizable but has not been
   realized, the LCOLOPT_REALIZED option retrieves the RGB color values as if
   the logical color table has been realized. Since realizing a logical color
   table affects the contents of the physical palette, the RGB color values
   retrieved with this option may be different from the values retrieved
   without the option.

   The GpiQueryRealColors function can also map the colors from the physical
   palette to the color-index values in the current logical color table. If
   the LCOLOPT_INDEX option is specified, the function copies a color-index
   and RGB-color pair to the array pointed to by aclr. Each value in the pair
   fills one element in the array, with the color index appearing first.

 Parameters

   hps  Identifies the presentation space.

   flClrType  Specifies whether the RGB color values are realized colors and
   whether color-index values are retrieved. It can be one of the following:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   0x0000              Retrieves RGB colors based on the colors in the
                       current physical palette.

   LCOLOPT_REALIZED    Retrieves the RGB colors corresponding to the realized
                       logical color table. This option does not realize the
                       table, but does return values as if the table had been
                       realized.

   LCOLOPT_INDEX       Retrieves indexes and RGB color values.
   ──────────────────────────────────────────────────────────────────────────

   The LCOLOPT_REALIZED and LCOLOPT_INDEX options can be combined.

   lStart  Specifies the ordinal number of the first color to copy.

   cclr  Specifies the number of RGB color values to retrieve. If the
   LCOLOPT_INDEX option is specified, this parameter must specify the total
   number of color indexes and RGB colors to retrieve; this value must be a
   multiple of 2.

   aclr  Points to the array that receives the RGB color values. It must have
   the number of elements specified by the cclr parameter. If the
   LCOLOPT_INDEX option is given, the first element in each pair of elements
   is the color index.

 Return Value

   The return value is the number of elements returned if the function is
   successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_COLOR_OPTIONS

 See Also

   GpiCreateLogColorTable, GpiQueryColorData, GpiQueryNearestColor,
   GpiQueryRGBColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryRegionBox
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryRegionBox (hps, hrgn, prcl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PRECTL prcl;            /*pointer to structure for enclosing rectangle  */

   The GpiQueryRegionBox function retrieves the dimensions of the smallest
   rectangle that encloses the region identified by hrgn. If the region is
   empty, the function sets the left and right coordinates and top and bottom
   coordinates to equal values. The function cannot be used if no device
   context is associated with the presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region.

   prcl  Points to the RECTL structure that receives the coordinates of the
   enclosing rectangle. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is
   successful, or RGN_ERROR if an error occurred.

 See Also

   GpiQueryClipBox


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryRegionRects
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryRegionRects (hps, hrgn, prclBound, prgnrc, arcl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PRECTL prclBound;       /*pointer to structure for enclosing rectangle  */
   PRGNRECT prgnrc;        /*pointer to structure controlling processing   */
   PRECTL arcl;            /*pointer to array of rectangle structures      */

   The GpiQueryRegionRects function retrieves the rectangles that define the
   region identified by the hrgn parameter. The rectangles can be used to
   recreate the region, by using the GpiCreateRegion function. The function
   copies the coordinates of one or more of the defining rectangles to the
   array of structures pointed to by the arcl parameter. It uses the
   rectangle pointed to by the prclBound parameter to determine which
   rectangles to retrieve. Only rectangles within this rectangle are
   retrieved. If the prclBound parameter is NULL, the function retrieves all
   rectangles in the region.

   The GpiQueryRegionRects function uses the fields of the RGNRECT structure
   pointed to by the prgnrc parameter to control how the defining rectangles
   are retrieved. Since a region may comprise several rectangles, the RGNRECT
   structure lets an application retrieve a few rectangles at a time. The
   structure specifies which rectangle to start with and how many to
   retrieve. The function copies the actual number of rectangles retrieved to
   the structure. Also, a field in this structure specifies the direction
   through the region the function is to take as it retrieves rectangles.

   The GpiQueryRegionRects function cannot be used if no device context is
   associated with the presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region.

   prclBound  Points to the RECTL structure that contains the enclosing
   rectangle. Only rectangles within this rectangle are retrieved. The RECTL
   structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prgnrc  Points to the RGNRECT structure that specifies how to retrieve the
   rectangles. The RGNRECT structure has the following form:

   typedef struct _RGNRECT {
       USHORT ircStart;
       USHORT crc;
       USHORT crcReturned;
       USHORT usDirection;
   } RGNRECT;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   arcl  Points to the array of RECTL structures that receives the defining
   rectangles.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_REGION_CONTROL

 See Also

   GpiCombineRegion, GpiCreateRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryRGBColor
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryRGBColor (hps, flClrType, lColorIndex)
   HPS hps;                /*presentation-space handle                     */
   ULONG flClrType;        /*color type                                    */
   LONG lColorIndex;       /*color-index value                             */

   The GpiQueryRGBColor function returns the RGB color value in the physical
   palette that corresponds to the color-index value specified by the
   lColorIndex parameter.

   If the current logical color table is realizable but has not been
   realized, the LCOLOPT_REALIZED option maps the color-index value as if the
   logical color table has been realized. Since realizing a logical color
   table affects the contents of the physical palette, the RGB color value
   returned with this option may be different from the value returned without
   the option.

   If the current logical color table was created using the LCOLF_RGB option,
   the lColorIndex parameter is interpreted as an RGB color value. In this
   case, the function is identical to the GpiQueryNearestColor function.

 Parameters

   hps  Identifies the presentation space.

   flClrType  Specifies whether the RGB color value is based on realized
   colors. If it is LCOLOPT_REALIZED, the function returns an RGB color based
   on the colors in the physical palette after the current logical color
   table is realized. If the parameter is zero, the function returns an RGB
   color based on the colors in the current physical palette.

   lColorIndex  Specifies the color index. This may be any valid color-index
   value except CLR_DEFAULT.

 Return Value

   The return value is the RGB color that is the closest match if the
   function is successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_COLOR_INDEX
         PMERR_INV_COLOR_OPTIONS

 See Also

   GpiCreateLogColorTable, GpiQueryColorData, GpiQueryNearestColor,
   GpiQueryRealColors, GpiQueryRGBColor, GpiSetColor


 ────────────────────────────────────────────────────────────────────────────
 GpiQuerySegmentAttrs
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQuerySegmentAttrs (hps, idSegment, lAttribute)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG lAttribute;        /*attribute                                     */

   The GpiQuerySegmentAttrs function checks a segment for the specified
   attribute. The function returns ATTR_ON or ATTR_OFF to specify whether the
   segment has or does not have the given attribute. The function can be used
   to check the attributes of any segment, including the currently open
   segment (if any).

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment identifier. It must be greater than zero.

   lAttribute  Specifies the attribute to check. It must be one of the
   following values:

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   ATTR_CHAINED            Chained

   ATTR_DETECTABLE         Detectability

   ATTR_DYNAMIC            Dynamic

   ATTR_FASTCHAIN          Fast chaining

   ATTR_PROP_DETECTABLE    Propagate detectability

   ATTR_PROP_VISIBLE       Propagate visibility

   ATTR_VISIBLE            Visibility
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return is ATTR_ON or ATTR_OFF if the function is successful, or
   ATTR_ERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 See Also

   GpiSetSegmentAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiQuerySegmentNames
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQuerySegmentNames (hps, idFirstSegment, idLastSegment, cidMax,
   aidSegments)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstSegment;    /*first segment                                 */
   LONG idLastSegment;     /*last segment                                  */
   LONG cidMax;            /*maximum number of segments                    */
   PLONG aidSegments;      /*pointer to array for segments                 */

   The GpiQuerySegmentNames function retrieves the identifiers of all
   existing segments whose identifiers are in the range specified by the
   idFirstSegment and idLastSegment parameters.

   If the idFirstSegment parameter is equal to or greater than the
   idLastSegment parameter, the function only checks for the segment having
   the identifier specified by idFirstSegment.

 Parameters

   hps  Identifies the presentation space.

   idFirstSegment  Specifies the first segment in the range; it must be
   greater than zero.

   idLastSegment  Specifies the last segment; it must be greater than zero.

   cidMax  Specifies the maximum number of segment identifiers to retrieve.

   aidSegments  Points to the array to receive the segment identifiers. It
   must have the number of elements specified by the cidMax parameter.

 Return Value

   The return value is the number of segment identifiers returned if the
   function is successful or GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 See Also

   GpiOpenSegment


 ────────────────────────────────────────────────────────────────────────────
 GpiQuerySegmentPriority
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQuerySegmentPriority (hps, idRefSegment, cmdOrder)
   HPS hps;                /*presentation-space handle                     */
   LONG idRefSegment;      /*reference-segment identifier                  */
   LONG cmdOrder;          /*segment order                                 */

   The GpiQuerySegmentPriority function returns the identifier of the segment
   having the next-highest or next-lowest priority, relative to the segment
   specified by idRefSegment. The priority of a segment affects how segments
   in the picture chain are drawn.

   The function uses the cmdOrder parameter to determine whether to look for
   the segment with next-highest or next-lowest priority. The function
   returns zero if there is no segment with next-highest or next-lowest
   priority.

 Parameters

   hps  Identifies the presentation space.

   idRefSegment  Specifies the identifier of the segment whose priority is
   compared, or is zero to specify the segment with lowest or highest
   priority.

   cmdOrder  Specifies whether to check for a segment with higher or lower
   priority. It can be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LOWER_PRI         Return the identifier for the segment with next-lowest
                     priority. If idRefSegment is zero, the function returns
                     the identifier of the segment with the lowest priority.

   HIGHER_PRI        Return the identifier of the segment with next-highest
                     priority. If idRefSegment is zero, the function returns
                     the identifier of the segment with the highest priority.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is the identifier of the segment with the next-highest or
   next-lowest priority if the function is successful. The return value is
   GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 See Also

   GpiDrawChain, GpiDrawFrom, GpiSetSegmentPriority


 ────────────────────────────────────────────────────────────────────────────
 GpiQuerySegmentTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQuerySegmentTransformMatrix (hps, idSegment, cElements, pmatlf)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure for matrix elements      */

   The GpiQuerySegmentTransformMatrix function retrieves one or more elements
   of the segment-transformation matrix for the segment specified by
   idSegment.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment identifier.

   cElements  Specifies the number of elements to retrieve. It must be an
   integer value in the range 0 through 9.

   pmatlf  Points to the MATRIXLF structure that receives the transformation
   matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME

 See Also

   GpiSetSegmentTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiQuerySetIds
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQuerySetIds (hps, cSets, alTypes, pstr8, alcid)
   HPS hps;                /*presentation-space handle                     */
   LONG cSets;             /*number of objects to query                    */
   PLONG alTypes;          /*pointer to array of types                     */
   PSTR8 pstr8;            /*pointer to array for names                    */
   PLONG alcid;            /*pointer to array for local identifiers        */

   The GpiQuerySetIds function retrieves a list of types, names, and local
   identifiers for all current logical fonts and tagged bitmaps. The function
   copies the information to the arrays pointed to by the alTypes, pstr8, and
   alcid parameters. The type specifies whether the object is a logical font
   or tagged bitmap. The name is an 8-character string that uniquely
   identifies the object. Not all objects have names.

   The GpiQuerySetIds function retrieves information for only the number of
   objects specified by the cSets parameter, starting with the object having
   local identifier 1. If information for all objects is needed, the
   GpiQueryNumberSetIds function returns a count of all local identifiers in
   use.

 Parameters

   hps  Identifies the presentation space.

   cSets  Specifies the number of objects to retrieve. It must not be greater
   than the number of local identifiers currently in use.

   alTypes  Points to the array to receive the type for each object. The
   function sets each element in this array to either LCIDT_FONT or
   LCIDT_BITMAP. The array must have the number of elements specified by
   cSets.

   pstr8  Points to the array to receive the name for each object. Each
   element, itself an array, receives an object name of up to eight
   characters. If an object has no name, the element is set to zero. The
   array must have the number of elements specified by cSet.

   alcid  Points to the array that receives the local identifiers. The array
   must have the number of elements specified by cSets.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQuerySetIds function to retrieve the local
   identifier for all logical fonts. It then uses the identifiers to delete
   the logical fonts.

   LONG cIds;
   SEL sel;
   PLONG plType;
   PSTR8 pstr8;
   PLONG plcid;

   cIds = GpiQueryNumberSetIds(hps); /* get number of local identifiers */

   /* Allocate space for type, name, and local-identifier arrays. */

   DosAllocSeg((USHORT) cIds * sizeof(LONG), &sel, SEG_NONSHARED);
   plType = MAKEP(sel, 0);
   DosAllocSeg((USHORT) cIds * sizeof(STR8), &sel, SEG_NONSHARED);
   pstr8 = MAKEP(sel, 0);
   DosAllocSeg((USHORT) cIds * sizeof(LONG), &sel, SEG_NONSHARED);
   plcid = MAKEP(sel, 0);

   /* Get the types, names, and local identifiers. */

   GpiQuerySetIds(hps, cIds, plType, pstr8, plcid);

   /* Delete each local identifier that has LCIDT_FONT type. */

   for (i = 1; i < cIds; i++)
       if (plTypes[i] == LCIDT_FONT)
           GpiDeleteSetId(hps, plcid[i]);

 See Also

   GpiCreateLogFont, GpiQueryNumberSetIds, GpiSetBitmapId


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryStopDraw
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiQueryStopDraw (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiQueryStopDraw function returns the state of the stop-draw
   condition.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is TRUE if the stop-draw condition is on or FALSE if it
   is not. The return value is GPI_ALTERROR if an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetStopDraw


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryTag
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryTag (hps, plTag)
   HPS hps;                /*presentation-space handle                     */
   PLONG plTag;            /*tag identifier                                */

   The GpiQueryTag function retrieves the current value of the tag
   identifier, as set by the GpiSetTag function. The function cannot be used
   in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   plTag  Points to the variable to receive the tag.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetDrawingMode, GpiSetTag


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryTextBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryTextBox (hps, cchString, pchString, cptl, aptl)
   HPS hps;                /*presentation-space handle                     */
   LONG cchString;         /*number of characters                          */
   PCH pchString;          /*pointer to string                             */
   LONG cptl;              /*number of points                              */
   PPOINTL aptl;           /*pointer to array of point structures          */

   The GpiQueryTextBox function retrieves the text box and concatenation
   point for the string pointed to by the pchString parameter. The text box
   is four points specifying the parallelogram that, if drawn, encloses the
   given string when the string is displayed on the device. The concatenation
   point is the point the current position advances to after the string is
   drawn. All coordinates are relative to the start point of the string──that
   is, the text box and concatenation point are given as if the string were
   drawn at the world-space origin.

   The GpiQueryTextBox function computes the text box and concatenation point
   using the current character attributes. It then copies the computed points
   to the array pointed to by the aptl parameter. In most cases, the function
   copies the upper-left, lower-left, upper-right, and lower-right corners of
   the text box first, followed by the concatenation point, but not all
   points need to be copied at all times. The function uses the cptl
   parameter to determine how many of these points to retrieve and copies
   only that number.

   Depending on the character attributes, the "upper-left" corner of the text
   box may not seem so when the text box is actually drawn. For this reason,
   the function copies the coordinates of the text box to the array prior to
   applying character attributes, such as base-line angle, that affect the
   orientation of the points.

   The function cannot be used in an open segment when the drawing mode is
   DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   cchString  Specifies the number of characters in the string pointed to by
   pchString.

   pchString  Points to the character string.

   cptl  Specifies the number of points to retrieve. If it is TXTBOX_COUNT,
   the function retrieves the maximum number of points for the text box.

   aptl  Points to the array of POINTL structures that receives a list of
   points. The list of points contains the relative coordinates of the
   character box. The elements of the array are defined as follows:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   TXTBOX_TOPLEFT        Upper-left corner

   TXTBOX_BOTTOMLEFT     Lower-left corner

   TXTBOX_TOPRIGHT       Upper-right corner

   TXTBOX_BOTTOMRIGHT    Lower-right corner

   TXTBOX_CONCAT         Concatenation point
   ──────────────────────────────────────────────────────────────────────────

   The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiQueryTextBox function to draw a line under the
   string. The GpiCharString function draws the string at the point
   (100,100). Since the points retrieved by GpiQueryTextBox are relative to
   the start of the string, the starting point needs to be added to the
   points that are used to draw the underline.

   POINTL aptl[TXTBOX_COUNT];
   POINTL ptl = { 100, 100 };

   GpiQueryTextBox(hps, 11L, "This string", TXTBOX_COUNT, aptl);
   aptl[1].x += ptl.x;
   aptl[1].y += ptl.y;
   GpiMove(hps, &aptl[1]);
   aptl[3].x += ptl.x;
   aptl[3].y += ptl.y;
   GpiLine(hps, &aptl[3]);
   GpiMove(hps, &ptl);
   GpiCharString(hps, 11L, "This string");

 See Also

   GpiCharStringAt, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryViewingLimits
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryViewingLimits (hps, prclLimits)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclLimits;      /*pointer to structure for viewing limits       */

   The GpiQueryViewingLimits function retrieves the current value of the
   viewing limits, as set by the GpiSetViewingLimits function. The function
   cannot be used in an open segment when the drawing mode is DM_RETAIN.

 Parameters

   hps  Identifies the presentation space.

   prclLimits  Points to the RECTL structure that receives the viewing
   limits. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryClipBox, GpiQueryClipRegion, GpiQueryGraphicsField,
   GpiQueryViewingLimits, GpiSetDrawingMode, GpiSetViewingLimits


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryViewingTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryViewingTransformMatrix (hps, cElements, pmatlf)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure for transformation       */
                           /*matrix                                        */

   The GpiQueryViewingTransformMatrix function retrieves the current
   viewing-transformation matrix.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements to retrieve. It must be an
   integer in the range 0 through 9.

   pmatlf  Points to the MATRIXLF structure that receives the elements of the
   viewing-transformation matrix. The MATRIXLF structure has the following
   form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetViewingTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiQueryWidthTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiQueryWidthTable (hps, lFirstChar, clWidths, alWidths)
   HPS hps;                /*presentation-space handle                     */
   LONG lFirstChar;        /*code point of first character                 */
   LONG clWidths;          /*number of elements                            */
   PLONG alWidths;         /*pointer to array for width table              */

   The GpiQueryWidthTable function retrieves the widths of one or more
   characters in the current font. A character width is the distance (in
   world coordinates) the system advances along the baseline after drawing
   the character. The function copies the widths, starting with the width for
   the character specified by the lFirstChar parameter, to the array pointed
   to by the alWidths parameter. The function uses the clWidths parameter to
   determine how many widths to retrieve.

   If the widths for all characters in the font are desired, the
   GpiQueryFontMetrics function can be used to retrieve the number of
   characters in the font.

 Parameters

   hps  Identifies the presentation space.

   lFirstChar  Specifies the code point of the first character for which a
   width is retrieved.

   clWidths  Specifies the number of widths to retrieve.

   alWidths  Points to the array that receives the character widths. The
   array must have the number of elements specified by clWidths.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_FIRST_CHAR

 See Also

   GpiQueryFontMetrics


 ────────────────────────────────────────────────────────────────────────────
 GpiRealizeColorTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiRealizeColorTable (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiRealizeColorTable function realizes the logical color table. The
   function realizes the color table by replacing the colors in the physical
   palette. It replaces the physical palette colors with the device colors
   that most closely match the RGB color values given in the logical color
   table.

   To realize a logical color table, the application must create the table
   using the LCOL_REALIZABLE option of the GpiCreateLogColorTable function
   and the device must be capable of realizing logical color tables. The
   DevQueryCaps function and CAPS_COLOR option can be used to determine if
   logical color tables can be realized.

   If the presentation space is currently associated with a screen window
   device, this function should be used only when the associated window is
   maximized. Changing the physical palette colors for the screen affects
   output for all visible windows.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Example

   This example uses the GpiRealizeColorTable function to realize the logical
   color table. The GpiUnrealizeColorTable function is used to restore the
   physical palette after the drawing is complete.

   RGB argb[16];      /* RGB color values for new logical color table */

   /* Create a realizable logical color table. */

   GpiCreateLogColorTable(hps, LCOL_REALIZABLE, LCOLF_CONSECRGB,
       0L, 16L, argb);

   GpiRealizeColorTable(hps);     /* realizes the logical color table */
       .
       .
       .
   GpiUnrealizeColorTable(hps);   /* restores the physical palette    */

 See Also

   DevQueryCaps, GpiUnrealizeColorTable


 ────────────────────────────────────────────────────────────────────────────
 GpiRectInRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiRectInRegion (hps, hrgn, prcl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PRECTL prcl;            /*pointer to rectangle structure                */

   The GpiRectInRegion function checks whether any part of a rectangle lies
   within the specified region. The function cannot be used if no device
   context is associated with the presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region.

   prcl  Points to the RECTL structure that contains the rectangle to check.
   The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RRGN_OUTSIDE, RRGN_PARTIAL, or RRGN_INSIDE if the
   function is successful, or RRGN_ERROR if an error occurred.

 See Also

   GpiPtInRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiRectVisible
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiRectVisible (hps, prcl)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prcl;            /*pointer to rectangle structure                */

   The GpiRectVisible function checks whether any part of a rectangle is
   visible on the device associated with the specified presentation space. A
   point in the rectangle is visible if it lies within the intersection of
   the current graphics field, viewing limit, clip path, clip region, and
   visible region (if any).

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to a RECTL structure that contains the rectangle in world
   coordinates. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is RVIS_INVISIBLE, RVIS_PARTIAL, or RVIS_VISIBLE if the
   function is successful, or RVIS_ERROR if an error occurred.

 See Also

   GpiPtVisible


 ────────────────────────────────────────────────────────────────────────────
 GpiRemoveDynamics
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiRemoveDynamics (hps, idFirstSegment, idLastSegment)
   HPS hps;                /*presentation-space handle                     */
   LONG idFirstSegment;    /*first segment identifier                      */
   LONG idLastSegment;     /*last segment identifier                       */

   The GpiRemoveDynamics function removes from the display any images drawn
   using dynamic segments. The function removes the image for any dynamic
   segment that is in the current picture chain and whose segment identifier
   is in the range specified by the idFirstSegment and idLastSegment
   parameters. The function removes only the image drawn using the dynamic
   segment and by the dynamic segment's segment calls.

   The GpiRemoveDynamics function checks for the segments specified by
   idFirstSegment and idLastSegment. If they do not exist, or are not in the
   chain, or idLastSegment is less than idFirstSegment, the function returns
   without removing segments and without an error value.

 Parameters

   hps  Identifies the presentation space.

   idFirstSegment  Specifies the name of the first segment in the section. It
   must be greater than zero.

   idLastSegment  Specifies the last segment in the section. It must be
   greater than zero.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_AREA_INCOMPLETE
         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_PATH_INCOMPLETE

 Comments

   An application should remove dynamic segments before associating a new
   device context with the presentation space.

 Example

   This example uses the GpiRemoveDynamics function to remove the image drawn
   by the dynamic segment whose segment identifier is 4. It then edits the
   segment and redraws it, using the GpiDrawDynamics function.

   POINTL ptl = {30, 40};

   /* Remove the image for dynamic segment #4. */

   GpiRemoveDynamics(hps, 4L, 4L);

   /* Edit the segment. */

   GpiSetDrawingMode(DM_RETAIN);
   GpiOpenSegment(hps, 4L);
   GpiSetElementPointer(hps, 1L);
   GpiMove(hps, &ptl);
   GpiCloseSegment(hps);

   GpiDrawDynamics(hps);    /* redraws the edited segment */

 See Also

   GpiCloseSegment, GpiDrawDynamics


 ────────────────────────────────────────────────────────────────────────────
 GpiResetBoundaryData
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiResetBoundaryData (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiResetBoundaryData function resets the boundary data, copying the
   maximum boundary value to the lower corner and the minimum boundary value
   to the upper corner of the boundary-data rectangle.

   The function is only necessary when accumulating boundary date in DM_DRAW
   drawing mode. For other drawing modes, drawing functions automatically
   reset the boundary data. (However, the GpiOpenSegment function does not
   reset the boundary data.)

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiSetDrawControl


 ────────────────────────────────────────────────────────────────────────────
 GpiResetPS
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiResetPS (hps, flOption)
   HPS hps;                /*presentation-space handle                     */
   ULONG flOption;         /*reset option                                  */

   The GpiResetPS function resets the presentation space. In general,
   resetting the presentation space restores attributes to their default
   values──that is, the values given to the attributes when the presentation
   space was created. The function can reset the presentation space in three
   ways: as if a segment were closed; as if the presentation space had just
   been created, but without deleting any resources; and as if the
   presentation space had just been created. It uses the flOption parameter
   to determine how to reset the presentation space.

   The GpiResetPS function does not draw or erase the device. It is up to the
   application to erase the screen, if this is required. Also, the function
   does not affect the association between the specified presentation space
   and a device context.

 Parameters

   hps  Identifies the presentation space.

   flOption  Specifies the reset option. It can be one of the following:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   GRES_ATTRS        Sets all current attributes to their default values, the
                     current model transform to unity, and the current
                     position to (0,0). The option also ends any open path,
                     area, or element brackets and closes any open segment.
                     Finally, it sets the current clip path and viewing
                     limits to their widest possible values.

   GRES_SEGMENTS     Resets as described for GRES_ATTRS, plus it deletes all
                     retained segments, clears any boundary data, releases
                     the clip region (if any), enables kerning (if the device
                     supports it), and sets the default values for initial
                     segment attributes, default viewing transform, graphics
                     field, drawing mode, draw controls, edit mode, and
                     attribute mode.

   GRES_ALL          Resets as described for GRES_ATTRS and GRES_SEGMENTS,
                     plus it deletes any logical fonts and local identifiers
                     for bitmaps and sets the logical color table to its
                     default value.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_RESET_OPTIONS

 See Also

   GpiAssociate, GpiCreatePS


 ────────────────────────────────────────────────────────────────────────────
 GpiRestorePS
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiRestorePS (hps, idPS)
   HPS hps;                /*presentation-space handle                     */
   LONG idPS;              /*identifier for the presentation space         */

   The GpiRestorePS function restores the state of the presentation space by
   popping the state from the presentation space (PS) stack. The function
   sets the attributes and resources of the presentation space to the values
   that were saved previously by using the GpiSavePS function.

   The PS stack, maintained internally by the system, can contain one or more
   saved presentation spaces. Each saved presentation space has a unique
   identifier. The GpiRestorePS function restores a specific presentation
   space if the idPS parameter contains the corresponding identifier. The
   function also accepts negative identifiers. In this case, the function
   uses the absolute value of the identifier to determine how many
   presentation spaces to pop from the PS stack. For example, if it is -2,
   the function pops two presentation spaces from the stack. In either case,
   identifier or negative number, the function discards any presentation
   spaces that are skipped over on the PS stack.

 Parameters

   hps  Identifies the presentation space.

   idPS  Specifies the identifier of the saved presentation space to restore,
   or a negative number indicating the number of saved presentation spaces to
   pop. If it is an identifier, it must have been returned previously by the
   GpiSavePS function. It must not be zero.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_ID

 Comments

   The function can be used in an open segment only if the drawing mode is
   DM_DRAW. The function can also be used in an element, area, or path
   bracket. If it is in an area or path bracket, the corresponding GpiSavePS
   function must have been called in the same bracket.

   If an error occurs, the function leaves the PS stack and the current
   presentation space unchanged.

 See Also

   GpiPop, GpiSavePS, GpiSetDrawingMode

 ────────────────────────────────────────────────────────────────────────────
 GpiSaveMetaFile
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSaveMetaFile (hmf, pszFilename)
   HMF hmf;                /*metafile handle                               */
   PSZ pszFilename;        /*pointer to filename                           */

   The GpiSaveMetaFile function saves a metafile to disk. The function
   deletes the metafile from memory and invalidates the metafile handle. The
   application can load the metafile by using the GpiLoadMetaFile function.

 Parameters

   hmf  Identifies the metafile.

   pszFilename  Points to a null-terminated string. This string must be a
   valid MS OS/2 filename that specifies the path and filename of the file to
   receive the metafile.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiLoadMetaFile, GpiPlayMetaFile


 ────────────────────────────────────────────────────────────────────────────
 GpiSavePS
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiSavePS (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiSavePS function saves the state of the presentation space on the
   presentation-space (PS) stack. The PS stack is a last-in, first-out stack,
   maintained by the system, on which an application can save one or more
   presentation-space states. The function saves the state and returns a
   unique identifier. The identifier can be used with the GpiRestorePS
   function to restore the given state.

   The GpiSavePS function saves the current position of the presentation
   space, the viewing limits, all attributes, and transformation matrices. It
   also saves the clip path, clip region, logical color table, and references
   to any loaded logical fonts and the regions created on the associated
   device context. It does not save the visible region. The function does not
   actually copy resources such as logical fonts and regions to the PS stack.
   Instead, it copies a reference to the resource. The application must
   ensure that the resources are available when these references are
   restored.

 Parameters

   hps  Identifies the presentation space. If it identifies a micro
   presentation space, the drawing mode must be DM_DRAW.

 Return Value

   The return value is an identifier of the saved presentation space if the
   function is successful or GPI_ERROR if an error occurred. The identifier
   is equal to the depth of the saved presentation space on the save/restore
   stack, with 1 as the base level.

 Comments

   The function can be used in an open segment, but only if the drawing mode
   is DM_DRAW. It can also be used in an element bracket. When it occurs
   within an open area or path bracket, then the corresponding call to the
   GpiRestorePS function should take place before the bracket is closed.
   Although the function can be used when creating a metafile, the drawing
   mode must be DM_DRAW when replaying the metafile.

   The PS stack is not the same as the attribute stack (that is, the stack
   used to save attributes when the attribute mode is AM_PRESERVE).

 See Also

   GpiPop, GpiRestorePS, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetArcParams
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetArcParams (hps, parcp)
   HPS hps;                /*presentation-space handle                     */
   PARCPARAMS parcp;       /*pointer to structure for arc parameters       */

   The GpiSetArcParams function sets the current arc parameters. The arc
   parameters define the shape and orientation of the ellipse used by the
   GpiPointArc, GpiFullArc, and GpiPartialArc functions to construct arcs.

   The arc parameters define a four-element transformation that maps the unit
   circle to the ellipse. The transformation has the form:

               x' = lP x x + lR x y
               y' = lS x x + lQ x y

   In the transformation, lP, lR, lS, and lQ are the fields of the structure
   pointed to by the parcp parameter. The lP and lQ fields determine the
   width and height of ellipse, and the lS and lR fields determine the shear
   of the ellipse.

   The fields also determine the direction of drawing for arcs drawn using
   the GpiFullArc and GpiPartialArc functions. If lP x lQ is greater than lR
   x lS, the direction is counterclockwise. If lP x lQ is less than lR x lS,
   the direction is clockwise. If lP x lQ is equal to lR x lS, a straight
   line is drawn.

   If the attribute mode is AM_PRESERVE, the function saves the previous arc
   parameters on the attribute stack when it sets the new parameters. The
   previous arc parameters can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   parcp  Points to an ARCPARAMS structure that contains the arc parameters.
   The ARCPARAMS structure has the following form:

   typedef struct _ARCPARAMS {
       LONG lP;
       LONG lQ;
       LONG lR;
       LONG lS;
   } ARCPARAMS;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Comments

   Although the arc parameters define the shape and orientation of arcs drawn
   by the GpiPointArc, GpiFullArc, and GpiPartialArc functions, the functions
   define the center point and the size of each arc. The GpiFullArc and
   GpiPartialArc functions use an explicit center point and a multiplier to
   scale the ellipse to a desired size. The GpiPointArc function computes the
   center point and size of the final ellipse so that it fits the given
   points.

   Orthogonal transformation provides the most accurate arcs. A
   transformation is orthogonal if lP x lR plus lS x lQ equals zero. By
   default, the arc parameters are as follows:

               lP = 1     lR = 0
               lS = 0     lQ = 1

   These values produce a unit circle.

   Arc-parameter transformation takes place in world coordinates. Any other
   transformations in force will change the shape of the figure accordingly.

 See Also

   GpiFullArc, GpiPartialArc, GpiPointArc, fbGpiQueryArcParams


 ────────────────────────────────────────────────────────────────────────────
 GpiSetAttrMode
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetAttrMode (hps, cmdMode)
   HPS hps;                /*presentation-space handle                     */
   LONG cmdMode;           /*attribute mode                                */

   The GpiSetAttrMode function sets the current attribute mode. If the
   attribute mode is AM_PRESERVE, the system saves the old value of a
   primitive attribute whenever the attribute is changed to a new value. The
   saved value of an attribute can be restored by using the GpiPop function.
   Any attributes that have been saved in a called segment are automatically
   restored on return to the caller.

 Parameters

   hps  Identifies the presentation space.

   cmdMode  Specifies the attribute mode. It can be one of the following
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   AM_PRESERVE       Preserve attributes.

   AM_NOPRESERVE     Do not preserve attributes.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_ATTR_MODE
         PMERR_INV_MICROPS_FUNCTION

 Comments

   The attribute mode is an API mode, meaning it does not affect
   attribute-setting functions that have been stored in a segment. The mode
   used for functions stored in a segment is the mode in effect when the
   function was stored. This is also true for any attribute-setting functions
   that are part of the graphics-order data in a GpiPutData, GpiElement, or
   GpiPlayMetaFile function.

 See Also

   GpiElement, GpiPlayMetaFile, GpiPop, GpiPutData, GpiSetAttrs,
   GpiSetColor


 ────────────────────────────────────────────────────────────────────────────
 GpiSetAttrs
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetAttrs (hps, flPrimType, flAttrsMask, flDefsMask, pbunAttrs)
   HPS hps;                /*presentation-space handle                     */
   LONG flPrimType;        /*primitive type                                */
   ULONG flAttrsMask;      /*attribute mask                                */
   ULONG flDefsMask;       /*defaults mask                                 */
   PBUNDLE pbunAttrs;      /*pointer to structure for attributes           */

   The GpiSetAttrs function sets attributes for the specified primitive type.
   The function uses the flPrimType parameter to determine the type of
   primitive attribute to set, then uses the flAttrsMask parameter to
   determine which attributes to set for that primitive. If the flDefsMask
   parameter specifies an attribute that is also specified by flAttrsMask,
   the function sets the attribute to its default value. Otherwise, the
   function uses the value found in the appropriate field of the buffer
   pointed to by pbunAttrs.

   The GpiSetAttrs function does not accept default values in the buffer
   fields. To set an attribute to its default value, both the flAttrsMask and
   flDefsMask parameters must specify the attribute. Any attribute not
   specified by flAttrsMask remains unchanged, regardless of the flDefsMask
   setting. If the attribute mode is AM_PRESERVE (as set by the
   GpiSetAttrMode function), the system saves the previous value of each
   attribute that is changed.

 Parameters

   hps  Identifies the presentation space.

   flPrimType  Specifies which primitive type to set attributes for. It can
   be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA         Area primitives

   PRIM_CHAR         Character primitives

   PRIM_IMAGE        Image primitives

   PRIM_LINE         Line and arc primitives

   PRIM_MARKER       Marker primitives
   ──────────────────────────────────────────────────────────────────────────

   flAttrsMask  Specifies which attributes to set. The values for this
   parameter depend on the primitive type specified by flPrimType. It can be
   any combination of the following values for a specific type:

   Type                Values
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA           ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE,
                       ABB_BACK_MIX_MODE, ABB_SET, ABB_SYMBOL, ABB_REF_POINT

   PRIM_CHAR           CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE,
                       CBB_BACK_MIX_MODE, CBB_SET, CBB_MODE, CBB_BOX,
                       CBB_ANGLE, CBB_SHEAR, CBB_DIRECTION

   PRIM_IMAGE          IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE,
                       IBB_BACK_MIX_MODE

   PRIM_LINE           LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH, LBB_GEOM_WIDTH,
                       LBB_TYPE, LBB_END, LBB_JOIN

   PRIM_MARKER         MBB_COLOR, MBB_BACK_COLOR, MBB_MIX_MODE,
                       MBB_BACK_MIX_MODE, MBB_SET, MBB_SYMBOL, MBB_BOX
   ──────────────────────────────────────────────────────────────────────────

   If this parameter is zero, no attributes are set, regardless of the value
   of the flDefsMask and pbunAttrs parameters.

   flDefsMask  Specifies which attributes to set to default values. The
   values for this parameter depend on the primitive type specified by
   flPrimType. Although it can be any combination of the values specified for
   the flAttrsMask parameter, only the attributes that are also specified by
   flAttrsMask are set.

   pbunAttrs  Points to a buffer that contains attribute values for each
   attribute specified by flAttrsMask and not also specified by flDefsMask.
   The buffer format depends on the primitive type specified by flPrimType.
   The following structures can be used for the specified primitive types:

   Type                Structure
   ──────────────────────────────────────────────────────────────────────────
   PRIM_AREA           AREABUNDLE

   PRIM_CHAR           CHARBUNDLE

   PRIM_IMAGE          IMAGEBUNDLE

   PRIM_LINE           LINEBUNDLE

   PRIM_MARKER         MARKERBUNDLE
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_BACKGROUND_MIX_ATTR
         PMERR_INV_CHAR_ANGLE_ATTR
         PMERR_INV_CHAR_DIRECTION_ATTR
         PMERR_INV_CHAR_MODE_ATTR
         PMERR_INV_CHAR_SET_ATTR
         PMERR_INV_CHAR_SHEAR_ATTR
         PMERR_INV_COLOR_ATTR
         PMERR_INV_GEOM_LINE_WIDTH_ATTR
         PMERR_INV_LINE_END_ATTR
         PMERR_INV_LINE_JOIN_ATTR
         PMERR_INV_LINE_TYPE_ATTR
         PMERR_INV_LINE_WIDTH_ATTR
         PMERR_INV_MARKER_BOX_ATTR
         PMERR_INV_MARKER_SET_ATTR
         PMERR_INV_MIX_ATTR
         PMERR_INV_PATTERN_ATTR
         PMERR_INV_PATTERN_SET_ATTR
         PMERR_INV_PRIMITIVE_TYPE

 See Also

   GpiQueryAttrs, GpiSetBackMix, GpiSetCharAngle, GpiSetCharBox,
   GpiSetColor, GpiSetCp, GpiSetLineType, GpiSetLineWidth,
   GpiSetMarkerBox, GpiSetMarkerSet, GpiSetMix, GpiSetPattern,
   GpiSetPatternRefPoint, GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBackColor
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetBackColor (hps, clr)
   HPS hps;                /*presentation-space handle                     */
   LONG clr;               /*background color                              */

   The GpiSetBackColor function sets the current background color for all
   primitive types. The background color specifies the color used to fill the
   background of the primitive, such as the gaps between dashes in a styled
   line. The function sets the background color to the color specified by
   clr. The clr parameter is either an RGB color value or a color-index
   value, depending on the current logical color table. The actual color the
   clr parameter represents also depends on the current logical color table.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   background color on the attribute stack when it sets the new color. The
   previous background color can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   clr  Specifies the color. The values depend on the current logical color
   table. If the logical color table has been created using the LCOLF_RGB
   constant, the values must be RGB color values. Otherwise, the values must
   be color-index values. If the default logical color table is used, the
   parameter can be any one of the following standard color-index values:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CLR_FALSE         All color planes are zero.

   CLR_TRUE          All color planes are 1.

   CLR_DEFAULT       Set to default value; same as zero.

   CLR_WHITE         White.

   CLR_BLACK         Black.

   CLR_BACKGROUND    Reset color (used by the GpiErase function).

   CLR_BLUE          Blue.

   CLR_RED           Red.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
  CLR_RED           Red.

   CLR_PINK          Pink.

   CLR_GREEN         Green.

   CLR_CYAN          Cyan.

   CLR_YELLOW        Yellow.

   CLR_NEUTRAL       Neutral.
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_BACKGROUND_COL_ATTR

 Comments

   The functions that draw primitives use the background-mix mode to combine
   the background color with colors already on the display surface. If the
   background-mix mode is BM_LEAVEALONE, the background color is ignored and
   existing colors remain unchanged.

 See Also

   GpiCreateLogColorTable, GpiErase, GpiPop, GpiSetBackMix


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBackMix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetBackMix (hps, lMixMode)
   HPS hps;                /*presentation-space handle                     */
   LONG lMixMode;          /*background-mix mode                           */

   The GpiSetBackMix function sets the current background-mix mode for all
   primitive types. The background-mix mode specifies how the background
   color is combined with colors in underlying primitives. The available
   background-mix modes depend on the device associated with the presentation
   space, but all devices support the BM_LEAVEALONE and BM_OVERPAINT mix
   modes. If the mix mode specified by lMixMode is not supported, the
   function uses FM_LEAVEALONE instead. The DevQueryCaps function can be used
   to determine which mix modes are supported.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   background-mix mode on the attribute stack when it sets the new mode. The
   previous background-mix mode can be retrieved by using the GpiPop
   function.

 Parameters

   hps  Identifies the presentation space.

   lMixMode  Specifies the background-mix mode. It can be one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   BM_DEFAULT        The default value (BM_LEAVEALONE).

   BM_LEAVEALONE     The background color is ignored. The existing color
                     remains unchanged.

   BM_OR             The individual pel colors are combined using the OR
                     operator.

   BM_OVERPAINT      The background color replaces the existing color.

   BM_XOR            The individual pel colors are combined using the XOR
                     operator.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_BACKGROUND_MIX_ATTR

 Comments

   The background-mix mode is used when drawing areas, images, markers, and
   characters. For areas and images, the mix mode applies to pels that are
   not set by the shading pattern. For markers, the mix mode applies to pels
   not set by the marker pattern. For characters, the mix mode applies to
   pels not set by the character pattern.

 See Also

   DevQueryCaps, GpiPop, GpiSetBackColor


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBitmap
 ────────────────────────────────────────────────────────────────────────────
   HBITMAP GpiSetBitmap (hps, hbm)
   HPS hps;                /*presentation-space handle                     */
   HBITMAP hbm;            /*bitmap handle                                 */

   The GpiSetBitmap function sets a bitmap as the current bitmap in a memory
   device context. The function sets the bitmap specified by hbm. This bitmap
   must not be set for any other device context and must not be set for area
   shading. If another bitmap is already set in the device context, the
   function releases the old bitmap and returns its handle.

   The specified presentation space must be currently associated with a
   memory device context. If the bitmap format is not the same as the device
   context, the bitmap format must be convertible to one supported by the
   device. This is guaranteed if the bitmap has one of the standard formats.

 Parameters

   hps  Identifies the presentation space.

   hbm  Identifies the bitmap to set. If it is NULL, the function releases
   the bitmap currently set in the associated device.

 Return Value

   The return value is the old bitmap handle, NULL for a null handle, or
   HBM_ERROR if an error occurred.

 See Also

   DevOpenDC, GpiCreateBitmap, GpiLoadBitmap, GpiSetBitmapId


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBitmapBits
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiSetBitmapBits (hps, iScanStart, cScans, pbBuffer, pbmi)
   HPS hps;                /*presentation-space handle                     */
   LONG iScanStart;        /*index of first scan line                      */
   LONG cScans;            /*number of scan lines                          */
   PBYTE pbBuffer;         /*pointer to buffer with bitmap data            */
   PBITMAPINFO pbmi;       /*pointer to structure with bitmap header table */

   The GpiSetBitmapBits function copies image data to a bitmap from the
   buffer pointed to by pbBuffer. The function copies the image data to the
   bitmap currently set for the presentation space. The presentation space
   must be associated with a memory device context.

   To copy the image data, the function needs the width and height of the
   bitmap, the count of planes and adjacent color bits, and the array of RGB
   color values for the bitmap pels. These values must be specified in the
   fields of the structure pointed to by pbmi. An application must make sure
   there is sufficient space in the structure to hold all elements of the
   array of RGB color values. The number of elements in the array depends on
   the format of the bitmap.

   The buffer holding the image data must have sufficient image data to set
   all pels in the bitmap. The number of bytes for the buffer is equal to the
   number of scan lines to be copied, multiplied by the width of the bitmap
   in bytes (multiplied by the number of adjacent color bits and rounded up
   to the next multiple of 4), multiplied by the number of color planes. If
   the bitmap width (in bytes) is not an exact multiple of 4, the function
   discards any extra bits. If the format of the bitmap does not match the
   device format, the function converts the bitmap. The function can convert
   standard formats only.

 Parameters

   hps  Identifies the presentation space.

   iScanStart  Specifies the number of the first scan line to copy to the
   buffer. If it is zero, the function copies the first scan line in the
   bitmap.

   cScans  Specifies the number of scan lines to copy.

   pbBuffer  Points to the buffer that contains the image data for the
   bitmap.

   pbmi  Points to the BITMAPINFO structure that contains the bitmap
   information table. The BITMAPINFO structure has the following form:

   typedef struct _BITMAPINFO {
       ULONG  cbFix;
       USHORT cx;
       USHORT cy;
       USHORT cPlanes;
       USHORT cBitCount;
       RGB    argbColor[1];
   } BITMAPINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is the number of scan lines set, or GPI_ALTERROR if an
   error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_DC_TYPE
         PMERR_INV_INFO_TABLE

 See Also

   GpiAssociate, GpiCreateBitmap, GpiLoadBitmap


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBitmapDimension
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetBitmapDimension (hbm, psizlBitmap)
   HBITMAP hbm;            /*bitmap handle                                 */
   PSIZEL psizlBitmap;     /*pointer to structure with size of bitmap      */

   The GpiSetBitmapDimension function sets the width and height of a bitmap
   (in 0.1 millimeter units). Although the system does not use the values set
   by this function, an application can retrieve the values by using the
   GpiQueryBitmapDimension function.

 Parameters

   hbm  Identifies the bitmap to be set.

   psizlBitmap  Points to the SIZEL structure that contains the width and
   height of the bitmap, in 0.1 millimeter units. The SIZEL structure has the
   following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCreateBitmap, GpiQueryBitmapDimension, GpiQueryBitmapParameters


 ────────────────────────────────────────────────────────────────────────────
 GpiSetBitmapId
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetBitmapId (hps, hbm, lcid)
   HPS hps;                /*presentation-space handle                     */
   HBITMAP hbm;            /*bitmap handle                                 */
   LONG lcid;              /*local identifier                              */

   The GpiSetBitmapId function tags the bitmap with the local identifier
   specified by lcid. The tagged bitmap can subsequently be used for area
   shading by specifying the local identifier in a call to the
   GpiSetPatternSet function. The bitmap must have a format supported by the
   device associated with the presentation space, and it must not be set in
   any other device.

   The GpiDeleteSetId function can subsequently be used to release the
   identifier.

 Parameters

   hps  Identifies the presentation space.

   hbm  Identifies the bitmap to tag.

   lcid  Specifies the local identifier for the bitmap. It can be any integer
   in the range 1 through 254 that has not already been used as a bitmap tag
   or local identifier for a logical font.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiBitBlt, GpiDeleteSetId, GpiSetBitmap, GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharAngle
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharAngle (hps, pgradlAngle)
   HPS hps;                /*presentation-space handle                     */
   PGRADIENTL pgradlAngle; /*pointer to structure with baseline angle      */

   The GpiSetCharAngle function sets the character angle. The character angle
   specifies the angle at which characters are drawn, relative to the x-axis.
   The function uses the point specified by the pgradlAngle parameter to
   compute the character angle. Any characters drawn are set on a baseline
   that is parallel to a line drawn through the specified point and the
   origin.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character angle on the attribute stack when it sets the new angle. The
   previous character angle can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   pgradlAngle  Points to the GRADIENTL structure that contains a point that
   defines the character angle. If both fields in the structure are zero, the
   function sets the character angle to the default value. The GRADIENTL
   structure has the following form:

   typedef struct _GRADIENTL {
       LONG x;
       LONG y;
   } GRADIENTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CHAR_ANGLE_ATTR

 Comments

   The character angle is used only when the character mode is CM_MODE2 or
   CM_MODE3, as set by the GpiSetCharMode function. In CM_MODE2, the system
   uses the character angle to compute the position of each character along
   the baseline. However, when the system draws a character, it places only
   the lower-left corner of the character box at the computed position. The
   orientation of the character box remains relative to the x-axis instead of
   the baseline. In CH_MODE3, the character boxes are rotated to be
   perpendicular to the character baseline. If the world-coordinate system is
   such that one x-axis unit is not physically equal to one y-axis unit, a
   rotated character string appears to be sheared.

 See Also

   GpiQueryCharAngle, GpiSetAttrMode, GpiSetAttrs, GpiSetCharMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharBox (hps, psizfxBox)
   HPS hps;                /*presentation-space handle                     */
   PSIZEF psizfxBox;       /*pointer to structure with character-box size  */

   The GpiSetCharBox function sets the current character-box attribute to the
   specified value. The character-box attribute specifies the width and
   height of the character box. The character box determines the spacing of
   consecutive characters along the baseline and the orientation of
   characters relative to the baseline.

   Both width and height can be positive, negative, or zero. When either
   value is negative, the spacing occurs in the opposite direction to normal
   and each character is drawn reflected in character-mode 3. For example, a
   negative height in the standard direction in mode 3 means that the
   characters are drawn upside down and the string is drawn below the
   baseline (assuming no other transformations cause inversion). A zero
   character width or height is also valid; in this case, the string of
   characters collapses into a line. If both values are zero, the string is
   drawn as a single point.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character-box attribute on the attribute stack when it sets the new
   character box. The previous character-box attribute can be retrieved by
   using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   psizfxBox  Points to a SIZEF structure that contains the width and height
   of the character box in world coordinates. The SIZEF structure has the
   following form:

   typedef struct _SIZEF {
       FIXED cx;
       FIXED cy;
   } SIZEF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryCharBox, GpiSetAttrMode, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharDirection
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharDirection (hps, flDirection)
   HPS hps;                /*presentation-space handle                     */
   LONG flDirection;       /*character direction                           */

   The GpiSetCharDirection function sets the character direction for drawing
   characters. The character direction specifies the direction to advance
   after drawing a character, relative to the baseline.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character direction on the attribute stack when it sets the new direction.
   The previous character direction can be retrieved by using the GpiPop
   function.

 Parameters

   hps  Identifies the presentation space.

   flDirection  Specifies the character direction. If it is CHDIRN_LEFTRIGHT,
   the character direction is from left to right. If it is CHDIRN_DEFAULT,
   the function sets the default character direction. The default is from
   left to right.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CHAR_DIRECTION_ATTR

 See Also

   GpiQueryCharDirection, GpiSetAttrMode, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharMode
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharMode (hps, flMode)
   HPS hps;                /*presentation-space handle                     */
   LONG flMode;            /*character mode                                */

   The GpiSetCharMode function sets the character mode. The character mode
   specifies which character attributes to use when drawing characters.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character mode on the attribute stack when it sets the new mode. The
   previous character mode can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   flMode  Specifies the character mode. It can be one of the following
   values:

   Value       Meaning
   ──────────────────────────────────────────────────────────────────────────
   CM_DEFAULT  Use the default.

   CM_MODE1    Use an image font, as determined by the character-set
               attribute. The positioning of characters is influenced only by
               the character-direction attribute; other character attributes
               are ignored.

   CM_MODE2    Use an image font, as determined by the character-set
               attribute. The character box, character angle, character
               direction, character shear, character spacing, character
               extra, and character break extra values are taken into
               consideration for positioning successive characters.
               Individual character definitions are not scaled or rotated.

   CM_MODE3    Use a vector font, as determined by the character-set
               attribute. All character attributes are followed exactly for
               positioning individual characters, scaling, rotating, and
               shearing.
   ──────────────────────────────────────────────────────────────────────────

   If the specified mode is not valid, the default is used.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CHAR_MODE_ATTR

 See Also

   GpiQueryAttrMode, GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharSet
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharSet (hps, lcid)
   HPS hps;                /*presentation-space handle                     */
   LONG lcid;              /*local identifier                              */

   The GpiSetCharSet function sets the current value of the character-set
   attribute. The character-set attribute specifies the logical font to use
   for drawing character strings. The logical font, specified by the lcid
   parameter, must have been previously created using the GpiCreateLogFont
   function.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character set on the attribute stack when it sets the new character set.
   The previous character set can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   lcid  Specifies the local identifier for a logical font. It can be any
   value in the range 1 through 254 that has been previously set as a local
   identifier for a logical font. If it is zero, the function sets the
   character-set attribute to the default character set.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CHAR_SET_ATTR

 See Also

   GpiQueryCharSet, GpiSetAttrMode, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCharShear
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCharShear (hps, pptlShear)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlShear;      /*pointer to structure with shear angle         */

   The GpiSetCharShear function sets the character-shear attribute. The
   character shear specifies how much to shear (tilt) characters from their
   normal vertical orientation. The function uses the coordinates of the
   point specified by pptlShear as the end point of a line originating at
   (0,0). The vertical strokes in subsequent character strings are drawn
   parallel to the line. The top of the character box remains parallel to the
   character baseline.

   The system draws upright characters if pptlShear specifies the point
   (0,1). This is the default character-shear attribute. If coordinates in
   the point are both positive or both negative, the characters slope from
   bottom-left to top-right. If the coordinates have opposite signs (one is
   positive and one is negative), the characters slope from top-left to
   bottom-right. Zero should not be used for the y-coordinate since it
   implies an infinite shear. However, if both coordinates are zero, the
   attribute is set to the default value.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   character-shear attribute on the attribute stack when it sets the new
   character shear. The previous character-shear attribute can be retrieved
   by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   pptlShear  Points to a POINTL structure that contains a point that defines
   the character shear. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CHAR_SHEAR_ATTR

 See Also

   GpiQueryCharShear, GpiSetAttrMode, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetClipPath
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetClipPath (hps, idPath, cmdOptions)
   HPS hps;                /*presentation-space handle                     */
   LONG idPath;            /*clip path identifier                          */
   LONG cmdOptions;        /*options                                       */

   The GpiSetClipPath function sets the clip path. The clip path specifies a
   path in device space that the system uses to clip output. The clip path
   includes all points inside and on the boundary of the path specified by
   idPath. Since the path coordinates are assumed to be device coordinates,
   no conversion is applied.

   The function creates the clip path by closing any open figures. It then
   releases any existing clip path (deleting the previous path, if any), and
   sets the specified path as the clip path. After a path is set as the clip
   path, it cannot be used again. However, its identifier is free to use for
   another path.

 Parameters

   hps  Identifies the presentation space.

   idPath  Specifies the identifier of the path to set to the clip path. It
   can be 1 to specify a path or zero to specify no clip path.

   cmdOptions  Specifies the filling and combining modes. It can be one or
   two of the following values:

   Value         Meaning
   ──────────────────────────────────────────────────────────────────────────
   SCP_ALTERNATE Computes the interior of the clip path, using alternate
                 mode. This is the default if neither SCP_ALTERNATE nor
                 SCP_WINDING is given.

   SCP_AND       Intersects the specified path with the current clip path.
                 This value must be specified if the idPath parameter is 1.

   SCP_RESET     Resets the clip path, releasing the current clip path if
                 any. This value must be specified if the idPath parameter is
                 0. This is the default if neither SCP_AND nor SCP_RESET is
                 given.

   SCP_WINDING   Computes the interior of the clip path, using winding mode.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_PATH_ID
         PMERR_PATH_UNKNOWN

 Comments

   Unless the segments in the picture chain have the fast-chaining attribute,
   the system releases the clip path when it draws each segment. Also, the
   GpiResetPS function releases the current clip path.

 See Also

   GpiBeginArea, GpiQueryClipBox, GpiResetPS


 ────────────────────────────────────────────────────────────────────────────
 GpiSetClipRegion
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiSetClipRegion (hps, hrgn, phrgn)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   PHRGN phrgn;            /*pointer to variable for previous region       */
                           /*handle                                        */

   The GpiSetClipRegion function sets the clip region. The clip region
   specifies a region in device space that the system uses to clip output.
   The clip region includes all points inside and on the boundary of the
   region specified by hrgn. Since the region coordinates are assumed to be
   device coordinates, no conversion is applied.

   The function creates the clip region by releasing the previous clip
   region, copying the handle of this region to the variable pointed to by
   phrgn, and setting the specified region as the clip region. Once a region
   is set as the clip region, it cannot be used in subsequent region
   operations. Once released from the clipping region, a region can be used
   again to restore the previous clip region.

 Parameters

   hps  Identifies the presentation space. The presentation space must be
   currently associated with the device context for which the specified
   regions were created.

   hrgn  Identifies the region. If the hrgn parameter is NULL, the function
   releases any previous clip region and sets no clip region.

   phrgn  Points to the variable that receives the handle of the previous
   region. If no previous clip region exists, the function copies NULL to the
   variable.

 Return Value

   The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is
   successful, or RGN_ERROR if an error occurred.

 See Also

   GpiCreateRegion, GpiOffsetClipRegion


 ────────────────────────────────────────────────────────────────────────────
 GpiSetColor
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetColor (hps, clr)
   HPS hps;                /*presentation-space handle                     */
   LONG clr;               /*color value                                   */

   The GpiSetColor function sets the current foreground color for all
   primitive types. The foreground color specifies the color used to draw the
   foreground of the primitive, such as the dashes in a styled line or the
   diagonal bars in a diagonal shading pattern. The function sets the
   foreground color to the color specified by clr. The clr parameter is
   either an RGB color value or a color index value, depending on the current
   logical color table. The actual color the clr parameter represents also
   depends on the current logical color table.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   foreground color on the attribute stack when it sets the new color. The
   previous foreground color can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   clr  Specifies the color. The values depend on the current logical color
   table. If the logical color table has been created using the LCOLF_RGB,
   the values must be RGB color values. Otherwise, the values must be
   color-index values. If the default logical color table is used, the
   parameter can be any one of the following standard color-index values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   CLR_FALSE             All color planes are zeros.

   CLR_TRUE              All color planes are ones.

   CLR_DEFAULT           Default value; same as CLR_NEUTRAL.

   CLR_WHITE             White.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  CLR_WHITE             White.

   CLR_BLACK             Black.

   CLR_BACKGROUND        Reset color (used by the GpiErase function).

   CLR_BLUE              Blue.

   CLR_RED               Red.

   CLR_PINK              Pink.

   CLR_GREEN             Green.

   CLR_CYAN              Cyan.

   CLR_YELLOW            Yellow.

   CLR_NEUTRAL           Neutral.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  CLR_NEUTRAL           Neutral.

   CLR_DARKGRAY          Dark gray.

   CLR_DARKBLUE          Dark blue.

   CLR_DARKRED           Dark red.

   CLR_DARKPINK          Dark pink.

   CLR_DARKGREEN         Dark green.

   CLR_DARKCYAN          Dark cyan.

   CLR_BROWN             Brown.

   CLR_PALEGRAY          Light gray.
   ──────────────────────────────────────────────────────────────────────────

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_COLOR_ATTR

 Comments

   The CLR_BACKGROUND color for the default logical color table is the
   natural background color for the device (for example, the paper color for
   a printer). For the display, the CLR_BACKGROUND color is the default
   window color as set by the WinSetSysColors function. The CLR_NEUTRAL color
   for the default logical color table is a device-dependent color that
   provides a contrasting color to CLR_BACKGROUND (for example, it is the ink
   color for a one-color printer). For the display, it is the default
   window-text color.

 See Also

   GpiErase, GpiPop, GpiQueryAttrs, GpiQueryColor, GpiSetAttrMode,
   GpiSetAttrs, GpiSetMix WinSetSysColors


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCp
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCp (hps, idcp)
   HPS hps;                /*presentation-space handle                     */
   USHORT idcp;            /*code-page identifier                          */

   The GpiSetCp function selects the code-page identifier to be used for
   graphics characters for the default character set.

   When a presentation space is first created, the code page used is the one
   defined by the process code page, as set by the DosSetProcCp function.

 Parameters

   hps  Identifies the presentation space.

   idcp  Specifies the code-page identifier. The WinQueryCpList function can
   be used to find which code pages are available.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_CODEPAGE

 See Also

   DosSetProcCp, GpiQueryCp, WinQueryCpList


 ────────────────────────────────────────────────────────────────────────────
 GpiSetCurrentPosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetCurrentPosition (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure with new position        */

   The GpiSetCurrentPosition function sets the current position to the
   specified point. When used in an area bracket, the function closes the
   current open figure (if any) and marks the start of a new figure.

   This function is equivalent to the GpiMove function, except that, if the
   current attribute mode is AM_PRESERVE (see the GpiSetAttrMode function),
   the function saves the current position before setting it to the new
   value. It can be restored by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to the POINTL structure that contains the new value of the
   current position. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiMove, GpiPop, GpiQueryCurrentPosition, GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetDefaultViewMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetDefaultViewMatrix (hps, cElements, pmatlf, flType)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure with transform matrix    */
   LONG flType;            /*transformation type                           */

   The GpiSetDefaultViewMatrix function sets the default viewing
   transformation. The function sets the transformation by adding or
   replacing the existing transformation matrix with the matrix pointed to by
   the pmatlf parameter. The function adds, preempts, or replaces the
   existing transformation matrix as specified by the flType parameter.

   The GpiSetDefaultViewMatrix function requires a nine-element matrix to set
   the default viewing transformation. If the specified matrix does not
   contain nine elements, the function uses the corresponding elements of the
   identity matrix for each unspecified element. The cElements parameter
   specifies the number of elements in the matrix. If this parameter equals
   zero, the identity matrix is used.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements in the matrix to set. It can
   be any integer in the range 0 to 9.

   pmatlf  Points to a MATRIXLF structure that contains the transformation
   matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flType  Specifies how a specified transformation matrix should be used to
   modify the default viewing transformation. It can be one of the following
   values:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   TRANSFORM_ADD         Additive. The specified transformation matrix is
                         combined with the existing default viewing
                         transformation, in the order of the existing
                         transformation first, the new transformation second.
                         This option is useful for incremental updates to
                         transformations.

   TRANSFORM_PREEMPT     Preemptive. The specified transformation matrix is
                         combined with the existing default viewing
                         transformation, in the order of the new
                         transformation first, the existing transformation
                         second.

   TRANSFORM_REPLACE     New/replace. The previous default viewing
                         transformation is discarded and replaced by the
                         specified transformation matrix.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_TRANSFORM_TYPE

 See Also

   GpiQueryDefaultViewMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiSetDrawControl
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetDrawControl (hps, lControl, flDraw)
   HPS hps;                /*presentation-space handle                     */
   LONG lControl;          /*draw control to change                        */
   LONG flDraw;            /*drawing flag                                  */

   The GpiSetDrawControl function sets the current draw controls. The draw
   controls specify whether the system carries out certain actions, such as
   accumulating boundary data, when the application draws. The function sets
   the draw control specified by the lControl parameter by turning it on or
   off as specified by the flDraw parameter. By default, all draw controls
   except DCTL_DISPLAY are off.

   The function cannot be used in an open segment or in an area, path, or
   element bracket.

 Parameters

   hps  Identifies the presentation space.

   lControl  Specifies the draw control to set. It can be one of the
   following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   DCTL_BOUNDARY         Accumulate boundary data. During any output
                         operations except GpiErase, accumulate the bounding
                         rectangle of the drawing. This control can be used
                         with a micro presentation space.

   DCTL_CORRELATE        Correlate the GpiPutData, GpiElement, and primitive
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  DCTL_CORRELATE        Correlate the GpiPutData, GpiElement, and primitive
                         functions. This control causes these functions to
                         return GPI_HITS if the drawing intersects with the
                         pick aperture. This control applies only to
                         drawing functions used when the drawing mode is
                         DM_DRAW or DM_DRAWANDRETAIN. Also, it does not
                         effect execution of functions stored in a segment.
                         This control can be used with a micro presentation
                         space.

   DCTL_DISPLAY          Allow drawing to occur on the device. If this
                         control is off, no output, other than output for
                         GpiErase, appears on the device associated with the
                         presentation space. This control can be used with a
                         micro presentation space.

   DCTL_DYNAMIC          Draw dynamic segments. This control causes the
                         GpiDrawChain, GpiDrawFrom, and GpiDrawSegment
                         functions to call the GpiRemoveDynamics function
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        functions to call the GpiRemoveDynamics function
                         before drawing and the GpiDrawDynamics function
                         after drawing. The effect is to update the dynamic
                         segments each time the picture chain or a segment is
                         drawn.

   DCTL_ERASE            Erasing before drawing. This control causes the
                         GpiDrawChain, GpiDrawFrom, and GpiDrawSegment
                         functions to call the GpiErase function before
                         drawing.
   ──────────────────────────────────────────────────────────────────────────


   flDraw  Specifies whether to turn a draw control on or off. It can be one
   of the following values:

   Value         Meaning
   ──────────────────────────────────────────────────────────────────────────
   DCTL_OFF      Set control off.

   DCTL_ON       Set control on.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_DRAW_CONTROL
         PMERR_INV_DRAW_VALUE
         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiDrawChain, GpiDrawDynamics, GpiDrawFrom, GpiDrawSegment,
   GpiElement, GpiErase, GpiPutData, GpiQueryDrawControl,
   GpiRemoveDynamics


 ────────────────────────────────────────────────────────────────────────────
 GpiSetDrawingMode
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetDrawingMode (hps, flMode)
   HPS hps;                /*presentation-space handle                     */
   LONG flMode;            /*drawing mode                                  */

   The GpiSetDrawingMode function sets the drawing mode. The drawing mode
   affects all subsequent drawing and attribute functions, including the
   GpiPutData function, that occur in open chained segments. The drawing mode
   specifies whether the functions are drawn, retained, or drawn and
   retained.

   The drawing mode does not affect the functions in unchained segments or
   outside of segments. For chained segments, the system stores the functions
   if the DM_RETAIN or DM_DRAWANDRETAIN mode is set. If the DM_DRAWANDRETAIN
   mode is set, the system draws as well as stores the functions. If the mode
   is DM_DRAW, the functions draw only. For unchained segments, drawing and
   attribute functions are always retained regardless of the drawing mode.
   Outside of segments, the functions draw only.

   The function cannot be used in an open segment or in an area, path, or
   element bracket.

 Parameters

   hps  Identifies the presentation space.

   flMode  Specifies the mode used for subsequent drawing and attribute
   functions. It can be one of the following values:

   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────
   DM_DRAW              Draw only.

   DM_RETAIN            Retain only.

   DM_DRAWANDRETAIN     Draw and retain.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_DRAWING_MODE
         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiCloseSegment, GpiOpenSegment, GpiPutData, GpiQueryDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetEditMode
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetEditMode (hps, flEditMode)
   HPS hps;                /*presentation-space handle                     */
   LONG flEditMode;        /*editing mode                                  */

   The GpiSetEditMode function sets the current editing mode. The editing
   mode specifies whether new elements added to a retained segment are
   inserted into the segment or whether they replace existing elements. The
   default editing mode (set by the GpiCreatePS or GpiResetPS function) is
   insert.

   Although the editing mode applies to retained segments only, the
   GpiSetEditMode function can be used to change the editing mode at any
   time, regardless of the drawing mode. However, the function cannot be used
   in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   flEditMode  Specifies the editing mode. It can be one of the following
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   SEGEM_INSERT      Insert. The system inserts a new element after the
                     element pointed to by the element pointer. The element
                     pointer is updated to point to the new element.

   SEGEM_REPLACE     Replace. The system replaces the element pointed by the
                     element pointer. The element pointer does not change.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_EDIT_MODE
         PMERR_INV_MICROPS_FUNCTION

 See Also

   GpiCreatePS, GpiQueryEditMode, GpiResetPS,
   GpiSetElementPointerAtLabel


 ────────────────────────────────────────────────────────────────────────────
 GpiSetElementPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetElementPointer (hps, idElement)
   HPS hps;                /*presentation-space handle                     */
   LONG idElement;         /*element number                                */

   The GpiSetElementPointer function moves the element pointer to the element
   specified by idElement. The function uses idElement as the number of
   elements to move from the beginning of the segment to reach the new
   element.

   The function can be used only in an open segment and only with DM_RETAIN
   as the drawing mode. The function cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   idElement  Specifies the element number. If the element number is
   negative, the element pointer is set to zero. If the value is greater than
   the number of elements in the segment, the element pointer is set to the
   last element.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_NOT_IN_RETAIN_MODE

 See Also

   GpiQueryElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiSetElementPointerAtLabel
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetElementPointerAtLabel (hps, idLabel)
   HPS hps;                /*presentation-space handle                     */
   LONG idLabel;           /*label identifier                              */

   The GpiSetElementPointerAtLabel function moves the element pointer to the
   element containing the specified label. The function starts the search at
   the next element after the current element-pointer position. If the
   function does not find the label before reaching the end of the segment,
   the function leaves the element pointer unchanged and returns an error.

   The function can be used only in an open segment and only with DM_RETAIN
   drawing mode. The function cannot be used in an element bracket.

 Parameters

   hps  Identifies the presentation space.

   idLabel  Specifies the label.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_LABEL_NOT_FOUND
         PMERR_NOT_IN_RETAIN_MODE

 See Also

   GpiLabel, GpiQueryElementPointer


 ────────────────────────────────────────────────────────────────────────────
 GpiSetGraphicsField
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetGraphicsField (hps, prclField)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclField;       /*pointer to structure with field               */

   The GpiSetGraphicsField function sets the size and position of the
   graphics field in presentation-page units. The graphics field defines the
   rectangle in the presentation page to clip. Any output outside the
   graphics field is not drawn on the device.

   The graphics field includes all points in the rectangle interior and all
   points on the lower and left edges, but not the points on the upper and
   right edges. Initially, the graphics field has the same size as the page
   space. The units for the graphics field are not affected by any
   transformation except the final device transformation.

 Parameters

   hps  Identifies the presentation space.

   prclField  Points to a RECTL structure containing the graphics field. It
   is an error if the top coordinate is less than the bottom, or the right
   coordinate less than the left. All values must be presentation-page units.
   The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryGraphicsField


 ────────────────────────────────────────────────────────────────────────────
 GpiSetInitialSegmentAttrs
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetInitialSegmentAttrs (hps, flAttribute, flAttrFlag)
   HPS hps;                /*presentation-space handle                     */
   LONG flAttribute;       /*attribute type                                */
   LONG flAttrFlag;        /*attribute on/off flag                         */

   The GpiSetInitialSegmentAttrs function sets the initial segment
   attributes. The system applies these attributes to each new segment as it
   is created. The function can change these attributes, one at a time, by
   turning them on or off.

   When the presentation space is first created, the initial segment
   attributes create visible, chained, dynamic, and fast-chaining segments
   that propagate visibility and detectability, even though they are not
   detectable. These attribute have no effect on primitives outside of
   segments.

 Parameters

   hps  Identifies the presentation space.

   flAttribute  Specifies the segment attribute to change. It can be one of
   the following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   ATTR_CHAINED          Adds the segment to the picture chain. If this
                         attribute is off, a new segment is an unchained
                         segment. Although unchained segments can be drawn
                         individually, they cannot be added to the picture
                         chain. (However, they can be called from a segment
                         in the picture chain.)

   ATTR_DETECTABLE       Enables correlation for the segment. If this
                         attribute is on, the GpiCorrelateChain,
                         GpiCorrelateFrom, and GpiCorrelateSegment functions
                         can be used to correlate each new segment.

   ATTR_DYNAMIC          Creates a dynamic segment. Dynamic segments are
                         designed to be rapidly updated without affecting
                         other segments in the picture chain. The system
                         draws dynamic segments using the exclusive-OR
                         operator. This lets the segments be erased. Only
                         retained segments can be dynamic.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   ATTR_FASTCHAIN        Relaxes the automatic reset of primitive attributes
                         for the segment. If this attribute is off, the
                         system resets all primitive attributes just before a
                         segment in the picture chain is drawn.

   ATTR_PROP_DETECTABLE  Forces all segments beneath the segment to inherit
                         the detectable attribute. If this attribute is on,
                         all segments called by the segment can be
                         correlated.

   ATTR_PROP_VISIBLE     Forces all segments beneath the segment to be
                         visible. The visibility lasts only as long as the
                         segment is called by the segment with this attribute
                         on.

   ATTR_VISIBLE          Makes the segment visible. The attribute lets the
                         system draw the segment on the output device.
   ──────────────────────────────────────────────────────────────────────────
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  ──────────────────────────────────────────────────────────────────────────


   flAttrFlag  Specifies whether to turn the attribute on or off. If it is
   ATTR_ON, the function turns the attribute on. If it is ATTR_OFF, the
   function turns the attribute off.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_ATTR

 See Also

   GpiCorrelateChain, GpiCorrelateFrom, GpiCorrelateSegment,
   GpiOpenSegment, GpiSetDrawControl, GpiSetDrawingMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetLineEnd
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetLineEnd (hps, lLineEnd)
   HPS hps;                /*presentation-space handle                     */
   LONG lLineEnd;          /*line end                                      */

   The GpiSetLineEnd function sets the current line-end attribute. The
   line-end attribute specifies the shape of the ends of lines drawn by the
   GpiStrokePath function or by the GpiModifyPath and GpiFillPath function
   pair.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   line-end attribute on the attribute stack when it sets the new line end.
   The previous line-end attribute can be retrieved by using the GpiPop
   function.

 Parameters

   hps  Identifies a presentation space.

   lLineEnd  Specifies the line end. It may be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LINEEND_DEFAULT   Use default.

   LINEEND_FLAT      Flat. The line is ended at the end point of the original
                     path.

   LINEEND_ROUND     Round. The line is ended as if a circle having a
                     diameter equal to the line width is drawn centered on
                     the end point of the original path.

   LINEEND_SQUARE    Square. The line is ended as if a square having the same
                     width as the line is drawn centered on the end point of
                     the original path.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if the function is successful. Otherwise, it is
   FALSE, indicating that an error occurred.

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_LINE_END_ATTR

 See Also

   GpiFillPath, GpiModifyPath, GpiPop, GpiQueryAttrs, GpiQueryLineEnd,
   GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetLineJoin
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetLineJoin (hps, flLineJoin)
   HPS hps;                /*presentation-space handle                     */
   LONG flLineJoin;        /*line-join flags                               */

   The GpiSetLineJoin function sets the current line-join attribute to the
   specified value. The line-join attribute specifies how the intersection of
   lines (at the end points) are drawn by the GpiStrokePath function or by
   the GpiModifyPath and GpiFillPath function pair.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   line-join attribute on the attribute stack when it sets the new line join.
   The previous line-join attribute can be retrieved by using the GpiPop
   function.

 Parameters

   hps  Identifies the presentation space.

   flLineJoin  Specifies line-join flags. It can be one of the following
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LINEJOIN_BEVEL    Bevel

   LINEJOIN_DEFAULT  Default

   LINEJOIN_MITRE    Mitre

   LINEJOIN_ROUND    Round
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_LINE_JOIN_ATTR

 See Also

   GpiFillPath, GpiModifyPath, GpiPop, GpiQueryAttrs, GpiQueryLineJoin,
   GpiSetAttrMode, GpiSetAttrs, GpiStrokePath


 ────────────────────────────────────────────────────────────────────────────
 GpiSetLineType
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetLineType (hps, flLineType)
   HPS hps;                /*presentation-space handle                     */
   LONG flLineType;        /*line type                                     */

   The GpiSetLineType function sets the current cosmetic line-type attribute
   to the specified value.

 Parameters

   hps  Identifies the presentation space.

   flLineType  Specifies the line type. If the specified line type is not
   valid, the default is used. A valid line type is one of the following:

         LINETYPE_DOT
         LINETYPE_SHORTDASH
         LINETYPE_DASHDOT
         LINETYPE_DOUBLEDOT
         LINETYPE_LONGDASH
         LINETYPE_DASHDOUBLEDOT
         LINETYPE_SOLID
         LINETYPE_INVISIBLE
         LINETYPE_ALTERNATE

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_LINE_TYPE_ATTR

 Comments

   A non-solid line type consists of a sequence of on-and-off runs that gives
   the appearance of a dotted line.

   This attribute specifies the cosmetic line type, which is used for all
   line and curve drawing. It does not depend on transforms. For example,
   dashes do not become longer if a "zoom in" occurs.

   The eight standard line types are implemented on each device to give a
   good appearance based on the "pel" resolution. Their definitions cannot be
   changed by applications, nor can applications define additional cosmetic
   line types.

   The system maintains position within the line-type definition. For
   example, a curve may be implemented as a polyline. However, the following
   functions cause the position to be reset:

         GpiCallSegmentMatrix
         GpiMove
         GpiPop
         GpiSetCurrentPosition
         GpiSetModelTransformMatrix
         GpiSetPageViewport
         GpiSetSegmentTransformMatrix

   The attribute mode (see GpiSetAttrMode) determines whether the current
   value of the line type attribute is preserved.

 See Also

   GpiQueryAttrs, GpiQueryLineType, GpiSetAttrMode, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetLineWidth
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetLineWidth (hps, fxLineWidth)
   HPS hps;                /*presentation-space handle                     */
   FIXED fxLineWidth;      /*line width                                    */

   The GpiSetLineWidth function sets the current cosmetic line-width
   attribute to the specified value. The line width specifies the width of
   cosmetic lines, that is, lines drawn by functions such as GpiLine. The
   function treats the line width as a multiplier for the normal line
   thickness for the device.

   If the attribute mode is AM_PRESERVE, the function saves the previous line
   width on the attribute stack when it sets the new width. The previous line
   width can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   fxLineWidth  Specifies the line-width multiplier. It must be a fixed-point
   number or one of the following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   LINEWIDTH_DEFAULT   Default

   LINEWIDTH_NORMAL    Normal width (1.0)
   ──────────────────────────────────────────────────────────────────────────

   Any other positive value is a multiplier on the normal line width. Only
   normal line widths are currently supported. Any value greater than
   LINEWIDTH_NORMAL will result in a warning.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_LINE_WIDTH_ATTR

 Comments

   The thickness of cosmetic lines is not affected by transformations.

 See Also

   GpiLine, GpiPop, GpiQueryAttrs, GpiQueryLineWidth, GpiSetAttrMode,
   GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetLineWidthGeom
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetLineWidthGeom (hps, lLineWidth)
   HPS hps;                /*presentation-space handle                     */
   LONG lLineWidth;        /*line width                                    */

   The GpiSetLineWidthGeom function sets the current geometric-line-width
   attribute to the specified value. The geometric line width specifies the
   width of lines drawn by using the GpiStrokePath function or the
   GpiModifyPath and GpiFillPath pair.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   geometric-line width on the attribute stack when it sets the new width.
   The previous geometric-line width can be retrieved using the GpiPop
   function.

 Parameters

   hps  Identifies the presentation space.

   lLineWidth  Specifies the geometric-line width in world coordinates. This
   value cannot be negative. If it is zero, the resulting line has zero
   width.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_GEOM_LINE_WIDTH_ATTR

 See Also

   GpiFillPath, GpiModifyPath, GpiPop, GpiQueryAttrs,
   GpiQueryLineWidthGeom, GpiSetAttrMode, GpiSetAttrs, GpiStrokePath


 ────────────────────────────────────────────────────────────────────────────
 GpiSetMarker
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetMarker (hps, lSymbol)
   HPS hps;                /*presentation-space handle                     */
   LONG lSymbol;           /*marker symbol                                 */

   The GpiSetMarker function sets the value of the marker attribute. The
   marker attribute specifies the marker drawn by the GpiMarker function.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   marker attribute on the attribute stack when it sets the new marker. The
   previous marker attribute can be retrieved by using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   lSymbol  Specifies the identity of the required marker symbol. Zero
   selects the default marker symbol; a value in the range 1 through 255
   identifies a symbol in the current marker set. If the default maker set is
   used, the parameter can be one of the following values:

╓┌─┌───────────────────────┌─────────────────────────────────────────────────╖
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   MARKSYM_CROSS           Cross
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   MARKSYM_CROSS           Cross

   MARKSYM_PLUS            Plus sign

   MARKSYM_DIAMOND         Diamond

   MARKSYM_SQUARE          Square

   MARKSYM_SIXPOINTSTAR    Six-pointed star

   MARKSYM_EIGHTPOINTSTAR  Eight-pointed star

   MARKSYM_SOLIDDIAMOND    Solid diamond

   MARKSYM_SOLIDSQUARE     Solid square

   MARKSYM_DOT             Dot

   MARKSYM_SMALLCIRCLE     Small circle
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
  MARKSYM_SMALLCIRCLE     Small circle

   MARKSYM_BLANK           Blank (nothing drawn)
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiMarker, GpiPop, GpiQueryMarker


 ────────────────────────────────────────────────────────────────────────────
 GpiSetMarkerBox
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetMarkerBox (hps, psizfxBox)
   HPS hps;                /*presentation-space handle                     */
   PSIZEF psizfxBox;       /*pointer to structure with marker box size     */

   The GpiSetMarkerBox function sets the current marker-box attribute. The
   marker box specifies the width and height of markers drawn by the
   GpiMarker function.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   marker-box attribute on the attribute stack when it sets the new marker
   box. The previous marker-box attribute can be retrieved by using the
   GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   psizfxBox  Points to a SIZEF structure containing the size of the marker
   box, in world coordinates. The SIZEF structure has the following form:

   typedef struct _SIZEF {
       FIXED cx;
       FIXED cy;
   } SIZEF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MARKER_BOX_ATTR

 See Also

   GpiQueryAttrs, GpiQueryMarkerBox, GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetMarkerSet
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetMarkerSet (hps, lcid)
   HPS hps;                /*presentation-space handle                     */
   LONG lcid;              /*local identifier                              */

   The GpiSetMarkerSet function sets the current marker-set attribute. The
   marker-set attribute specifies the marker or character set from which
   markers can be chosen. The marker set can be the default marker set or any
   logical font created by using the GpiCreateLogFont function.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   marker-set attribute on the attribute stack when it sets the new marker
   set. The previous marker-set attribute can be retrieved by using the
   GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   lcid  Specifies the logical identifier for the marker set. It can be any
   integer in the range 1 to 254 for which a logical font has be created, or
   it can be LCID_DEFAULT to specify the default marker set.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MARKER_SET_ATTR

 See Also

   GpiCreateLogFont, GpiPop, GpiQueryAttrs, GpiQueryMarkerSet,
   GpiSetAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetMetaFileBits
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetMetaFileBits (hmf, off, cbBuffer, pbBuffer)
   HMF hmf;                /*message-queue handle                          */
   LONG off;               /*offset into the metafile                      */
   LONG cbBuffer;          /*length of the metafile data                   */
   PBYTE pbBuffer;         /*pointer to the metafile data                  */

   The GpiSetMetaFileBits function copies data to the metafile specified by
   hmf from the buffer pointed to by the pbBuffer parameter. The function
   inserts the bytes into the metafile, up to the number of bytes specified
   by cbBuffer, at the byte in the metafile where the offset from the
   beginning of the metafile is specified by the off parameter.

   The application must ensure that the metafile data has the correct format.
   The data should not be changed after it is created by the
   GpiQueryMetaFileBits function.

 Parameters

   hmf  Identifies the metafile memory.

   off  Specifies the offset in bytes from the beginning of the metafile to
   the first byte that receives copied data.

   cbBuffer  Specifies the number of bytes of metafile data to copy.

   pbBuffer  Points to the buffer to receive the metafile data. It must have
   the number of bytes specified by the cbBuffer parameter.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_METAFILE_LENGTH
         PMERR_INV_METAFILE_OFFSET

 See Also

   GpiQueryMetaFileBits


 ────────────────────────────────────────────────────────────────────────────
 GpiSetMix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetMix (hps, flMixMode)
   HPS hps;                /*presentation-space handle                     */
   LONG flMixMode;         /*color-mixing mode                             */

   The GpiSetMix function sets the current foreground-mix mode. The
   foreground-mix mode specifies how the foreground color is combined with
   the colors in underlying primitives. The available mixing modes depend on
   the device that is associated with the presentation space, but all devices
   support the mix- ing modes FM_LEAVEALONE, FM_XOR, and FM_OVERPAINT. If the
   mixing mode specified by flMixMode is not supported, the function uses
   FM_OVERPAINT instead. The DevQueryCaps function can be used to determine
   which mixing modes are supported.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   foreground-mix mode on the attribute stack when it sets the new mode. Thep
   previous foreground-mix mode can be retrieved using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   flMixMode  Specifies the color-mixing mode. It can be one of the following
   values:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   FM_AND            The individual pel colors are combined using the AND
                     operator.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    operator.

   FM_DEFAULT        Default. This is the same as FM_OVERPAINT.

   FM_INVERT         All existing pel colors are inverted. The foreground
                     color is ignored.

   FM_LEAVEALONE     The foreground color is ignored. The existing color
                     remains unchanged.

   FM_MASKSRCNOT     The individual pel colors are combined using the AND
                     operator after inverting the existing pel colors.

   FM_MERGENOTSRC    The individual pel colors are combined using the OR
                     operator after inverting the foreground color.

   FM_MERGESRCNOT    The individual pel colors are combined using the OR
                     operator after inverting the existing pel colors.

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────

   FM_NOTCOPYSRC     The inverse of the foreground color replaces the
                     existing color.

   FM_NOTMASKSRC     The individual pel colors are inverted after being
                     combined using the AND operator.

   FM_NOTMERGESRC    The individual pel colors are inverted after being
                     combined using the OR operator.

   FM_NOTXORSRC      The individual pel colors are inverted after being
                     combined using the XOR operator.

   FM_ONE            All pels are set to one.

   FM_OR             The individual pel colors are combined using the OR
                     operator.

   FM_OVERPAINT      The foreground color replaces the existing color.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
  FM_OVERPAINT      The foreground color replaces the existing color.

   FM_SUBTRACT       The individual pel colors are combined using the AND
                     operator after inverting the foreground color.

   FM_XOR            The individual pel colors are combined using the XOR
                     operator.

   FM_ZERO           All pels are set to zero.
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   DevQueryCaps, GpiQueryMix, GpiSetBackMix


 ────────────────────────────────────────────────────────────────────────────
 GpiSetModelTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetModelTransformMatrix (hps, cElements, pmatlf, flType)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure with transformation      */
                           /*matrix                                        */
   LONG flType;            /*transformation types                          */

   The GpiSetModelTransformMatrix function sets the model transformation. The
   model transformation applies to all primitives used inside and outside of
   segments. The function sets the transformation by adding or replacing the
   existing transformation matrix with the matrix pointed to by the pmatlf
   parameter. The function adds, preempts, or replaces the existing
   transformation matrix as specified by the flType parameter.

   The GpiSetModelTransformMatrix function requires a nine-element matrix to
   set the model transformation. If the specified matrix does not contain
   nine elements, the function uses the corresponding elements of the
   identity matrix for each unspecified element. The cElements parameter
   specifies the number of elements in the matrix. If this parameter equals
   zero, the identity matrix is used. If scaling values greater than one are
   given, care must be taken that the combined effect of this and any other
   relevant transformations do not exceed the limit for fixed-point numbers.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   model transformation on the attribute stack when it sets the new
   transformation. The previous model transformation can be retrieved using
   the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements in the matrix to set. It can
   be any integer in the range 0 through 9.

   pmatlf  Points to a MATRIXLF structure that contains the transformation
   matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see the "Structures" section.

   flType  Specifies how a specified matrix should be used to modify the
   segment transformation. It can be one of the following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   TRANSFORM_ADD       Additive. The specified transformation matrix is
                       combined with the existing model transformation, in
                       the order of the existing transformation first, the
                       new transformation second. This option is useful for
                       incremental updates to transformations.

   TRANSFORM_PREEMPT   Preemptive. The specified transformation matrix is
                       combined with the existing model transformation, in
                       the order of the new transformation first, the
                       existing transformation second.

   TRANSFORM_REPLACE   New/replace. The previous model transformation is
                       discarded and replaced by the specified transformation
                       matrix.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_TRANSFORM_TYPE

 See Also

   GpiQueryModelTransformMatrix, GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPageViewport
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPageViewport (hps, prclViewport)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclViewport;    /*pointer to structure with page viewport       */

   The GpiSetPageViewport function sets the page viewport within device
   space. The page viewport and the presentation page size (specified by the
   GpiCreatePS function) specify the device transformation.

   The function can only be used if the presentation space has an associated
   device context.

 Parameters

   hps  Identifies the presentation space.

   prclViewport  Points to a RECTL structure defining the page viewport in
   device units. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Comments

   When a presentation space is associated with a device context, the system
   sets a default page viewport. The default page viewport depends on the
   page units selected for the presentation space.

 See Also

   GpiCreatePS, GpiQueryPageViewport


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPattern
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPattern (hps, lSymbol)
   HPS hps;                /*presentation-space handle                     */
   LONG lSymbol;           /*shading pattern                               */

   The GpiSetPattern function sets the current value of the pattern
   attribute. The pattern attribute specifies the shading pattern used to
   fill areas. The pattern can be any pattern from the default pattern set or
   any character from a raster font. If the specified pattern is not valid
   for the device associated with the presentation space, the function sets
   the default pattern.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   pattern attribute on the attribute stack when it sets the new pattern. The
   previous pattern attribute can be retrieved using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   lSymbol  Specifies the shading pattern to set. The values depend on the
   particular pattern set selected by the pattern-set attribute. It can be
   zero to specify the default pattern, or a number in the range 1 through
   255 to specify a particular pattern from the current pattern set. If the
   default pattern set is used, it can be one of the following values:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   PATSYM_BLANK        Blank pattern (background only)

   PATSYM_DEFAULT      Default pattern (device-dependent)

   PATSYM_DENSE1       Density-1 pattern (mostly foreground)

   PATSYM_DENSE2       Density-2 pattern

   PATSYM_DENSE3       Density-3 pattern

   PATSYM_DENSE4       Density-4 pattern

   PATSYM_DENSE5       Density-5 pattern

   PATSYM_DENSE6       Density-6 pattern

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────

   PATSYM_DENSE7       Density-7 pattern

   PATSYM_DENSE8       Density-8 pattern (mostly background)

   PATSYM_DIAG1        Upward-diagonal pattern (steep)

   PATSYM_DIAG2        Upward-diagonal pattern (gradual)

   PATSYM_DIAG3        Downward-diagonal pattern (steep)

   PATSYM_DIAG4        Downward-diagonal pattern (gradual)

   PATSYM_HALFTONE     Alternating foreground and background pattern

   PATSYM_HORIZ        Horizontal pattern

   PATSYM_NOSHADE      Blank pattern (background only)

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────

   PATSYM_SOLID        Solid pattern (foreground only)

   PATSYM_VERT         Vertical pattern
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_PATTERN_SET_ATTR

 Comments

   If the current pattern set specifies a bitmap (see the GpiSetBitmapId or
   GpiSetPatternSet function), the pattern attribute is ignored.

 See Also

   GpiQueryPattern, GpiSetBitmapId, GpiSetPatternRefPoint,
   GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPatternRefPoint
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPatternRefPoint (hps, pptlRef)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlRef;        /*pointer to structure with reference point     */

   The GpiSetPatternRefPoint function sets the current pattern reference
   point to the specified value. The pattern reference point is the point to
   which the origin of the fill pattern maps. The pattern reference point
   does need not be inside the actual area to be filled. The default pattern
   reference point is (0,0).

   If the attribute mode is AM_PRESERVE, the function saves the previous
   pattern reference point on the attribute stack when it sets the new
   reference point. The previous pattern reference point can be retrieved
   using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   pptlRef  Points to the POINTL structure that contains the pattern
   reference point in world coordinates. The POINTL structure has the
   following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Comments

   The pattern reference point is subject to all transformations. This means
   that moving an area by using a transformation also moves the fill pattern
   so that the pattern keeps its position relative to the area boundaries.
   This allows part of a picture to be moved using the GpiBitBlt function,
   and the remainder is drawn without discontinuity by changing the
   appropriate transformation.

 See Also

   GpiBitBlt, GpiQueryPatternRefPoint, GpiSetAttrMode, GpiSetPattern,
   GpiSetPatternSet


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPatternSet
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPatternSet (hps, lcid)
   HPS hps;                /*presentation-space handle                     */
   LONG lcid;              /*local identifier                              */

   The GpiSetPatternSet function sets the current pattern-set attribute to
   the specified value. The pattern set specifies the pattern or character
   set from which patterns can be chosen. The pattern set can be the default
   pattern set, any logical font created using the GpiCreateLogFont function,
   or any tagged bitmap.

   If a logical font is set as the pattern set, the GpiSetPattern function
   can be used to choose which character in the font as the pattern.
   Depending on the device associated with the presentation space, not all of
   the character may be used as the pattern. For example, some devices use
   only 8-by-8 patterns, and therefore use only the lower-left corner of a
   character.

   If a tagged bitmap is set as the pattern set, the bitmap is used as the
   pattern. As with characters, not all of the bitmap may be used as the
   pattern. Also, if the bitmap is color and the device is monochrome, the
   system converts the bitmap to monochrome.

   If the attribute mode is AM_PRESERVE, the function saves the previous
   pattern-set attribute on the attribute stack when it sets the new pattern
   set. The previous pattern-set attribute can be retrieved using the GpiPop
   function.

 Parameters

   hps  Identifies the presentation space.

   lcid  Specifies the local identifier for the pattern set. It can be any
   integer in the range 1 through 254 for which a logical font or tagged
   bitmap has been created. It can be LCID_DEFAULT to specify the default
   pattern set.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_PATTERN_ATTR

 Comments

   Certain fonts cannot be used for patterns. The function returns an error
   if an application attempts to set such a font as the pattern set. Fonts
   that cannot be used as patterns include device fonts which cannot be used
   for shading, and any kind of raster font used for a plotter device.

 See Also

   GpiQueryPatternSet, GpiSetPattern, GpiSetPatternRefPoint


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPel
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiSetPel (hps, pptl)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptl;           /*pointer to structure with point position      */

   The GpiSetPel function sets the pel at the specified position to the
   current foreground color. The pel's position is expressed in world
   coordinates. If the pel is not visible (that is, the point lies outside
   the clip area), the color remains unchanged.

 Parameters

   hps  Identifies the presentation space.

   pptl  Points to a POINTL structure containing the position in world
   coordinates. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 See Also

   GpiQueryPel, GpiSetAttrs, GpiSetColor, GpiSetMix


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPickAperturePosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPickAperturePosition (hps, pptlPick)
   HPS hps;                /*presentation-space handle                     */
   PPOINTL pptlPick;       /*pointer to structure with center of           */
                           /*pick aperture                                 */

   The GpiSetPickAperturePosition function sets the center of the pick
   aperture, in presentation-page space, for subsequent non-retained
   correlation operations.

 Parameters

   hps  Identifies the presentation space.

   pptlPick  Points to the POINTL structure that contains the center of the
   pick aperture. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiQueryPickAperturePosition, GpiSetPickApertureSize


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPickApertureSize
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPickApertureSize (hps, flOption, psizlPick)
   HPS hps;                /*presentation-space handle                     */
   LONG flOption;          /*options                                       */
   PSIZEL psizlPick;       /*pointer to structure with pick-aperture size  */

   The GpiSetPickApertureSize function sets the pick-aperture size. The
   function sets the pick aperture to either the default value or to the size
   specified by psizlPick. The default size is a rectangle in
   presentation-page space that produces a square in device space that has a
   width and height equal to the default-character cell height.

 Parameters

   hps  Identifies the presentation space.

   flOption  Specifies the pick-aperture type. It can be one of the following
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   PICKAP_DEFAULT    Use default pick aperture. The psizlPick parameter is
                     ignored.

   PICKAP_REC        Use psizlPick value.
   ──────────────────────────────────────────────────────────────────────────

   psizlPick  Points to the SIZEL structure that contains the pick-aperture
   size. The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_PICK_APERTURE_OPTION

 See Also

   GpiQueryPickApertureSize, GpiSetPickAperturePosition


 ────────────────────────────────────────────────────────────────────────────
 GpiSetPS
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetPS (hps, psizl, flOptions)
   HPS hps;                /*presentation-space handle                     */
   PSIZEL psizl;           /*pointer to structure for presentation-space   */
                           /*size                                          */
   ULONG flOptions;        /*options                                       */

   The GpiSetPS function sets the page size and units for the presentation
   space. The function is often used to change the device transformation for
   the presentation space.

   The function does not affect the device context associated with the
   presentation space. This means the device context that was already
   associated remains associated. Also, the function does not change the
   presentation space type, such as micro-presentation space or a normal
   presentation space.

   When this function is called, it resets the presentation space to a state
   that is equivalent to setting the value GRES_ALL in the GpiResetPS
   function.

 Parameters

   hps  Identifies the presentation space.

   psizl  Points to the SIZEL structure that contains the size of the
   presentation page. The SIZEL structure has the following form:

   typedef struct _SIZEL {
       LONG cx;
       LONG cy;
   } SIZEL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flOptions  Specifies the presentation-space options. The options define
   the page unit for the presentation space. Although the flOptions parameter
   can include many other options (as specified by the GpiCreatePS function),
   the function ignores all but the page units. The page units can be one of
   the following values:

   Page unit         Meaning
   ──────────────────────────────────────────────────────────────────────────
   PU_ARBITRARY      Sets units initially to pels but permits the units to be
                     modified later using the GpiSetPageViewport function.

   PU_HIENGLISH      Sets units to 0.001 inch.

   PU_HIMETRIC       Sets units to 0.01 millimeter.

   PU_LOENGLISH      Sets units to 0.01 inch.

   PU_LOMETRIC       Sets units to 0.1 millimeter.

   PU_PELS           Sets units to pels.

   PU_TWIPS          Sets units to 1/1440 inch (1/20 point).
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCreatePS, GpiResetPS


 ────────────────────────────────────────────────────────────────────────────
 GpiSetRegion
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetRegion (hps, hrgn, crcl, arcl)
   HPS hps;                /*presentation-space handle                     */
   HRGN hrgn;              /*region handle                                 */
   LONG crcl;              /*number of rectangles                          */
   PRECTL arcl;            /*pointer to array of rectangle structures      */

   The GpiSetRegion function redefines the region specified by the hrgn
   parameter. The function replaces the old region by creating a region that
   consists of the union of the rectangles pointed to by the arcl parameter.
   This function is similar to the GpiCreateRegion function.

   The function can be used only if a device context is associated with the
   presentation space.

 Parameters

   hps  Identifies the presentation space.

   hrgn  Identifies the region handle.

   crcl  Specifies the number of rectangles to use to create the new region.
   If it is zero, the function creates an empty region and the arcl parameter
   is ignored.

   arcl  Points to the array of RECTL structures that contains the rectangles
   for the replacement region. The array must have the number of elements
   specified by crcl. The RECTL structures have the form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiCombineRegion, GpiCreateRegion

 ────────────────────────────────────────────────────────────────────────────
 GpiSetSegmentAttrs
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetSegmentAttrs (hps, idSegment, flAttribute, flAttrFlag)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG flAttribute;       /*attributes                                    */
   LONG flAttrFlag;        /*attribute on/off flag                         */

   The GpiSetSegmentAttrs function sets a segment attribute for a retained
   segment. The segment attributes specify whether a segment is chained,
   visible, detectable, dynamic, and so on. The function can turn these
   attributes on or off, one attribute at a time.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment to change. It must be greater than zero.

   flAttribute  Specifies the segment attribute to set or clear. It can be
   one of the the following values:

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   ATTR_CHAINED            Chained

   ATTR_DETECTABLE         Detectability

   ATTR_DYNAMIC            Dynamic

   ATTR_FASTCHAIN          Fast chaining

   ATTR_PROP_DETECTABLE    Propagate detectability

   ATTR_PROP_VISIBLE       Propagate visibility

   ATTR_VISIBLE            Visibility
   ──────────────────────────────────────────────────────────────────────────

   flAttrFlag  Specifies whether to turn the attribute on or off. If it is
   ATTR_ON, the function turns on the attribute; if ATTR_OFF, the function
   turns off the attribute.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_ATTR
         PMERR_INV_SEG_NAME

 Comments

   When a segment is modified from non-chained to chained, it is added to the
   end of the drawing chain.

 See Also

   GpiQuerySegmentAttrs


 ────────────────────────────────────────────────────────────────────────────
 GpiSetSegmentPriority
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetSegmentPriority (hps, idSegment, idRefSegment, cmdOrder)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG idRefSegment;      /*reference-segment identifier                  */
   LONG cmdOrder;          /*command options                               */

   The GpiSetSegmentPriority function sets the priority for the segment
   specified by idSegment. Segment priority applies only to chained segments.
   The segment priority of a segment specifies the position of that segment
   in the picture chain. The priority affects how the segment appears when
   drawn, since segments with higher priorities (later positions in the
   chain) may draw over the segment.

   The function changes a segment's priority by moving its position in the
   picture chain relative to a given segment. The function places the segment
   either before or after the segment specified by the idRefSegment
   parameter. The cmdOrder parameter specifies the priority that the segment
   should have relative to the idRefSegment segment, and therefore determines
   whether it goes before or after. The function places the segment at either
   the beginning or end of the picture chain if the idRefSegment parameter is
   zero.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the identifier of the segment whose priority is to
   change; it must be greater than zero.

   idRefSegment  Specifies the reference-segment identifier. It must be the
   identifier of a segment in the picture chain, or it must be zero. If it is
   zero, the function uses the beginning or end of the picture chain.

   cmdOrder  Specifies whether to give the segment higher or lower priority
   than the segment specified by idRefSegment. It can be one of the following
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LOWER_PRI         Gives the segment lower priority. The function places
                     the segment before the reference-segment in the chain.
                     If the idRefSegment is zero, the function makes the
                     segment the highest-priority segment.

   HIGHER_PRI        Gives the segment higher priority. The function places
                     the segment after the reference-segment in the chain. If
                     the idRefSegment is zero, the function makes the segment
                     the lowest-priority segment.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_SEG_AND_REFSEG_ARE_SAME

 See Also

   GpiDrawChain, GpiDrawFrom, GpiQuerySegmentPriority


 ────────────────────────────────────────────────────────────────────────────
 GpiSetSegmentTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetSegmentTransformMatrix (hps, idSegment, cElements, pmatlf,
   flType)
   HPS hps;                /*presentation-space handle                     */
   LONG idSegment;         /*segment identifier                            */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure with transformation      */
                           /*matrix                                        */
   LONG flType;            /*type of transformation                        */

   The GpiSetSegmentTransformMatrix function sets the segment transformation
   for the specified segment. The segment transformation applies to all
   primitives in the segment. The function sets the transformation by adding
   or replacing the existing transformation matrix with the matrix pointed to
   by the pmatlf parameter. The function adds, preempts, or replaces the
   existing transformation matrix as specified by the flType parameter.

   The GpiSetSegmentTransformMatrix function requires a nine-element matrix
   to set the segment transformation. If the specified matrix does not
   contain nine elements, the function uses the corresponding elements of the
   identity matrix for each unspecified element. The cElements parameter
   specifies the number of elements in the matrix. If this parameter equals
   zero, the identity matrix is used. If scaling values greater than one are
   given, care must be taken that the combined effect of this and any other
   relevant transformations do not exceed the limit for fixed-point numbers.

 Parameters

   hps  Identifies the presentation space.

   idSegment  Specifies the segment identifier; it must be greater than zero.
   The segment transformation does not affect primitives outside the
   specified segment.

   cElements  Specifies the number of elements in the matrix to set. It can
   be any integer in the range 0 through 9.

   pmatlf  Points to a MATRIXLF structure that contains the transformation
   matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flType  Specifies how a specified matrix should be used to modify the
   segment transformation. It can be one of the following values:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   TRANSFORM_ADD         Additive. The specified transformation matrix is
                         combined with the existing segment transformation,
                         in the order of the existing transformation first,
                         the new transformation second. This option is useful
                         for incremental updates to transformations.

   TRANSFORM_PREEMPT     Preemptive. The specified transformation matrix is
                         combined with the existing segment transformation,
                         in the order of the new transformation first, the
                         existing transformation second.

   TRANSFORM_REPLACE     New/replace. The previous segment transformation is
                         discarded and replaced by the specified
                         transformation matrix.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_SEG_NAME
         PMERR_INV_TRANSFORM_TYPE

 Comments

   The system applies a segment transformation to the primitives in the given
   segment after applying the model transformation and any instance and
   segment transformations from calling segments.

 Example

   This example uses the GpiSetSegmentTransformMatrix function to replace the
   existing segment transformation. The new transformation doubles the width
   and height of drawing.

   MATRIXLF matlf = { MAKEFIXED(2,0), 0, 0, 0, MAKEFIXED(2,0), 0, 100 };

   GpiSetSegmentTransformMatrix(hps, 7L, &matlf, TRANSFORM_REPLACE);

 See Also

   GpiQueryDefaultViewMatrix, GpiQuerySegmentTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiSetStopDraw
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetStopDraw (hps, fStopDraw)
   HPS hps;                /*presentation-space handle                     */
   LONG fStopDraw;         /*stop-draw condition flag                      */

   The GpiSetStopDraw function sets or clears the stop-draw condition. The
   stop-draw condition terminates specific functions that may be executing in
   another thread of the process. If the stop-draw condition is set, the
   system stops the following functions and forces each to return an error:

         GpiDrawChain
         GpiDrawDynamics
         GpiDrawFrom
         GpiDrawSegment
         GpiPlayMetaFile
         GpiPutData

 Parameters

   hps  Identifies the presentation space.

   fStopDraw  Specifies the stop-draw condition. If it is FALSE, the function
   clears the stop-draw condition. If it is TRUE, the function sets the
   condition.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_STOP_DRAW_VALUE

 Comments

   The GpiSetStopDraw function lets an application set up and control an
   asynchronous thread that carries out long drawing operations. If the
   controlling thread needs to stop drawing, it sets the condition. If it
   wants to allow drawing, it clears the condition. The stop-draw condition
   only affects the listed functions.

   Using the stop-draw condition to stop drawing to a metafile creates an
   unusable metafile.

 See Also

   GpiDrawChain, GpiDrawDynamics, GpiDrawFrom, GpiDrawSegment,
   GpiPlayMetaFile, GpiPutData


 ────────────────────────────────────────────────────────────────────────────
 GpiSetTag
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetTag (hps, lTag)
   HPS hps;                /*presentation-space handle                     */
   LONG lTag;              /*tag                                           */

   The GpiSetTag function sets the current primitive tag. A primitive tag is
   a way of identifying a primitive stored in a segment. The function sets
   the primitive tag and the system applies this tag to all subsequent
   primitives. The default tag is zero.

   Primitive tags are typically used when correlating segments. The
   GpiCorrelateChain, GpiCorrelateFrom, and GpiCorrelateSegment functions
   return the segment identifier and the primitive tag of objects that lie in
   the pick aperture.

   The GpiSetTag function cannot be used in an area bracket, but can be used
   before an area bracket to give all primitives in the area the same tag. If
   the attribute mode is AM_PRESERVE, the function saves the previous tag on
   the attribute stack when it sets the new tag. The previous tag can be
   retrieved using the GpiPop function.

 Parameters

   hps  Identifies the presentation space.

   lTag  Specifies a tag. It must be an integer value.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_INV_MICROPS_FUNCTION

 Comment

   Although primitives in an unnamed segment can be tagged, the correlation
   functions cannot pick or correlate unnamed segments or any tags applied to
   them are ignored.

 See Also

   GpiBeginArea, GpiCorrelateChain, GpiCorrelateFrom,
   GpiCorrelateSegment, GpiEndArea, GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetViewingLimits
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetViewingLimits (hps, pgrcLimits)
   HPS hps;                /*presentation-space handle                     */
   PRECTL prclLimits;      /*pointer to structure with viewing limits      */

   The GpiSetViewingLimits function sets the viewing limits. The viewing
   limits specify a rectangle in model space that the system uses to clip
   output. The viewing limits include all points inside the rectangle and all
   points on the left and bottom edges. It does not include points on the
   right and top edges. Points on these edges are clipped.

   The GpiSetViewingLimits function can be used in a segment to set the
   viewing limits for subsequent primitives in the segment. The viewing
   limits also apply to any called segments, unless the called segment itself
   sets the viewing limits.

 Parameters

   hps  Identifies the presentation space.

   prclLimits  Points to the RECTL structure that contains the coordinates of
   the viewing limits. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Comments

   Unless the segments in the picture chain have the fast-chaining attribute,
   the system resets the default viewing limits when each segment in the
   chain is drawn. The default viewing limits include all model space,
   meaning nothing is clipped.

   The segment and model transformations do not affect the viewing limits,
   but the current viewing and default viewing transformations do.

 See Also

   GpiQueryViewingLimits, GpiSetAttrMode


 ────────────────────────────────────────────────────────────────────────────
 GpiSetViewingTransformMatrix
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiSetViewingTransformMatrix (hps, cElements, pmatlf, flType)
   HPS hps;                /*presentation-space handle                     */
   LONG cElements;         /*number of elements                            */
   PMATRIXLF pmatlf;       /*pointer to structure with transformation      */
                           /*matrix                                        */
   LONG flType;            /*transformation type                           */

   The GpiSetViewingTransformMatrix function sets the viewing transformation.
   The viewing transformation applies to all primitives inside subsequently
   opened (new) segments (it has no effect on primitives outside segments).
   All graphics primitives in a segment have the same viewing transformation,
   since the function cannot be used in an open segment. Also, once set for a
   segment, the viewing transformation cannot be altered.

   The GpiSetViewingTransformMatrix function sets the transformation by
   replacing the existing transformation matrix with the matrix pointed to by
   the pmatlf parameter. The function replaces the existing transformation
   matrix as specified by the flType parameter. The function requires a
   nine-element matrix to set the viewing transformation. If the specified
   matrix does not contain nine elements, the function uses the corresponding
   elements of the identity matrix for each unspecified element. The
   cElements parameter specifies the number of elements in the matrix. If
   this parameter equals zero, the identity matrix is used. If scaling values
   greater than one are given, care must be taken that the combined effect of
   this and any other relevant transformations do not exceed the limit for
   fixed-point numbers.

 Parameters

   hps  Identifies the presentation space.

   cElements  Specifies the number of elements in the matrix to set. It can
   be any integer in the range 0 through 9.

   pmatlf  Points to the MATRIXLF structure that contains the transformation
   matrix. The MATRIXLF structure has the following form:

   typedef struct _MATRIXLF {
       FIXED fxM11;
       FIXED fxM12;
       LONG  lM13;
       FIXED fxM21;
       FIXED fxM22;
       LONG  lM23;
       LONG  lM31;
       LONG  lM32;
       LONG  lM33;
   } MATRIXLF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   flType  Specifies the transform type. It can be TRANSFORM_REPLACE. The
   previous viewing transformation is discarded and replaced by a specified
   transformation.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_INV_MICROPS_FUNCTION
         PMERR_INV_TRANSFORM_TYPE

 Example

   This example uses the GpiSetViewingTransformMatrix function to replace the
   existing viewing transformation. The new transformation doubles the width
   and height of drawing.

   MATRIXLF matlf = { MAKEFIXED(2,0), 0, 0, 0, MAKEFIXED(2,0), 0, 100 };

   GpiSetViewingTransformMatrix(hps, 7L, &matlf, TRANSFORM_REPLACE);

 See Also

   GpiQueryDefaultViewMatrix, GpiQueryViewingTransformMatrix


 ────────────────────────────────────────────────────────────────────────────
 GpiStrokePath
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiStrokePath (hps, lPath, flOptions)
   HPS hps;                /*presentation-space handle                     */
   LONG lPath;             /*stroke path                                   */
   ULONG flOptions;        /*reserved                                      */

   The GpiStrokePath function strokes a path and then draws it using the area
   attributes. This function first converts the path to one describing the
   envelope of a wide line stroked using the current geometric wide-line
   attribute (see the GpiSetLineWidthGeom function).

 Parameters

   hps  Identifies a presentation space.

   lPath  Specifies the path to stroke.

   flOptions  Specifies a reserved value; it must be zero.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Example

   This example uses the GpiStrokePath to draw a wide line.

   POINTL ptlStart = { 0, 0 };
   POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };

   /* create the path */

   GpiBeginPath(hps, 1L);
   GpiMove(hps, &ptlStart);
   GpiPolyLine(hps, 3, ptlTriangle);
   GpiEndPath(hps);

   GpiSetLineWidthGeom(hps, 20L); /* set the line width           */
   GpiStrokePath(hps, 1L, 0L);    /* draw the wide line           */

 See Also

   GpiBeginPath, GpiEndPath, GpiModifyPath, GpiSetLineWidthGeom


 ────────────────────────────────────────────────────────────────────────────
 GpiUnloadFonts
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiUnloadFonts (hab, pszModName)
   HAB hab;                /*anchor-block handle                           */
   PSZ pszModName;         /*pointer to the module name                    */

   The GpiUnloadFonts function unloads font definitions that were previously
   loaded from the resource file specified by the pszModName parameter.
   Before unloading fonts, the application should delete any local
   identifiers previously assigned to the fonts. The function unloads the
   fonts for the application only. If any other applications have loaded the
   fonts, they remain available for those applications.

 Parameters

   hab  Identifies the anchor block.

   pszModName  Points to a null-terminated string. This string must be a
   valid MS OS/2 filename. If it does not specify a path and the filename
   extension, the function appends the default extension (.dll) and searches
   for the font resource file in the directories specified by the libpath
   command in the config.sys file.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   the following:

         PMERR_FONT_NOT_LOADED

 See Also

   GpiCreateLogFont, GpiDeleteSetId, GpiLoadFonts, GpiSetCharSet


 ────────────────────────────────────────────────────────────────────────────
 GpiUnrealizeColorTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL GpiUnrealizeColorTable (hps)
   HPS hps;                /*presentation-space handle                     */

   The GpiUnrealizeColorTable function "unrealizes" the logical color table.
   The function has the opposite effect of the GpiRealizeColorTable function.
   It restores the default device colors for the physical palette for the
   device associated with the given presentation space.

   The function does not change the logical color table.

 Parameters

   hps  Identifies the presentation space.

 Return Value

   The return value is GPI_OK if the function is successful or GPI_ERROR if
   an error occurred.

 See Also

   GpiRealizeColorTable


 ────────────────────────────────────────────────────────────────────────────
 GpiWCBitBlt
 ────────────────────────────────────────────────────────────────────────────
   LONG GpiWCBitBlt (hps, hbm, cPoints, aptl, lRop, flOptions)
   HPS hps;                /*presentation-space handle                     */
   HBITMAP hbm;            /*bitmap handle                                 */
   LONG cPoints;           /*number of points                              */
   PPOINTL aptl;           /*pointer to structure with points              */
   LONG lRop;              /*mixing function                               */
   ULONG flOptions;        /*options                                       */

   The GpiWCBitBlt function copies a bitmap to a presentation space. It can
   also modify the bitmap within a rectangle in a presentation space. The
   exact operation carried out by GpiWCBitBlt depends on the raster operation
   specified by the lRop parameter.

   If lRop directs GpiWCBitBlt to copy a bitmap, the function copies the
   bitmap specified by hbm to the presentation space. The presentation space
   must be associated with a device context for the display, for memory, or
   for some other suitable raster device. The aptl parameter points to an
   array of points that specify the corners of a rectangle in the bitmap as
   well as the corners of the rectangle in the presentation space to receive
   the bitmap. The bitmap rectangle is specified in device coordinates; the
   presentation-space rectangle in world coordinates. If the bitmap and
   presentation-space rectangles are not the same (after converting the
   presentation space to device coordinates), GpiWCBitBlt stretches or
   compresses the bitmap to fit the presentation-space rectangle.

   If lRop directs GpiWCBitBlt to modify a bitmap, the function uses the
   raster operation to determine how to alter the bits in a rectangle in the
   presentation space. Raster operations include changes such as inverting
   existing bits, replacing bits with pattern bits, and mixing existing and
   pattern bits to create new colors. For some raster operations, the
   function mixes the bits of the bitmap with the presentation space and/or
   pattern bits.

 Parameters

   hps  Identifies the presentation space.

   hbm  Identifies the bitmap.

   cPoints  Specifies the number of points pointed to by the aptl parameter.
   It must be 4.

   aptl  Points to an array of POINTL structures that contains the number of
   points specified in the cPoints parameter. The points must be given in the
   following order:

   Element      Coordinate
   index
   ──────────────────────────────────────────────────────────────────────────
   0            Specifies the lower-left corner of the target rectangle in
                world coordinates.

   1            Specifies the upper-right corner of the target rectangle in
                world coordinates.

   3            Specifies the lower-left corner of the source rectangle in
                device coordinates.

   4            Specifies the upper-right corner of the source rectangle in
                device coordinates.
   ──────────────────────────────────────────────────────────────────────────

   The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lRop  Specifies the raster operation for the function. It can be any value
   in the range 0 through 255 or one of the following values, which represent
   common raster operations:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   ROP_DSTINVERT       Inverts the target.

   ROP_MERGECOPY       Combines the source and the pattern using the bitwise
                       AND operator.

   ROP_MERGEPAINT      Combines the inverse of the source and the target
                       using the bitwise OR operator.

   ROP_NOTSRCCOPY      Copies the inverse of the source to the target.

   ROP_NOTSRCERASE     Combines the inverse of the source and the inverse of
                       the target bitmaps using the bitwise AND operator.

   ROP_ONE             Sets all target pels to 1.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  ROP_ONE             Sets all target pels to 1.

   ROP_PATCOPY         Copies the pattern to the target.

   ROP_PATINVERT       Combines the target and the pattern using the bitwise
                       exclusive XOR operator.

   ROP_PATPAINT        Combines the inverse of the source, the pattern, and
                       target using the bitwise OR operator.

   ROP_SRCAND          Combines the source and target bitmaps using the
                       bitwise AND operator.

   ROP_SRCCOPY         Copies the source bitmap to the target.

   ROP_SRCERASE        Combines the source and the inverse of the target
                       bitmaps using the bitwise AND operator.

   ROP_SRCINVERT       Combines the source and target bitmaps using the
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  ROP_SRCINVERT       Combines the source and target bitmaps using the
                       bitwise exclusive OR operator.

   ROP_SRCPAINT        Combines the source and target bitmaps using the
                       bitwise OR operator.

   ROP_ZERO            Sets all target pels to 0.
   ──────────────────────────────────────────────────────────────────────────


   flOptions  Specifies how to compress a bitmap if the target rectangle is
   smaller than the source. It can be one of the following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   BBO_AND             Compresses two rows or columns into one by combining
                       them with the bitwise AND operator. This value is
                       useful for compressing bitmaps that have black images
                       on a white background.

   BBO_OR              Compresses two rows or columns into one by combining
                       them with the bitwise OR operator. This value is the
                       default and is useful for compressing bitmaps that
                       have white images on a black background.

   BBO_IGNORE          Compresses two rows or columns by throwing one out.
                       This value is useful for compressing color bitmaps.
   ──────────────────────────────────────────────────────────────────────────

   All values in the range 0x0100 to 0xFF00 are reserved for privately
   supported modes for particular devices.

 Return Value

   The return value is GPI_OK or GPI_HITS if the function is successful (it
   is GPI_HITS if the detectable attribute is set for the presentation space
   and a correlation hit occurs). The return value is GPI_ERROR if an error
   occurs.

 Errors

   Use the WinGetLastError function to retrieve the error value, which may be
   one of the following:

         PMERR_BASE_ERROR
         PMERR_BITMAP_NOT_SELECTED
         PMERR_INCOMPATIBLE_BITMAP
         PMERR_INV_BITBLT_MIX
         PMERR_INV_BITBLT_STYLE
         PMERR_INV_COORDINATE
         PMERR_INV_DC_TYPE
         PMERR_INV_HBITMAP
         PMERR_INV_HDC
         PMERR_INV_IN_AREA
         PMERR_INV_IN_PATH
         PMERR_INV_LENGTH_OR_COUNT

 Comments

   The GpiWCBitBlt function can be used in an open segment. If the drawing
   mode is DM_DRAWANDRETAIN or DM_RETAIN, the function builds a graphics
   order in the current open segment. The order identifies the bitmap handle
   and uses uses long or short coordinates, as determined by the
   presentation-space format.

   GpiWCBitBlt does not affect the pels in the upper and right boundaries of
   the presentation-space rectangle. This means the function draws up to but
   does not include those pels. Also, the function ignores any rotation
   transformations.

   If the lRop parameter includes a pattern, GpiWCBitBlt uses the current
   area color, area background color, pattern set, and pattern symbol of the
   presentation space. Although the function may stretch or compress the
   bitmap, it never stretches or compresses the pattern.

   If the presentation-space and the bitmap have different color formats,
   GpiWCBitBlt converts the bitmap color format as it copies the bitmap. This
   applies to bitmaps copied to a device context having a monochrome format.
   To convert a monochrome bitmap to a color bitmap, GpiWCBitBlt converts 1
   pels to the presentation foreground color, and 0 pels to the current-area
   background color.

 Example

   This example uses GpiWCBitBlt to copy and compress a bitmap in a
   presentation space. The function copies the bitmap that is 100 pels wide
   and 100 pels high into a 50-by-50-pel rectangle at the location (300,400).
   Since the raster operation is ROP_SRCCOPY, GpiWCBitBlt replaces the image
   previously in the presentation-space rectangle. The function compresses
   the bitmap to fit the new rectangle by discarding extra rows and columns
   as specified by the BBO_IGNORE option.

   HPS hps;
   HBITMAP hbm;
   POINTL aptl[4] = {
       300, 400,      /* lower-left corner of target             */
       350, 450,      /* upper-right corner of target            */
       0, 0,          /* lower-left corner of source             */
       100, 100 };    /* upper-right corner of source            */

   GpiWCBitBlt(hps,   /* presentation space                      */
       hbm,           /* bitmap handle                           */
       4L,            /* four points needed to compress          */
       aptl,          /* points for source and target rectangles */
       ROP_SRCCOPY,   /* copy source replacing target            */
       BBO_IGNORE);   /* discard extra rows and columns          */

 See Also

   DevOpenDC, GpiBitBlt, GpiCreateBitmap, GpiLoadBitmap, GpiSetBitmap,
   GpiSetBitmapDimension, GpiSetBitmapId

 ────────────────────────────────────────────────────────────────────────────
 WinAddAtom
 ────────────────────────────────────────────────────────────────────────────
   ATOM WinAddAtom (hAtomTbl, pszAtomName)
   HATOMTBL hAtomTbl;      /*handle to the atom table                      */
   PSZ pszAtomName;        /*address of the buffer for the atom name       */

   The WinAddAtom function adds an atom to an atom table and sets its use
   count to 1. If the atom name already exists in the table, this function
   adds 1 to its use count.

 Parameters

   hAtomTbl  Identifies the atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable or WinQuerySystemAtomTable
   function.

   pszAtomName  Points to the null-terminated character string that contains
   an atom name to be added to the table. If the string begins with a "#"
   character, the ASCII digits that follow are converted into a 16-bit
   integer. If this integer is a valid integer atom, this function returns
   that atom without actually modifying the atom table. If the string begins
   with an "!" character, the next two bytes are interpreted as an atom.

   If the high word of pszAtomName is 0xFFFF, the low word is treated as an
   atom. If it is an integer atom, that atom is returned. Otherwise the
   reference count associated with that atom is increased by one and the atom
   is returned.

 Return Value

   The return value is the atom associated with the passed string or NULL.
   The return value is zero if an invalid atom table or atom name was
   specified.

 See Also

   WinCreateAtomTable, WinDeleteAtom, WinFindAtom, WinQueryAtomLength,
   WinQueryAtomName, WinQueryAtomUsage


 ────────────────────────────────────────────────────────────────────────────
 WinAddProgram
 ────────────────────────────────────────────────────────────────────────────
   HPROGRAM WinAddProgram (hab, ppib, hGroupHandle)
   HAB hab;                /*handle to the anchor block                    */
   PPIBSTRUCT ppib;        /*address of structure with program information */
   HPROGRAM hGroupHandle;  /*handle of the program group                   */

   The WinAddProgram function adds a program title to the program list of a
   group. Program titles need not be unique, although duplicate titles within
   the same group are not allowed.

 Parameters

   hab  Identifies the anchor block.

   ppib  Points to a PIBSTRUCT structure that contains program information
   for the program being added to the program list.

   The PIBSTRUCT structure has the following form:

   typedef struct _PIBSTRUCT {
       PROGTYPE  progt;
       CHAR      szTitle[MAXNAMEL+1];
       CHAR      szIconFileName[MAXPATHL+1];
       CHAR      szExecutable[MAXPATHL+1];
       CHAR      szStartupDir[MAXPATHL+1];
       XYWINSIZE xywinInitial;
       USHORT    res1;
       LHANDLE   res2;
       USHORT    cchEnvironmentVars;
       PCH       pchEnvironmentVars;
       USHORT    cchProgramParameter;
       PCH       pchProgramParameter;
   } PIBSTRUCT;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   hGroupHandle  Identifies the program group to which the program is added.
   The special value SGH_ROOT may be used, indicating the root group.

 Return Value

   The return value is the program handle for the program added to the
   program list.

 See Also

   WinCreateGroup, WinQueryDefinition, WinQueryProgramTitles


 ────────────────────────────────────────────────────────────────────────────
 WinAddSwitchEntry
 ────────────────────────────────────────────────────────────────────────────
   HSWITCH WinAddSwitchEntry (pswctl)
   PSWCNTRL pswctl;        /*address of structure with new entry           */
                           /*information                                   */

   The WinAddSwitchEntry function adds an entry to the switch list (the list
   of running programs that is displayed by the Task Manager).

 Parameters

   pswctl  Points to the SWCNTRL structure that contains information about
   the new switch-list entry. If the szSwtitle field in the SWCNTRL structure
   is NULL, the system uses the name under which the application was started.
   This applies only for the first call to this function for that program
   (since the program was started). Otherwise, a NULL entry name is invalid.

   The SWCNTRL structure has the following form:

   typedef struct _SWCNTRL {
       HWND     hwnd;
       HWND     hwndIcon;
       HPROGRAM hprog;
       USHORT   idProcess;
       USHORT   idSession;
       UCHAR    uchVisibility;
       UCHAR    fbJump;
       CHAR     szSwtitle[MAXNAMEL+1];
       BYTE     fReserved;
   } SWCNTRL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is a handle to the new switch-list entry, or NULL if an
   error occurs.

 Example

   This example calls WinQueryWindowProcess to get the current processor
   identifier (needed for the SWCNTRL structure). It then sets up the swctl
   structure and calls WinAddSwitchEntry to add the program's name to the
   task list. The returned handle can be used in subsequent calls to
   WinChangeSwitchEntry if the title needs to be changed. The variables
   swctl, hswitch, and pid should be global if your application will be
   calling the WinChangeSwitchEntry function to avoid having to set up the
   structure again.

   SWCNTRL swctl;
   HSWITCH hswitch;
   PID pid;

   WinQueryWindowProcess(hwndFrame, &pid, NULL);

   swctl.hwnd = hwndFrame;                 /* window handle      */
   swctl.hwndIcon = NULL;                  /* icon handle        */
   swctl.hprog = NULL;                     /* program handle     */
   swctl.idProcess = pid;                  /* process identifier */
   swctl.idSession = NULL;                 /* session identifier */
   swctl.uchVisibility = SWL_VISIBLE;      /* visibility         */
   swctl.fbJump = SWL_JUMPABLE;            /* jump indicator     */
   swctl.szSwtitle[0] = NULL;              /* program name       */

   hswitch = WinAddSwitchEntry(&swctl);

 Comment

   Leading and trailing blanks are removed from the title. The title is
   truncated to 60 characters. There is a system limit to the number of
   switch-list entries (several hundred) but it is unlikely to be reached
   because other system limits, such as memory size, will impinge first.

 See Also

   WinChangeSwitchEntry, WinQueryWindowProcess, WinRemoveSwitchEntry


 ────────────────────────────────────────────────────────────────────────────
 WinAlarm
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinAlarm (hwndDesktop, fsType)
   HWND hwndDesktop;       /*handle of the desktop                         */
   USHORT fsType;          /*alarm style                                   */

   The WinAlarm function generates an audible alarm that can be used to alert
   the user about special conditions.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fsType  Specifies the alarm style. It can be one of the following values:

         WA_WARNING
         WA_NOTE
         WA_ERROR

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The duration and frequency of the alarm can be changed by the
   WinSetSysValue function. The alarm is not generated if the system value
   SV_ALARM is set to FALSE.

   The following system values control the alarm:

   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────
   SV_ALARM             Specifies whether calls to WinAlarm generate a sound.
                        A value of TRUE means sound is generated.

   SV_ERRORDURATION     Specifies the duration in milliseconds of a WA_ERROR
                        sound.

   SV_ERRORFREQ         Specifies the frequency in cycles per second of a
                        WA_ERROR sound.

   SV_NOTEDURATION      Specifies the duration in milliseconds of a WA_NOTE
                        sound.

   SV_NOTEFREQ          Specifies the frequency in cycles per second of a
                        WA_NOTE sound.

   SV_WARNINGDURATION   Specifies the duration in milliseconds of a
                        WA_WARNING sound.

   SV_WARNINGFREQ       Specifies the frequency in cycles per second of a
                        WA_WARNING sound.
   ──────────────────────────────────────────────────────────────────────────

 Example

   This example calls an application-defined initialization function, and if
   the function fails it calls WinAlarm to generate an audible alarm
   notifying the user the initialization failed.

   if (!GenericInit()) {                      /* general initialization */
       WinAlarm(HWND_DESKTOP, WA_ERROR);

 See Also

   WinFlashWindow, WinSetSysValue


 ────────────────────────────────────────────────────────────────────────────
 WinAllocMem
 ────────────────────────────────────────────────────────────────────────────
   NPBYTE WinAllocMem (hHeap, cb)
   HHEAP hHeap;            /*handle of the heap                            */
   USHORT cb;              /*number of bytes to allocate                   */

   The WinAllocMem function allocates memory from a heap and returns the
   16-bit offset from the start of the segment that contains the heap.

 Parameters

   hHeap  Identifies the heap from which to allocate memory. This handle is
   returned by a previous call to the WinCreateHeap function.

   cb  Specifies the number of bytes to allocate.

 Return Value

   The return value points to the allocated memory block if the function is
   successful or is NULL if an error occurs.

 Comments

   The low two bits of the returned pointer are always zero. This function
   returns NULL when it cannot allocate the memory object, either because an
   invalid heap handle is specified or because there is not enough room in
   the heap for an object of the specified size and it is unable to grow the
   segment containing the heap by an amount large enough to satisfy the
   request.

   If the specified heap is created with the HM_MOVEABLE option, the value of
   the cb parameter is remembered in the second reserved word of the
   allocated block.

   If no free block is found, WinAllocMem seeks space by calling the
   WinAvailMem function. If this does not generate a free block large enough,
   WinAllocMem attempts to grow the segment by the maximum of the size of the
   request and the minimum growth parameter specified on the call to the
   WinCreateHeap function. If that fails, this function returns NULL.

   No synchronization is done for this call. Multi-threaded applications
   should use semaphores if more than one thread will be making this call to
   prevent two or more threads from calling this function at the same time.

   If the heap was created in the default data segment, the returned value
   may be used directly as a near pointer. Otherwise, it must be combined
   with the selector of the heap segment to create a far pointer. The MAKEP
   macro can be used for this purpose as in the following code fragment:

   NPBYTE npb;
   PBYTE pb;

   npb = WinAllocMem(...);
   pb = MAKEP(sel,          /* heap segment selector           */
       (USHORT) npb);       /* value returned from WinAllocMem */

 See Also

   WinAvailMem, WinCreateHeap, WinFreeMem, WinReallocMem


 ────────────────────────────────────────────────────────────────────────────
 WinAvailMem
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinAvailMem (hHeap, fCompact, cbMinFree)
   HHEAP hHeap;            /*handle of the heap                            */
   BOOL fCompact;          /*memory-compaction flag                        */
   USHORT cbMinFree;       /*amount of storage requested                   */

   The WinAvailMem function returns the size of the largest free block on the
   heap.

 Parameters

   hHeap  Identifies the heap. This handle must have been created by a
   previous call to the WinCreateHeap function.

   fCompact  Specifies the memory-compaction flag. If TRUE, the heap is
   reorganized. If FALSE, the heap is not reorganized.

   cbMinFree  This parameter is currently not used, but should be set to the
   amount of storage the caller is requesting. A future release may use this
   value to limit the scope of the compaction.

 Return Value

   The return value is the largest memory block available if the function is
   successful, or 0xFFFF if an error occurs.

 Comments

   If the passed heap was created with the HM_MOVEABLE option, the
   reorganization entails moving all movable blocks toward the beginning of
   the heap. The presence of fixed objects may inhibit the amount of movement
   that can occur. While the compaction is occurring, the dedicated and
   nondedicated free lists are reconstructed from any free blocks that cannot
   be filled by the compactor.

   If the passed heap was not created with the HM_MOVEABLE option, the
   reorganization entails sorting all free lists into a single list in
   address order, scanning the list for adjacent blocks to coalesce, and then
   reconstructing the dedicated and nondedicated free lists.

   No synchronization is done for this call. Multi-threaded applications
   should use semaphores if more then one thread will be making this call to
   prevent two or more threads from calling this function at the same time.

 See Also

   WinAllocMem, WinCreateHeap, WinFreeMem, WinReallocMem


 ────────────────────────────────────────────────────────────────────────────
 WinBeginEnumWindows
 ────────────────────────────────────────────────────────────────────────────
   HENUM WinBeginEnumWindows (hwnd)
   HWND hwnd;              /*handle of the parent window                   */

   The WinBeginEnumWindows function begins the enumeration process for all
   immediate child windows of a specified window. This function takes a
   snapshot of the window hierarchy at the time the function is called and
   enumerates the windows in the order they were at the time the snapshot is
   taken. The topmost child window is enumerated first, guaranteeing that all
   child windows are enumerated.

 Parameters

   hwnd  Identifies the parent window whose child windows are enumerated. If
   this parameter is HWND_DESKTOP, all main windows are enumerated.

 Return Value

   The return value is the handle to an enumeration list and is used in
   subsequent calls to WinGetNextWindow to retrieve the window handles in
   succession. When the application has finished the enumeration, this handle
   must be destroyed by the WinEndEnumWindows function.

 Comments

   The enumerated windows are not locked and can be destroyed between the
   time this function is called and the time that the WinGetNextWindow
   function is used to obtain the window handle. However, enumerated window
   handles referenced by the enumeration handle will be removed from the
   enumeration list if they are destroyed. Thus they will not be returned by
   WinGetNextWindow.

 See Also

   WinEndEnumWindows, WinGetNextWindow


 ────────────────────────────────────────────────────────────────────────────
 WinBeginPaint
 ────────────────────────────────────────────────────────────────────────────
   HPS WinBeginPaint (hwnd, hps, prclPaint)
   HWND hwnd;              /*handle of the window handle                   */
   HPS hps;                /*handle of the presentation space              */
   PRECTL prclPaint;       /*address of structure for bounding rectangle   */

   The WinBeginPaint function obtains a presentation space whose visible
   region is the window's update region. This sets up the presentation space
   so that any drawing will only occur within the update region. The
   presentation space can be an existing one supplied to this function, in
   which case its visible region will be set to the update region of hwnd.
   Otherwise, a cached presentation space is obtained specifically for the
   window.

   The WinEndPaint function must be called when drawing is complete.

 Parameters

   hwnd  Identifies the window where drawing will occur.

   hps  Identifies the presentation space to use. If this parameter is NULL,
   a cache presentation space is created.

   prclPaint  Points to a RECTL structure that will be set to the smallest
   rectangle bounding the update region. The RECTL structure has the
   following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is a handle to a presentation space, or NULL if an error
   occurred.

 Comments

   This function hides the cursor, if it is in the window, until the
   WinEndPaint function is called.

 Example

   This example calls WinBeginPaint when it receives a WM_PAINT message to
   get a presentation-space handle to the update region, and to get the
   coordinates of the update rectangle. It then fills the update rectangle
   and calls WinEndPaint to release the presentation space.

   case WM_PAINT:
       hps = WinBeginPaint(hwnd,   /* handle of the window      */
           NULL,                   /* get a cache ps            */
           &rcl);                  /* receives update rectangle */
       WinFillRect(hps, &rcl, CLR_WHITE);
       WinEndPaint(hps);

 See Also

   WinEndPaint


 ────────────────────────────────────────────────────────────────────────────
 WinBroadcastMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinBroadcastMsg (hwnd, msg, mp1, mp2, fs)
   HWND hwnd;              /*handle of the parent window                   */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*message parameter                             */
   MPARAM mp2;             /*message parameter                             */
   USHORT fs;              /*windows to send message to                    */

   The WinBroadcastMsg function broadcasts a message to multiple windows.
   This function sends or posts a message to all immediate child windows of
   the specified window.

 Parameters

   hwnd  Identifies the window whose immediate child windows will receive the
   message. If this parameter is NULL, the function sends the message to all
   main windows on the screen.

   msg  Specifies the message.

   mp1  Specifies the first message parameter.

   mp2  Specifies the second message parameter.

   fs  Specifies which windows to send the message to, and whether the
   message should be sent or posted. The value consists of a flag from each
   of the following lists combined using the OR operator.

   The following list contains the values specifying which windows to
   broadcast the message to:

   Destination       Meaning
   ──────────────────────────────────────────────────────────────────────────
   BMSG_DESCENDANTS  Post or send the message to hwnd and all of its
                     descendants.

   BMSG_FRAMEONLY    Post or send the message to frame windows only.
   ──────────────────────────────────────────────────────────────────────────

   The following list contains the values specifying how to broadcast the
   message (send or post):

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   BMSG_POST         Post a message to all child windows of the window
                     specified by the hwnd parameter.

   BMSG_POSTQUEUE    Post a message to all threads that have a message queue.
                     The message's hwnd parameter will be NULL.

   BMSG_SEND         Send a message to all children of the window specified
                     by the hwnd parameter.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinPostMsg, WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinCalcFrameRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCalcFrameRect (hwndFrame, prcl, fClient)
   HWND hwndFrame;         /*handle of the frame window                    */
   PRECTL prcl;            /*address of structure with window rectangle    */
   BOOL fClient;           /*client-indicator flag                         */

   The WinCalcFrameRect function calculates a client rectangle from a frame
   rectangle or calculates a frame rectangle from a client rectangle. This
   function provides the size and position of the client area within the
   specified frame window, or conversely, the size and position of the frame
   window that would contain a client window of the specified size and
   position.

 Parameters

   hwndFrame  Identifies the frame window.

   prcl  Points to the RECTL structure that contains the coordinates of the
   window. If the fClient parameter is TRUE, this structure contains the
   coordinates of the frame window, and on return, it will contain the
   coordinates of a client window. If the fClient parameter is FALSE, this
   structure contains the coordinates of the client window, and on return, it
   will contain the coordinates of a frame window. The RECTL structure has
   the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   fClient  Specifies whether the window to calculate is a client window or a
   frame window. If TRUE, a client window is calculated. If FALSE, a frame
   window is calculated.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.


 ────────────────────────────────────────────────────────────────────────────
 WinCallMsgFilter
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCallMsgFilter (hab, pqmsg, msgf)
   HAB hab;                /*handle of the anchor block                    */
   PQMSG pqmsg;            /*address of structure with message             */
   USHORT msgf;            /*message-filter code                           */

   The WinCallMsgFilter function calls a message-filter hook. This function
   allows an application to pass a message to the message-filter hook
   procedure(s).

 Parameters

   hab  Identifies the anchor block.

   pqmsg  Points to the QMSG structure that contains the message to be passed
   to the message-filter hook procedure. The QMSG structure has the following
   form:

   typedef struct _QMSG {
       HWND   hwnd;
       USHORT msg;
       MPARAM mp1;
       MPARAM mp2;
       ULONG  time;
       POINTL ptl;
   } QMSG;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   msgf  Specifies the message-filter code passed to the message-filter hook.
   This can be one of the following values:

   Message           Meaning
   ──────────────────────────────────────────────────────────────────────────
   MSGF_DIALOGBOX    Message originated while processing a modal dialog.

   MSGF_MESSAGEBOX   Message originated while processing a message box.

   MSGF_TRACK        Message originated while tracking a control, such as a
                     scroll bar.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if a message-filter hook returned TRUE.
   Otherwise, it is FALSE, indicating that all message-filter hooks returned
   FALSE or that no message-filter hooks are defined.

 See Also

   WinDispatchMsg, WinGetMsg


 ────────────────────────────────────────────────────────────────────────────
 WinCancelShutdown
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCancelShutdown (hmq, fCancelAlways)
   HMQ hmq;                /*handle of the message queue                   */
   BOOL fCancelAlways;     /*status of WM_QUIT message                     */

   The WinCancelShutdown function allows a thread to function after receiving
   a WM_QUIT message. The thread must call the WinCancelShutdown function,
   passing its message-queue handle for identification. If the thread owns
   the active window, that window is pushed to the bottom and deactivated.
   WinCancelShutdown maintains a list of queues associated with the threads
   that called it to avoid sending another WM_QUIT message to the same thread
   later.

 Parameters

   hmq  Identifies the message queue for the current thread.

   fCancelAlways  Specifies whether the thread receives WM_QUIT messages
   during system shutdown. If this parameter is TRUE, the thread does not
   receive WM_QUIT messages during system shutdown. Note that this does not
   prevent a WM_QUIT message from being put into the queue for this thread by
   some other mechanism. If this parameter is FALSE, the thread ignores the
   WM_QUIT message. Note that a subsequent system shutdown causes a new
   WM_QUIT message to be sent to this thread.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.


 ────────────────────────────────────────────────────────────────────────────
 WinCatch
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinCatch (pcatchbuf)
   PCATCHBUF pcatchbuf;    /*address of structure for execution            */
                           /*environment                                   */

   The WinCatch function captures the current execution environment and
   copies it to a buffer. The buffer can later be used by the WinThrow
   function to restore the execution environment. The execution environment
   includes the state of all system registers and the instruction counter.

 Parameters

   pcatchbuf  Points to the CATCHBUF structure that receives the execution
   environment. The CATCHBUF structure has the following form:

   typedef struct _CATCHBUF {
       ULONG reserved[4];
   } CATCHBUF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The WinCatch function returns immediately with a return value of zero. It
   returns again when the WinThrow function is called, this time with the
   return value specified in the sErrorReturn parameter of the WinThrow
   function.

 Comments

   The routine that calls WinCatch is responsible for freeing any resources
   allocated between the time WinCatch was called and the time WinThrow was
   called.

 Example

   This example calls WinCatch to save the current execution environment
   before calling a recursive sort function. The first return from WinCatch
   is zero. If the doSort function calls WinThrow, execution will again
   return to the WinCatch function. This time, WinCatch will return the
   STACKOVERFLOW error passed by the doSort function. The doSort function is
   recursive, that is, it calls itself. It maintains a variable,
   usStackCheck, that is used to check to see how much stack space has been
   used. If more then 3K of the stack has been used, it calls WinThrow to
   drop out of all the nested function calls back into the function that
   called WinCatch.

   USHORT usStackCheck
   CATCHBUF ctchbf;

   main() {
       SHORT sErrorReturn;

       sErrorReturn = WinCatch(&ctchbf); /* save execution environment */
       if (sErrorReturn) {
           .
           . /* error processing */
           .
       }
       usStackCheck = 0;              /* initialize stack usage count  */
       doSort(1, 1000);               /* call sort function            */
   }

   VOID doSort(sLeft, sRight)
   SHORT sLeft, sRight;
   {
       SHORT i, sLast;

       /*
        * check to see if more than 3K of the stack has been used, and if
        * so, call WinThrow to drop back into the original calling program
        */

       usStackCheck += 10;
       if (usStackCheck > (3 * 1024))
           WinThrow(&ctchbf, STACKOVERFLOW);
       .
       . /* sorting algorithm */
       .
       doSort(sLeft, sLast - 1);         /* note recursive call         */
       usStackCheck -= 10;               /* update stack check variable */
   }

 See Also

   WinThrow


 ────────────────────────────────────────────────────────────────────────────
 WinChangeSwitchEntry
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinChangeSwitchEntry (hSwitch, pswctl)
   HSWITCH hSwitch;        /*handle to task-switch list                    */
   PSWCNTRL pswctl;        /*address of structure with change information  */

   The WinChangeSwitchEntry function changes information in the switch list
   (the list of running programs displayed by the Task Manager).

 Parameters

   hSwitch  Identifies the switch-list entry to change. This handle is
   returned by the WinAddSwitchEntry function.

   pswctl  Points to the SWCNTRL structure that contains information about
   the changed switch-list entry. The SWCNTRL structure has the following
   form:

   typedef struct _SWCNTRL {
       HWND     hwnd;
       HWND     hwndIcon;
       HPROGRAM hprog;
       USHORT   idProcess;
       USHORT   idSession;
       UCHAR    uchVisibility;
       UCHAR    fbJump;
       CHAR     szSwtitle[MAXNAMEL+1];
       BYTE     fReserved;
   } SWCNTRL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is zero if the function is successful or nonzero if an
   error occurs.

 Example

   This example changes a swctl structure (SWCNTRL) and then calls
   WinChangeSwitchEntry to change the title of the application in the task
   list. For this example to work, the swctl structure must have been a
   global that was initialized prior to this call. See the example for the
   WinAddSwitchEntry function to see how to set up a SWCNTRL structure.

   strcpy(swctl.szSwtitle, "Generic: ");     /* application name */
   strcat(swctl.szSwtitle, pszFileName);     /* current filename */
   WinChangeSwitchEntry(hswitch, &swctl);    /* make the change  */

 See Also

   WinAddSwitchEntry, WinRemoveSwitchEntry


 ────────────────────────────────────────────────────────────────────────────
 WinCloseClipbrd
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCloseClipbrd (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinCloseClipbrd function closes the clipboard, allowing other
   applications to open it. This function sends a WM_DRAWCLIPBOARD message,
   causing the clipboard contents to be drawn in the clipboard-viewer window.
   The clipboard must be open prior to this function being called.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinEmptyClipbrd, WinOpenClipbrd


 ────────────────────────────────────────────────────────────────────────────
 WinCompareStrings
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinCompareStrings (hab, idcp, idcc, psz1, psz2, reserved)
   HAB hab;                /*handle of the anchor block                    */
   USHORT idcp;            /*code-page identifier                          */
   USHORT idcc;            /*country-code identifier                       */
   PSZ psz1;               /*address of first string                       */
   PSZ psz2;               /*address of second string                      */
   USHORT reserved;        /*must be zero                                  */

   The WinCompareStrings function compares two strings.

 Parameters

   hab  Identifies the anchor block.

   idcp  Identifies the code page.

   idcc  Identifies the country code.

   psz1  Points to the first string.

   psz2  Points to the second string.

   reserved  Specifies a reserved value; must be zero.

 Return Value

   The return value is the comparison result. It can be one of the following
   values:

   Value     Meaning
   ──────────────────────────────────────────────────────────────────────────
   WCS_EQ    Strings are equal.

   WCS_LT    String 1 is less than string 2.

   WCS_GT    String 1 is greater than string 2.

   WCS_ERROR Invalid country-code or code-page identifier.
   ──────────────────────────────────────────────────────────────────────────


 ────────────────────────────────────────────────────────────────────────────
 WinCopyAccelTable
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinCopyAccelTable (haccel, pacct, cbCopyMax)
   HACCEL haccel;          /*handle of the accelerator table               */
   PACCELTABLE pacct;      /*address of structure receiving information    */
   USHORT cbCopyMax;       /*maximum size of data area                     */

   The WinCopyAccelTable function copies an accelerator table. This function
   is used to obtain the accelerator-table data that corresponds to an
   accelerator-table handle or to determine the size of the accelerator-table
   data.

 Parameters

   haccel  Identifies the accelerator table.

   pacct  Points to the area of memory where the accelerator-table
   information will be copied (in the form of an ACCELTABLE structure). If
   this parameter is NULL, the function will return with the number of bytes
   needed to copy the table. The ACCELTABLE structure has the following form:

   typedef struct _ACCELTABLE {
       USHORT cAccel;
       USHORT codepage;
       ACCEL aaccel[1];
   } ACCELTABLE;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cbCopyMax  Specifies the maximum size of the data area pointed to by the
   pacct parameter. This parameter is ignored if pacct is NULL.

 Return Value

   The return value is the amount of data copied or the length required for
   the complete accelerator table if the function was successful, or it is
   zero if an error occurs.


 ────────────────────────────────────────────────────────────────────────────
 WinCopyRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCopyRect (hab, prclDst, prclSrc)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prclDst;         /*address of structure with destination         */
                           /*rectangle                                     */
   PRECTL prclSrc;         /*address of structure with source rectangle    */

   The WinCopyRect function copies the coordinates of one rectangle to
   another.

 Parameters

   hab  Identifies the anchor block.

   prclDst  Points to the RECTL structure that receives a copy of the
   rectangle specified by the prclSrc parameter. The RECTL structure has the
   following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prclSrc  Points to the RECTL structure that specifies the source
   rectangle.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinSetRectEmpty


 ────────────────────────────────────────────────────────────────────────────
 WinCpTranslateChar
 ────────────────────────────────────────────────────────────────────────────
   UCHAR WinCpTranslateChar (hab, cpSrc, chSrc, cpDst)
   HAB hab;                /*handle of the anchor block                    */
   USHORT cpSrc;           /*code page of source string                    */
   UCHAR chSrc;            /*character to be translated                    */
   USHORT cpDst;           /*code page of resultant string                 */

   The WinCpTranslateChar function translates a character from one code page
   to another.

 Parameters

   hab  Identifies the anchor block.

   cpSrc  Specifies the code page of the source string.

   chSrc  Specifies the character to be translated.

   cpDst  Specifies the code page of the resultant string.

 Return Value

   The return value is the translated character. If a match for this
   character is not found, 0xFF is returned.

 See Also

   WinCpTranslateString


 ────────────────────────────────────────────────────────────────────────────
 WinCpTranslateString
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCpTranslateString (hab, cpSrc, pszSrc, cpDst, cchDestMax, pszDest)
   HAB hab;                /*handle of the anchor block                    */
   USHORT cpSrc;           /*code page source string                       */
   PSZ pszSrc;             /*address of string to be translated            */
   USHORT cpDst;           /*code page of resultant string                 */
   USHORT cchDestMax;      /*maximum length of output string               */
   PSZ pszDest;            /*address of buffer for translated string       */

   The WinCpTranslateString function translates a string from one code page
   to another. Both source and destination strings are null terminated.

 Parameters

   hab  Identifies the anchor block.

   cpSrc  Specifies the code page of the source string.

   pszSrc  Points to the string to be translated.

   cpDst  Specifies the code page of the resultant string.

   cchDestMax  Specifies the maximum length of the output string.

   pszDest  Points to the buffer to receive the translated string.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs. A return value of TRUE indicates that most, if not all,
   characters were translated successfully. All untranslated characters are
   converted to 0xFF.

 See Also

   WinCpTranslateChar


 ────────────────────────────────────────────────────────────────────────────
 WinCreateAccelTable
 ────────────────────────────────────────────────────────────────────────────
   HACCEL WinCreateAccelTable (hab, pacct)
   HAB hab;                /*handle of the anchor block                    */
   PACCELTABLE pacct;      /*address of structure for accelerator table    */

   The WinCreateAccelTable function allocates an accelerator table with its
   contents initialized to that of the specified ACCELTABLE structure.

 Parameters

   hab  Identifies the anchor block.

   pacct  Points to the ACCELTABLE structure that contains an accelerator
   table. The ACCELTABLE structure has the following form:

   typedef struct _ACCELTABLE {
       USHORT cAccel;
       USHORT codepage;
       ACCEL aaccel[1];
   } ACCELTABLE;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value identifies an accelerator table.

 Comments

   When an application terminates it must call WinDestroyAccelTable to
   destroy every accelerator table created by the call to the
   WinCreateAccelTable function.

 See Also

   WinCopyAccelTable, WinDestroyAccelTable, WinQueryAccelTable,
   WinSetAccelTable


 ────────────────────────────────────────────────────────────────────────────
 WinCreateAtomTable
 ────────────────────────────────────────────────────────────────────────────
   HATOMTBL WinCreateAtomTable (cbInitial, cBuckets)
   USHORT cbInitial;       /*number of bytes for atom table                */
   USHORT cBuckets;        /*size of hash table                            */

   The WinCreateAtomTable function creates an empty atom table. This function
   must be called before any other atom-manager function.

 Parameters

   cbInitial  Specifies the number of initial bytes reserved for the atom
   table. This is a lower bound on the amount of memory reserved. The amount
   of memory actually used by an atom table depends on the actual number of
   atoms stored in the table. If this parameter is zero, the size of the atom
   table is the minimum size needed to store the atom hash table.

   cBuckets  Specifies the size of the hash table used to access atoms. If
   this parameter is zero, the default value 37 is used. For best results,
   this parameter should be a prime number.

 Return Value

   The return value is a handle to an atom table, or NULL if an error occurs.

 See Also

   WinAddAtom, WinDeleteAtom, WinDestroyAtomTable,
   WinQuerySystemAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinCreateCursor
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCreateCursor (hwnd, x, y, cx, cy, fs, prclClip)
   HWND hwnd;              /*handle of the window with the cursor          */
   SHORT x;                /*horizontal position of the cursor             */
   SHORT y;                /*vertical position of the cursor               */
   SHORT cx;               /*cursor width                                  */
   SHORT cy;               /*cursor height                                 */
   USHORT fs;              /*cursor appearance                             */
   PRECTL prclClip;        /*address of structure with cursor area         */

   The WinCreateCursor function creates a cursor for a specified window.

 Parameters

   hwnd  Identifies the window in which the cursor is displayed. This
   parameter can be the desktop window handle or HWND_DESKTOP.

   x  Specifies the horizontal position of the cursor.

   y  Specifies the vertical position of the cursor.

   cx  Specifies the width of the cursor. If this parameter is zero, the
   system border width (SV_CXBORDER) is used.

   cy  Specifies the height size of cursor. If this parameter is zero, the
   system border height (SV_CYBORDER) is used.

   fs  Specifies the appearance of the cursor. This parameter can be one of
   the following values:

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   CURSOR_FLASH          Cursor flashes.

   CURSOR_FRAME          Cursor is a rectangular frame.

   CURSOR_HALFTONE       Cursor is halftone.

   CURSOR_SOLID          Cursor is solid.

   CURSOR_SETPOS         Set a new cursor position. The cx and cy parameters
                         are ignored. Used when a cursor has already been
                         created. All other appearance flags are ignored.
   ──────────────────────────────────────────────────────────────────────────

   prclClip  Points to the RECTL structure that contains the coordinates of a
   rectangle within which the cursor is visible. If the cursor goes outside
   this rectangle, it becomes invisible (it is clipped). The rectangle is
   specified in window coordinates. If prclClip is NULL, the cursor is
   clipped to the window identified by the hwnd parameter. The RECTL
   structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The cursor is used to indicate the position of text input. It is initially
   hidden and must be made visible by using the WinShowCursor function.

   Only one cursor is available at a time on a given screen. If another
   cursor exists when this function is called, it is destroyed. An
   application should create and display a cursor when it has the input focus
   or is the active window. Creating a cursor at any other time may stop the
   cursor from flashing in another window. Similarly, when the application
   loses the input focus or becomes inactive, it should destroy its cursor.

   The cursor width is typically specified as zero (default width is used).
   This is preferable to a value of 1 because such a fine width will be
   almost invisible on a high-resolution device.

 See Also

   WinDestroyCursor, WinQueryCursorInfo, WinShowCursor


 ────────────────────────────────────────────────────────────────────────────
 WinCreateDlg
 ────────────────────────────────────────────────────────────────────────────
   HWND WinCreateDlg (hwndParent, hwndOwner, pfnDlgProc, pdlgt,
   pCreateParams)
   HWND hwndParent;        /*handle of the parent window                   */
   HWND hwndOwner;         /*handle of the owner window                    */
   PFNWP pfnDlgProc;       /*address of dialog procedure                   */
   PDLGTEMPLATE pdlgt;     /*address of structure with dialog template     */
   PVOID pCreateParams;

   The WinCreateDlg function creates a dialog window from a dialog template
   in memory. This function works like the WinLoadDlg function, which creates
   a dialog window from a dialog template in a resource.

 Parameters

   hwndParent  Identifies the parent window.

   hwndOwner  Identifies the owner window.

   pfnDlgProc  Points to the dialog procedure.

   pdlgt  Points to the DLGTEMPLATE structure that contains the dialog
   template. The DLGTEMPLATE structure has the following form:

   typedef struct _DLGTEMPLATE {
       USHORT      cbTemplate;
       USHORT      type;
       USHORT      codepage;
       USHORT      offadlgti;
       USHORT      fsTemplateStatus;
       USHORT      iItemFocus;
       USHORT      coffPresParams;
       DLGTITEM    adlgti[1];
   } DLGTEMPLATE;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pCreateParams  Contains application-specific data that is passed to the
   dialog procedure as part of the WM_INITDLG message.

 Return Value

   The return value is the handle of the dialog window that was created, or
   NULL if an error occurred.

 Example

   This example loads a dialog template from the application's resources and
   uses the template with the WinCreateDlg function to create a dialog
   window. This example is identical to calling the WinLoadDlg function, but
   gives the application the advantage of reviewing and modifying the dialog
   template before creating the dialog window.

   SEL sel;
   PDLGTEMPLATE pdlgt;

   DosGetResource(NULL, RT_DIALOG, ID_DIALOG, &sel);
   pdlgt = MAKEP(sel, 0);    /* convert resource to structure pointer */

   /* make any changes to dialog template here */

   WinCreateDlg(HWND_DESKTOP,
       NULL,        /* owner window                */
       MyDlgProc,   /* address of dialog procedure */
       pdlgt,       /* address of dialog structure */
       NULL);       /* application-specific data   */
   DosFreeSeg(sel); /* free the memory             */

 See Also

   DosGetResource, WinDlgBox, WinLoadDlg, WinProcessDlg


 ────────────────────────────────────────────────────────────────────────────
 WinCreateFrameControls
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinCreateFrameControls (hwndFrame, pfcdata, pszTitle, hmod)
   HWND hwndFrame;         /*handle of the frame window                    */
   PFRAMECDATA pfcdata;    /*address of structure                          */
   PSZ pszTitle;           /*address of title-bar string                   */
   HMODULE hmod;           /*handle of module with the frame controls      */

   The WinCreateFrameControls function creates standard frame controls for a
   specified window. This function is used when the standard frame controls
   are needed for a nonstandard window; for example, with a window with a
   class other than WC_FRAME.

 Parameters

   hwndFrame  Identifies the frame window that becomes the parent and owner
   window of all the frame controls created.

   pfcdata  Points to the FRAMECDATA structure that contains information
   about the frame controls that are to be created. The FRAMECDATA structure
   has the following form:

   typedef struct _FRAMECDATA {
       USHORT       cb;
       ULONG        flCreateFlags;
       HMODULE      hmodResources;
       USHORT       idResources;
   } FRAMECDATA;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pszTitle  Points to a null-terminated string displayed in a title-bar
   control. hmod  Identifies the module that contains the frame controls.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreateWindow


 ────────────────────────────────────────────────────────────────────────────
 WinCreateGroup
 ────────────────────────────────────────────────────────────────────────────
   HPROGRAM WinCreateGroup (hab, pszTitle, fVisible, hprogDest, pszHelp)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszTitle;           /*address of the group title                    */
   BYTE fVisible;          /*visibility flag                               */
   HPROGRAM hprogDest;     /*handle of the destination group               */
   PSZ pszHelp;            /*address of help text                          */

   The WinCreateGroup function creates a new program-group entry in the
   installed program list. The new group is created empty. The WinAddProgram
   function must be used to add program entries to the group. If the group
   already exists, the existing group handle is returned.

 Parameters

   hab  Identifies the anchor block.

   pszTitle  Points to the title of the new group. The maximum string size is
   60 characters. Strings that exceed this limit are truncated to 60
   characters. Leading and trailing blanks are removed. The string must
   contain at least one nonblank character and must not contain a backslash
   (\).

   fVisible  Specifies the visibility of the new group. If it is SHE_VISIBLE,
   the group is visible (can be viewed by end-user). If it is SHE_INVISIBLE,
   the group is invisible.

   hprogDest  Identifies the program group into which the new group is
   placed. If this parameter is NULL, the new group is placed in the root
   group.

   pszHelp  Points to a null-terminated text string that is used as a short
   piece of help information relating to the new program group. This
   parameter is optional and can be NULL. If used, the string must contain at
   least one nonblank character and be less than 60 characters in length.

 Return Value

   The return value is the group handle for the newly created group if the
   function is successful. Otherwise, the return value is NULL, indicating
   that an error occurred.

 See Also

   WinAddProgram


 ────────────────────────────────────────────────────────────────────────────
 WinCreateHeap
 ────────────────────────────────────────────────────────────────────────────
   HHEAP WinCreateHeap (selHeapBase, cbHeap, cbGrow, cbMinDed, cbMaxDed,
   fsOptions)
   USHORT selHeapBase;     /*selector of the heap                          */
   USHORT cbHeap;          /*initial heap size                             */
   USHORT cbGrow;          /*number of bytes heap must grow                */
   USHORT cbMinDed;        /*minimum number of dedicated free lists        */
   USHORT cbMaxDed;        /*maximum number of dedicated free lists        */
   USHORT fsOptions;       /*heap options                                  */

   The WinCreateHeap function creates a heap that can used for memory
   management.

 Parameters

   selHeapBase  Specifies the selector of the segment that will contain the
   local heap.

   cbHeap  Specifies the initial heap size (in bytes).

   cbGrow  Specifies the minimum number of bytes by which the heap must be
   increased if it is too small to satisfy a memory allocation request (see
   the WinAllocMem and WinReallocMem functions). If this parameter is zero,
   the default value of 512 bytes is used.

   cbMinDed  Specifies the minimum number of dedicated free lists.

   cbMaxDed  Specifies the maximum number of dedicated free lists.

   fsOptions  Specifies the optional characteristics for the heap. It may be
   one or more of the following values:

   Value         Meaning
   ──────────────────────────────────────────────────────────────────────────
   HM_MOVEABLE   Specifies that the created heap supports movable objects.
                 WinAllocMem then reserves an additional two words at the
                 beginning of each allocated object.

   HM_VALIDSIZE  Specifies that the heap manager should check the size
                 arguments to WinReallocMem and WinFreeMem function calls
                 against the two additional words stored at the beginning of
                 each allocated object. This option is only valid if
                 HM_MOVEABLE is also specified.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is a handle to the heap, or zero if an error occurred.

 Comments

   There are three types of segments that can contain a heap:

   ■  Automatic data segment of an application

   ■  Automatic data segment of a dynamic-link package

   ■  Segment allocated by the DosAllocSeg function (public or shared)

   To accommodate these various targets for heaps, all four possible
   combinations of the parameters are used to discriminate between the
   various options.

   These combinations are shown in the following list:

╓┌─┌───────────┌─────────┌───────────────────────────────────────────────────╖
   selHeapBase cbHeap    Meaning
   ──────────────────────────────────────────────────────────────────────────
   Zero        Zero      Caller is an application that places the heap at the
                         end of its automatic data segment. The size of the
                         heap was specified with the HEAPSIZE keyword in the
                         application's .def file to the linker. This function
                         extracts the heap-size parameter from the local
                         information segment and uses that many bytes at the
                         end of the caller's automatic data segment. No
                         reallocation of the data segment occurs, as the
                         loader already reserved space at the end of the data
   selHeapBase cbHeap    Meaning
   ──────────────────────────────────────────────────────────────────────────
                        loader already reserved space at the end of the data
                         segment, after the static data was loaded from the
                         .exe file.

   Selector    Nonzero   Caller is a dynamic-link package that places a heap
                         at the end of its automatic data segment. The cbHeap
                         parameter must be less than or equal to the HEAPSIZE
                         value from the .def file that was passed to the
                         dynamic-link package's initialization entry point in
                         the cx register. Otherwise, this function may
                         produce incorrect results.

   Selector    Zero      Caller is either an application or a dynamic-link
                         package that has explicitly allocated a segment
                         using the DosAllocSeg function and places a heap in
                         that segment. The heap is placed at the beginning of
                         the segment and the size of the segment (determined
                         by using DosSizeSeg) is the size of the heap.

   selHeapBase cbHeap    Meaning
   ──────────────────────────────────────────────────────────────────────────

   Zero        Nonzero   Caller is either an application or a dynamic-link
                         package that places a heap of a specific size in a
                         separate segment but does not call DosAllocSeg. For
                         information about accessing the segment implicitly
                         allocated by WinCreateHeap when called with this
                         combination of parameters, see the WinLockHeap
                         function.
   ──────────────────────────────────────────────────────────────────────────


 See Also

   DosAllocSeg, DosSizeSeg, WinAllocMem, WinDestroyHeap, WinFreeMem,
   WinLockHeap, WinReallocMem


 ────────────────────────────────────────────────────────────────────────────
 WinCreateMenu
 ────────────────────────────────────────────────────────────────────────────
   HWND WinCreateMenu (hwndParent, pvmt)
   HWND hwndParent;        /*handle of the parent window                   */
   PVOID pvmt;             /*address of the menu template                  */

   The WinCreateMenu function creates a menu window from a menu template. The
   menu window is created with its parent and owner set to the hwndParent
   parameter.

 Parameters

   hwndParent  Identifies the owner and parent window which should be a frame
   window.

   pvmt  Points to the menu template. The format of the pvmt parameter is the
   binary menu-template-resource format.

 Return Value

   The return value is the menu-window handle, or zero if an error occurred.

 See Also

   WinCreateWindow, WinLoadMenu


 ────────────────────────────────────────────────────────────────────────────
 WinCreateMsgQueue
 ────────────────────────────────────────────────────────────────────────────
   HMQ WinCreateMsgQueue (hab, cmsg)
   HAB hab;                /*handle of the anchor block                    */
   SHORT cmsg;             /*size of the message queue                     */

   The WinCreateMsgQueue function creates a message queue for the current
   thread. This function must be called after the WinInitialize function but
   before any other Presentation Manager functions are called. It can be
   called only once per thread.

 Parameters

   hab  Identifies the anchor block.

   cmsg  Specifies the maximum queue size. This parameter can use a value of
   DEFAULT_QUEUE_SIZE to get the system default queue size.

 Return Value

   The return value identifies a message queue, or it is NULL if the queue
   cannot be created.

 Comments

   The default queue size is 10 messages which is sufficient for most
   applications. However, if an application processes a high volume of
   messages, and the processing of some of these messages is slow, the
   application should create a larger queue.

 Example

   This example shows the typical startup code for a thread that will be
   making Presentation Manager function calls; in this case the startup
   function of the application. It calls WinInitialize to initialize the
   thread for making Presentation Manager function calls, and
   WinCreateMsgQueue to create a message queue for the thread. Before the
   thread terminates, it calls WinDestroyMsgQueue to destroy the message
   queue.

   HAB hab;    /* handle to the anchor block  */
   HMQ hmq;    /* handle to the message queue */

   VOID cdecl main() {
       hab = WinInitialize(NULL);
       hmq = WinCreateMsgQueue(hab, DEFAULT_QUEUE_SIZE);
           .
           . /* initialization and message loop */
           .
       WinDestroyMsgQueue(hmq);
       WinTerminate(hab);
       DosExit(EXIT_PROCESS, 0);
   }

 See Also

   WinDestroyMsgQueue, WinInitialize


 ────────────────────────────────────────────────────────────────────────────
 WinCreatePointer
 ────────────────────────────────────────────────────────────────────────────
   HPOINTER WinCreatePointer (hwndDesktop, hbmPointer, fPointer, xHotspot,
   yHotspot)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HBITMAP hbmPointer;     /*handle of the bitmap                          */
   BOOL fPointer;          /*full-size or icon-size pointer                */
   SHORT xHotspot;         /*horizontal hot spot                           */
   SHORT yHotspot;         /*vertical hot spot                             */

   The WinCreatePointer function creates a pointer from a bitmap.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hbmPointer  Identifies the bitmap from which the pointer image is created.
   The bitmap must be of an even vertical size, logically divided into two
   sections in the vertical direction, each half representing one of the two
   images used as the successive drawing masks for the pointer. The top half
   is the XOR image. The bottom half is the AND image. This allows a pointer
   to have four colors: black, white, background, and inverted background.

   fPointer  Indicates if the pointer is pointer- or icon-sized. If this
   parameter is TRUE, the bitmap will be stretched (if necessary) to the
   system-pointer dimensions. If this parameter is FALSE, the bitmap will be
   stretched (if necessary) to the system-icon dimensions.

   xHotspot  Specifies the horizontal offset of the pointer hot spot from the
   lower-left corner (in pels).

   yHotspot  Specifies the vertical offset of the pointer hot spot from the
   lower-left corner (in pels).

 Return Value

   The return value is the handle of the new pointer, or it is NULL if an
   error occurs.

 Comments

   Since the bitmap needs to include two images, one on top of the other, the
   height of the bitmap must be an even number. This function will fail if
   the height is not an even number.

 See Also

   WinDestroyPointer, WinDrawPointer, WinLoadPointer, WinQueryPointer,
   WinSetPointer


 ────────────────────────────────────────────────────────────────────────────
 WinCreateStdWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinCreateStdWindow (hwndParent, flStyle, pflCreateFlags,
   pszClientClass, pszTitle, flClientStyle, hmod, idResources, phwndClient)
   HWND hwndParent;        /*handle of the parent window                   */
   ULONG flStyle;          /*frame-window style                            */
   PULONG pflCreateFlags;  /*creation flags                                */
   PSZ pszClientClass;     /*client-window class name                      */
   PSZ pszTitle;           /*address of title-bar text                     */
   ULONG flClientStyle;    /*client-window style                           */
   HMODULE hmod;           /*handle of the resource module                 */
   USHORT idResources;     /*frame-window identifier                       */
   PHWND phwndClient;      /*address of client-window handle               */

   The WinCreateStdWindow function creates a standard frame window.

 Parameters

   hwndParent  Identifies the parent window. A main window is created if this
   parameter is NULL, HWND_DESKTOP, or a window handle returned by the
   WinQueryDesktopWindow function. An object window is created if this
   parameter is HWND_DESKTOP or a window handle returned by the
   WinQueryObjectWindow function.

   flStyle  Specifies the frame-window style. It can be any combination of
   the WS_ styles (see the description for flClientStyle) and the following
   values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   FS_ACCELTABLE         Creates an accelerator table. The table is loaded
                         from the application's resource file. It should have
                         the same identifier as the menu and the icon (if
                         any).

   FS_BORDER             Creates a window that has a border with an inner
                         border drawn with the active title-bar color. It is
                         most often used by dialog boxes.

   FS_DLGBORDER          Creates a window with a single line border around
                         it. The width of the border line is SV_CXBORDER and
                         the height is SV_CYBORDER. For a description of
                         these system values, see the comments section of
                         WinSetSysValue.

   FS_ICON               The created window has an icon with the same
                         identifier as the menu and accelerator table (if
                         any).
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        any).

   FS_MOUSEALIGN         Creates a window whose position is relative to the
                         current position of the mouse. Normally, this is
                         only used by dialog boxes.

   FS_NOBYTEALIGN        Creates a window whereby the frame window is not
                         byte aligned. Setting this flag will decrease the
                         performance of drawing operations to the client
                         window.

   FS_NOMOVEWITHOWNER    Creates a frame window that will not move if the
                         owner window moves.

   FS_SCREENALIGN        Creates a window that is aligned with respect to the
                         screen. Normally, this is only used by dialog boxes.

   FS_SHELLPOSITION      The Presentation Manager (shell) determines the
                         position of the window, typically in a cascaded
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        position of the window, typically in a cascaded
                         position from the last application that started.

   FS_SIZEBORDER         Creates a sizing border.

   FS_SYSMODAL           Creates a system modal window. For a description of
                         a system modal window, see the comments section of
                         the WinSetSysModalWindow function.

   FS_TASKLIST           The window title is added to the Task Manager's
                         list.

   FS_STANDARD           Specifies a combination of the following flags:

                             FS_ICON
                             FS_ACCELTABLE
                             FS_SHELLPOSITION
                             FS_TASKLIST

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   ──────────────────────────────────────────────────────────────────────────


   pflCreateFlags  Specifies options that control how the frame window is
   created. If no options are specified, FCF_STANDARD is used. The flags may
   be any combination of the following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   FCF_ACCELTABLE        Creates an accelerator table. The table is loaded
                         from the application's resource file. It should have
                         the same identifier as the menu and the icon (if
                         any).

   FCF_BORDER            Creates a window with a single line border around
                         it. The width of the border line is SV_CXBORDER and
                         the height is SV_CYBORDER. For a description of
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        the height is SV_CYBORDER. For a description of
                         these system values, see the WinSetSysValue
                         function.

   FCF_DLGBORDER         Creates a window that has a border with an inner
                         border drawn with the active title-bar color. It is
                         most often used by dialog boxes.

   FCF_HORZSCROLL        Creates a horizontal scroll bar.

   FCF_ICON              The created window has an icon with the same
                         identifier as the menu and accelerator table (if
                         any).

   FCF_MAXBUTTON         Creates a maximize button.

   FCF_MENU              Creates a menu bar.

   FCF_MINBUTTON         Creates a minimize button.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  FCF_MINBUTTON         Creates a minimize button.

   FCF_MINMAX            Creates a minimize and a maximize button
                         (FCF_MINBUTTON | FCF_MAXBUTTON).

   FCF_MOUSEALIGN        Creates a window whose position is relative to the
                         current position of the mouse. Normally, this is
                         only used by dialog boxes.

   FCF_NOBYTEALIGN       Creates a window whereby the client window is not
                         byte aligned. Setting this flag will decrease the
                         performance of drawing operations to the client
                         window.

   FCF_NOMOVEWITHOWNER   Creates a window that will not move if the owner
                         window moves.

   FCF_SCREENALIGN       Creates a window that is aligned with respect to the
                         screen. Normally, this is only used by dialog boxes.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        screen. Normally, this is only used by dialog boxes.

   FCF_SHELLPOSITION     The Presentation Manager (shell) determines the
                         position of the window, typically in a cascaded
                         position from the last application that started.

   FCF_SIZEBORDER        Creates a sizing border.

   FCF_SYSMENU           Creates a system menu.

   FCF_SYSMODAL          Creates a system modal window. For a description of
                         a system modal window, see the WinSetSysModalWindow
                         function.

   FCF_TASKLIST          Adds the window to the switch list of the Task
                         Manager.

   FCF_TITLEBAR          Creates a title bar.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   FCF_VERTSCROLL        Creates a vertical scroll bar.

   FCF_STANDARD          Specifies a combination of the following flags:

                             FCF_TITLEBAR
                             FCF_SYSMENU
                             FCF_MENU
                             FCF_SIZEBORDER
                             FCF_MINMAX
                             FCF_ICON
                             FCF_ACCELTABLE
                             FCF_SHELLPOSITION
                             FCF_TASKLIST

   ──────────────────────────────────────────────────────────────────────────


   pszClientClass  Points to the client-window class name. If the
   pszClientClass parameter is not a zero-length string, a client window of
   style flClientStyle and class pszClientClass is created. This parameter is
   an application-specified name (defined by the WinRegisterClass function),
   the name of a preregistered WC class, or a WC constant. If this parameter
   is NULL, no client area is created.

   pszTitle  Points to the title-bar text. This parameter is ignored if
   FCF_TITLEBAR is not specified in the pflCreateFlags parameter.

   flClientStyle  Specifies the client-window style. It can be a combination
   of one or more of the following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   WS_CLIPCHILDREN       Prevents a window from painting over its child
                         windows.

   WS_CLIPSIBLINGS       Prevents a window from painting over its sibling
                         windows.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   WS_DISABLED           Disables mouse and keyboard input to the window. It
                         is used to temporarily prevent the user from using
                         the window.

   WS_MAXIMIZED          Enlarges the window to the maximum size.

   WS_MINIMIZED          Reduces the window to the minimum size.

   WS_PARENTCLIP         Prevents a window from painting over its parent
                         window.

   WS_SAVEBITS           Saves the image under the window as a bitmap. When
                         the window is moved or hidden, the system restores
                         the image by copying the bits.

   WS_SYNCPAINT          Causes the window to immediately receive WM_PAINT
                         messages after a part of the window becomes invalid.
                         Without this style, the window receives WM_PAINT
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        Without this style, the window receives WM_PAINT
                         messages only if no other message is waiting to be
                         processed.

   WS_VISIBLE            Makes the window visible. This window will be drawn
                         on the screen unless overlapping windows completely
                         obscure it. Windows without this style are hidden.
   ──────────────────────────────────────────────────────────────────────────


   This parameter is ignored if the pszClientClass parameter is a zero-length
   string.

   hmod  Identifies the module that contains the resource definitions. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module. This parameter is ignored
   unless FS_ICON, FS_ACCELTABLE, or FS_MENU is specified in the flStyle
   parameter.

   idResources  Identifies the frame-window identifier and the identifier
   within the resource definition of the required resource. The application
   must ensure that all resources related to one frame window have the same
   identifier value.

   phwndClient  Points to the variable that receives the client-window
   handle. It will be NULL if the function fails.

 Return Value

   The return value is the handle of the frame window, or it is NULL if an
   error occurs.

 Example

   This example shows a typical initialization function for a window. The
   function first registers the window class, then calls WinCreateStdWindow
   to create a standard window and returns immediately if the function fails.
   Otherwise, it continues on to do other initialization processing.

   Note: The FCF_STANDARD constant can only be used if you have all the
   resources in defines. For example, if you use this constant, and you don't
   have an accelerator table, the function will fail.

   CHAR szClassName[] = "Generic";    /* window class name    */
   HWND hwndClient;                   /* handle to the client */
   HWND hwndClient;                   /* handle to the client */

   BOOL GenericInit()
   {
       ULONG flStyle;

       flStyle = FCF_STANDARD;
       if (!WinRegisterClass(hab, szClassName, GenericWndProc, 0L, 0))
           return (FALSE);

       hwndFrame = WinCreateStdWindow(HWND_DESKTOP,
           0L,                     /* frame-window style            */
           &flStyle,               /* window style                  */
           szClassName,            /* class name                    */
           "Generic Application",  /* window title                  */
           0L,                     /* default client style          */
           NULL,                   /* resource in executable file   */
           IDM_RESOURCE,           /* resource id                   */
           &hwndClient);           /* receives client window handle */

       if (! hwndFrame)
           return (FALSE);
       else {
           .
           . /* other initialization code */
           .

 See Also

   DosLoadModule, WinCreateWindow, WinQueryDesktopWindow,
   WinQueryObjectWindow, WinSetSysModalWindow, WinSetSysValue,
   WinSetWindowPos, WinSetWindowUShort


 ────────────────────────────────────────────────────────────────────────────
 WinCreateWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinCreateWindow (hwndParent, pszClass, pszName, flStyle, x, y, cx,
   cy, hwndOwner, hwndInsertBehind, id, pCtlData, pPresParams)
   HWND hwndParent;        /*desktop-window handle                         */
   PSZ pszClass;           /*address of registered class name              */
   PSZ pszName;            /*address of window text                        */
   ULONG flStyle;          /*window style                                  */
   SHORT x;                /*horizontal position of window                 */
   SHORT y;                /*vertical position of window                   */
   SHORT cx;               /*window width                                  */
   SHORT cy;               /*window depth                                  */
   HWND hwndOwner;         /*owner-window handle                           */
   HWND hwndInsertBehind;  /*handle to sibling window                      */
   USHORT id;              /*window identifier                             */
   PVOID pCtlData;         /*address of buffer                             */
   PVOID pPresParams;      /*reserved                                      */

   The WinCreateWindow function creates a new window.

 Parameters

   hwndParent  Specifies the parent window for the new window. Any valid
   window handle can be used.

   pszClass  Points to the registered class name. This parameter is either an
   application-specified name (defined by the WinRegisterClass function), the
   name of a preregistered WC class, or a WC constant.

   pszName  Points to window text or other class-specific data. The actual
   structure of the data is class-specific. This data is usually a
   zero-terminated string, which is often displayed in the window.

   flStyle  Specifies the window style. It can be a combination of one or
   more of the following values:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   WS_CLIPCHILDREN     Prevents a window from painting over its child
                       windows.

   WS_CLIPSIBLINGS     Prevents a window from painting over its sibling
                       windows.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      windows.

   WS_DISABLED         Disables mouse and keyboard input to the window. It is
                       used to temporarily prevent the user from using the
                       window.

   WS_MAXIMIZED        Enlarges the window to the maximum size.

   WS_MINIMIZED        Reduces the window to the minimum size.

   WS_PARENTCLIP       Prevents a window from painting over its parent
                       window.

   WS_SAVEBITS         Saves the image under the window as a bitmap. When the
                       window is moved or hidden, the system restores the
                       image by copying the bits.

   WS_SYNCPAINT        Causes the window to immediately receive WM_PAINT
                       messages after a part of the window becomes invalid.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      messages after a part of the window becomes invalid.
                       Without this style, the window receives WM_PAINT
                       messages only if no other message is waiting to be
                       processed.

   WS_VISIBLE          Makes the window visible. This window will be drawn on
                       the screen unless overlapping windows completely
                       obscure it. Windows without this style are hidden.
   ──────────────────────────────────────────────────────────────────────────


   x  Specifies the horizontal position of the window relative to the origin
   of the parent window.

   y  Specifies the vertical position of the window relative to the origin of
   the parent window.

   cx  Specifies the window width in pels.

   cy  Specifies the window depth in pels.

   hwndOwner  Identifies the owner window.

   hwndInsertBehind  Identifies the sibling window behind which the specified
   window is placed. If this parameter is HWND_TOP, the specified window is
   placed on top of all its sibling windows. If this parameter is
   HWND_BOTTOM, the specified window is placed behind all its sibling
   windows. If this parameter is not HWND_TOP or HWND_BOTTOM, or it is a
   child window of the desktop window identified by hwndParent, then NULL is
   returned.

   id  Specifies the window identifier, a value given by the application that
   allows a specific child window to be identified. For example, the controls
   of a dialog box have unique identifiers so that an owner window can
   distinguish which control has notified it. Window identifiers are also
   used for frame windows.

   pCtlData  Points to the buffer that contains class-specific information.
   This data is passed to the window procedure by the WM_CREATE message.

   pPresParams  Points to the presentation parameters. This is a reserved
   field and must be zero.

 Return Value

   The return value is the handle of the window, or NULL if an error occurs.

 Comments

   WinCreateWindow sends a WM_CREATE message to the window procedure of the
   window being created, and then sends the WM_ADJUSTWINDOWPOS message before
   the window is displayed. The values passed are those given to the
   WinCreateWindow function.

   The WM_SIZE message is not sent by WinCreateWindow while the window is
   being created. Any required size processing is performed during the
   processing of the WM_CREATE message.

 See Also

   WinCreateStdWindow, WinQueryObjectWindow, WinRegisterClass


 ────────────────────────────────────────────────────────────────────────────
 WinDdeInitiate
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDdeInitiate (hwndClient, pszAppName, pszTopicName)
   HWND hwndClient;        /*handle of the client window                   */
   PSZ pszAppName;         /*address of application name                   */
   PSZ pszTopicName;       /*address of topic name                         */

   The WinDdeInitiate function initiates a DDE conversation by sending a
   WM_DDE_INITIATE message. All server applications matching the supplied
   application name will reply with a WM_DDE_INITIATEACK message if they
   support the specified topic.

 Parameters

   hwndClient  Identifies the client window. Since the window handle serves
   as the recipient of DDE messages for its conversation, it need not be
   visible. All applications must rely only on their own window handles to
   identify conversations.

   pszAppName  Points to a NULL terminated string containing the server's
   application name. If the string has zero length, any server application
   may respond.

   pszTopicName  Points to a NULL terminated string containing the topic
   name. If the string has zero length, the server will respond once for each
   topic that it supports.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The WM_DDE_INITIATE is sent to all top-level frame windows in the system.
   Any prospective server must subclass a top-level frame window in order to
   retrieve this message.

 See Also

   WinDdePostMsg, WinDdeRespond


 ────────────────────────────────────────────────────────────────────────────
 WinDdePostMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDdePostMsg (hwndTo, hwndFrom, wm, pddes, fRetry)
   HWND hwndTo;            /*handle of the window to post to               */
   HWND hwndFrom;          /*handle of the window that is posting          */
   USHORT wm;              /*message number                                */
   PDDESTRUCT pddes;       /*address of the structure to pass              */
   BOOL fRetry;            /*retry flag                                    */

   The WinDdePostMsg function posts a DDE message to the specified window's
   message queue.

 Parameters

   hwndTo  Identifies the window the message is to be posted to.

   hwndFrom  Identifies the window that is posting the message.

   wm  Specifies the message being sent. The following messages may be sent:

         WM_DDE_ACK
         WM_DDE_ADVISE
         WM_DDE_DATA
         WM_DDE_EXECUTE
         WM_DDE_INITIATE
         WM_DDE_INITIATEACK
         WM_DDE_POKE
         WM_DDE_REQUEST
         WM_DDE_TERMINATE
         WM_DDE_UNADVISE

   pddes  Points to a DDESTRUCT structure. The structure has the following
   form:

   typedef struct _DDESTRUCT {
       ULONG     cbData;
       USHORT    fsStatus;
       USHORT    usFormat;
       USHORT    offszItemName;
       USHORT    offabData;
   } DDESTRUCT;

   For more information, see Chapter 4, "Types, Macros, Structures."

   fRetry  Specifies whether or not to try to send the message again if it
   fails the first time because the destination queue was full. If TRUE, the
   message is sent repeatedly at one second intervals until it could be
   successfully posted.

 Return Value

   The return value is TRUE if the function is successful, or FALSE if an
   error occurred. If the fRetry parameter is TRUE, this function will still
   return FALSE if the message cannot be sent for any reason other then the
   destination queue being full.

 See Also

   WinDdeInitiate, WinDdeRespond


 ────────────────────────────────────────────────────────────────────────────
 WinDdeRespond
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinDdeRespond (hwndClient, hwndServer, pszAppName, pszTopicName)
   HWND hwndClient;        /*handle of the client window                   */
   HWND hwndServer;        /*handle of the server window                   */
   PSZ pszAppName;         /*address of name of application                */
   PSZ pszTopicName;       /*address of name of topic                      */

   The WinDdeRespond function sends an acknowledgement message
   (WM_DDE_INITIATEACK) back to the application that sent a WM_DDE_INITIATE
   message.

 Parameters

   hwndClient  Identifies the client window.

   hwndServer  Identifies the server window.

   pszAppName  Points to the name of the application that is acknowledging
   the WM_DDE_INITIATE message.

   pszTopicName  Points to the topic name that the acknowledging application
   will accept.

 Return Value

   The return value is the result of sending the WM_DDE_INITIATEACK message
   to the client window.

 See Also

   WinDdeInitiate


 ────────────────────────────────────────────────────────────────────────────
 WinDefAVioWindowProc
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinDefAVioWindowProc (hwnd, msg, mp1, mp2)
   HWND hwnd;              /*handle of the window                          */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*message parameter                             */
   MPARAM mp2;             /*message parameter                             */

   The WinDefAVioWindowProc function calls the default window procedure for
   an advanced video-input-and-output (AVIO) window. An AVIO application must
   use this function instead of the WinDefWindowProc function that is used
   with Presentation Manager applications.

   The default window procedure provides default processing for any window
   messages that an application does not process. This function is used to
   ensure that every message is processed. It should be called with the same
   parameters as those received by the window procedure.

 Parameters

   hwnd  Identifies the window that received the message.

   msg  Specifies the message.

   mp1  Specifies message parameter 1.

   mp2  Specifies message parameter 2.

 Return Value

   The return value is dependent on the message that was passed to this
   function.

 See Also

   WinDefWindowProc


 ────────────────────────────────────────────────────────────────────────────
 WinDefDlgProc
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinDefDlgProc (hwndDlg, msg, mp1, mp2)
   HWND hwndDlg;           /*handle of the dialog                          */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*message parameter                             */
   MPARAM mp2;             /*message parameter                             */

   The WinDefDlgProc function calls the default dialog procedure. The default
   dialog procedure provides default processing for any dialog window
   messages that an application does not process. This function is used to
   ensure that every message is processed. It should be called with the same
   parameters as those received by the dialog procedure.

 Parameters

   hwndDlg  Identifies the dialog window that received the message.

   msg  Specifies the message.

   mp1  Specifies message parameter 1.

   mp2  Specifies message parameter 2.

 Return Value

   The return value is dependent on the message that was passed to this
   function.

 Example

   This example shows a typical dialog box procedure. A switch statement is
   used to process individual messages. All messages not processed are passed
   on to the WinDefDlgProc function.

   MRESULT CALLBACK AboutDlg(hwnd, usMessage, mp1, mp2)
   HWND   hwnd;
   USHORT usMessage;
   MPARAM mp1;
   MPARAM mp2;
   {
       switch (usMessage) {

           /*
            * process whatever messages you want here and send the rest
            * to WinDefWindowProc
            */

           default:
               return (WinDefDlgProc(hwnd, usMessage, mp1, mp2));
       }
   }

 See Also

   WinDefWindowProc


 ────────────────────────────────────────────────────────────────────────────
 WinDefWindowProc
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinDefWindowProc (hwnd, msg, mp1, mp2)
   HWND hwnd;              /*handle of the window                          */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*message parameter                             */
   MPARAM mp2;             /*message parameter                             */

   The WinDefWindowProc function calls the default window procedure. The
   default window procedure provides default processing for any window
   messages that an application does not process. This function is used to
   ensure that every message is processed. It should be called with the same
   parameters as those received by the window procedure.

 Parameters

   hwnd  Identifies the window that received the message.

   msg  Specifies the message.

   mp1  Specifies message parameter 1.

   mp2  Specifies message parameter 2.

 Return Value

   The return value is dependent on the message that was passed to this
   function.

 Example

   This example shows a typical window procedure. A switch statement is used
   to process individual messages. All messages not processed are passed on
   to the WinDefWindowProc function.

   MRESULT CALLBACK GenericWndProc(hwnd, usMessage, mp1, mp2)
   HWND   hwnd;
   USHORT usMessage;
   MPARAM mp1;
   MPARAM mp2;
   {
       switch (usMessage) {

           /*
            * process whatever messages you want here and send the rest
            * to WinDefWindowProc
            */

           default:
               return (WinDefWindowProc(hwnd, usMessage, mp1, mp2));
       }
   }

 See Also

   WinDefAVioWindowProc, WinDefDlgProc


 ────────────────────────────────────────────────────────────────────────────
 WinDeleteAtom
 ────────────────────────────────────────────────────────────────────────────
   ATOM WinDeleteAtom (hAtomTbl, atom)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */
   ATOM atom;              /*atom                                          */

   The WinDeleteAtom function deletes an atom from the atom table.

 Parameters

   hAtomTbl  Identifies the atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable function.

   atom  Specifies the atom to be deleted.

 Return Value

   The return value is NULL if the function is successful. Otherwise, it is
   equal to the value of the atom parameter if the function failed and the
   atom has not been deleted.

   If the passed atom is an integer atom, NULL is returned. If it is not an
   integer atom and it is a valid atom for the given atom table (it has an
   atom name and use count associated with it), the use count is decreased by
   one and NULL is returned. If the use count has been decreased to zero, the
   atom name and use count are removed from the atom table.

 See Also

   WinAddAtom, WinCreateAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyAccelTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDestroyAccelTable (haccel)
   HACCEL haccel;          /*handle of the accelerator table               */

   The WinDestroyAccelTable function destroys an accelerator table. Before an
   application terminates, it should call this function for each accelerator
   table created with a call to the WinCreateAccelTable function.

 Parameters

   haccel  Identifies the accelerator table to be destroyed. This handle must
   have been created by a previous call to the WinCreateAccelTable function.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreateAccelTable


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyAtomTable
 ────────────────────────────────────────────────────────────────────────────
   HATOMTBL WinDestroyAtomTable (hAtomTbl)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */

   The WinDestroyAtomTable function destroys an atom table created by the
   WinCreateAtomTable function.

 Parameters

   hAtomTbl  Identifies the atom table to be destroyed. This handle must have
   been created by a previous call to the WinCreateAtomTable function.

 Return Value

   The return value is NULL if the function is successful. Otherwise, the
   return value is the hAtomTbl parameter.

   This method of returning failure allows for updating the status of an atom
   table and destroying it at the same time with a call similar to the
   following:

   hAtomTbl = WinDestroyAtomTable(hAtomTbl);

 See Also

   WinCreateAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyCursor
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDestroyCursor (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinDestroyCursor function erases and destroys the current cursor, if
   it belongs to the specified window.

   This function has no effect if the current cursor does not belong to the
   specified window.

 Parameters

   hwnd  Identifies the window to which the cursor belongs.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   It is not necessary to call the WinDestroyCursor function before calling
   the WinCreateCursor function, as the WinCreateCursor function will
   automatically destroy any existing cursor.

 See Also

   WinCreateCursor, WinQueryCursorInfo, WinShowCursor


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyHeap
 ────────────────────────────────────────────────────────────────────────────
   HHEAP WinDestroyHeap (hHeap)
   HHEAP hHeap;            /*handle of the heap                            */

   The WinDestroyHeap function destroys a heap created by the WinCreate- Heap
   function. If the WinCreateHeap function allocated a segment, the
   WinDestroyHeap will free that segment.

 Parameters

   hHeap  Identifies the heap to be destroyed. This handle must have been
   created by a previous call to the WinCreateHeap function.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   nonzero, indicating that an error occurred.

 See Also

   WinCreateHeap


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyMsgQueue
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDestroyMsgQueue (hmq)
   HMQ hmq;                /*handle of the message queue                   */

   The WinDestroyMsgQueue function destroys a message queue. Any thread or
   application that creates a message queue should call WinDestroyMsgQueue to
   destroy that message queue before terminating.

 Parameters

   hmq  Identifies the message queue to be destroyed. This handle must have
   been created by a previous call to the WinCreateMsgQueue function in the
   same thread that is calling the WinDestroyMsgQueue function.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Example

   This example calls WinInitialize to initialize the thread for making
   Presentation Manager function calls, and calls WinCreateMsgQueue to create
   a message queue for the thread. Before the thread terminates, it calls
   WinDestroyMsgQueue to destroy the message queue.

   hab = WinInitialize(NULL);
   hmq = WinCreateMsgQueue(hab, DEFAULT_QUEUE_SIZE);
       .
       . /* initialization and message loop */
       .
   WinDestroyMsgQueue(hmq);

 See Also

   WinCreateMsgQueue, WinInitialize


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDestroyPointer (hptr)
   HPOINTER hptr;          /*handle of the pointer or icon                 */

   The WinDestroyPointer function destroys a pointer or an icon. A pointer
   can be destroyed only by the process that created it. The system pointers
   and icons cannot be destroyed.

 Parameters

   hptr  Identifies the pointer or icon to destroy.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreatePointer


 ────────────────────────────────────────────────────────────────────────────
 WinDestroyWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDestroyWindow (hwnd)
   HWND hwnd;              /*handle of the window to destory               */

   The WinDestroyWindow function destroys a window and any child windows of
   that window. If the window is locked, this function will not return until
   the window has been unlocked (and destroyed).

 Parameters

   hwnd  Identifies the window to be destroyed.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The window to be destroyed must have been created by the thread that
   issues this call. Before the window identified by the hwnd parameter is
   itself destroyed, all child windows it owns are also destroyed.

   Note that any presentation spaces created with the WinGetPS function must
   be released by calling the WinReleasePS function. This must be done before
   calling WinDestroyWindow.

   The following messages are sent by this function:

   Value                       Meaning
   ──────────────────────────────────────────────────────────────────────────
   WM_ACTIVATE                 Sent with the first message parameter equal to
                               FALSE if the window being destroyed is the
                               active window.

   WM_DESTROY                  Always sent to the window being destroyed
                               after the window has been hidden on the
                               device, but before its child windows have been
                               destroyed.

   WM_OTHERWINDOWDESTROYED     Sent to all main windows if the window being
                               destroyed, or any of its descendants, has been
                               registered with the WinRegisterWindowDestroy
                               function.

   WM_RENDERALLFMTS            Sent if the clipboard owner is being destroyed
                               and there are unrendered formats in the
                               clipboard.
   ──────────────────────────────────────────────────────────────────────────

   If the window being destroyed is the active window, then both the active
   window and the input-focus window are transferred to another window when
   the window is destroyed.

 See Also

   WinCreateStdWindow, WinCreateWindow, WinGetPS, WinLockWindow,
   WinRegisterWindowDestroy, WinReleasePS


 ────────────────────────────────────────────────────────────────────────────
 WinDismissDlg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDismissDlg (hwndDlg, usResult)
   HWND hwndDlg;           /*handle of the dialog                          */
   USHORT usResult;        /*result code to return                         */

   The WinDismissDlg function hides the dialog window and causes the
   WinProcessDlg or WinDlgBox function to return.

 Parameters

   hwndDlg  Identifies the dialog window to be hidden.

   usResult  Specifies the value that is returned to the caller of
   WinProcessDlg or WinDlgBox.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   This function is required to complete the processing of a modal dialog
   window and is called from its dialog procedure.

   The WinDismissDlg function is automatically called by the WinDefDlgProc
   function upon receiving a WM_COMMAND message. The WinDefDlgProc function
   will set usResult to the identifier of the control that generated the
   WM_COMMAND message.

   Note that this function can be called from a modeless dialog box, although
   this is not necessary since there is no internal message processing loop.
   If the function is called, the dialog box window is hidden. The
   application must destroy the dialog box window, if required.

 Example

   This example shows a typical dialog procedure that has both an OK and a
   Cancel button. If the user selects the OK button, WinDismissDlg is called
   with a result value of TRUE. If the user selects the Cancel button,
   WinDismissDlg is called with a result value of TRUE.

   case WM_COMMAND:
       switch (SHORT1FROMMP(mp1)) {
           case ID_ENTER: /* OK button selected  */
               WinDismissDlg(hwnd, TRUE);
               return (0L);

           case ID_CANCEL: /* Cancel button selected */
               WinDismissDlg(hwnd, FALSE);
               return (0L);

 See Also

   WinDlgBox, WinProcessDlg


 ────────────────────────────────────────────────────────────────────────────
 WinDispatchMsg
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinDispatchMsg (hab, pqmsg)
   HAB hab;                /*handle of the anchor block                    */
   PQMSG pqmsg;            /*address of structure for message queue        */

   The WinDispatchMsg dispatches a message to a window. It is typically used
   to dispatch a message retrieved with the WinGetMsg function. Unlike the
   WinSendMsg function, the WinDispatchMsg function does not call any hooks
   installed with the WinSetHook function.

 Parameters

   hab  Identifies an anchor block.

   pqmsg  Points to a QMSG structure that contains the message. The QMSG
   structure has the following form:

   typedef struct _QMSG {
       HWND hwnd;
       USHORT msg;
       MPARAM mp1;
       MPARAM mp2;
       ULONG time;
       POINTL ptl;
   } QMSG;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is the value returned by the window procedure that was
   called.

 Example

   This example calls WinGetMsg to retrieve a message and WinDispatchMsg to
   send the message.

   HAB hab;
   QMSG qmsg;

   while (WinGetMsg(hab,   /* handle to the anchor block             */
           &qmsg,          /* address of the message queue structure */
           NULL,           /* accept messages for any window         */
           0,              /* first message to accept                */
           0))             /* accept all messages                    */
       WinDispatchMsg(hab, &qmsg);

 See Also

   WinGetMsg, WinProcessDlg, WinSendMsg, WinSetHook


 ────────────────────────────────────────────────────────────────────────────
 WinDlgBox
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinDlgBox (hwndParent, hwndOwner, pfnDlgProc, hmod, idDlg,
   pCreateParams)
   HWND hwndParent;        /*handle of the parent window                   */
   HWND hwndOwner;         /*handle of the owner window                    */
   PFNWP pfnDlgProc;       /*dialog procedure address                      */
   HMODULE hmod;           /*handle of resource module                     */
   USHORT idDlg;           /*identifies the dialog                         */
   PVOID pCreateParams;    /*address of application-specific data          */

   The WinDlgBox function loads and processes a modal dialog box and returns
   the usResult value passed to the WinDismissDlg function. It is equivalent
   to calling WinLoadDlg, WinProcessDlg, and WinDestroyWindow.

   This function does not return until the dialog procedure calls the
   WinDismissDlg function.

 Parameters

   hwndParent  Identifies the parent window.

   hwndOwner  Identifies the owner window.

   pfnDlgProc  Points to the dialog procedure.

   hmod  Identifies the module that contains the dialog template. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

   idDlg  Identifies the dialog window.

   pCreateParams  Points to application-specific data that is passed to the
   dialog procedure as part of the WM_INITDLG message.

 Return Value

   The return value is the value specified in the usResult parameter of the
   WinDismissDlg function, or DID_ERROR if an error occurred while trying to
   load the dialog box.

 Example

   This example processes an application-defined message (IDM_OPEN) and calls
   WinDlgBox to load a dialog box.

   case IDM_OPEN:
       if (WinDlgBox(HWND_DESKTOP,
               hwndFrame,    /* handle of the owner         */
               OpenDlg,      /* dialog procedure address    */
               NULL,         /* location of dialog resource */
               IDD_OPEN,     /* resource identifier         */
               NULL)) {      /* application-specific data   */
          .
          . /* code executed if dialog box returns TRUE */
          .
       }

 See Also

   DosLoadModule, WinDismissDlg, WinLoadDlg, WinProcessDlg


 ────────────────────────────────────────────────────────────────────────────
 WinDrawBitmap
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDrawBitmap (hpsDst, hbm, prclSrc, pptlDst, clrFore, clrBack, fs)
   HPS hpsDst;             /*handle of the destination presentation space  */
   HBITMAP hbm;            /*handle of the bitmap                          */
   PRECTL prclSrc;         /*address of structure with rectangle           */
                           /*coordinates                                   */
   PPOINTL pptlDst;        /*address of structure with bitmap position     */
   LONG clrFore;           /*color of the foreground                       */
   LONG clrBack;           /*color of the background                       */
   USHORT fs;              /*bitmap-drawing flags                          */

   The WinDrawBitmap function draws a bitmap using the current image colors
   and mixes.

 Parameters

   hpsDst  Identifies the presentation space in which the bitmap is drawn.

   hbm  Identifies the bitmap.

   prclSrc  Points to the RECTL data structure that contains the coordinates
   of the rectangle to be drawn. If this parameter is NULL, the entire bitmap
   is drawn. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pptlDst  Points to the position of the lower left of the bitmap in the
   presentation space (in presentation space coordinates).

   clrFore  Specifies the color of the foreground.

   clrBack  Specifies the color of the background.

   fs  Specifies the flags that determine how the bitmap is drawn. It can be
   one of the following values:

   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   DBM_HALFTONE    Use the OR operator to combine the bitmap with an
                   alternating pattern of ones and zeros before drawing it.
                   This flag can be used in conjunction with either
                   DBM_NORMAL or DBM_INVERT.

   DBM_IMAGEATTRS  The clrFore and clrBack parameters are ignored and the
                   image attribute colors already selected in hpsDst are used
                   instead.

   DBM_INVERT      Draw the bitmap inverted, using ROP_NOTSRCCOPY.

   DBM_NORMAL      Draw the bitmap normally, using ROP_SRCCOPY.

   DBM_STRETCH     The pptlDst parameter points to a RECTL data structure,
                   representing a rectangle in the destination presentation
                   space to which the bitmap should be stretched.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   GpiCreateBitmap, GpiLoadBitmap, WinGetSysBitmap

 ────────────────────────────────────────────────────────────────────────────
 WinDrawBorder
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDrawBorder (hps, prcl, cx, cy, clrFore, clrBack, fsCmd)
   HPS hps;                /*handle of the presentation space              */
   PRECTL prcl;            /*address of structure with bounding rectangle  */
   SHORT cx;               /*width of the border                           */
   SHORT cy;               /*height of the border                          */
   LONG clrFore;           /*color of the foreground                       */
   LONG clrBack;           /*color of the background                       */
   USHORT fsCmd;           /*border-drawing flags                          */

   The WinDrawBorder function draws a border (a rectangular frame, normally
   used around the edge of a window).

 Parameters

   hps  Identifies the presentation space in which the border is drawn.

   prcl  Points to a RECTL structure that contains the bounding rectangle for
   the border. The border is drawn within this rectangle. The RECTL structure
   has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cx  Specifies the width of the left and right sides of the border
   rectangle.

   cy  Specifies the height of the top and bottom sides of the border
   rectangle.

   clrFore  Specifies the color of the foreground.

   clrBack  Specifies the color of the background.

   fsCmd  Specifies the flags that determine how the border is drawn. It can
   be one of the following values:

╓┌─┌───────────────┌─────────────────────────────────────────────────────────╖
   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   DB_AREAMIXMODE  Draws the border with the current area attributes, using
                   the current-area foreground mix mode mapped to a GpiBitBlt
                   raster operation. Note that the background mix mode is
                   ignored by WinDrawBorder in this release because GpiBitBlt
                   ignores it.

   DB_DESTINVERT   Inverts the border.

   DB_DLGBORDER    A standard dialog border is drawn. If DB_PATCOPY is
                   specified, then an active dialog border is drawn. If
                   DB_PATINVERT is specified, then an inactive dialog border
   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
                  DB_PATINVERT is specified, then an inactive dialog border
                   is drawn. If this option is specified, the cx and cy
                   parameters are ignored.

   DB_INTERIOR     The interior of the border is drawn with the current
                   pattern background color. The border is drawn in the
                   current pattern foreground color.

   DB_PATCOPY      Draws the border with the current area attributes, forcing
                   a mix mode of ROP_SRCCOPY.

   DB_PATINVERT    Draws the border with the current area attributes, forcing
                   a mix mode of ROP_PATINVERT.

   DB_ROP          Used as a mask to isolate the raster operation related
                   flags of the fsCmd parameter.

   DB_STANDARD     The cx and cy parameters are multiplied by the system
                   SV_CXBORDER and SV_CYBORDER constants to produce the width
   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
                  SV_CXBORDER and SV_CYBORDER constants to produce the width
                   and height of the border sides.
   ──────────────────────────────────────────────────────────────────────────


   The current area attributes pattern is used. For instance, if the caller
   selects a diagonal-crosshatch symbol, the borders will be drawn with
   diagonal crosshatches, no matter what colors are selected. The only raster
   operation which does not use the pattern is DB_DESTINVERT.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   GpiBitBlt


 ────────────────────────────────────────────────────────────────────────────
 WinDrawPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinDrawPointer (hps, x, y, hptr, fs)
   HPS hps;                /*handle of the presentation space              */
   SHORT x;                /*horizontal position                           */
   SHORT y;                /*vertical position                             */
   HPOINTER hptr;          /*handle to the mouse pointer                   */
   USHORT fs;              /*pointer-drawing flags                         */

   The WinDrawPointer function draws a pointer.

 Parameters

   hps  Identifies the presentation space in which the pointer is drawn.

   x  Specifies the x-coordinate at which to draw the pointer.

   y  Specifies the y-coordinate at which to draw the pointer.

   hptr  Identifies the pointer.

   fs  Specifies the flags that determine how the pointer is drawn. It can be
   one of the following values:

   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   DP_HALFTONED    Draw the pointer with a halftone pattern where black
                   normally appears.

   DP_INVERTED     Draw the pointer inverted──black for white and white for
                   black.

   DP_NORMAL       Draw the pointer as it normally appears.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreatePointer, WinLoadPointer


 ────────────────────────────────────────────────────────────────────────────
 WinDrawText
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinDrawText (hps, cchText, pszText, pcrl, clrFore, clrBack, fsCmd)
   HPS hps;                /*handle of the presentation space              */
   SHORT cchText;          /*number of characters in the string            */
   PSZ pszText;            /*address of the text                           */
   PRECTL prcl;            /*address of structure with formatting          */
                           dimensions
   LONG clrFore;           /*color of the foreground                       */
   LONG clrBack;           /*color of the background                       */
   USHORT fsCmd;           /*text-drawing flags                            */

   The WinDrawText function draws a single line of formatted text into a
   specified rectangle.

 Parameters

   hps  Identifies the presentation space in which to draw the text.

   cchText  Specifies the number of characters in the string to draw. If this
   is set to 0xFFFF, the string is assumed to be null-terminated and its
   length is calculated by the function itself.

   pszText  Points to the character string to draw. A carriage-return or
   linefeed character terminates the line, even if the line is shorter than
   specified by the cchText parameter.

   prcl  Points to a RECTL data structure that contains the rectangle in
   which the text is formatted. If DT_QUERYEXTENT is specified in the fsCmd
   parameter, the RECTL structure is set to the string's bounding rectangle
   upon return from WinDrawText. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   clrFore  Specifies the color of the foreground. This parameter is ignored
   if DT_TEXTATTRS is set in the fsCmd parameter.

   clrBack  Specifies the color of the background. This parameter is ignored
   if DT_TEXTATTRS is set in the fsCmd parameter.

   fsCmd  Specifies an array of flags that determine how the text is drawn.
   It can be any of the following values:

╓┌─┌────────────────────┌────────────────────────────────────────────────────╖
   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────
   DT_LEFT              Left justify the text.

   DT_RIGHT             Right justify the text.

   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────

   DT_TOP               Top justify the text.

   DT_BOTTOM            Bottom justify the text.

   DT_CENTER            Center the text.

   DT_VCENTER           Center the text vertically.

   DT_ERASERECT         This flag causes the RECTL structure specified in
                        prcl to be filled with the window color before
                        printing the text, but only if the DT_QUERYEXTENT
                        flag is not specified.

   DT_EXTERNALLEADING   This flag causes the external leading value from the
                        passed font to be added to the bottom of the bounding
                        rectangle before returning. It only has an effect
                        when both DT_TOP and DT_QUERYEXTENT are also
                        specified.
   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────
                       specified.

   DT_HALFTONE          Make the text display halftone.

   DT_MNEMONIC          If a mnemonic prefix character is encountered, draw
                        the next character with mnemonic emphasis.

   DT_QUERYEXTENT       No drawing is performed. The prcl parameter is
                        changed to a rectangle that bounds the string if it
                        was drawn with the WinDrawText function.

   DT_TEXTATTRS         This flag causes the colors specified in clrFore and
                        clrBack to be ignored. The colors already selected in
                        the presentation space are used instead.

   DT_WORDBREAK         Only words that fit completely within the supplied
                        rectangle are drawn. A word is defined as any number
                        of leading spaces followed by one or more visible
                        characters and terminated by a space,
   Value                Meaning
   ──────────────────────────────────────────────────────────────────────────
                       characters and terminated by a space,
                        carriage-return, or linefeed character. When
                        calculating whether a particular word will fit within
                        the given rectangle, WinDrawText does not consider
                        the trailing blanks. It tests only the length of the
                        visible part of the word against the right edge of
                        the rectangle. Note that WinDrawText will always try
                        to draw at least one word, even if that word does not
                        fit in the passed rectangle. This is so that progress
                        is always made when drawing multi-line text.
   ──────────────────────────────────────────────────────────────────────────


   Some of the DT flags are mutually exclusive. Only one flag from each of
   the following groups is significant:

   ■  DT_LEFT, DT_CENTER, DT_RIGHT

   ■  DT_TOP, DT_VCENTER, DT_BOTTOM

 Return Value

   The return value is the number of characters, drawn by the function, that
   fit completely within the structure pointed to by prcl.

 Example

   This example shows how the WinDrawText function can be used to wrap text
   within a window by using the DT_WORDBREAK flag. The cchDrawn variable
   receives the number of characters actually drawn by the WinDrawText
   function. If this value is zero, no text was drawn and the for loop is
   exited. This can occur if the vertical height of the window is too short
   for the entire text. Otherwise, cchDrawn is added to the cchTotalDrawn
   variable to provide an offset into the string for the next call to
   WinDrawText.

   hps = WinGetPS(hwnd);          /* get a ps for the entire window */
   WinQueryWindowRect(hwnd, &rcl);         /* get window dimensions */
   WinFillRect(hps, &rcl, CLR_WHITE);      /* clear entire window   */
   cchText = strlen(pszText);              /* get length of string  */
   cyCharHeight = 15L;                     /* set character height  */
   for (cchTotalDrawn = 0;
           cchTotalDrawn != cchText;       /* until all chars drawn */
           rcl.yTop -= cyCharHeight) {

       /* draw the text */

       cchDrawn = WinDrawText(hps,     /* presentation-space handle */
           cch - cchTotalDrawn,        /* length of text to draw    */
           pszText + cchTotalDrawn,    /* address of the text       */
           &rcl,                       /* rectangle to draw in      */
           0L,                         /* foreground color          */
           0L,                         /* background color          */
           DT_WORDBREAK | DT_TOP | DT_LEFT | DT_TEXTATTRS);
       if (cchDrawn)
           cchTotalDrawn += cchDrawn;
       else
           break;                      /* text could not be drawn   */
   }
   WinReleasePS(hps);                  /* release the ps            */

 See Also

   WinSetDlgItemText


 ────────────────────────────────────────────────────────────────────────────
 WinEmptyClipbrd
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEmptyClipbrd (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinEmptyClipbrd function empties the clipboard, removing and freeing
   all handles to data that were on the clipboard.

 Parameters

   hab  Identifies an anchor block.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comment

   This function will send a WM_DESTROYCLIPBOARD message to the clipboard
   owner.

 See Also

   WinCloseClipbrd, WinOpenClipbrd


 ────────────────────────────────────────────────────────────────────────────
 WinEnablePhysInput
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEnablePhysInput (hwndDesktop, fEnable)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fEnable;           /*input status                                  */

   The WinEnablePhysInput function enables or disables queuing of keyboard
   and mouse input.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fEnable  Specifies whether the input is queued or disabled. If TRUE,
   keyboard and mouse input are queued. If FALSE, keyboard and mouse input
   are disabled.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinIsPhysInputEnabled


 ────────────────────────────────────────────────────────────────────────────
 WinEnableWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEnableWindow (hwnd, fEnable)
   HWND hwnd;              /*handle of the window                          */
   BOOL fEnable;           /*enable-state flag                             */

   The WinEnableWindow function sets the window's enabled state.

 Parameters

   hwnd  Identifies the window whose enabled state is to be set.

   fEnable  Specifies the new enabled state. If TRUE, the window state is set
   to enabled. If FALSE, the window state is set to disabled.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If the enable state of the window is changing, a WM_ENABLE message is sent
   before this function returns.

   If a window is disabled, all its child windows are implicitly disabled,
   although they are not sent a WM_ENABLE message.

 See Also

   WinIsWindowEnabled


 ────────────────────────────────────────────────────────────────────────────
 WinEnableWindowUpdate
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEnableWindowUpdate (hwnd, fEnable)
   HWND hwnd;              /*handle of the window to be enabled or         */
                           /*disabled                                      */
   BOOL fEnable;           /*enabled-state flag                            */

   The WinEnableWindowUpdate function enables or disables the window
   visibility state for subsequent drawing to a window. This function can be
   used to prevent unnecessary redrawing when making changes to a window. The
   window can then be redrawn by calling this function with the fEnable
   parameter set to TRUE.

 Parameters

   hwnd  Identifies the window whose enable state will be changed.

   fEnable  Specifies whether drawing to the window is enabled. If TRUE, any
   subsequent drawing into the window will be visible. If FALSE, any
   subsequent drawing into the window will be invisible.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   When the WinEnableWindowUpdate function is called with the fEnable
   parameter TRUE, the entire window is invalidated, however WS_SYNCPAINT
   windows are not redrawn. If you need to redraw a WS_SYNCPAINT window, you
   must call the WinShowWindow function.

 See Also

   WinShowWindow


 ────────────────────────────────────────────────────────────────────────────
 WinEndEnumWindows
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEndEnumWindows (henum)
   HENUM henum;            /*handle of the enumeration list                */

   The WinEndEnumWindows function ends an enumeration process. This function
   destroys the snapshot of the window hierarchy captured by the
   WinBeginEnumWindows function.

 Parameters

   henum  Identifies the enumeration list. This handle must have been created
   by a previous call to the WinBeginEnumWindows function.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinBeginEnumWindows


 ────────────────────────────────────────────────────────────────────────────
 WinEndPaint
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEndPaint (hps)
   HPS hps;                /*handle of the presentation space              */

   The WinEndPaint function restores the presentation space to its state
   prior to the WinBeginPaint call. If a cache presentation space was created
   by the WinBeginPaint function, it is released. If the text cursor was
   hidden by the WinBeginPaint function, it is displayed.

 Parameters

   hps  Identifies the presentation space. This must be the handle of the
   presentation space returned by a previous call to the WinBeginPaint
   function.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Example

   This example calls WinBeginPaint when it receives a WM_PAINT message to
   get a presentation-space handle to the update region and to get the
   coordinates of the update rectangle. It then fills the update rectangle
   and calls WinEndPaint to release the presentation space.

   case WM_PAINT:
       hps = WinBeginPaint(hwnd,   /* handle of the window      */
           NULL,                   /* get a cache ps            */
           &rcl);                  /* receives update rectangle */
       WinFillRect(hps, &rcl, CLR_WHITE);
       WinEndPaint(hps);

 See Also

   WinBeginPaint


 ────────────────────────────────────────────────────────────────────────────
 WinEnumClipbrdFmts
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinEnumClipbrdFmts (hab, fmt)
   HAB hab;                /*handle of the anchor block                    */
   USHORT fmt;             /*index of last format enumerated               */

   The WinEnumClipbrdFmts function enumerates the list of clipboard data
   formats available in the clipboard. The clipboard must have been
   previously opened by calling the WinOpenClipbrd function.

 Parameters

   hab  Identifies the anchor block.

   fmt  Specifies the index of the last clipboard data format enumerated
   using this function. This should start at zero, in which case the first
   available format is obtained. Subsequently, it should be set to the last
   format index value returned by this function.

 Return Value

   The return value is the index of the next available clipboard data format
   in the clipboard. When zero is returned, enumeration is complete (there
   are no further formats available).

 See Also

   WinOpenClipbrd


 ────────────────────────────────────────────────────────────────────────────
 WinEnumDlgItem
 ────────────────────────────────────────────────────────────────────────────
   HWND WinEnumDlgItem (hwndDlg, hwnd, code, fLock)
   HWND hwndDlg;           /*handle of the dialog window                   */
   HWND hwnd;              /*handle of the child window                    */
   USHORT code;            /*returned dialog item                          */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinEnumDlgItem function returns the handle of a dialog item within a
   dialog window.

 Parameters

   hwndDlg  Identifies the dialog window that contains the dialog item.

   hwnd  Identifies the child window of the dialog window. This may be an
   immediate child window or a window lower in the hierarchy, such as a child
   of a child window.

   code  Specifies which dialog item to return. This parameter is one of the
   following values:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   EDI_FIRSTGROUPITEM  First item in same group.

   EDI_FIRSTTABITEM    First item in dialog window with style WS_TABSTOP. The
                       hwnd window is ignored.

   EDI_LASTGROUPITEM   Last item in same group.

   EDI_LASTTABITEM     Last item in dialog box with style WS_TABSTOP. The
                       hwnd window is ignored.

   EDI_NEXTGROUPITEM   Next item in same group. Wraps to beginning of group
                       when end of group is reached.

   EDI_NEXTTABITEM     Next item with style WS_TABSTOP. Wraps around to
                       beginning of dialog-item list when end is reached.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      beginning of dialog-item list when end is reached.

   EDI_PREVGROUPITEM   Previous item in same group. Wraps to end of group
                       when start of group is reached.

   EDI_PREVTABITEM     Previous item with style WS_TABSTOP. Wraps to end of
                       dialog-item list when beginning is reached.
   ──────────────────────────────────────────────────────────────────────────


   fLock  Specifies whether the dialog item is to be locked or unlocked. If
   TRUE, the item is locked. If FALSE, it is not.

 Return Value

   The return value is the item handle obtained by this function, specified
   by the code parameter. The window is always an immediate child window of
   the window identified by the hwndDlg parameter.

 Comments

   If the dialog item is locked by this function, then you must at some point
   call the WinLockWindow function to unlock the dialog item. The reason for
   locking the dialog item is so that it cannot be destroyed until you are
   done using it.


 ────────────────────────────────────────────────────────────────────────────
 WinEqualRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinEqualRect (hab, prcl1, prcl2)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl1;           /*address of structure for first rectangle      */
   PRECTL prcl2;           /*address of structure for second rectangle     */

   The WinEqualRect function compares two rectangles for equality. Equal
   rectangles have identical coordinates (all sides are the same).

 Parameters

   hab  Identifies the anchor block.

   prcl1  Points to the RECTL structure that contains the first rectangle.
   The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prcl2  Points to the RECTL structure that contains the second rectangle.

 Return Value

   The return value is TRUE if the rectangles are equal, or FALSE if they are
   not.


 ────────────────────────────────────────────────────────────────────────────
 WinExcludeUpdateRegion
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinExcludeUpdateRegion (hps, hwnd)
   HPS hps;                /*handle of the presentation space              */
   HWND hwnd;              /*handle of the window                          */

   The WinExcludeUpdateRegion function subtracts the update region of a
   window from the clipping region of a presentation space. If the
   presentation space does not have a clipping region, one is created. The
   result of this function is that drawing into the update region of a window
   will be clipped (will not be drawn). This function is typically used to
   prevent drawing into parts of a window known to be invalid.

 Parameters

   hps  Identifies the presentation space whose clipping region is updated.

   hwnd  Identifies the window whose update region is subtracted from the
   clipping region of the presentation space.

 Return Value

   The return value is EXRGN_NULL, EXRGN_RECT, or EXREGN_COMPLEX if the
   function is successful. The return value is EXRGN_ERROR if an error
   occurs.

 See Also

   GpiCombineRegion, WinValidateRect


 ────────────────────────────────────────────────────────────────────────────
 WinFillRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinFillRect (hps, pcrl, clr)
   HPS hps;                /*handle of the presentation space              */
   PRECTL pcrl;            /*address of the structure with the rectangle   */
   COLOR clr;              /*color of the rectangle                        */

   The WinFillRect function fills a rectangular area. It does not change any
   presentation-space state.

 Parameters

   hps  Identifies the presentation space where the rectangle is drawn.

   pcrl  Points to the RECTL structure that contains the coordinates of the
   rectangle to fill. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   clr  Specifies the rectangle color. This parameter is either a color index
   or an RGB color value, depending on how a logical color table has been
   loaded. (For more information on color tables, see
   GpiCreateLogColorTable.)

   Typically, this parameter will be a color index taken from one of the
   following values:

       CLR_WHITE                  CLR_DARKGRAY
       CLR_BLACK                  CLR_DARKBLUE
       CLR_BACKGROUND             CLR_DARKRED
       CLR_BLUE                   CLR_DARKPINK
       CLR_RED                    CLR_DARKGREEN
       CLR_PINK                   CLR_DARKCYAN
       CLR_GREEN                  CLR_BROWN
       CLR_CYAN                   CLR_PALEGRAY
       CLR_YELLOW                 CLR_NEUTRAL

       SYSCLR_WINDOWSTATICTEXT    SYSCLR_WINDOWTEXT
       SYSCLR_SCROLLBAR           SYSCLR_TITLETEXT
       SYSCLR_BACKGROUND          SYSCLR_ACTIVEBORDER
       SYSCLR_ACTIVETITLE         SYSCLR_INACTIVEBORDER
       SYSCLR_INACTIVETITLE       SYSCLR_APPWORKSPACE
       SYSCLR_MENU                SYSCLR_HELPBACKGROUND
       SYSCLR_WINDOW              SYSCLR_HELPTEXT
       SYSCLR_WINDOWFRAME         SYSCLR_HELPHILITE
       SYSCLR_MENUTEXT            SYSCLR_CSYSCOLORS

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Example

   This example calls WinBeginPaint to get a presentation-space handle and
   the coordinates of the update rectangle. It then calls WinFillRect to fill
   the update rectangle.

   case WM_PAINT:
       hps = WinBeginPaint(hwnd, NULL, &rcl);
       WinFillRect(hps,    /* presentation-space handle    */
           &rcl,           /* coordinates of the rectangle */
           CLR_WHITE);     /* color to use                 */
       WinEndPaint(hps);

 See Also

   GpiCreateLogColorTable


 ────────────────────────────────────────────────────────────────────────────
 WinFindAtom
 ────────────────────────────────────────────────────────────────────────────
   ATOM WinFindAtom (hAtomTbl, pszAtomName)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */
   PSZ pszAtomName;        /*address of the atom name                      */

   The WinFindAtom function finds an atom in the atom table. This function is
   identical to the WinAddAtom function, with two exceptions: If the atom
   name is not found in the table, it is not added to the table and NULL is
   returned as the value of this function; if the atom name is found in the
   table, the use count is not increased.

   Because integer atoms do not have a use count and do not actually occupy
   memory in the atom table, this function is identical to WinAddAtom with
   respect to integer atoms.

 Parameters

   hAtomTbl  Identifies the atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable function.

   pszAtomName  Points to the null-terminated character string containing the
   atom name. If the string begins with a "#" character, the ASCII digits
   that follow are converted into an integer atom. If the string begins with
   an "!" character, the next two bytes are interpreted as an atom. If the
   high word of this parameter is -1, the low word is an atom and that atom
   is returned.

 Return Value

   The return value is the atom associated with the passed string, or it is
   NULL if the string is not in the atom table.

 See Also

   WinAddAtom, WinCreateAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinFlashWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinFlashWindow (hwndFrame, fFlash)
   HWND hwndFrame;         /*handle of the window to flash                 */
   BOOL fFlash;            /*start/stop flashing flag                      */

   The WinFlashWindow function starts or stops flashing a window. Flashing is
   achieved by inverting the title bar continuously. A beep is emitted for
   the first five flashes. If the window has been minimized, the icon text
   will flash when this function is called.

 Parameters

   hwndFrame  Identifies the window to flash.

   fFlash  Specifies whether the window flashes. If TRUE, the window starts
   flashing. If FALSE, the window stops flashing.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If an application needs to display a message box, but it does not have the
   focus, then it should call the WinFlashWindow function to flash its frame
   window and emit a beep to get the user's attention. Once it receives the
   focus, it can call WinFlashWindow again to stop the flashing, and then
   display its message box. By using this method, a message box from your
   application will not be displayed while the user is working with another
   application.

 See Also

   WinAlarm


 ────────────────────────────────────────────────────────────────────────────
 WinFocusChange
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinFocusChange (hwndDesktop, hwndSetFocus, fsFocusChange)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwndSetFocus;      /*handle of the focus window                    */
   USHORT fsFocusChange;   /*focus-changing flags                          */

   The WinFocusChange function sets the focus to the specified window.

   A window may temporarily set the focus to itself without changing the
   active window or the selection. Examples of this are menu and scroll bar
   windows. When complete, the window sets the focus back to the previous
   focus window.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwndSetFocus  Identifies the new focus window.

   fsFocusChange  Specifies the flags that control the focus-changing
   process. This parameter can be a combination of the following values:

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   FC_NOLOSEACTIVE     Do not send the WM_ACTIVATE message to the window
                       being deactivated.

   FC_NOLOSEFOCUS      Do not send the WM_SETFOCUS message to the window
                       losing the focus.

   FC_NOLOSESELECTION  Do not send the WM_SETSELECTION message to the window
                       losing the selection.

   FC_NOSETACTIVE      Do not send the WM_ACTIVATE message to the window
                       becoming active.

   FC_NOSETFOCUS       Do not send the WM_SETFOCUS message to the window
                       receiving the focus.

   FC_NOSETSELECTION   Do not send the WM_SETSELECTION message to the window
                       receiving the selection.
   ──────────────────────────────────────────────────────────────────────────

   By using various combinations of these flags, an application can control
   activation, selection, focus changes, and other default activities, such
   as bringing frame windows to the top of their sibling windows. If
   fsFocusChange is zero, the system takes the default action (this is the
   same as calling the WinSetFocus function).

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryFocus, WinSetFocus


 ────────────────────────────────────────────────────────────────────────────
 WinFormatFrame
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinFormatFrame (hwndFrame, prclFrame, pswp, cswpMax, prclClient)
   HWND hwndFrame;         /*handle of window with frame controls to be    */
                           /*formatted                                     */
   PRECTL prclFrame;       /*address of structure with rectangle           */
   PSWP pswp;              /*address of array of structures                */
   USHORT cswpMax;         /*number of SWP structures                      */
   PRECTL prclClient;      /*address of client window rectangle            */

   The WinFormatFrame function calculates the size and position of all
   standard frame controls within a frame window. The data is calculated and
   returned in an array with one entry for each control window. This function
   allows an application which has subclassed its frame window, to more
   easily modify the appearance of a frame window and its controls.

 Parameters

   hwndFrame  Identifies the window whose frame controls are to be formatted.

   prclFrame  Points to the RECTL structure that contains the rectangle where
   the frame controls are formatted. This typically is the window rectangle
   identified by the hwndFrame parameter, but where the window has a wide
   border, (for example, as specified by FS_DLGBORDER), the rectangle is
   inset by the size of the border. The RECTL structure has the following
   form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pswp  Points to an array of SWP structures. There must be one SWP
   structure for each frame control. Typically, the count of frame windows is
   calculated as follows:

         (FID_CLIENT - FID_SYSMENU + 1)

   This can change, however, if the frame window is subclassed. The SWP
   structure has the following form:

   typedef struct _SWP {
       USHORT fs;
       SHORT  cy;
       SHORT  cx;
       SHORT  y;
       SHORT  x;
       HWND   hwndInsertBehind;
       HWND   hwnd;
   } SWP;

   For a full description, See Chapter 4, "Types, Macros, Structures."

   cswpMax  Specifies the number of SWP structures.

   prclClient  Points to the window rectangle of the FID_CLIENT window after
   formatting. If this parameter is NULL, no client window rectangle is
   returned.

 Return Value

   The return value is the number of SWP structures returned in the array
   pointed to by pswp.

 Comments

   An SWP structure will be filled in for the following frame controls:

   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   FID_CLIENT      Identifies the client window.

   FID_HORZSCROLL  Identifies the horizontal scroll bar.

   FID_MENU        Identifies the system menu.

   FID_MINMAX      Identifies the minimum/maximum box.

   FID_SYSMENU     Identifies the system menu.

   FID_TITLEBAR    Identifies the title bar.

   FID_VERTSCROLL  Identifies the vertical scroll bar.
   ──────────────────────────────────────────────────────────────────────────

   The returned array of SWP structures can be used in the
   WinSetMultWindowPos function to set the position and size of the frame
   windows.

   The WinFormatFrame function typically is used by applications that require
   a nonstandard frame-window layout. This function is called while the
   WM_UPDATEFRAME message is being processed. The application should alter
   the calculated positions and sizes as required, after returning from this
   function. Any additional windows added to the standard set can be handled
   by adding SWP structures to the array, with positions and sizes set as
   necessary.

 See Also

   WinSetMultWindowPos


 ────────────────────────────────────────────────────────────────────────────
 WinFreeErrorInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinFreeErrorInfo (perrinfo)
   PERRINFO perrinfo;      /*address of structure with error-info block    */

   The WinFreeErrorInfo function frees memory allocated for an error
   information block.

 Parameters

   perrinfo  Points to the ERRINFO structure that contains the
   error-information block whose memory is to be freed. The ERRINFO structure
   has the following form:

   typedef struct _ERRINFO {
       USHORT    cbFixedErrInfo;
       ERRORID   idError;
       USHORT    cDetailLevel;
       USHORT    offaoffszMsg;
       USHORT    offBinaryData;
   } ERRINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinGetErrorInfo, WinGetLastError


 ────────────────────────────────────────────────────────────────────────────
 WinFreeMem
 ────────────────────────────────────────────────────────────────────────────
   NPBYTE WinFreeMem (hHeap, npMem, cbMem)
   HHEAP hHeap;            /*handle of the heap                            */
   NPBYTE npMem;           /*address of memory block to free               */
   USHORT cbMem;           /*size of the memory to free                    */

   The WinFreeMem function frees memory allocated by the WinAllocMem
   function.

 Parameters

   hHeap  Identifies the heap. This handle must have been created by a
   previous call to the WinCreateHeap function.

   npMem  Points to the memory block to free. This parameter must have been
   returned by a previous call to the WinAllocMem or WinReallocMem function.

   cbMem  Specifies the size of the memory to free; it must match the
   allocated size of the block.

 Return Value

   The return value is NULL if the function is successful. Otherwise, it
   returns the npMem parameter. This method of returning failure allows for
   updating the memory pointer and freeing the memory at the same time with a
   call similar to the following:

   npMem = WinFreeMem(hHeap, npMem, cbMem);

 Comments

   This function does not attempt to coalesce the block being freed with
   other free blocks. Use the WinAvailMem function to coalesce free blocks.

   If the heap was created with the HM_MOVEABLE option, the value of the
   cbMem parameter is ignored and the value of the size word in the allocated
   memory block is used instead.

   If the heap was created with the HM_MOVEABLE and HM_VALIDSIZE options, the
   value of the cbMem parameter is checked against the value of the size word
   and an error is generated if the two values are not the same.

 See Also

   WinAllocMem, WinAvailMem, WinCreateHeap, WinReallocMem


 ────────────────────────────────────────────────────────────────────────────
 WinGetClipPS
 ────────────────────────────────────────────────────────────────────────────
   HPS WinGetClipPS (hwnd, hwndClip, fs)
   HWND hwnd;              /*address of the parent window                  */
   HWND hwndClip;          /*handle of clipping type                       */
   USHORT fs;              /*clipping flags                                */

   The WinGetClipPS function returns a specially clipped presentation space
   for a specified window.

 Parameters

   hwnd  Identifies the parent window.

   hwndClip  Identifies the type of clipping to perform. This parameter can
   be one of the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   HWND_BOTTOM       Clip the last window in the sibling chain and continue
                     clipping until the next window is hwnd or NULL.

   HWND_TOP          Clip the first window in the sibling chain and continue
                     clipping until the next window is hwnd or NULL.

   NULL              Clip all siblings to the window identified by the hwnd
                     parameter.
   ──────────────────────────────────────────────────────────────────────────

   fs  Specifies one or more clipping flags. This parameter can be one of the
   following values:

╓┌─┌───────────────────────┌─────────────────────────────────────────────────╖
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   PSF_CLIPCHILDREN        Clip out all child windows of hwnd. Same as
                           PSF_CLIPWINDOWLIST and the hwndClip parameter
                           equal to the first child window of hwnd.

   PSF_CLIPDOWNWARDS       Clip out all windows from hwndClip to the
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
  PSF_CLIPDOWNWARDS       Clip out all windows from hwndClip to the
                           bottom-most sibling window of hwndClip.

   PSF_CLIPSIBLINGS        Clip out all sibling windows of hwnd. Same as
                           PSF_CLIPWINDOWLIST and hwndClip equal to NULL.

   PSF_CLIPUPWARDS         Clip out all windows from the sibling windows
                           directly in front of hwndClip to the front-most
                           sibling window of hwndClip.

   PSF_LOCKWINDOWUPDATE    The presentation space returned is not locked from
                           updating hwnd because of calls to
                           WinLockWindowUpdate.

   PSF_PARENTCLIP          Obtain presentation space with a visible region
                           for the parent window, but with window origin set
                           to the origin of hwnd.
   ──────────────────────────────────────────────────────────────────────────

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value identifies a presentation space if the function is
   successful, or it is NULL if an error occurs.

 See Also

   WinGetPS, WinLockWindowUpdate


 ────────────────────────────────────────────────────────────────────────────
 WinGetCurrentTime
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinGetCurrentTime (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinGetCurrentTime function returns the current time.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is the system timer count (in milliseconds) from the time
   the system is restarted.

 See Also

   WinQueryMsgTime


 ────────────────────────────────────────────────────────────────────────────
 WinGetErrorInfo
 ────────────────────────────────────────────────────────────────────────────
   PERRINFO WinGetErrorInfo (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinGetErrorInfo function returns detailed error information.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value points to an ERRINFO structure that contains information
   about the previous error code for the current thread, or it is NULL if no
   error information is available.

 Comments

   This function allocates a single private segment to contain the ERRINFO
   structure. All pointers to string fields within ERRINFO are offsets to
   memory within that segment. The ERRINFO structure has the following form:

   typedef struct _ERRINFO {    /* erri */
       USHORT    cbFixedErrInfo;
       ERRORID   idError;
       USHORT    cDetailLevel;
       USHORT    offaoffszMsg;
       USHORT    offBinaryData;
   } ERRINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   The memory allocated by this function is not freed until the returned
   pointer is passed to the WinFreeErrorInfo function.

   Like the WinGetLastError function, the WinGetErrorInfo function releases
   any saved error information after formatting the error message. If two
   calls are made to WinGetErrorInfo without any intervening calls, the
   second call will return NULL because the saved error information was
   released by the first call.

 See Also

   WinFreeErrorInfo, WinGetLastError


 ────────────────────────────────────────────────────────────────────────────
 WinGetKeyState
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinGetKeyState (hwndDesktop, vkey)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT vkey;             /*virtual key                                   */

   The WinGetKeyState function returns the key state at the time the last
   message from the queue was posted. This function is used to determine
   whether a virtual key is up, down, or toggled.

   This function can be used to obtain the state of the mouse buttons with
   the VK_BUTTON1, VK_BUTTON2, and VK_BUTTON3 virtual-key codes.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   vkey  Specifies the virtual-key value in the low byte and zero in the high
   byte.

 Return Value

   If the key is down, the 0x8000 bit is set (less than 0); if the key is up,
   this bit is not set. If the key is toggled, the 0x0001 bit is set (a key
   is toggled if it has been pressed an odd number of times since the system
   was started).

 See Also

   WinGetPhysKeyState


 ────────────────────────────────────────────────────────────────────────────
 WinGetLastError
 ────────────────────────────────────────────────────────────────────────────
   ERRORID WinGetLastError (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinGetLastError function returns the error state set by the failure of
   a Presentation Manager function. This function returns the last nonzero
   error code and sets the error code to zero.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is the last error code.

 Comments

   In multiple-thread applications where there are multiple anchor blocks,
   errors are stored in the anchor block created by the WinInitialize
   function of the thread. The application must specify the correct
   anchor-block value for the thread calling WinGetLastError.

 See Also

   WinGetErrorInfo, WinInitialize


 ────────────────────────────────────────────────────────────────────────────
 WinGetMaxPosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinGetMaxPosition (hwnd, pswp)
   HWND hwnd;              /*handle of the window                          */
   PSWP pswp;              /*address of structure for maximum window size  */
                           /*and position                                  */

   The WinGetMaxPosition function fills an SWP structure with the
   maximized-window size and position. On return, the SWP_SIZE and SWP_MOVE
   flags will have been combined using the OR operator into the fs field of
   the SWP structure.

 Parameters

   hwnd  Identifies the window whose maximum size will be retrieved.

   pswp  Points to the SWP structure that retrieves the size and position of
   a maximized window. The SWP structure has the following form:

   typedef struct _SWP {
       USHORT fs;
       SHORT  cy;
       SHORT  cx;
       SHORT  y;
       SHORT  x;
       HWND   hwndInsertBehind;
       HWND   hwnd;
   } SWP;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinGetMinPosition


 ────────────────────────────────────────────────────────────────────────────
 WinGetMinPosition
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinGetMinPosition (hwnd, pswp, pptl)
   HWND hwnd;              /*handle of the window                          */
   PSWP pswp;              /*address of structure with icon information    */
   PPOINTL pptl;           /*address of structure with minimum window      */
                           /*position                                      */

   The WinGetMinPosition function fills an SWP structure with the
   minimized-window size and position. On return, the SWP_SIZE and SWP_MOVE
   flags will have been combined using the OR operator into the fs field of
   the SWP structure.

 Parameters

   hwnd  Identifies the window whose minimum size will be retrieved.

   pswp  Points to the SWP structure that will receive the size and position
   of a minimized-window icon. The SWP structure has the following form:

   typedef struct _SWP {
       USHORT fs;
       SHORT  cy;
       SHORT  cx;
       SHORT  y;
       SHORT  x;
       HWND   hwndInsertBehind;
       HWND   hwnd;
   } SWP;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pptl  Points to the POINTL structure that specifies the position (in
   screen coordinates) to place the minimized window. If NULL, the system
   will determine the position. Otherwise, an icon location as near as
   possible to the specified position is chosen.

   The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinGetMaxPosition


 ────────────────────────────────────────────────────────────────────────────
 WinGetMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinGetMsg (hab, pqmsg, hwndFilter, msgFilterFirst, msgFilterLast)
   HAB hab;                /*handle of the anchor block                    */
   PQMSG pqmsg;            /*address of structure with message             */
   HWND hwndFilter;        /*window-filter handle                          */
   USHORT msgFilterFirst;  /*first message                                 */
   USHORT msgFilterLast;   /*last message                                  */

   The WinGetMsg function retrieves a message from the thread's message
   queue, waits if necessary, and returns when a message conforming to the
   filtering criteria is available.

 Parameters

   hab  Identifies the anchor block.

   pqmsg  Points to the QMSG structure that contains a message. The QMSG
   structure has the following form:

   typedef struct _QMSG {
       HWND hwnd;
       USHORT msg;
       MPARAM mp1;
       MPARAM mp2;
       ULONG time;
       POINTL ptl;
   } QMSG;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   hwndFilter  Identifies the window filter.

   msgFilterFirst  Specifies the first message.

   msgFilterLast  Specifies the last message.

 Return Value

   The return value is TRUE if the returned message is not WM_QUIT. The
   return value is FALSE if the returned message is WM_QUIT.

 Comments

   Filtering allows an application to process messages in a different order
   than the one in the queue. Filtering is used so the application can
   receive messages of a particular type only, rather than receiving other
   types of messages at an inconvenient point in the logic of the
   application. For example, when a "mouse button down" message is received,
   the application can use filtering to wait for the "mouse button up"
   message without having to process other messages.

   When using filtering, you must ensure that a message satisfying the
   specification of the filtering parameters can occur; otherwise, the
   WinGetMsg function cannot completely execute. For example, calling the
   WinGetMsg function with the msgFilterFirst and msgFilterLast parameters
   equal to WM_CHAR and with the hwndFilter parameter set to a window handle
   that does not have the input focus prevents WinGetMsg from returning.

   Keystrokes are passed to the WinTranslateAccel function. This means that
   accelerator keys are translated into WM_COMMAND or WM_SYSCOMMAND messages
   and are not seen as WM_CHAR messages by the application.

   The hwndFilter parameter limits the returned message to a specific window
   or its child windows. When hwndFilter is NULL, the returned message can be
   for any window. The message identity is restricted to the range specified
   by the msgFilterFirst and msgFilterLast parameters. When msgFilterFirst
   and msgFilterLast are both zero, any message satisfies the range
   constraint. When msgFilterFirst is greater than msgFilterLast, messages
   except those whose identities lie between msgFilterFirst and msgFilterLast
   can be returned. Messages that do not conform to the filtering criteria
   remain in the queue.

   When msgFilterFirst and msgFilterLast are both zero, all messages are
   returned.

   The constants WM_MOUSEFIRST and WM_MOUSELAST can be used for
   msgFilterFirst and msgFilterLast to filter all but mouse messages.

   The constants WM_BUTTONCLICKFIRST and WM_BUTTONCLICKLAST can be used for
   msgFilterFirst and msgFilterLast to filter all but mouse button messages.

   The constants WM_DDE_FIRST and WM_DDE_LAST can be used for msgFilterFirst
   and msgFilterLast to filter all but dynamic data exchange messages.

 Example

   This example calls WinGetMsg to retrieve a message and WinDispatchMsg to
   send the message.

   HAB hab;
   QMSG qmsg;

   while (WinGetMsg(hab,    /* handle to the anchor block             */
           &qmsg,           /* address of the message queue structure */
           NULL,            /* accept messages for any window         */
           0,               /* first message to accept                */
           0))              /* accept all messages                    */
       WinDispatchMsg(hab, &qmsg);

 See Also

   WinDispatchMsg, WinPeekMsg, WinPostMsg, WinTranslateAccel,
   WinWaitMsg


 ────────────────────────────────────────────────────────────────────────────
 WinGetNextWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinGetNextWindow (henum)
   HENUM henum;            /*handle of the enumeration list                */

   The WinGetNextWindow function obtains the handle of the next window in a
   specified enumeration list.

   The enumeration list details the window hierarchy at the time
   WinBeginEnumWindows was called. Enumeration starts with the top-most child
   window (listed first) and proceeds through the list each time the function
   is called, until all windows have been enumerated. Once all windows have
   been enumerated, the function returns NULL. The enumeration then returns
   to the top of the list and the handle of the top-most child window is
   returned on the next call.

   When a valid window handle is returned, the window is locked by this
   function. The window must then be unlocked by using the WinLockWindow
   function before WinGetNextWindow is called again.

 Parameters

   henum  Identifies the enumeration list. This parameter is created by the
   WinBeginEnumWindows function.

 Return Value

   The return value is the handle of the next window in the enumeration list,
   or it is NULL if an error occurs.

 See Also

   WinBeginEnumWindows, WinLockWindow


 ────────────────────────────────────────────────────────────────────────────
 WinGetPhysKeyState
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinGetPhysKeyState (hwndDesktop, sc)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT sc;               /*scan code of the key                          */

   The WinGetPhysKeyState function returns the physical-key state of the key
   represented by the scan-code parameter. This function is not synchronized
   to the processing of input.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   sc  Specifies the scan code of the key.

 Return Value

   The return value is a flag indicating if the key is currently up or down,
   and whether the key has gone down since the last time WinGetPhysKeyState
   was called. If the high bit is set (0x8000), the key is currently down,
   otherwise the key is currently up. If the low bit is set (0x0001), the key
   has gone down since the last time WinGetPhysKeyState was called.

 See Also

   WinGetKeyState


 ────────────────────────────────────────────────────────────────────────────
 WinGetPS
 ────────────────────────────────────────────────────────────────────────────
   HPS WinGetPS (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinGetPS function retrieves a cache presentation space that is a cache
   micro presentation space present in the system. This space can be used for
   simple drawing operations that do not depend on long-term data being
   stored in the presentation space.

 Parameters

   hwnd  Identifies the window to retrieve a presentation space for.

 Return Value

   The return value identifies presentation space that can be used for
   drawing in the window.

 Comments

   The initial state of the presentation space is the same as that of a
   presentation space created using the GpiCreatePS function. The color table
   is in default color-index mode. The visible region associated with the
   presentation space depends on the window and class styles of the window
   identified by the hwnd parameter. The visible region can have one of the
   following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   WS_CLIPCHILDREN   All the window's child windows are excluded.

   WS_CLIPSIBLINGS   All the window's sibling windows are excluded.

   WS_PARENTCLIP     The visible region is the same as that of the window's
                     parent window.
   ──────────────────────────────────────────────────────────────────────────

   Note that any presentation spaces created with the WinGetPS function must
   be released by calling the WinReleasePS function. This must be done before
   the application terminates.

 Example

   This example processes an application-defined message (IDM_FILL). It calls
   WinGetPS to get a presentation space to the entire window. It gets the
   dimensions of the current window, fills the window, and calls WinReleasePS
   to release the presentation space.

   case IDM_FILL:
       hps = WinGetPS(hwnd);           /* get ps for the entire window */
       WinQueryWindowRect(hwnd, &rcl);    /* get window dimensions     */
       WinFillRect(hps, &rcl, CLR_WHITE); /* clear entire window       */
       WinReleasePS(hps);                 /* release the ps            */
       return 0L;

 See Also

   GpiCreatePS, WinGetClipPS, WinGetScreenPS, WinReleasePS


 ────────────────────────────────────────────────────────────────────────────
 WinGetScreenPS
 ────────────────────────────────────────────────────────────────────────────
   HPS WinGetScreenPS (hwndDesktop)
   HWND hwndDesktop;       /*handle of the desktop                         */

   The WinGetScreenPS function returns a presentation space that can be used
   for drawing anywhere on the screen.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

 Return Value

   The return value is a presentation space, or NULL if an error occurs.

 Comments

   When your application finishes using the presentation space, the space
   should be released by calling the WinReleasePS function.

   The WinLockWindowUpdate function should be used to avoid updating the same
   part of the screen at the same time.

 See Also

   WinGetPS, WinLockWindowUpdate, WinReleasePS


 ────────────────────────────────────────────────────────────────────────────
 WinGetSysBitmap
 ────────────────────────────────────────────────────────────────────────────
   HBITMAP WinGetSysBitmap (hwndDesktop, ibm)
   HWND hwndDesktop;       /*handle of the desktop                         */
   USHORT ibm;             /*index of the system bitmap                    */

   The WinGetSysBitmap function returns a handle to one of the standard
   bitmaps provided by the system. This bitmap can be used for any of the
   normal bitmap operations. When your application is done with the bitmap,
   it should free it by calling GpiDeleteBitmap.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   ibm  Specifies the system-bitmap index value. It can be one of the
   following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   SBMP_BTNCORNERS       Push button corners.

   SBMP_CHECKBOXES       Check box/radio button check mark.

   SBMP_CHILDSYSMENU     Smaller version of the system menu bitmap to use in
                         child windows.

   SBMP_DRIVE            A symbol used by the file system to indicate a disk
                         drive.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        drive.

   SBMP_FILE             A symbol used by the file system to indicate a file.

   SBMP_FOLDER           A symbol used by the file system to show
                         subdirectories.

   SBMP_MAXBUTTON        Maximize button.

   SBMP_MENUATTACHED     A symbol used to indicate that a menu item has an
                         attached hierarchical menu.

   SBMP_MENUCHECK        Menu check mark.

   SBMP_MINBUTTON        Minimize button.

   SBMP_PROGRAM          A symbol used by the file system to indicate that a
                         file is an executable program.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SBMP_RESTOREBUTTON    Restore button.

   SBMP_SBDNARROW        Scroll-bar down arrow.

   SBMP_SBLFARROW        Scroll-bar left arrow.

   SBMP_SBRGARROW        Scroll-bar right arrow.

   SBMP_SBUPARROW        Scroll-bar up arrow.

   SBMP_SIZEBOX          A symbol used to indicate an area of a window that a
                         user can click to resize the window.

   SBMP_SYSMENU          System menu.

   SBMP_TREEMINUS        A symbol used by the file system to show that an
                         entry in the directory tree contains no more files.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SBMP_TREEPLUS         A symbol used by the file system to show that an
                         entry in the directory tree contains more files.
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is a handle to a bitmap, or NULL if an error occurs.

 See Also

   GpiDeleteBitmap, WinDrawBitmap


 ────────────────────────────────────────────────────────────────────────────
 WinInflateRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinInflateRect (hab, prcl, cx, cy)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of structure with expanded rectangle  */
   SHORT cx;               /*amount to expand width                        */
   SHORT cy;               /*amount to expand height                       */

   The WinInflateRect function expands the coordinates of a rectangle. If the
   specified expansion values are positive, the rectangle is expanded on all
   sides. If the specified expansion values are negative, the horizontal
   expansion value is subtracted from the left and added to the right, and
   the vertical expansion value is subtracted from the bottom and added to
   the top.

 Parameters

   hab  Identifies the anchor block.

   prcl  Points to the RECTL structure that contains the rectangle to be
   expanded. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cx  Specifies the amount of horizontal expansion.

   cy  Specifies the amount of vertical expansion.

 Return Value

   The return value is always TRUE.

 See Also

   WinOffsetRect


 ────────────────────────────────────────────────────────────────────────────
 WinInitialize
 ────────────────────────────────────────────────────────────────────────────
   HAB WinInitialize (fsOptions)
   USHORT fsOptions;       /*initialization options                        */

   The WinInitialize function initializes a thread for making Presentation
   Manager function calls. This must be the first Presentation Manager
   function called by any thread that will be calling Presentation Manager
   functions.

 Parameters

   fsOptions  Specifies the initialization options. Currently this parameter
   must be zero.

 Return Value

   The return value is the handle of an anchor block, or NULL if an error
   occurred.

 Example

   This example calls WinInitialize so that the thread can use Presentation
   Manager functions, processes the message loop, and calls WinTerminate when
   it is finished calling Presentation Manager functions.

   HAB hab;                /* handle to the anchor block  */

   VOID cdecl main() {
       hab = WinInitialize(NULL);
       .
       . /* any other initialization */
       .
       while (WinGetMsg(hab, &qmsg, NULL, 0, 0))
           WinDispatchMsg(hab, &qmsg);
       WinTerminate(hab);

 See Also

   WinCreateMsgQueue, WinTerminate


 ────────────────────────────────────────────────────────────────────────────
 WinInSendMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinInSendMsg (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinInSendMsg function determines whether the current thread is
   processing a message sent by another thread.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is TRUE if the current thread is processing a message
   sent by another thread, or FALSE if it is not processing a message.

 Comments

   The WinInSendMsg function can be used to tell if a function is being
   called recursively.

 See Also

   WinIsThreadActive, WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinIntersectRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIntersectRect (hab, prclDst, prclSrc1, prclSrc2)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prclDst;         /*address of structure for intersection         */
                           /*of rectangles                                 */
   PRECTL prclSrc1;        /*address of structure with first rectangle     */
   PRECTL prclSrc2;        /*address of structure with second rectangle    */

   The WinIntersectRect function calculates the intersection of two source
   rectangles and places the coordinates of the intersection rectangle into
   the destination rectangle. If the rectangles do not intersect, an empty
   rectangle (0, 0, 0, 0) is placed into the destination rectangle.

 Parameters

   hab  Identifies the anchor block.

   prclDst  Points to the RECTL structure that receives the intersection of
   the rectangles designated by the prclSrc1 and prclSrc2 parameters. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prclSrc1  Points to the RECTL structure that contains the first source
   rectangle.

   prclSrc2  Points to the RECTL structure that contains the second source
   rectangle.

 Return Value

   The return value is TRUE if the source rectangles intersect, or FALSE if
   they do not.

 See Also

   WinUnionRect


 ────────────────────────────────────────────────────────────────────────────
 WinInvalidateRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinInvalidateRect (hwnd, prcl, fIncludeChildren)
   HWND hwnd;              /*handle of window with changed update region   */
   PRECTL prcl;            /*address of structure with rectangle           */
   BOOL fIncludeChildren;  /*invalidation-scope flag                       */

   The WinInvalidateRect function adds a rectangle to a window's update
   region. The update region represents the area of the window that must be
   redrawn.

 Parameters

   hwnd  Identifies the window whose update region has changed. If this
   parameter is HWND_DESKTOP, this function updates the entire screen.

   prcl  Points to the RECTL structure that contains the coordinates of the
   rectangle to add to the window's update region. If this parameter is NULL,
   the entire window is put into the update region. The RECTL structure has
   the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   fIncludeChildren  Specifies whether child windows of hwnd are included in
   the invalid region. If TRUE, child windows are included. If FALSE, they
   are not.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If the window style is WS_SYNCPAINT, the window is redrawn before
   returning from the WinInvalidateRect function.

   If the window style is WS_CLIPCHILDREN and part of the window's update
   region overlaps child windows that have the style WS_SYNCPAINT, those
   child windows are updated before WinInvalidateRect returns.

 Example

   This example gets the dimensions of the window and calls WinInvalidateRect
   to invalidate the window. The application will be sent a WM_PAINT message
   with the entire window as the update rectangle.

   WinQueryWindowRect(hwnd, &rcl);
   WinInvalidateRect(hwnd,   /* window to invalidate    */
       &rcl,                 /* invalid rectangle       */
       FALSE);               /* do not include children */

 See Also

   WinInvalidateRegion


 ────────────────────────────────────────────────────────────────────────────
 WinInvalidateRegion
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinInvalidateRegion (hwnd, hrgn, fIncludeChildren)
   HWND hwnd;              /*handle of window with changed update region   */
   HRGN hrgn;              /*handle of the region to add                   */
   BOOL fIncludeChildren;  /*invalidation-scope flag                       */

   The WinInvalidateRegion function adds a region to a window's update
   region. The update region represents the area of the window that needs to
   be redrawn.

 Parameters

   hwnd  Identifies the window whose update region has changed. If this
   parameter is HWND_DESKTOP, this function updates the entire screen.

   hrgn  Identifies the region to be added to the window's update region. If
   this parameter is NULL, the entire window is put into the update region.

   fIncludeChildren  Specifies whether child windows of hwnd are included in
   the invalid region. If TRUE, child windows are included. If FALSE, they
   are not.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If the window style is WS_SYNCPAINT, the window is redrawn before
   returning from the WinInvalidateRegion function.

   If the window style is WS_CLIPCHILDREN and part of the window's update
   region overlaps child windows that have the style WS_SYNCPAINT, those
   child windows are updated before WinInvalidateRegion returns.

 See Also

   WinInvalidateRect


 ────────────────────────────────────────────────────────────────────────────
 WinInvertRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinInvertRect (hps, prcl)
   HPS hps;                /*handle of the presentation space              */
   PRECTL prcl;            /*address of structure with rectangle to invert */

   The WinInvertRect function inverts a rectangular area. Inversion is a
   logical NOT operation and flips the bits of each pel.

 Parameters

   hps  Identifies the presentation space.

   prcl  Points to the RECTL structure that contains the coordinates of the
   rectangle to invert. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   GpiBitBlt


 ────────────────────────────────────────────────────────────────────────────
 WinIsChild
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsChild (hwnd, hwndParent)
   HWND hwnd;              /*handle of the child window                    */
   HWND hwndParent;        /*handle of the parent window                   */

   The WinIsChild function tests whether a specified window is a child of a
   specified parent window.

 Parameters

   hwnd  Identifies the child window.

   hwndParent  Identifies the parent window.

 Return Value

   The return value is TRUE if the child window is a descendant of the parent
   window. The return value is FALSE if the child window is not a descendant
   of the parent or if an error occurs.

 See Also

   WinSetParent


 ────────────────────────────────────────────────────────────────────────────
 WinIsPhysInputEnabled
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsPhysInputEnabled (hwndDesktop)
   HWND hwndDesktop;       /*handle of the desktop                         */

   The WinIsPhysInputEnabled function returns the status of hardware input
   (on or off).

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

 Return Value

   The return value is TRUE if input is enabled or FALSE if input is
   disabled.

 See Also

   WinEnablePhysInput


 ────────────────────────────────────────────────────────────────────────────
 WinIsRectEmpty
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsRectEmpty (hab, prcl)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of structure with rectangle to check  */

   The WinIsRectEmpty function tests whether a rectangle is empty. (An empty
   rectangle is one with no area. The right side is less than or equal to the
   left and the bottom side is less than or equal to the top.)

 Parameters

   hab  Identifies the anchor block.

   prcl  Points to the RECTL structure that contains the rectangle to be
   tested. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the rectangle is empty or FALSE if the
   rectangle is not empty.

 See Also

   WinSetRectEmpty


 ────────────────────────────────────────────────────────────────────────────
 WinIsThreadActive
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsThreadActive (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinIsThreadActive function determines whether the active window
   belongs to the calling thread.

 Parameters

   hab  Identifies the anchor block of the calling thread.

 Return Value

   The return value is TRUE if the active window belongs to the calling
   thread, or it is FALSE if the active window does not belong to the thread.

 See Also

   WinInSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinIsWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsWindow (hab, hwnd)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of window to test                      */

   The WinIsWindow function determines whether a specified window is valid.

 Parameters

   hab  Identifies the anchor block.

   hwnd  Identifies the window whose validity is to be checked.

 Return Value

   The return value is TRUE if the window is valid or FALSE if it is not.

 Comments

   An invalid window is one which has been destroyed. If hwnd contains the
   handle of an invalid window, or it contains the handle of something other
   than a window, this function will return FALSE.

 See Also

   WinIsWindowEnabled, WinIsWindowVisible


 ────────────────────────────────────────────────────────────────────────────
 WinIsWindowEnabled
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsWindowEnabled (hwnd)
   HWND hwnd;              /*handle of window to check                     */

   The WinIsWindowEnabled function determines whether a specified window is
   enabled or disabled.

 Parameters

   hwnd  Identifies the window to check.

 Return Value

   The return value is TRUE if the window is enabled, or FALSE if it is
   disabled.

 See Also

   WinEnableWindow, WinIsWindowVisible


 ────────────────────────────────────────────────────────────────────────────
 WinIsWindowVisible
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinIsWindowVisible (hwnd)
   HWND hwnd;              /*handle of the window to test                  */

   The WinIsWindowVisible function determines the visibility state of a
   window.

 Parameters

   hwnd  Identifies the window to test.

 Return Value

   The return value is TRUE if the specified window and all its parent
   windows have the WS_VISIBLE style bit set. The return value is FALSE if
   the window is not visible. Because the return value reflects only the
   value of the window's WS_VISIBLE flag, it may be TRUE even if the window
   is totally obscured by other windows.

 Comments

   A window possesses a visibility state indicated by the WS_VISIBLE style
   bit. When the WS_VISIBLE style bit is set, the window is shown and
   subsequent drawing into the window is displayed as long as the window or
   any of the windows in the parent chain have the WS_VISIBLE style.

   When the WS_VISIBLE style bit is not set, the window is not shown (hidden)
   and subsequent drawing into the window is not displayed.

   If the value of the WS_VISIBLE style bit has been changed, the message
   WM_WINDOWPOSCHANGED is sent to the window of the hwnd parameter before the
   function returns.

   Drawing to a window with a WS_VISIBLE style will not be displayed if the
   window is covered by other windows, or clipped by its parent.

 See Also

   WinIsWindowEnabled, WinShowWindow


 ────────────────────────────────────────────────────────────────────────────
 WinLoadAccelTable
 ────────────────────────────────────────────────────────────────────────────
   HACCEL WinLoadAccelTable (hab, hmod, idAccelTable)
   HAB hab;                /*handle of the anchor block                    */
   HMODULE hmod;           /*handle of the module                          */
   USHORT idAccelTable;    /*accelerator table identifier                  */

   The WinLoadAccelTable function loads an accelerator table.

 Parameters

   hab  Identifies the anchor block.

   hmod  Identifies the module that contains the accelerator table. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

   idAccelTable  Identifies the accelerator table.

 Return Value

   The return value is the handle of the accelerator table.

 See Also

   DosLoadModule, WinCreateAccelTable, WinDestroyAccelTable,
   WinSetAccelTable


 ────────────────────────────────────────────────────────────────────────────
 WinLoadDlg
 ────────────────────────────────────────────────────────────────────────────
   HWND WinLoadDlg (hwndParent, hwndOwner, pfnDlgProc, hmod, idDlg,
   pCreateParams)
   HWND hwndParent;        /*handle of the parent window                   */
   HWND hwndOwner;         /*handle of the owner window                    */
   PFNWP pfnDlgProc;       /*pointer to the dialog procedure               */
   HMODULE hmod;           /*handle of resource with dialog template       */
   USHORT idDlg;           /*dialog window and template                    */
   PVOID pCreateParams;    /*address of dialog-procedure data              */

   The WinLoadDlg function creates a dialog window from a dialog template and
   returns the handle of the dialog window created.

 Parameters

   hwndParent  Identifies the parent window of the dialog window.

   hwndOwner  Identifies the owner window for the dialog window.

   pfnDlgProc  Points to the dialog procedure.

   hmod  Identifies the module that contains the dialog template. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

   idDlg  Identifies the dialog window and the dialog-resource file.

   pCreateParams  Points to dialog-procedure data (application-specific data
   passed to the dialog procedure with the WM_INITDLG message).

 Return Value

   The return value is the handle of the dialog window created, or it is NULL
   if an error occurs.

 See Also

   DosLoadModule, WinCreateDlg, WinDestroyWindow, WinDlgBox,
   WinProcessDlg, WinSubstituteStrings


 ────────────────────────────────────────────────────────────────────────────
 WinLoadMenu
 ────────────────────────────────────────────────────────────────────────────
   HWND WinLoadMenu (hwndFrame, hmod, idMenu)
   HWND hwndFrame;         /*handle of the frame window                    */
   HMODULE hmod;           /*handle of the module with resource            */
   USHORT idMenu;          /*menu template identifier                      */

   The WinLoadMenu function creates a menu window from the menu template.

 Parameters

   hwndFrame  Identifies the frame window for the menu.

   hmod  Identifies the module that contains the menu template. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

   idMenu  Identifies the menu template in the resource identified by the
   hmod parameter.

 Return Value

   The return value is the handle of the menu window.

 Comments

   Menus are created as child windows of the frame window and are initially
   visible. If the menu contains submenus, these submenus are initially
   created as object windows that are owned by the menu window. If the
   submenus contain other submenus, these new submenus are also object
   windows whose owner is the submenu that contains it. The menu hierarchy is
   defined by the owner-window chain.

 See Also

   DosLoadModule, WinCreateMenu, WinQueryObjectWindow


 ────────────────────────────────────────────────────────────────────────────
 WinLoadMessage
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinLoadMessage (hab, hmod, id, cchMax, pszBuffer)
   HAB hab;                /*handle of the anchor block                    */
   HMODULE hmod;           /*module handle                                 */
   USHORT id;              /*message identifier                            */
   SHORT cchMax;           /*buffer size                                   */
   PSZ pszBuffer;          /*address of buffer for message                 */

   The WinLoadMessage function loads a message from a resource, copies the
   message to the specified buffer, and appends a terminating null character.

 Parameters

   hab  Identifies the anchor block.

   hmod  Identifies the module that contains the message. This parameter can
   be either the module handle returned by the DosLoadModule function or NULL
   for the application's module.

   id  Identifies the message.

   cchMax  Specifies the size of the buffer.

   pszBuffer  Points to the buffer that receives the message.

 Return Value

   The return value is the length of the returned message (excluding the
   terminating null character). The return value can have a maximum value of
   (cchMax -1). The return value is zero if an error occurs.

 Comments

   Message resources contain up to 16 messages each. The resource identifier
   is calculated from the id parameter value passed to WinLoadMessage as
   follows:

         resource identifier = (id / 16) + 1

   To save storage on disk and in memory, applications should group their
   message resources sequentially, starting at a multiple of 16.

 See Also

   DosLoadModule, WinLoadString


 ────────────────────────────────────────────────────────────────────────────
 WinLoadPointer
 ────────────────────────────────────────────────────────────────────────────
   HPOINTER WinLoadPointer (hwndDesktop, hmod, idPtr)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HMODULE hmod;           /*handle of the module with the resource        */
   USHORT idPtr;           /*resource identifier                           */

   The WinLoadPointer function loads a pointer. The pointer can then be used
   as the mouse pointer by calling the WinSetPointer function.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hmod  Identifies the module that contains the pointer. This parameter can
   be either the module handle returned by the DosLoadModule function or NULL
   for the application's module.

   idPtr  Identifies the pointer.

 Return Value

   The return value is a handle to the pointer if the function is successful,
   or NULL if an error occurs.

 Example

   This example calls WinLoadPointer to load an application-defined pointer.
   When processing the WM_MOUSEMOVE message, the loaded pointer is displayed
   by calling WinSetPointer.

   case WM_CREATE:
       hptrCrossHair = WinLoadPointer(HWND_DESKTOP,
           NULL,              /* load from .exe file    */
           IDP_CROSSHAIR);    /* identifies the pointer */

   case WM_MOUSEMOVE:
       WinSetPointer(HWND_DESKTOP, hptrCrossHair);

 See Also

   DosLoadModule, WinCreatePointer, WinDestroyPointer, WinDrawPointer,
   WinQuerySysPointer, WinSetPointer


 ────────────────────────────────────────────────────────────────────────────
 WinLoadString
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinLoadString (hab, hmod, id, cchMax, pszBuffer)
   HAB hab;                /*handle of the anchor block                    */
   HMODULE hmod;           /*handle of the module with the string          */
   USHORT id;              /*string identifier                             */
   SHORT cchMax;           /*size of the buffer                            */
   PSZ pszBuffer;          /*address of the buffer for the string          */

   The WinLoadString function loads a string from a resource, copies the
   string to the specified buffer, and appends a terminating null character.

 Parameters

   hab  Identifies the anchor block.

   hmod  Identifies the module that contains the string. This parameter can
   be either the module handle returned by the DosLoadModule function or NULL
   for the application's module.

   id  Identifies the string identifier.

   cchMax  Specifies the size of the supplied buffer.

   pszBuffer  Points to the buffer that receives the string.

 Return Value

   The return value is the length of the returned string (excluding the
   terminating null character). The return value can have a maximum value of
   (cchMax -1). The return value is zero if an error occurs.

 Comments

   String resources contain up to 16 strings each. The resource identifier is
   calculated from the id value passed to WinLoadString as follows:

         resource identifier = (id / 16) + 1

   To save storage on disk and in memory, applications should group their
   string resources sequentially, starting at a multiple of 16.

 See Also

   DosLoadModule, WinLoadMessage


 ────────────────────────────────────────────────────────────────────────────
 WinLockHeap
 ────────────────────────────────────────────────────────────────────────────
   PVOID WinLockHeap (hHeap)
   HHEAP hHeap;            /*handle of the heap                            */

   The WinLockHeap function returns a far address to the beginning of the
   heap.

 Parameters

   hHeap  Identifies the heap. This parameter is returned by the
   WinCreateHeap function.

 Return Value

   The return value is a far pointer to the beginning of the segment that
   contains the passed heap.

 See Also

   WinAllocMem, WinCreateHeap


 ────────────────────────────────────────────────────────────────────────────
 WinLockVisRegions
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinLockVisRegions (hwndDesktop, fLock)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinLockVisRegions function locks or unlocks the visible regions of all
   windows on the screen, preventing any of the visible regions from
   changing.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fLock  Specifies whether to lock or unlock the visible regions. If TRUE,
   the visible regions are locked. If FALSE, the visible regions are
   unlocked.

 Comments

   This function is used to prevent a window's visible regions from changing
   while a thread performs a screen operation. For example, WinLockVisRegions
   should be used if the application is moving bits from one part of a window
   to another. Calling WinLockVisRegions during this operation ensures that
   no other window will appear on top of the window that bits are being
   copied from and therefore no physical change in the bits will take place.
   Using WinLockWindowUpdate for this bit copying will not work, because
   although no bits will changed in the locked area, it is still possible
   that the visible region of the presentation space being used for the bit
   copying might change.

   While the visible regions are locked, no messages should be sent and no
   functions called that could send messages.

   Only one thread can lock the visible regions at any one time. The same
   thread can call WinLockVisRegions multiple times. A lock count is
   maintained by the system and is incremented each time a locking call is
   made and decremented each time an unlocking call is made. The visible
   regions are unlocked when the count is zero.

   If WinLockVisRegions is called while another thread has locked the visible
   regions, the function will not return until the thread locking the visible
   regions has unlocked them.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinLockWindowUpdate


 ────────────────────────────────────────────────────────────────────────────
 WinLockWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinLockWindow (hwnd, fLock)
   HWND hwnd;              /*handle of the window                          */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinLockWindow function locks or unlocks a specified window. A window
   cannot be destroyed while it is locked.

 Parameters

   hwnd  Identifies the window to be locked or unlocked.

   fLock  Specifies whether the window is to be locked or unlocked. If TRUE,
   the window is locked. If FALSE, the window is unlocked.

 Return Value

   The return value is the handle of the window that was locked or unlocked
   if the function is successful. It is NULL if an error occurred.

 Comments

   If the WinDestroyWindow function is called with a locked window handle,
   the window is not destroyed until the window is unlocked.

   A count is maintained of the number of times a window has been locked
   without a corresponding call to unlock the window. The window cannot be
   destroyed until the count is zero. The WinQueryWindowLockCount function
   can be called to get the current lock count.

 See Also

   WinDestroyWindow, WinLockWindowUpdate, WinQueryWindowLockCount


 ────────────────────────────────────────────────────────────────────────────
 WinLockWindowUpdate
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinLockWindowUpdate (hwndDesktop, hwndLockUpdate)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwndLockUpdate;    /*handle of the window to lock/unlock           */

   The WinLockWindowUpdate function prevents or allows the updating of a
   window and its child windows. While updating is locked, no drawing will
   take place on the screen. When updating is unlocked, portions of the
   screen are invalidated and repainted.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwndLockUpdate  Identifies the window to be locked. If this parameter is
   NULL, all windows are unlocked.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinLockVisRegions


 ────────────────────────────────────────────────────────────────────────────
 WinMapDlgPoints
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinMapDlgPoints (hwndDlg, pptl, cwpt, fCalcWindowCoords)
   HWND hwndDlg;           /*handle of the dialog window                   */
   PPOINTL pptl;           /*address of array of structures with points    */
                           /*to map                                        */
   USHORT cwpt;            /*number of POINTL structures                   */
   BOOL fCalcWindowCoords; /*type of points                                */

   The WinMapDlgPoints function converts points of a dialog window from
   dialog coordinates to window coordinates or from window coordinates to
   dialog coordinates.

 Parameters

   hwndDlg  Identifies the dialog window.

   pptl  Points to the array of POINTL structures that contain the points to
   be converted. The converted points are substituted in the array. The
   POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cwpt  Specifies the number of POINTL structures in the pptl array.

   fCalcWindowCoords  Specifies the type of points to convert. If TRUE, the
   points are dialog coordinates and are converted to window coordinates
   relative to the dialog window. If FALSE, the points are window coordinates
   relative to the dialog window and are converted to dialog coordinates.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinMapWindowPoints


 ────────────────────────────────────────────────────────────────────────────
 WinMapWindowPoints
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinMapWindowPoints (hwndFrom, hwndTo, pptl, cwpt)
   HWND hwndFrom;          /*handle of the window to be mapped from        */
   HWND hwndTo;            /*handle of the window to be mapped to          */
   PPOINTL pptl;           /*address of array of structures with points    */
                           /*to map                                        */
   SHORT cwpt;             /*number of POINTL structures                   */

   The WinMapWindowPoints function converts a set of points from a coordinate
   space relative to one window to a coordinate space relative to another
   window.

 Parameters

   hwndFrom  Identifies the window from which points are converted. If this
   parameter is NULL or HWND_DESKTOP, the points are assumed to be in screen
   coordinates.

   hwndTo  Identifies the window to which points are converted. If this
   parameter is NULL or HWND_DESKTOP, the points are converted to screen
   coordinates.

   pptl  Points to an array of POINTL structures that contain the set of
   points. This parameter can also point to a RECTL structure, in which case
   the cwpt parameter should be set to 2. The POINTL structure has the
   following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   The RECTL structure has the following form:

   typedef struct _RECTL {    /* rcl */
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cwpt  Specifies the number of POINTL structures in the pptl array.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinMapDlgPoints


 ────────────────────────────────────────────────────────────────────────────
 WinMessageBox
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinMessageBox (hwndParent, hwndOwner, pszText, pszCaption,
   idWindow, flStyle)
   HWND hwndParent;        /*handle of the parent window                   */
   HWND hwndOwner;         /*handle of the owner window                    */
   PSZ pszText;            /*address of text in message box                */
   PSZ pszCaption;         /*address of title of message box               */
   USHORT idWindow;        /*message-box identifier                        */
   USHORT flStyle;         /*type of message box                           */

   The WinMessageBox function creates, displays, and operates a message-box
   window. The message-box window consists of a message and a simple dialog
   with the user.

 Parameters

   hwndParent  Identifies the parent window of the newly created message-box
   window. This parameter is the desktop-window handle, HWND_DESKTOP, or NULL
   if the message box is a main window.

   hwndOwner  Identifies the owner window of the message-box window. The
   owner window is activated when WinMessageBox returns.

   pszText  Points to the text displayed as the message within the
   message-box window. The text will be automatically wrapped as necessary to
   fit within the message box. The "\n" characters can be used to force a
   line break, however this is not recommended except between paragraphs, as
   different fonts could change the appearance of the text.

   pszCaption  Points to the title of the message-box window. If this
   parameter is NULL, "Error" (the default title) is displayed. The maximum
   length of the text is device-dependent. If the text is too long, it will
   be clipped.

   idWindow  Identifies the identifier of the message-box window. This value
   is passed to the HK_HELP hook if the WM_HELP message is received by the
   message-box window.

   flStyle  Specifies the type of message-box window created. This parameter
   consists of a button flag, an icon flag, a default button flag, and any
   number of special flags. The following four lists describe the available
   flags which can be combined using the OR operator together for this
   parameter:

   Buttons                  Meaning
   ──────────────────────────────────────────────────────────────────────────
   MB_ABORTRETRYIGNORE      Message box contains Abort, Retry, and Ignore
                            push buttons.

   MB_ENTER                 Message box contains an Enter push button.

   MB_ENTERCANCEL           Message box contains Enter and Cancel push
                            buttons.

   MB_OK                    Message box contains an OK push button.

   MB_OKCANCEL              Message box contains OK and Cancel push buttons.

   MB_RETRYCANCEL           Message box contains Retry and Cancel push
                            buttons.

   MB_YESNO                 Message box contains Yes and No push buttons.

   MB_YESNOCANCEL           Message box contains Yes, No, and Cancel push
                            buttons.
   ──────────────────────────────────────────────────────────────────────────

   Icon                     Meaning
   ──────────────────────────────────────────────────────────────────────────
   MB_ICONASTERISK          Message box contains asterisk icon.

   MB_ICONEXCLAMATION       Message box contains exclamation-point icon.

   MB_ICONHAND              Message box contains hand icon.

   MB_ICONQUESTION          Message box contains question-mark icon.

   MB_NOICON                Message box does not contain an icon.
   ──────────────────────────────────────────────────────────────────────────

   Default button           Meaning
   ──────────────────────────────────────────────────────────────────────────
   MB_DEFBUTTON1            First button is the default (first button is
                            always the default unless MB_DEFBUTTON2 or
                            MB_DEFBUTTON3 is specified).

   MB_DEFBUTTON2            Second button is the default.

   MB_DEFBUTTON3            Third button is the default.
   ──────────────────────────────────────────────────────────────────────────

   Special flags            Meaning
   ──────────────────────────────────────────────────────────────────────────
   MB_APPLMODAL             Message box is application modal.

   MB_SYSTEMMODAL           Message box is system modal.

   MB_HELP                  Message box contains Help push button.

   MB_MOVEABLE              Message box is movable.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value indicates the user's response to the message. It can be
   one of the following vlaues:

   Value                    Meaning
   ──────────────────────────────────────────────────────────────────────────
   MBID_ABORT               Abort button was selected.

   MBID_CANCEL              Cancel button was selected.

   MBID_ENTER               Enter button was selected.

   MBID_IGNORE              Ignore button was selected.

   MBID_NO                  No button was selected.

   MBID_OK                  OK button was selected.

   MBID_RETRY               Retry button was selected.

   MBID_YES                 Yes button was selected.

   MDID_ERROR               The WinMessageBox function failed──an error
                            occurred.
   ──────────────────────────────────────────────────────────────────────────

   If a message box has a Cancel button, MBID_CANCEL is returned if the
   ESCAPE key is pressed or if the Cancel button is selected. If the message
   box has no Cancel button, pressing the ESCAPE key has no effect.

 Comments

   If a message-box window is created as part of the processing of a dialog
   window, the dialog window should be made the owner of the message-box
   window.

   If a system modal message-box window is created to tell the user that the
   system is running out of memory, the strings passed into this function
   should not be taken from a resource file because an attempt to load the
   resource file may fail due to lack of memory. Such a message-box window
   can safely use the hand icon (MB_ICONHAND), however, because this icon is
   always memory-resident.

 Example

   This example shows a typical use of the WinMessageBox function when
   debugging an application. The C run-time function sprintf is used to
   format the body of the message. In this case, it converts the coordinates
   of the mouse pointer (retrieved with the WinQueryPointerPos function) into
   a string. The string is then displayed by calling WinMessageBox.

   CHAR szMsg[100];
   POINTL ptl;

   WinQueryPointerPos(HWND_DESKTOP, &ptl);
   sprintf(szMsg, "x = %ld   y = %ld", ptl.x, ptl.y);
   WinMessageBox(HWND_DESKTOP,
       hwndClient,                /* client-window handle  */
       szMsg,                     /* body of the message   */
       "Debugging information",   /* title of the message  */
       0,                         /* message box id        */
       MB_NOICON | MB_OK);        /* icon and button flags */

 See Also

   WinFlashWindow


 ────────────────────────────────────────────────────────────────────────────
 WinMsgMuxSemWait
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinMsgMuxSemWait (pisemCleared, pmxsl, lTimeOut)
   PUSHORT pisemCleared;   /*address of variable that receives             */
                           /*index number                                  */
   PVOID pmxsl;            /*address of structure with semaphore list      */
   LONG lTimeOut;          /*length of time to wait                        */

   The WinMsgMuxSemWait function waits for one or more of the specified
   semaphores to clear. This function checks the specified list. If any of
   the semaphores are clear, the function returns. Otherwise, the function
   waits until the specified time elapses or until one of the semaphores in
   the list clears.

 Parameters

   pisemCleared  Points to the variable that receives the index number of the
   most recently cleared semaphore.

   pmxsl  Points to the MUXSEMLIST structure containing a semaphore list that
   defines the semaphores to be cleared. The semaphore list consists of one
   or more semaphore handles. The MUXSEMLIST structure has the following
   form:

   typedef struct _MUXSEMLIST {
       USHORT cmxs;
       MUXSEM amxs[16];
   } MUXSEMLIST;

   The structure may contain up to 16 semaphores.

   For a full description, see Chapter 4, "Types, Macros, Structures."

   lTimeOut  Specifies how long to wait for the semaphores to become
   available. If the value is greater then zero, this parameter specifies the
   number of milliseconds to wait before returning. If the value is
   SEM_IMMEDIATE_RETURN, the function returns immediately. If the value is
   SEM_INDEFINITE_WAIT, the function waits indefinitely.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   an error value, which may be one of the following:

         ERROR_EXCL_SEM_ALREADY_OWNED
         ERROR_INTERRUPT
         ERROR_INVALID_EVENT_COUNT
         ERROR_INVALID_HANDLE
         ERROR_INVALID_LIST_FORMAT
         ERROR_SEM_TIMEOUT
         ERROR_TOO_MANY_MUXWAITERS

 Comments

   This function is identical to the DosMuxSemWait function with the
   following exceptions: Window messages sent via the WinSendMsg function by
   another thread may be received; the function can wait for 15 semaphores
   simultaneously (DosMaxSemWait can wait for 16).

   This function should be used to wait for a semaphore when the semaphore
   owner may need to issue a WinSendMsg function (or another Win function
   that implicitly issues a WinSendMsg function) before clearing the
   semaphore.

 See Also

   DosMuxSemWait, WinMsgSemWait, WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinMsgSemWait
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinMsgSemWait (hsem, lTimeOut)
   HSEM hsem;              /*handle of the semaphore                       */
   LONG lTimeOut;          /*time-out value                                */

   The WinMsgSemWait function waits for a specified semaphore to be cleared.
   WinMsgSemWait waits until a thread uses the DosSemClear function to clear
   the semaphore or until a time-out occurs. If no previous thread has set
   the semaphore, WinMsgSemWait returns immediately.

 Parameters

   hsem  Identifies the semaphore to set. This value can be the handle of a
   system semaphore that has been previously created or opened by using the
   DosCreateSem or DosOpenSem function, or it can be the address of a RAM
   semaphore.

   lTimeOut  Specifies how long to wait for the semaphore to clear. If the
   value is greater then zero, this parameter specifies the number of
   milliseconds to wait before returning. If the value is
   SEM_IMMEDIATE_RETURN, the function returns immediately. If the value is
   SEM_INDEFINITE_WAIT, the function waits indefinitely.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   an error value, which may be one of the following:

         ERROR_EXCL_SEM_ALREADY_OWNED
         ERROR_INTERRUPT
         ERROR_INVALID_HANDLE
         ERROR_SEM_TIMEOUT

 Comments

   This function is identical to DosSemWait except that in addition to
   waiting on the specified semaphore, window messages sent via the
   WinSendMsg function by another thread may be received.

 See Also

   DosCreateSem, DosOpenSem, DosSemClear, DosSemWait, WinMsgMuxSemWait,
   WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinMultWindowFromIDs
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinMultWindowFromIDs (hwndParent, phwnd, idFirst, idLast)
   HWND hwndParent;        /*handle of the parent window                   */
   PHWND phwnd;            /*address of array of window handles            */
   USHORT idFirst;         /*first window identifier in range              */
   USHORT idLast;          /*last window identifier in range               */

   The WinMultWindowFromIDs function finds the handles of specified child
   windows that have window-identifier values within a specified range. This
   function may be used to enumerate all the items in a dialog group, for
   example, or to enumerate all the frame controls of a standard window. This
   function is faster than making individual calls to the WinWindowFromID
   function.

 Parameters

   hwndParent  Identifies the parent window.

   phwnd  Points to the array that contains the window handles. This array
   must contain (idLast - idFirst + 1) elements; the zero-based index of a
   window in the array is (idWindow - idFirst), where idWindow is the window
   identifier of the specified window. If there is no window for a window
   identifier within the range, the corresponding element in the array is
   NULL.

   idFirst  Identifies the first window-identifier value in the range
   (inclusive).

   idLast  Identifies the last window-identifier value in the range
   (inclusive).

 Return Value

   The return value is the number of window handles returned in the array.
   The return value is zero if no window handles are returned.

 See Also

   WinWindowFromID

 ────────────────────────────────────────────────────────────────────────────
 WinNextChar
 ────────────────────────────────────────────────────────────────────────────
   PSZ WinNextChar (hab, idcp, idcc, psz)
   HAB hab;                /*handle of the anchor block                    */
   USHORT idcp;            /*code page                                     */
   USHORT idcc;            /*country code                                  */
   PSZ psz;                /*address of character in string                */

   The WinNextChar function moves to the next character in a string.

 Parameters

   hab  Identifies the anchor block.

   idcp  Identifies the code page.

   idcc  Identifies the country code.

   psz  Points to a character in a null-terminated string.

 Return Value

   The return value points to the next character in the string or the NULL
   terminating character.

 See Also

   WinPrevChar


 ────────────────────────────────────────────────────────────────────────────
 WinOffsetRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinOffsetRect (hab, prcl, cx, cy)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of the structure with rectangle       */
   SHORT cx;               /*horizontal offset                             */
   SHORT cy;               /*vertical offset                               */

   The WinOffsetRect function offsets a rectangle by adding a specified value
   to both the left and right coordinates and adding a specified value to
   both the top and bottom coordinates.

 Parameters

   hab  Identifies an anchor block.

   prcl  Points to the RECTL structure that contains the rectangle to be
   offset. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cx  Specifies the value of the horizontal offset. This value is added to
   the left and right sides of the rectangle.

   cy  Specifies the value of the vertical offset. This value is added to the
   top and bottom sides of the rectangle.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinInflateRect


 ────────────────────────────────────────────────────────────────────────────
 WinOpenClipbrd
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinOpenClipbrd (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinOpenClipbrd function opens the clipboard and prevents other threads
   and processes from examining or changing the clipboard contents. If
   another thread or process already has the clipboard open, this function
   does not return until the clipboard is closed.

   Messages can be received from other threads and processes during the
   processing of this function.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCloseClipbrd, WinEnumClipbrdFmts


 ────────────────────────────────────────────────────────────────────────────
 WinOpenWindowDC
 ────────────────────────────────────────────────────────────────────────────
   HDC WinOpenWindowDC (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinOpenWindowDC function opens a device context for a window.

 Parameters

   hwnd  Identifies the window with the device context.

 Return Value

   The return value is the handle of the device context.

 Comments

   Only one device context can be opened for each window.

   A handle to a device context is used to associate a presentation space
   with the window.

   The window device context is automatically closed when its associated
   window is destroyed. It must not be closed with the DevCloseDC function.

   This function is used by applications that typically have a lot of state
   information associated with a presentation space, such as coordinate
   mapping transforms, attributes, fonts, etc. This interface provides a
   "global" presentation space for a given window. This global can be kept in
   the application until the window is destroyed.

 See Also

   WinQueryWindowDC


 ────────────────────────────────────────────────────────────────────────────
 WinPeekMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinPeekMsg (hab, pqmsg, hwndFilter, msgFilterFirst, msgFilterLast,
   fs)
   HAB hab;                /*handle of the anchor block                    */
   PQMSG pqmsg;            /*address of structure                          */
   HWND hwndFilter;        /*handle of the filter window                   */
   USHORT msgFilterFirst;  /*first message                                 */
   USHORT msgFilterLast;   /*last message                                  */
   USHORT fs;              /*status of message in queue                    */

   The WinPeekMsg function inspects the thread's message queue.

 Parameters

   hab  Identifies the anchor block.

   pqmsg  Points to the QMSG structure. The QMSG structure has the following
   form:

   typedef struct _QMSG {
       HWND hwnd;
       USHORT msg;
       MPARAM mp1;
       MPARAM mp2;
       ULONG time;
       POINTL ptl;
   } QMSG;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   hwndFilter  Identifies the window filter.

   msgFilterFirst  Specifies the first message.

   msgFilterLast  Specifies the last message.

   fs  Specifies whether to remove the message from the queue. If this
   parameter is PM_REMOVE, the message is removed from the queue. If this
   parameter is PM_NOREMOVE, the message remains in the queue. An application
   should specify only one of these flags. If neither flag is specified, the
   message is not removed. If both are specified, the message is removed.

 Return Value

   The return value is TRUE if a message is available, or it is FALSE if no
   message is available.

 Comments

   This function is identical to the WinGetMsg function, except that it does
   not wait for the arrival of a message and allows for leaving the message
   in the queue.

   The constants WM_MOUSEFIRST and WM_MOUSELAST can be used for
   msgFilterFirst and msgFilterLast to filter all but mouse messages.

   The constants WM_BUTTONCLICKFIRST and WM_BUTTONCLICKLAST can be used for
   msgFilterFirst and msgFilterLast to filter all but mouse button messages.

   The constants WM_DDE_FIRST and WM_DDE_LAST can be used for msgFilterFirst
   and msgFilterLast to filter all but dynamic data exchange messages.

 See Also

   WinGetMsg


 ────────────────────────────────────────────────────────────────────────────
 WinPostMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinPostMsg (hwnd, msg, mp1, mp2)
   HWND hwnd;              /*handle of the window to post message to       */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*first message parameter                       */
   MPARAM mp2;             /*second message parameter                      */

   The WinPostMsg function posts a message to the message queue for the
   specified window.

 Parameters

   hwnd  Identifies the window to post the message to. If this parameter is
   NULL, the message is posted to the queue associated with the current
   thread.

   msg  Specifies the message.

   mp1  Specifies the first message parameter.

   mp2  Specifies second message parameter.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The following are some of the differences between WinPostMsg and
   WinSendMsg:

   ■  WinPostMsg returns immediately. WinSendMsg waits for the receiver to
      return.

   ■  A thread that does not have a message queue can still call WinPostMsg.
      It cannot call WinSendMsg.

   ■  Calling WinSendMsg to send a message to another thread is costly in
      terms of CPU time. This is not true of the WinPostMsg.

 See Also

   WinBroadcastMsg, WinGetMsg, WinPeekMsg, WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinPostQueueMsg
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinPostQueueMsg (hmq, msg, mp1, mp2)
   HMQ hmq;                /*handle of the message queue                   */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*first message parameter                       */
   MPARAM mp2;             /*second message parameter                      */

   The WinPostQueueMsg function posts a message to a message queue. This
   function can be used to post messages to any queue in the system.

 Parameters

   hmq  Identifies the message queue.

   msg  Specifies the message.

   mp1  Specifies the first message parameter.

   mp2  Specifies the second message parameter.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs or if the queue was full.

 Comments

   The last three parameters are placed into the queue as part of a QMSG
   structure. The QMSG hwnd field is set to NULL, and the QMSG time and pt
   fields are derived from the system time and mouse position at the time
   WinPostQueueMsg was called.

 See Also

   WinPostMsg, WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinPrevChar
 ────────────────────────────────────────────────────────────────────────────
   PSZ WinPrevChar (hab, idcp, idcc, pszStart, psz)
   HAB hab;                /*handle of the anchor block                    */
   USHORT idcp;            /*code page                                     */
   USHORT idcc;            /*country code                                  */
   PSZ pszStart;           /*address of string with character              */
   PSZ psz;                /*address of character in string                */

   The WinPrevChar function moves to the previous character in a string.

 Parameters

   hab  Identifies the anchor block.

   idcp  Identifies the code page.

   idcc  Identifies the country code.

   pszStart  Points to the character string that contains the character
   pointed to by the psz parameter.

   psz  Points to a character in the string pointed to by the pszStart
   parameter.

 Return Value

   The return value points to the previous character in a string, or to the
   first character if the psz parameter equals the pszStart parameter.

 See Also

   WinNextChar


 ────────────────────────────────────────────────────────────────────────────
 WinProcessDlg
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinProcessDlg (hwndDlg)
   HWND hwndDlg;           /*handle of the dialog queue                    */

   The WinProcessDlg function processes messages intended for a dialog
   window. This function does not return until the WinDismissDlg function is
   called by the dialog procedure.

 Parameters

   hwndDlg  Identifies a dialog window.

 Return Value

   The return value is set to the value returned by the WinDismissDlg
   function.

 See Also

   WinDismissDlg, WinDlgBox, WinLoadDlg


 ────────────────────────────────────────────────────────────────────────────
 WinPtInRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinPtInRect (hab, prcl, pptl)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of structure with rectangle           */
                           /*coordinates                                   */
   PPOINTL pptl;           /*address of structure with point coordinates   */

   The WinPtInRect function determines whether a point lies within a
   rectangle.

 Parameters

   hab  Identifies an anchor block.

   prcl  Points to a RECTL structure containing the rectangle to be checked.
   The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   pptl  Points to a POINTL structure containing the point to be checked. The
   POINTL structure has the following form:

   typedef struct _POINTL {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the point lies within the rectangle, or FALSE
   if the point is outside the rectangle.

 Example

   This example processes a WM_BUTTON1UP message, converts the mouse pointer
   coordinates into a POINTL structure, and calls WinPtInRect to determine if
   the mouse was clicked in the predefined global rectangle.

   RECTL rclGlobal;    /* global set to some predefined rectangle */
   POINTL ptl;
   HPS hps;

   case WM_BUTTON1UP:
       ptl.x = (LONG) SHORT1FROMMP(mp1);
       ptl.y = (LONG) SHORT2FROMMP(mp1);
       if (WinPtInRect(hab,   /* anchor-block handle      */
           &rclGlobal,        /* address of the rectangle */
           &ptl)) {           /* address of the point     */

 See Also

   GpiPtInRegion


 ────────────────────────────────────────────────────────────────────────────
 WinQueryAccelTable
 ────────────────────────────────────────────────────────────────────────────
   HACCEL WinQueryAccelTable (hab, hwndFrame)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwndFrame;         /*handle of the frame window                    */

   The WinQueryAccelTable function queries the window or queue accelerator
   table.

 Parameters

   hab  Identifies an anchor block.

   hwndFrame  Identifies the frame window. This parameter can be NULL.

 Return Value

   The return value is an accelerator-table handle if the function is
   successful, or NULL if an error occurred.

 Comments

   If the hwndFrame parameter is NULL, then the handle of the queue
   accelerator is returned. Otherwise, the handle of the window accelerator
   table is returned by sending the WM_QUERYACCELTABLE message to the frame
   window specified by hwndFrame.

 See Also

   WinCreateAccelTable


 ────────────────────────────────────────────────────────────────────────────
 WinQueryActiveWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryActiveWindow (hwndDesktop, fLock)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinQueryActiveWindow function retrieves the active frame window.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fLock  Specifies whether the active window should be locked. If TRUE, the
   window is locked. If FALSE, it is not.

 Return Value

   The return value is the active window handle or NULL if no window was
   active at the time of the call or the hwndDesktop handle is invalid.

 Comments

   If this function is called while the active window is changing, then it
   may return NULL, indicating that no window was active at the time of the
   call. Since a NULL value can also be returned if the hwndDesktop handle is
   invalid, you must call WinGetLastError to determine if a NULL return value
   is caused by an invalid hwndDesktop handle or because the active window
   was changing when you made the call.

   If the active window is locked by this function, then you must at some
   point call the WinLockWindow function to unlock the window. The reason for
   locking the window is so that the window cannot be destroyed until you are
   done using it.

 See Also

   WinLockWindow, WinQueryFocus


 ────────────────────────────────────────────────────────────────────────────
 WinQueryAtomLength
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryAtomLength (hAtomTbl, atom)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */
   ATOM atom;              /*atom                                          */

   The WinQueryAtomLength function queries the length of a string associated
   with the passed atom. The purpose of this function is to allow an
   application to determine the size of the buffer to pass to the
   WinQueryAtomName function.

 Parameters

   hAtomTbl  Identifies an atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable function.

   atom  Specifies the atom whose length is to be returned.

 Return Value

   The return value is the length of the string associated with the atom, not
   including the null terminating byte. If the specified atom or atom table
   is invalid, the return value is zero. Integer atoms always return a length
   of 6.

 See Also

   WinCreateAtomTable, WinQueryAtomName


 ────────────────────────────────────────────────────────────────────────────
 WinQueryAtomName
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryAtomName (hAtomTbl, atom, pszBuffer, cchBufferMax)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */
   ATOM atom;              /*atom                                          */
   PSZ pszBuffer;          /*address of the buffer                         */
   USHORT cchBufferMax;    /*length of the buffer                          */

   The WinQueryAtomName function retrieves an atom name associated with an
   atom.

 Parameters

   hAtomTbl  Identifies an atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable function.

   atom  Specifies an atom identifying the character string to retrieve. For
   integer atoms, the format of the string is #ddddd, where ddddd are decimal
   digits in the system code page (which will be an ASCII code page). No
   leading zeros are generated, and the length can be from three to seven
   characters.

   pszBuffer  Points to the buffer to receive the character string.

   cchBufferMax  Specifies the maximum size (in bytes) of the buffer pointed
   to by pszBuffer.

 Return Value

   The return value is the actual number of bytes copied to the buffer,
   excluding the null terminating byte. If the specified atom or the atom
   table is invalid, the return value is zero.

 See Also

   WinCreateAtomTable, WinFindAtom, WinQueryAtomLength


 ────────────────────────────────────────────────────────────────────────────
 WinQueryAtomUsage
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryAtomUsage (hAtomTbl, atom)
   HATOMTBL hAtomTbl;      /*handle of the atom table                      */
   ATOM atom;              /*atom                                          */

   The WinQueryAtomUsage function returns the number of times an atom has
   been used.

 Parameters

   hAtomTbl  Identifies an atom table. This handle must have been created by
   a previous call to the WinCreateAtomTable function.

   atom  Specifies the atom whose use count is to be returned.

 Return Value

   The return value is the use count of the atom. It is 0xFFFF for integer
   atoms. If the atom table or atom is invalid, then the return value is
   zero.

 See Also

   WinAddAtom, WinCreateAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinQueryCapture
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryCapture (hwndDesktop, fLock)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinQueryCapture function returns the window handle of the window that
   has the mouse capture.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fLock  Specifies whether the window that has the mouse capture should be
   locked. If TRUE, the window is locked. If FALSE, it is not.

 Return Value

   The return value is the window handle with the mouse capture, or NULL if
   no window has the capture or an error occurred.

 Comments

   If the window that has the mouse capture is locked by this function, then
   you must at some point call the WinLockWindow function to unlock the
   window. The reason for locking the window is so that the window cannot be
   destroyed until you are done using it.

 See Also

   WinLockWindow, WinSetCapture


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClassInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryClassInfo (hab, pszClassName, pclsi)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszClassName;       /*address of the class name                     */
   PCLASSINFO pclsi;       /*address of structure for class information    */

   The WinQueryClassInfo function retrieves window class information. This
   function is used in creating subclasses of a given class.

 Parameters

   hab  Identifies an anchor block.

   pszClassName  Points to a null-terminated string containing the class
   name. The class name is either an application-specified name as defined by
   the WinRegisterClass function or the name of a preregistered WC class.

   pclsi  Points to a CLASSINFO structure that will contain the retrieved
   information about the class. The CLASSINFO structure has the following
   form:

   typedef struct _CLASSINFO {
       ULONG   flClassStyle;
       PFNWP   pfnWindowProc;
       USHORT  cbWindowData;
   } CLASSINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful. Otherwise, it is
   FALSE, indicating that the class does not exist.

 See Also

   WinRegisterClass


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClassName
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryClassName (hwnd, cchMax, psz)
   HWND hwnd;              /*handle of the window                          */
   SHORT cchMax;           /*length of the buffer                          */
   PSZ psz;                /*address of the buffer                         */

   The WinQueryClassName function copies the window class name, as a
   null-terminated string, into a buffer.

   If the class name is longer than (cchMax - 1), only the first (cchMax - 1)
   characters of the class name are copied.

   If the specified window is of any of the preregistered WC classes, the
   class name returned is in the form #nnnnn, where nnnnn is up to five
   digits that correspond to the low word of the WC class-name constant.

 Parameters

   hwnd  Identifies a window.

   cchMax  Specifies the length of the buffer pointed to by the psz
   parameter.

   psz  Points to a buffer for the class name.

 Return Value

   The return value is the length of the returned class name, not including
   the null termination character.

 See Also

   WinQueryClassInfo, WinRegisterClass


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClipbrdData
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinQueryClipbrdData (hab, fmt)
   HAB hab;                /*handle of the anchor block                    */
   USHORT fmt;             /*specifies the format of the data              */

   The WinQueryClipbrdData function obtains a handle to the current clipboard
   data having a specified format.

   The returned data handle cannot be used after the WinCloseClipbrd function
   is called. For this reason, the application must either copy the data, if
   required for long-term use, or process the data before WinCloseClipbrd is
   called.

   The application should not free the data handle itself nor leave it locked
   in any way.

 Parameters

   hab  Identifies an anchor block.

   fmt  Specifies the format of the data that is accessed by this function.

 Return Value

   The return value is a handle to the data in the clipboard in the format
   specified by the fmt parameter. If the format does not exist or if an
   error occurred, the return value is NULL.

 Comments

   For a description of the possible formats and data handles, see the
   WinSetClipbrdData function.

 See Also

   WinCloseClipbrd, WinOpenClipbrd, WinSetClipbrdData


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClipbrdFmtInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryClipbrdFmtInfo (hab, fmt, pfsFmtInfo)
   HAB hab;                /*handle of the anchor block                    */
   USHORT fmt;             /*specifies data format                         */
   PUSHORT pfsFmtInfo;     /*receives memory model and usage flags         */

   The WinQueryClipbrdFmtInfo function determines whether a particular format
   of data is present in the clipboard and, if so, provides information about
   that format.

 Parameters

   hab  Identifies an anchor block.

   fmt  Specifies the format of the data that this function queries. The
   following list describes the standard clipboard formats:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CF_BITMAP         The data is a bitmap. The CFI_HANDLE memory-model flag
                     must be set in the pfsFmtInfo parameter.

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────

   CF_DSPBITMAP      The data is a bitmap representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
                     CFI_HANDLE must be set in the pfsFmtInfo parameter.

   CF_METAFILE       The data is a metafile. The CFI_HANDLE memory-model flag
                     must be set in the pfsFmtInfo parameter.

   CF_DSPMETAFILE    The data is a metafile representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
                     CFI_HANDLE must be set in the pfsFmtInfo parameter.

   CF_TEXT           The data is an array of text characters, which may
                     include newline characters to mark line breaks. The null
                     character indicates the end of the text data. The
                     CFI_SELECTOR memory-model flag must be set in the
                     pfsFmtInfo parameter.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    pfsFmtInfo parameter.

   CF_DSPTEXT        The data is a textual representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
                     CFI_SELECTOR must be set in the pfsFmtInfo parameter.
   ──────────────────────────────────────────────────────────────────────────


   pfsFmtInfo  Points to a variable that receives the memory-model and usage
   (CFI) flags. It consists of a memory-model flag and a usage flag from the
   following lists:

   Memory-model flag  Meaning
   ──────────────────────────────────────────────────────────────────────────
   CFI_SELECTOR       Handle is a selector plus zero offset to a segment in
                      storage.

   CFI_HANDLE         Handle is the handle to a metafile or bitmap.
   ──────────────────────────────────────────────────────────────────────────

   Usage flag         Meaning
   ──────────────────────────────────────────────────────────────────────────
   CFI_OWNERFREE      Handle is not freed by the WinEmptyClipbrd function.
                      The application must free the data if necessary.

   CFI_OWNERDISPLAY   Format will be drawn by the clipboard owner in the
                      clipboard-viewer window by means of the
                      WM_PAINTCLIPBOARD message. The ulData parameter should
                      be NULL.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is TRUE if the format exists. Otherwise, it is FALSE,
   indicating that the format does not exist.

 Comments

   For a description of the possible formats and data handles, see the
   WinSetClipbrdData function.

 See Also

   WinOpenClipbrd, WinSetClipbrdData


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClipbrdOwner
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryClipbrdOwner (hab, fLock)
   HAB hab;                /*handle of the anchor block                    */
   BOOL fLock;             /*lock/unlock viewer flag                       */

   The WinQueryClipbrdOwner function obtains the handle of the window that
   currently owns the clipboard (if any).

 Parameters

   hab  Identifies an anchor block.

   fLock  Specifies whether the clipboard owner window should be locked. If
   TRUE, the window is locked. If FALSE, it is not.

 Return Value

   The return value is the window handle of the current clipboard owner. If
   the clipboard is not owned by any window or if an error occurred, the
   return value is NULL.

 Comments

   If the clipboard owner window is locked by this function, then you must at
   some point call the WinLockWindow function to unlock the window. The
   reason for locking the window is so that the window cannot be destroyed
   until you are done using it.

 See Also

   WinLockWindow, WinQueryClipbrdViewer, WinSetClipbrdOwner


 ────────────────────────────────────────────────────────────────────────────
 WinQueryClipbrdViewer
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryClipbrdViewer (hab, fLock)
   HAB hab;                /*handle of the anchor block                    */
   BOOL fLock;             /*lock/unlock viewer flag                       */

   The WinQueryClipbrdViewer function obtains the handle of the current
   clipboard viewer window (if any).

 Parameters

   hab  Identifies an anchor block.

   fLock  Specifies whether the clipboard owner window should be locked. If
   TRUE, the window is locked. If FALSE, it is not.

 Return Value

   The return value is the handle of the current clipboard viewer window. If
   the clipboard does not have a current viewer window or if an error
   occurred, the return value is NULL.

 Comments

   If the clipboard owner window is locked by this function, then you must at
   some point call the WinLockWindow function to unlock the window. The
   reason for locking the window is so that the window cannot be destroyed
   until you are done using it.

 See Also

   WinLockWindow, WinQueryClipbrdOwner, WinSetClipbrdViewer


 ────────────────────────────────────────────────────────────────────────────
 WinQueryCp
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryCp (hmq)
   HMQ hmq;                /*handle of the message queue                   */

   The WinQueryCp function retrieves the code page for the specified message
   queue.

 Parameters

   hmq  Identifies a message queue.

 Return Value

   The return value is the code page for the specified message queue if the
   function is successful. Otherwise, it is zero, indicating that an error
   occurred.

 See Also

   DosGetCp, GpiQueryCp, VioGetCp


 ────────────────────────────────────────────────────────────────────────────
 WinQueryCpList
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryCpList (hab, ccpMax, pacp)
   HAB hab;                /*handle of the anchor block                    */
   USHORT ccpMax;          /*maximum number of code pages to retrieve      */
   PUSHORT pacp;           /*address of array to receive code pages        */

   The WinQueryCpList function obtains available code pages.

 Parameters

   hab  Identifies an anchor block.

   ccpMax  Specifies the maximum number of code pages that will be returned.

   pacp  Points to an array that will receive the available code pages. It
   will include all code pages available to the Gpi and Vio functions,
   including any EBCDIC ones. This list is a superset of those code pages
   available to the WinSetCp function and the Dos functions.

 Return Value

   The return value is the the total number of code pages in the system.

 See Also

   GpiSetCp, VioGetCp, WinQueryCp, WinSetCp


 ────────────────────────────────────────────────────────────────────────────
 WinQueryCursorInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryCursorInfo (hwndDesktop, pcsri)
   HWND hwndDesktop;       /*handle of the desktop                         */
   PCURSORINFO pcsri;      /*address of structure for cursor information   */

   The WinQueryCursorInfo function retrieves information about the current
   cursor.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   pcsri  Points to a CURSORINFO structure that receives information about
   the current cursor. The values are equivalent to the parameters to the
   WinCreateCursor function, except that the fs field never includes the
   CURSOR_SETPOS flag. The size and position of the cursor are returned in
   window coordinates relative to the window identified by the hwnd field of
   the structure. The CURSORINFO structure has the following form:

   typedef struct _CURSORINFO {
       HWND   hwnd;
       SHORT  x;
       SHORT  y;
       SHORT  cx;
       SHORT  cy;
       USHORT fs;
       RECTL  rclClip;
   } CURSORINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the cursor exists, or FALSE if it does not.

 See Also

   WinCreateCursor, WinDestroyCursor, WinShowCursor


 ────────────────────────────────────────────────────────────────────────────
 WinQueryDefinition
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryDefinition (hab, hProgHandle, ppib, cbMax)
   HAB hab;                /*handle of the anchor block                    */
   HPROGRAM hProgHandle;   /*handle of the program                         */
   PPIBSTRUCT ppib;        /*address of structure for program information  */
   USHORT cbMax;           /*length of ppib buffer                         */

   The WinQueryDefinition function retrieves information about a program or
   program group.

 Parameters

   hab  Identifies the anchor block.

   hProgHandle  Identifies the program or group.

   ppib  Points to a PIBSTRUCT structure that receives the program
   information data. If the hProgHandle parameter is a group handle, only the
   program type and program title fields are significant. The structure has
   the following form:

   typedef struct _PIBSTRUCT {
       PROGTYPE  progt;
       CHAR      szTitle[MAXNAMEL+1];
       CHAR      szIconFileName[MAXPATHL+1];
       CHAR      szExecutable[MAXPATHL+1];
       CHAR      szStartupDir[MAXPATHL+1];
       XYWINSIZE xywinInitial;
       USHORT    res1;
       LHANDLE   res2;
       USHORT    cchEnvironmentVars;
       PCH       pchEnvironmentVars;
       USHORT    cchProgramParameter;
       PCH       pchProgramParameter;
   } PIBSTRUCT;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cbMax  Specifies the maximum length of data (in bytes) that can be
   returned in the data structure pointed to by ppib. If cbMax is zero, this
   function returns the number of bytes in the program information block.

 Return Value

   The return value is the length of the data actually returned in the data
   structure, or zero if an error occurred.

   If the target is a program rather than a program group, the data returned
   in ppib is in a format usable by the WinAddProgram function.

 See Also

   WinAddProgram


 ────────────────────────────────────────────────────────────────────────────
 WinQueryDesktopWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryDesktopWindow (hab, hdc)
   HAB hab;                /*handle of the anchor block                    */
   HDC hdc;                /*handle of the device context                  */

   The WinQueryDesktopWindow function retrieves the desktop window handle.

 Parameters

   hab  Identifies an anchor block.

   hdc  Identifies a device context. For MS OS/2, version 1.1, this parameter
   must be NULL.

 Return Value

   The return value is the desktop window handle or NULL if the device does
   not support windowing.

 Comments

   For most Win calls the constant HWND_DESKTOP can be used for the desktop
   window handle.

 See Also

   WinCreateWindow, WinQueryObjectWindow


 ────────────────────────────────────────────────────────────────────────────
 WinQueryDlgItemShort
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryDlgItemShort (hwndDlg, idItem, pResult, fSigned)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*dialog-item identifier                        */
   PSHORT pResult;         /*address of variable for result                */
   BOOL fSigned;           /*signed/unsigned flag                          */

   The WinQueryDlgItemShort function translates the text of a dialog item
   into an integer value. This function is useful in translating a numerical
   input field into a numeric value for further processing.

 Parameters

   hwndDlg  Identifies a dialog-box window.

   idItem  Identifies the dialog item whose text is translated. The
   dialog-item text is assumed to be an ASCII string.

   pResult  Points to the integer value resulting from the translation.

   fSigned  Specifies whether the item text is treated as signed or unsigned.
   If this parameter is TRUE, the item text is treated as signed, in which
   case the translation checks for a minus sign in the text. If it is FALSE,
   the item text is treated as unsigned.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If the text string does not contain a valid representation of a number, as
   in "size," or "-3" when fSigned is FALSE, then the return value will be
   FALSE.

 See Also

   WinSetDlgItemShort


 ────────────────────────────────────────────────────────────────────────────
 WinQueryDlgItemText
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryDlgItemText (hwndDlg, idItem, cchBufferMax, pszBuf)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*identifies the dialog item                    */
   SHORT cchBufferMax;     /*size of the buffer                            */
   PSZ pszBuf;             /*address of the buffer                         */

   The WinQueryDlgItemText function retrieves the text associated with the
   specified dialog item.

 Parameters

   hwndDlg  Identifies the dialog box.

   idItem  Identifies the dialog item.

   cchBufferMax  Specifies the maximum number of characters to place in the
   buffer pointed to by the pszBuf parameter.

   pszBuf  Points to a buffer that receives the dialog item text.

 Return Value

   The return value is the length of the dialog item text, or zero if an
   error occurred.

 See Also

   WinQueryDlgItemTextLength


 ────────────────────────────────────────────────────────────────────────────
 WinQueryDlgItemTextLength
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryDlgItemTextLength (hwndDlg, idItem)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*dialog-item identifier                        */

   The WinQueryDlgItemTextLength function retrieves the length of the dialog
   item text, not including any null termination character.

   This function sends a WM_QUERYFRAMEINFO message to the window identified
   by the hwndDlg parameter.

 Parameters

   hwndDlg  Identifies the dialog box.

   idItem  Identifies the dialog item.

 Return Value

   The return value is the length of the dialog item text, or zero if an
   error occurred.

 See Also

   WinQueryDlgItemText


 ────────────────────────────────────────────────────────────────────────────
 WinQueryFocus
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryFocus (hwndDesktop, fLock)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinQueryFocus function returns the handle of the window that currently
   has the focus.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fLock  Specifies whether the focus window should be locked. If TRUE, the
   window is locked. If FALSE, it is not.

 Return Value

   The return value is a handle to the focus window or NULL if there is no
   focus window or an error occurs.

 Comments

   If the focus window is locked by this function, then you must at some
   point call the WinLockWindow function to unlock the window. The reason for
   locking the window is so that the window cannot be destroyed until you are
   done using it.

 See Also

   WinFocusChange, WinLockWindow, WinQueryActiveWindow, WinSetFocus


 ────────────────────────────────────────────────────────────────────────────
 WinQueryMsgPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryMsgPos (hab, pptl)
   HAB hab;                /*handle of the anchor block                    */
   PPOINTL pptl;           /*address of structure for pointer position     */

   The WinQueryMsgPos function retrieves the pointer position, in screen
   coordinates, when the last message obtained from the current message queue
   was posted. To obtain the current position of the pointer, use the
   WinQueryPointerPos function.

 Parameters

   hab  Identifies an anchor block.

   pptl  Points to a POINTL structure that receives the pointer position in
   screen coordinates. The pointer position is the same as that in the ptl
   field of the QMSG structure. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryPointerPos


 ────────────────────────────────────────────────────────────────────────────
 WinQueryMsgTime
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinQueryMsgTime (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinQueryMsgTime function retrieves the message time for the last
   message retrieved by the WinGetMsg or WinPeekMsg function from the current
   message queue.

   The message time is the time, in milliseconds, when the message was
   posted. The time value is the same as that in the time field of the QMSG
   structure.

   You cannot assume that time values are always increasing. Since the time
   value is the number of milliseconds since the system was booted, it is
   possible that the value may wrap to zero. To accurately calculate time
   delays between messages, subtract the time of the first message from the
   time of the second.

 Parameters

   hab  Identifies an anchor block.

 Return Value

   The return value is the time, in milliseconds, when the message was
   posted.

 See Also

   WinGetCurrentTime, WinGetMsg, WinPeekMsg


 ────────────────────────────────────────────────────────────────────────────
 WinQueryObjectWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryObjectWindow (hwndDesktop)
   HWND hwndDesktop;       /*handle of the desktop                         */

   The WinQueryObjectWindow function returns the desktop object-window
   handle.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

 Return Value

   The return value is the desktop object-window handle, or NULL if an error
   occurs.

 Comments

   For most API calls the constant HWND_OBJECT can be used for the desktop
   object-window handle.

 See Also

   WinQueryDesktopWindow


 ────────────────────────────────────────────────────────────────────────────
 WinQueryPointer
 ────────────────────────────────────────────────────────────────────────────
   HPOINTER WinQueryPointer (hwndDesktop)
   HWND hwndDesktop;       /*handle of the desktop                         */

   The WinQueryPointer function retrieves the handle to the desktop pointer.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

 Return Value

   The return value is a handle to the desktop pointer or NULL if an error
   occurred.

 See Also

   WinQuerySysPointer, WinSetPointer


 ────────────────────────────────────────────────────────────────────────────
 WinQueryPointerInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryPointerInfo (hptr, pptri)
   HPOINTER hptr;          /*handle of the pointer                         */
   PPOINTERINFO pptri;     /*address of structure for pointer information  */

   The WinQueryPointerInfo function retrieves information about the mouse
   pointer such as the pointer's bitmap handle and hotspot coordinates.

 Parameters

   hptr  Identifies a pointer.

   pptri  Points to a POINTERINFO structure that receives information about
   the mouse pointer. The POINTERINFO structure has the following form:

   typedef struct _POINTERINFO {
       BOOL    fPointer;
       SHORT   xHotspot;
       SHORT   yHotspot;
       HBITMAP hbmPointer;
   } POINTERINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryPointerPos


 ────────────────────────────────────────────────────────────────────────────
 WinQueryPointerPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryPointerPos (hwndDesktop, pptl)
   HWND hwndDesktop;       /*handle of desktop window                      */
   PPOINTL pptl;           /*address of structure for pointer position     */

   The WinQueryPointerPos function retrieves the mouse pointer position. The
   position returned is the position of the pointer at the time
   WinQueryPointerPos is called and is not synchronized with the WinGetMsg
   and WinPeekMsg functions. Use the WinQueryMsgPos function to get the
   pointer position of the last message obtained via WinGetMsg or WinPeekMsg.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   pptl  Points to a POINTL structure that receives the pointer position in
   screen coordinates. The POINTL structure has the following form:

   typedef struct _POINTL  {
       LONG  x;
       LONG  y;
   } POINTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The position retrieved is in screen coordinates, not window coordinates.
   You can convert screen coordinates to window coordinates with the
   WinMapWindowPoints function.

 See Also

   WinGetMsg, WinPeekMsg, WinQueryMsgPos, WinQueryPointerInfo


 ────────────────────────────────────────────────────────────────────────────
 WinQueryProfileData
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryProfileData (hab, pszAppName, pszKeyName, pvBuf, cbBuf)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszAppName;         /*address of the application name               */
   PSZ pszKeyName;         /*address of the keyname                        */
   PVOID pvBuf;            /*address of the buffer                         */
   PUSHORT cbBuf;          /*length of the buffer                          */

   The WinQueryProfileData function retrieves binary data from the os2.ini
   file. Where the data is located is determined by an application name and a
   keyname which are passed to the function.

 Parameters

   hab  Identifies an anchor block.

   pszAppName  Points to a null-terminated text string that contains the name
   of the application. Its length must be less than 1024 bytes, including the
   null termination character. The application name is always case-dependent.

   pszKeyName  Points to a null-terminated text string that contains the
   keyname. Its length must be less than 1024 bytes, including the null
   termination character. If pszKeyName is NULL, all keynames and their data
   are deleted. The keyname is always case-dependent.

   pvBuf  Points to a buffer that receives the data.

   cbBuf  Points to a variable that contains the size of the buffer pointed
   to by pvBuf. When the function returns, this variable will contain the
   actual number of bytes placed into the buffer.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   You can find out the size of the data prior to calling this function by
   calling WinQueryProfileSize.

 See Also

   WinQueryProfileSize, WinWriteProfileData


 ────────────────────────────────────────────────────────────────────────────
 WinQueryProfileInt
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryProfileInt (hab, pszAppName, pszKeyName, sError)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszAppName;         /*address of the application name               */
   PSZ pszKeyName;         /*address of the keyname                        */
   SHORT sError;           /*value returned if keyname not found           */

   The WinQueryProfileInt function retrieves an integer from the os2.ini
   file. Where the integer is located is determined by an application name
   and a keyname which are passed to this function. The integer must have
   been previously stored as a text string using the WinWriteProfileString
   function. For example, a text string stored as "123" would be returned as
   the integer 123. The text string may contain a leading minus sign if the
   number is negative.

 Parameters

   hab  Identifies the anchor block.

   pszAppName  Points to a null-terminated text string that contains the name
   of the application. Its length must be less than 1024 bytes, including the
   null termination character. The application name is always case-dependent.

   pszKeyName  Points to a null-terminated text string that contains the
   keyname. Its length must be less than 1024 bytes, including the null
   termination character. If pszKeyName is NULL, all keynames and their data
   are deleted. The keyname is always case-dependent.

   sError  Specifies the error value returned if the keyname (pszKeyName)
   cannot be found.

 Return Value

   The return value is the integer representation of the text string. If the
   keyname cannot be found, the error value specified by sError is returned.

 See Also

   WinQueryProfileData, WinWriteProfileString


 ────────────────────────────────────────────────────────────────────────────
 WinQueryProfileSize
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryProfileSize (hab, pszAppName, pszKeyName, pcb)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszAppName;         /*points to the application name                */
   PSZ pszKeyName;         /*points to the keyname                         */
   PUSHORT pcb;            /*points to variable with length of the data    */

   The WinQueryProfileSize function retrieves the size of the data stored at
   a specified location in the os2.ini file. Where the data is located is
   determined by an application name and a keyname which are passed to this
   function. This function is typically called prior to calling
   WinQueryProfileData in order to determine how much memory to allocate for
   the data.

 Parameters

   hab  Identifies an anchor block.

   pszAppName  Points to a null-terminated text string that contains the name
   of the application. Its length must be less than 1024 bytes, including the
   null termination character. The application name is always case-dependent.

   pszKeyName  Points to a null-terminated text string that contains the
   keyname. Its length must be less than 1024 bytes, including the null
   termination character. If pszKeyName is NULL, all keynames and their data
   are deleted. The keyname is always case-dependent.

   pcb  Points to a variable that will receive the length of the data. If an
   error occurs, the length will not be returned.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   an error value.

 See Also

   WinQueryProfileData, WinQueryProfileString


 ────────────────────────────────────────────────────────────────────────────
 WinQueryProfileString
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryProfileString (hab, pszAppName, pszKeyName, pszError,
   pszBuf, cchBuf)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszAppName;         /*points to the application name                */
   PSZ pszKeyName;         /*points to the keyname                         */
   PSZ pszError;           /*points to a default string                    */
   PSZ pszBuf;             /*address of the buffer for the string          */
   USHORT cchBuf;          /*size of buffer                                */

   The WinQueryProfileString function retrieves a string from the os2.ini
   file. Where the string is located is determined by an application name and
   a keyname which are passed to this function.

 Parameters

   hab  Identifies an anchor block.

   pszAppName  Points to a null-terminated text string that contains the name
   of the application. Its length must be less than 1024 bytes, including the
   null termination character. The application name is always case-dependent.

   pszKeyName  Points to a null-terminated text string that contains the
   keyname. Its length must be less than 1024 bytes, including the null
   termination character. If pszKeyName is NULL, all keynames and their data
   are deleted. The keyname is always case-dependent.

   pszError  Points to a null-terminated string that is placed in pszBuf if
   the key is not found.

   pszBuf  Points to a buffer that will receive the null-terminated string.

   cchBuf  Specifies the length of the buffer (pszBuf). If the retrieved
   string is longer than this value, it will be truncated.

 Return Value

   The return value is the number of characters in the buffer pointed to by
   pszBuf.

 See Also

   WinWriteProfileString


 ────────────────────────────────────────────────────────────────────────────
 WinQueryProgramTitles
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryProgramTitles (hab, hGroup, paproge, cbBuf, pcTitles)
   HAB hab;                /*handle of the anchor block                    */
   HPROGRAM hGroup;        /*handle of the group                           */
   PPROGRAMENTRY paproge;  /*array of PROGRAMENTRY structures              */
   USHORT cbBuf;           /*length of paproge buffer                      */
   PUSHORT pcTitles;       /*receives number of titles                     */

   The WinQueryProgramTitles function obtains information about programs
   within a specified program group.

   This function can be used to find out the number of entries within a group
   by passing a buffer of zero bytes. The function will return the total
   number of entries within the group.

   The list of returned program entries may contain group handles. This
   allows the tree structure to be built by the caller. Note, though, that
   information from only one level of the tree structure is returned by this
   call.

   The handle specified can also be a program handle, in which case the
   buffer will contain only the entry for one program. Thus, this call can be
   used to get the program title.

 Parameters

   hab  Identifies the anchor block.

   hGroup  Identifies the group for which information is returned. This
   handle is either the handle of a program group or SGH_ROOT for the root
   group.

   paproge  Points to a storage area where the program information is
   returned. This is an array of PROGRAMENTRY structures. The PROGRAMENTRY
   structure has the following form:

   typedef struct _PROGRAMENTRY {
       HPROGRAM hprog;
       PROGTYPE progt;
       CHAR     szTitle[MAXNAMEL+1];
   } PROGRAMENTRY;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cbBuf  Specifies the total length (in bytes) of the area pointed to by the
   paproge parameter. Values of cbBuf less than the size of a PROGRAMENTRY
   structure are invalid.

   pcTitles  Points to a variable that receives the count of the available
   titles. If the hGroup parameter is SGH_ROOT or SGH_MASTER and the buffer
   length specified in the cbBuf parameter is too small to hold all the
   titles, the return value is zero, none of the titles are copied to the
   buffer, and pcTitles contains the number of titles available. If hGroup is
   a program handle, both the return value and pcTitles are the number of
   handles available.

 Return Value

   The return value is the count of available titles. If an error occurred,
   the return value is zero.

 See Also

   WinAddProgram


 ────────────────────────────────────────────────────────────────────────────
 WinQueryQueueInfo
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryQueueInfo (hmq, pmqi, cbCopy)
   HMQ hmq;                /*handle of the message queue                   */
   PMQINFO pmqi;           /*address of structure for queue information    */
   USHORT cbCopy;          /*number of bytes of information to copy        */

   The WinQueryQueueInfo function is used to obtain information about a
   specified queue, such as the process and thread identifier associated with
   the queue, the maximum number of messages the queue can hold, and the
   queue procedure address.

 Parameters

   hmq  Identifies the message queue. This handle must either have been
   created by a previous call to WinCreateMsgQueue, or it must be HMQ_CURRENT
   to specify the message queue of the thread that is calling this function.

   pmqi  Points to an MQINFO structure that will receive information about
   the message queue. This MQINFO structure has the following form:

   typedef struct _MQINFO {
       USHORT cb;
       PID    pid;
       TID    tid;
       USHORT cmsgs;
       PVOID  pReserved;
   } MQINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cbCopy  Specifies the number of bytes of data that will be copied into the
   MQINFO structure. Normally, it should be set to the length of the
   structure.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   An important side effect of this function is that a DLL procedure or hook
   can use this function to find out if the current thread has a message
   queue associated with it.

 See Also

   WinCreateMsgQueue


 ────────────────────────────────────────────────────────────────────────────
 WinQueryQueueStatus
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinQueryQueueStatus (hwndDesktop)
   HWND hwndDesktop;       /*handle of the desktop                         */

   The WinQueryQueueStatus function returns a code that indicates the status
   of the message queue associated with the current queue.

   This function is very fast and is typically used inside loops to determine
   whether the WinGetMsg or WinPeekMsg function should be called to process
   input.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

 Return Value

   The high word of the return value indicates the types of messages
   currently in the queue. The low word of the return value shows the types
   of messages added to the queue since the last call to WinQueryQueueStatus
   that are still in the queue.

   The following list describes the types of messages that may be in the
   queue:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   QS_KEY            A WM_CHAR message is in the queue.

   QS_MOUSE          A WM_MOUSEMOVE or WM_BUTTON message is in the queue.

   QS_MOUSEBUTTON    A WM_BUTTON message is in the queue.

   QS_MOUSEMOVE      A WM_MOUSEMOVE message is in the queue.

   QS_PAINT          A WM_PAINT message is in the queue.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
  QS_PAINT          A WM_PAINT message is in the queue.

   QS_POSTMSG        A posted message other than those listed above is in the
                     queue.

   QS_SEM1           A WM_SEM1 message is in the queue.

   QS_SEM2           A WM_SEM2 message is in the queue.

   QS_SEM3           A WM_SEM3 message is in the queue.

   QS_SEM4           A WM_SEM4 message is in the queue.

   QS_SENDMSG        A message sent by another application is in the queue.

   QS_TIMER          A WM_TIMER message is in the queue.
   ──────────────────────────────────────────────────────────────────────────


 See Also

   WinGetMsg, WinPeekMsg


 ────────────────────────────────────────────────────────────────────────────
 WinQuerySysColor
 ────────────────────────────────────────────────────────────────────────────
   COLOR WinQuerySysColor (hwndDesktop, clr, lReserved)
   HWND hwndDesktop;       /*handle of the desktop                         */
   COLOR clr;              /*color index of color to retrieve              */
   LONG lReserved;         /*reserved                                      */

   The WinQuerySysColor function retrieves a specified system color.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   clr  Specifies the system color-index value to be returned. This parameter
   must be one of the SYSCLR index values. For a description of the possible
   color indexes, see the WinSetSysColors function.

   lReserved  Reserved; must be zero.

 Return Value

   The return value is the RGB value corresponding to the index value
   specified by the clr parameter.

 See Also

   WinSetSysColors


 ────────────────────────────────────────────────────────────────────────────
 WinQuerySysModalWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQuerySysModalWindow (hwndDesktop, fLock)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinQuerySysModalWindow function returns the current system modal
   window.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fLock  Specifies whether the system modal window should be locked during
   processing. If this parameter is TRUE, the window is locked. If FALSE, it
   is not.

 Return Value

   The return value is the handle of the current system modal window. If
   there is none, the return value is NULL.

 Comments

   If the system modal window is locked by this function, then you must at
   some point call the WinLockWindow function to unlock the window. The
   reason for locking the window is so that the window cannot be destroyed
   until you are done using it.

 See Also

   WinLockWindow, WinSetSysModalWindow


 ────────────────────────────────────────────────────────────────────────────
 WinQuerySysPointer
 ────────────────────────────────────────────────────────────────────────────
   HPOINTER WinQuerySysPointer (hwndDesktop, iptr, fLoad)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT iptr;             /*system-pointer identifier                     */
   BOOL fLoad;             /*load/unload flag                              */

   The WinQuerySysPointer function returns the system pointer handle.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   iptr  Specifies the system pointer from the following list. The appearance
   of system pointers is implementation dependent.

╓┌─┌───────────────────────┌─────────────────────────────────────────────────╖
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   SPTR_APPICON            Standard application icon

   SPTR_ARROW              Normal arrow pointer

   SPTR_ICONERROR          Exclamation-mark icon

   SPTR_ICONINFORMATION    Hand icon

   SPTR_ICONQUESTION       Question-mark icon

   SPTR_ICONWARNING        Note icon

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────

   SPTR_MOVE               Move pointer

   SPTR_SIZENESW           Upward sloping double-headed arrow

   SPTR_SIZENS             Vertical double-headed arrow

   SPTR_SIZENWSE           Downward sloping double-headed arrow

   SPTR_SIZEWE             Horizontal double-headed arrow

   SPTR_TEXT               Text I-beam pointer

   SPTR_WAIT               Hourglass pointer
   ──────────────────────────────────────────────────────────────────────────


   fLoad  Specifies whether to copy the system pointer. If this parameter is
   TRUE, the system pointer is copied and the handle to the new pointer is
   returned. If it is FALSE, then the system pointer handle is returned. You
   should specify TRUE if you intend to modify an existing pointer.

 Return Value

   The return value is a pointer handle.

 Example

   This example calls WinQuerySysPointer to get a handle to the system
   pointer, and then loads an application-defined pointer. After it is done
   using the application-defined pointer, it restores it to the system
   pointer.

   /* get the system pointer */

   hptrDefault = WinQuerySysPointer(HWND_DESKTOP, SPTR_ARROW, FALSE);

   /* load an application-defined pointer */

   hptrCrossHair = WinLoadPointer(HWND_DESKTOP, NULL, IDP_CROSSHAIR);

   /* change the pointer to the application pointer */

   WinSetPointer(HWND_DESKTOP, hptrCrossHair);

   /* restore the system pointer */

   WinSetPointer(HWND_DESKTOP, hptrDefault);

 See Also

   WinQueryPointer, WinQueryPointerInfo


 ────────────────────────────────────────────────────────────────────────────
 WinQuerySystemAtomTable
 ────────────────────────────────────────────────────────────────────────────
   HATOMTBL WinQuerySystemAtomTable (VOID)

   The WinQuerySystemAtomTable function returns the handle of the system atom
   table. This allows two different applications to share an atom table.

 Parameters

   This function has no parameters.

 Return Value

   The return value is the handle of the system atom table.

 See Also

   WinCreateAtomTable


 ────────────────────────────────────────────────────────────────────────────
 WinQuerySysValue
 ────────────────────────────────────────────────────────────────────────────
   LONG WinQuerySysValue (hwndDesktop, iSysValue)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT iSysValue;        /*system value to retrieve                      */

   The WinQuerySysValue function retrieves a specified system value.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   iSysValue  Specifies the system value.

 Return Value

   The return value is the system value if the function was successful, or
   zero if an error occurred.

 Comments

   The following list describes the system values:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
   SV_CMOUSEBUTTONS    Specifies the number of mouse buttons: 1, 2, or 3.

   SV_MOUSEPRESENT     Specifies whether the mouse is present. A value of
                       TRUE means the mouse is present.

   SV_SWAPBUTTON       Specifies if the mouse buttons are swapped. TRUE if
                       mouse buttons are swapped.

   SV_CXDBLCLK         Specifies the mouse double click horizontal spacing.
                       The horizontal spatial requirement for considering two
                       mouse clicks a double click is met if the horizontal
                       distance between two mouse clicks is less than this
                       value.

   SV_CYDBLCLK         Specifies the mouse double click vertical spacing. The
                       vertical spatial requirement for considering two mouse
                       clicks a double click is met if the vertical distance
                       between two mouse clicks is less than this value.

   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_DBLCLKTIME       Specifies the mouse double click time in milliseconds.
                       The temporal requirement for considering two mouse
                       clicks a double click is met if the time between two
                       mouse clicks is less than this value.

   SV_CXSIZEBORDER     Specifies the count of pels along the x-axis in the
                       left and right parts of a window sizing border.

   SV_CYSIZEBORDER     Specifies the count of pels along the y-axis in the
                       top and bottom sections of a window sizing border.

   SV_ALARM            Specifies whether calls to WinAlarm generate a sound.
                       A value of TRUE means sound is generated.

   SV_CURSORRATE       Specifies the cursor blinking rate in milliseconds.
                       The blinking rate is the time that the cursor remains
                       visible or invisible. Twice this value is the length
                       of a complete cursor visible/invisible cycle.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      of a complete cursor visible/invisible cycle.

   SV_FIRSTSCROLLRATE  Specifies the delay (in milliseconds) until scroll bar
                       autorepeat activity begins when the mouse is held down
                       on a scroll bar arrow or within a scroll bar.

   SV_SCROLLRATE       Specifies the delay (in milliseconds) between scroll
                       bar autorepeat events.

   SV_NUMBEREDLISTS    Reserved.

   SV_ERRORFREQ        Specifies the frequency (in cycles per second) of a
                       WinAlarm WA_ERROR sound.

   SV_NOTEFREQ         Specifies the frequency (in cycles per second) of a
                       WinAlarm WA_NOTE sound.

   SV_WARNINGFREQ      Specifies the frequency (in cycles per second) of a
                       WinAlarm WA_WARNING sound.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      WinAlarm WA_WARNING sound.

   SV_ERRORDURATION    Specifies the duration (in milliseconds) of a WinAlarm
                       WA_ERROR sound.

   SV_NOTEDURATION     Specifies the duration (in milliseconds) of a WinAlarm
                       WA_NOTE sound.

   SV_WARNINGDURATION  Specifies the duration (in milliseconds) of a WinAlarm
                       WA_WARNING sound.

   SV_CXSCREEN         Specifies the count of pels along the screen's x-axis.

   SV_CYSCREEN         Specifies the count of pels along the screen's y-axis.

   SV_CXVSCROLL        Specifies the count of pels along the x-axis of a
                       vertical scroll bar.

   SV_CYHSCROLL        Specifies the count of pels along the y-axis of a
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_CYHSCROLL        Specifies the count of pels along the y-axis of a
                       horizontal scroll bar.

   SV_CXHSCROLLARROW   Specifies the count of pels along the x-axis of a
                       horizontal scroll bar arrow.

   SV_CYVSCROLLARROW   Specifies the count of pels along the y-axis of a
                       vertical scroll bar arrow.

   SV_CXBORDER         Specifies the count of pels along the x-axis of a
                       window border.

   SV_CYBORDER         Specifies the count of pels along the y-axis of a
                       window border.

   SV_CXDLGFRAME       Specifies the count of pels along the x-axis of a
                       dialog frame.

   SV_CYDLGFRAME       Specifies the count of pels along the y-axis of a
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_CYDLGFRAME       Specifies the count of pels along the y-axis of a
                       dialog frame.

   SV_CYTITLEBAR       Specifies the count of pels along the y-axis of a
                       title-bar window.

   SV_CXHSLIDER        Specifies the count of pels along the x-axis of a
                       horizontal scroll bar slider.

   SV_CYVSLIDER        Specifies the count of pels along the y-axis of a
                       vertical scroll bar slider.

   SV_CXMINMAXBUTTON   Specifies the width (in pels) of a minimize/ maximize
                       button.

   SV_CYMINMAXBUTTON   Specifies the height (in pels) of a minimize/ maximize
                       button.

   SV_CYMENU           Specifies the height (in pels) of an action-bar menu.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_CYMENU           Specifies the height (in pels) of an action-bar menu.

   SV_CXFULLSCREEN     Specifies the count of pels along the x-axis of a
                       maximized frame window's client window.

   SV_CYFULLSCREEN     Specifies the count of pels along the y-axis of a
                       maximized frame window's client window.

   SV_CXICON           Specifies the count of pels along an icon's x-axis.

   SV_CYICON           Specifies the count of pels along an icon's y-axis.

   SV_CXPOINTER        Specifies the count of pels along the mouse pointer's
                       x-axis.

   SV_CYPOINTER        Specifies the count of pels along the mouse pointer's
                       y-axis.

   SV_DEBUG            Reserved.
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_DEBUG            Reserved.

   SV_CURSORLEVEL      Specifies the cursor display count. The cursor is
                       visible only when the display count is zero.

   SV_POINTERLEVEL     Specifies the mouse pointer display count. The mouse
                       is visible only when the display count is zero.

   SV_TRACKRECTLEVEL   Specifies the tracking rectangle display count. The
                       tracking rectangle is visible only when the display
                       count is zero.

   SV_CTIMERS          Specifies the number of available timers.

   SV_CXBYTEALIGN      Set by a device driver at initialization time to
                       indicate any horizontal alignment that is more
                       efficient for the driver.

   SV_CYBYTEALIGN      Set by a device driver at initialization time to
   Value               Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_CYBYTEALIGN      Set by a device driver at initialization time to
                       indicate any vertical alignment that is more efficient
                       for the driver.

   SV_CSYSVALUES       Specifies the number of system values.
   ──────────────────────────────────────────────────────────────────────────


 See Also

   WinSetSysValue


 ────────────────────────────────────────────────────────────────────────────
 WinQueryTaskTitle
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryTaskTitle (idProcess, pszTitle, cbTitle)
   USHORT idProcess;       /*identifies the process                        */
   PSZ pszTitle;           /*address of the buffer                         */
   USHORT cbTitle;         /*length of the buffer                          */

   The WinQueryTaskTitle function obtains the title under which a specified
   application was started or added to the switch list. If this function is
   used after a switch-list entry is created for the application, the title
   in the switch-list entry is obtained.

   This function is useful when an application should use the same name in
   its window title and its entry in the switch list as the end-user invokes
   to start the application. This provides a visual link for the user.

 Parameters

   idProcess  Identifies the application whose title is requested.

   pszTitle  Points to the buffer to receive the title. The received string
   will be null-terminated.

   cbTitle  Specifies the length, in bytes, of the pszTitle buffer. If the
   retrieved title is longer then this length, it will be truncated.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   an error value.

 Comments

   The length of the title is guaranteed not to exceed MAXNAMEL bytes, plus
   one for the null-terminating character.

 See Also

   WinAddSwitchEntry


 ────────────────────────────────────────────────────────────────────────────
 WinQueryUpdateRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryUpdateRect (hwnd, prcl)
   HWND hwnd;              /*handle of the window                          */
   PRECTL prcl;            /*address of structure for update rectangle     */

   The WinQueryUpdateRect function retrieves the rectangle that bounds the
   update region of a specified window. This function, in conjunction with
   the WinValidateRect function, is useful for implementing an incremental
   update scheme as an alternative to the WinBeginPaint and WinEndPaint
   functions. You can use the returned update rectangle as the clip region
   for a presentation space so that drawing output can be clipped to the
   window's update region.

 Parameters

   hwnd  Identifies the window whose update rectangle is retrieved.

   prcl  Points to a RECTL structure that receives the coordinates of the
   rectangle bounding the window's update region. The RECTL structure has the
   following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinBeginPaint, WinEndPaint, WinQueryUpdateRegion, WinValidateRect


 ────────────────────────────────────────────────────────────────────────────
 WinQueryUpdateRegion
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryUpdateRegion (hwnd, hrgn)
   HWND hwnd;              /*handle of the window                          */
   HRGN hrgn;              /*handle of the region                          */

   The WinQueryUpdateRegion function obtains the update region of a window.
   This function, in conjunction with the WinValidateRegion function, is
   useful for implementing an alternative update scheme to the use of the
   WinBeginPaint and WinEndPaint functions. You can use the returned update
   region as the clip region for a presentation space so that drawing output
   can be clipped to the window's update region.

 Parameters

   hwnd  Identifies the window whose update region is to be retrieved.

   hrgn  Identifies the region that will receive the window's update region.

 Return Value

   The return value is the type of the region identified by the hrgn
   parameter, as defined by the GpiCombineRegion function.

 See Also

   GpiCombineRegion, WinBeginPaint, WinEndPaint, WinValidateRegion


 ────────────────────────────────────────────────────────────────────────────
 WinQueryVersion
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinQueryVersion (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinQueryVersion function returns the version and revision level of MS
   OS/2.

 Parameters

   hab  Identifies an anchor block.

 Return Value

   The return value is the version number, consisting of the major and minor
   version number and the revision character. The low word contains the minor
   version in the low byte and the major version in the high byte. The high
   word contains the revision character in the low byte. You can use the
   following macros to extract this information:

   Macro                       Result
   ──────────────────────────────────────────────────────────────────────────
   LOBYTE(LOUSHORT(return))    Retrieves the major version number.

   HIBYTE(LOUSHORT(return))    Retrieves the minor version number.

   LOUCHAR(HIUSHORT(return))   Retrieves the revision character.
   ──────────────────────────────────────────────────────────────────────────

 See Also

   DosGetVersion


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindow
 ────────────────────────────────────────────────────────────────────────────
   HWND WinQueryWindow (hwnd, cmd, fLock)
   HWND hwnd;              /*handle of the window                          */
   SHORT cmd;              /*which window to retrieve                      */
   BOOL fLock;             /*lock/unlock flag                              */

   The WinQueryWindow function retrieves the handle of a window that has a
   specified relationship to a specified window.

   If WinQueryWindow is used to enumerate windows of other threads, it is not
   guaranteed that all the windows are enumerated, because the z ordering of
   the windows may change during the enumeration. The WinGetNextWindow
   function must be used for this purpose.

 Parameters

   hwnd  Identifies a window. The window handle retrieved is relative to this
   window, based on the value in the cmd parameter.

   cmd  Specifies which window to retrieve. The following are the possible
   values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   QW_BOTTOM         Bottommost child window.

   QW_FRAMEOWNER     Returns the owner of hwnd, normalized so that it shares
                     the same parent as hwnd.

   QW_NEXT           Next window in z order (window below).

   QW_NEXTTOP        Next main window in the enumeration order defined for
                     the ALT+ESCAPE function of the user interface.

   QW_OWNER          Owner of window.

   QW_PARENT         Parent of window; HWND_OBJECT if object window.

   QW_PREV           Previous window in z order (window above).

   QW_PREVTOP        Previous main window, in the enumeration order defined
                     by QW_NEXTTOP.

   QW_TOP            Topmost child window.
   ──────────────────────────────────────────────────────────────────────────

   fLock  Specifies whether the retrieved window is to be locked or unlocked.
   If TRUE, the window is locked. If FALSE, it is not.

 Return Value

   The return value is the handle of the window related to the window
   identified by the hwnd parameter.

 Comments

   If the retrieved window is locked by this function, then you must at some
   point call the WinLockWindow function to unlock the window. The reason for
   locking the window is so that the window cannot be destroyed until you
   have finished using it.

 See Also

   WinGetNextWindow, WinLockWindow


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowDC
 ────────────────────────────────────────────────────────────────────────────
   HDC WinQueryWindowDC (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinQueryWindowDC function retrieves the device context created by a
   call to the WinOpenWindowDC function for the specified window.

 Parameters

   hwnd  Identifies the window that has the device context.

 Return Value

   The return value is the handle of the device context or NULL if an error
   occurred.

 See Also

   WinOpenWindowDC


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowLockCount
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryWindowLockCount (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinQueryWindowLockCount function returns a window's lock count. Since
   a window may be locked by another thread or process at any time, the value
   returned by this function may also change at any time.

 Parameters

   hwnd  Identifies the window whose lock count is being retrieved.

 Return Value

   The return value is the window lock count if the window is locked.
   Otherwise, it is zero, indicating that the window is not locked or that an
   error occurred.

 See Also

   WinLockWindow


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryWindowPos (hwnd, pswp)
   HWND hwnd;              /*handle of the window                          */
   PSWP pswp;              /*address of the structure for window           */
                           /*information                                   */

   The WinQueryWindowPos function retrieves a window's size and position.

 Parameters

   hwnd  Identifies the window to get the size and position of.

   pswp  Points to an SWP structure that receives the window's size and
   position. The SWP structure has the following form:

   typedef struct _SWP {
       USHORT fs;
       SHORT  cy;
       SHORT  cx;
       SHORT  y;
       SHORT  x;
       HWND   hwndInsertBehind;
       HWND   hwnd;
   } SWP;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinSetWindowPos


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowProcess
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryWindowProcess (hwnd, ppid, ptid)
   HWND hwnd;              /*handle of the window                          */
   PPID ppid;              /*address of variable for process identifier    */
   PTID ptid;              /*address of variable for thread identifier     */

   The WinQueryWindowProcess function obtains the process identifier and
   thread identifier of the thread that created a window.

 Parameters

   hwnd  Identifies the window.

   ppid  Specifies the process identifier of the thread that created the
   window. It can be NULL if you aren't interested in this value.

   ptid  Specifies the thread identifier of the thread that created the
   window. It can be NULL if you aren't interested in this value.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   DosGetPID


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowPtr
 ────────────────────────────────────────────────────────────────────────────
   PVOID WinQueryWindowPtr (hwnd, index)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index to the pointer                          */

   The WinQueryWindowPtr function retrieves a pointer value from a specified
   window's reserved memory.

   The window handle that is passed to this function can be the handle of a
   window with the same or a different message queue from the caller; that
   is, this function allows the caller to obtain data from windows belonging
   to other threads.

 Parameters

   hwnd  Identifies the window that contains the pointer to retrieve.

   index  Specifies the zero-based index of the pointer to retrieve. Valid
   values are in the range zero through the number of bytes of window data
   (for example, a value of 8 would be an index to the third pointer), or
   QWP_PFNWP to address the index of the window procedure.

 Return Value

   The return value is the specified ULONG value in the window's reserved
   memory.

 Comments

   The specified index is valid only if all the bytes referenced are within
   the reserved memory. For example, this function would fail if an index
   value of zero was specified and only two bytes had been reserved.

 See Also

   WinQueryWindowULong, WinSetWindowPtr


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinQueryWindowRect (hwnd, prcl)
   HWND hwnd;              /*handle of the window                          */
   PRECTL prcl;            /*address of structure for window coordinates   */

   The WinQueryWindowRect function retrieves the coordinates of a window.

 Parameters

   hwnd  Identifies the window whose coordinates are retrieved.

   prcl  Points to a RECTL structure that receives the window's coordinates.
   The xLeft and yBottom fields will be zero. The xRight and yTop fields will
   contain the width and height of the window. The RECTL structure has the
   following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Example

   This example calls WinQueryWindowRect to get the dimensions of the window,
   and then calls WinFillRect to fill the window.

   HPS hps;
   RECTL rcl;

   WinQueryWindowRect(hwnd, &rcl);       /* get window dimensions */
   WinFillRect(hps, &rcl, CLR_WHITE);    /* clear entire window   */

 See Also

   WinQueryWindowPos


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowText
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryWindowText (hwnd, cbBuf, pszBuf)
   HWND hwnd;              /*handle of the window                          */
   SHORT cbBuf;            /*length of the buffer                          */
   PSZ pszBuf;             /*address of the buffer                         */

   The WinQueryWindowText function copies window text into a buffer. If the
   window is a frame window, the title-bar window text is copied.

   If the window text is longer than (cbBuf - 1), only the first (cbBuf - 1)
   characters of window text are copied.

   This function sends a WM_QUERYWINDOWPARAMS message to the window
   identified by the hwnd parameter.

 Parameters

   hwnd  Identifies the window containing the text.

   cbBuf  Specifies the length of the buffer pointed to by the pszBuf
   parameter. If the text is larger then this value, it will be truncated.

   pszBuf  Points to a buffer the receives the window text.

 Return Value

   The return value is the length of the returned text.

 Comments

   You can determine the size of the window text ahead of time by calling the
   WinQueryWindowTextLength function.

 See Also

   WinQueryWindowTextLength


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowTextLength
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinQueryWindowTextLength (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinQueryWindowTextLength function retrieves the length of the window
   text, not including any null termination character.

   This function sends a WM_QUERYFRAMEINFO message to the window identified
   by the hwnd parameter.

 Parameters

   hwnd  Identifies the window containing the text.

 Return Value

   The return value is the length of the window text.

 See Also

   WinQueryWindowText


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowULong
 ────────────────────────────────────────────────────────────────────────────
   ULONG WinQueryWindowULong (hwnd, index)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index of value to retrieve                    */

   The WinQueryWindowULong function retrieves an unsigned long integer value
   at a specified offset into the reserved memory of a given window.

   The window handle that is passed to this function can be the handle of a
   window with the same or a different message queue from the caller; that
   is, this function allows the caller to obtain data from windows belonging
   to other threads.

 Parameters

   hwnd  Identifies the window to query.

   index  Specifies the zero-based index of the ULONG value to retrieve.
   Valid values are in the range zero through the number of bytes of window
   data (for example, a value of 8 would be an index to the third long
   integer), or any of the following QWL values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   QWL_HHEAP             Handle of the heap.

   QWL_HMQ               Handle of the message queue of the window.

   QWL_HWNDFOCUSSAVE     Handle of the window that last had the focus.

   QWL_STYLE             Window style.

   QWL_USER              ULONG value present in windows of the following
                         preregistered window classes:

                             WC_DIALOG
                             WC_FRAME
                             WC_LISTBOX
                             WC_BUTTON
                             WC_STATIC
                             WC_ENTRYFIELD
                             WC_SCROLLBAR
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                            WC_SCROLLBAR
                             WC_MENU

                         This value can be used to retrieve
                         application-specific data in controls.
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is the specified ULONG value in the window's reserved
   memory.

 Comments

   The specified index is valid only if all the bytes referenced are within
   the reserved memory. For example, this function would fail if an index
   value of zero was specified and only two bytes had been reserved.

 See Also

   WinQueryWindowUShort, WinRegisterClass, WinSetWindowULong


 ────────────────────────────────────────────────────────────────────────────
 WinQueryWindowUShort
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinQueryWindowUShort (hwnd, index)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index of value to retrieve                    */

   The WinQueryWindowUShort function retrieves an unsigned short integer
   value at a specified offset into the reserved memory of a given window.

   The window handle that is passed to this function can be the handle of a
   window with the same or a different message queue from the caller; that
   is, this function allows the caller to obtain data from windows belonging
   to other threads.

 Parameters

   hwnd  Identifies the window to query.

   index  Specifies the zero-based index of the USHORT value to retrieve.
   Valid values are in the range zero through the number of bytes of window
   data (for example, a value of 8 would be an index to the fifth integer),
   or any of the following QWS values:

   Value     Meaning
   ──────────────────────────────────────────────────────────────────────────
   QWS_ID    Window identifier (as passed by the WinCreateWindow function).

   QWS_USER  USHORT value present in windows of the following preregistered
             window classes:

                 WC_DIALOG
                 WC_FRAME
                 WC_LISTBOX
                 WC_BUTTON
                 WC_STATIC
                 WC_ENTRYFIELD
                 WC_SCROLLBAR
                 WC_MENU

             This value can be used to retrieve application-specific data in
             controls.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is the USHORT value in the window's reserved memory.

 See Also

   WinCreateWindow, WinQueryWindowULong, WinRegisterClass,
   WinSetWindowUShort


 ────────────────────────────────────────────────────────────────────────────
 WinReallocMem
 ────────────────────────────────────────────────────────────────────────────
   NPBYTE WinReallocMem (hHeap, npMem, cbOld, cbNew)
   HHEAP hHeap;            /*handle of the heap                            */
   NPBYTE npMem;           /*address of memory block to reallocate         */
   USHORT cbOld;           /*old memory block length                       */
   USHORT cbNew;           /*new memory block length                       */

   The WinReallocMem function reallocates the size of a memory block on the
   heap.

   The calling routine must specify both the old size of the memory object
   and the new size. If the new size is larger than the old size, then this
   function calls the WinAllocMem function to allocate the new, larger
   object, copies the number of bytes specified by the cbOld parameter from
   the old object to the new, frees the old object, and returns a pointer to
   the new object. (It never causes an object to grow in place.)

   If the passed heap is created with the HM_MOVEABLE option, then the value
   of the cbOld parameter is ignored and the value in the size word of the
   allocated object is used. On completion, the size word contains the value
   of the cbNew parameter. If this function has to move the object in order
   to satisfy the request, then the handle value word is updated by adding to
   it the distance of the move, in bytes. The returned address is then the
   address of the first reserved word.

 Parameters

   hHeap  Identifies the heap. This parameter must have been returned from a
   previous call to the WinCreateHeap function.

   npMem  Points to the memory block to be reallocated. The low two bits of
   npMem are ignored, although they are preserved in the return value of this
   function, even if the memory object is moved as a result of growing.
   Except for the two low bits, the value of the npMem parameter must have
   been returned by either the WinAllocMem function or a previous call to
   WinReallocMem.

   cbOld  Specifies the old size of the memory block, in bytes.

   cbNew  Specifies the new size of the memory block, in bytes.

 Return Value

   The return value is a pointer to the reallocated memory block if the
   function was successful. Otherwise, it is NULL, indicating that the memory
   could not be reallocated to the requested size.

   The return pointer is a 16-bit offset from the start of the segment
   containing the heap of the reallocated memory object. The function returns
   NULL when the memory object cannot be reallocated because an invalid heap
   handle is specified, there is not enough room in the heap to increase the
   object to the specified size, or the npMem parameter points to memory
   outside the bounds of the passed heap.

 See Also

   WinAllocMem, WinCreateHeap, WinFreeMem


 ────────────────────────────────────────────────────────────────────────────
 WinRegisterClass
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinRegisterClass (hab, pszClassName, pfnWndProc, flStyle,
   cbWindowData)
   HAB hab;                /*handle of the anchor block                    */
   PSZ pszClassName;       /*points to the class name                      */
   PFNWP pfnWndProc;       /*address of the window procedure               */
   ULONG flStyle;          /*window-style flags                            */
   USHORT cbWindowData;    /*amount of reserved data                       */

   The WinRegisterClass function registers a window class.

   When an application registers a private class with the window procedure in
   a dynamic-link library, it is the application's responsibility to resolve
   the window procedure address before issuing WinRegisterClass.

   Private classes are deleted when the process that registers them
   terminates.

 Parameters

   hab  Identifies the anchor block.

   pszClassName  Points to the window classname. It can either be an
   application-specified name or the name of one of the following
   preregistered classes:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Class             Description
   ──────────────────────────────────────────────────────────────────────────
   WC_BUTTON         A button control, including push buttons, radio buttons,
                     check boxes, and user buttons.

   WC_ENTRYFIELD     An entry-field control that allows single line-text
                     editing.

   WC_FRAME          A standard frame window.

   WC_LISTBOX        A list box that displays a scrolling list of items.

   WC_MENU           A menu, including the action bar and pull-down menus.

   WC_SCROLLBAR      A scroll bar that allows a user to scroll the contents
                     of a window.

   WC_STATIC         A static control that displays text, icon, or bitmap
                     data.
   Class             Description
   ──────────────────────────────────────────────────────────────────────────
                    data.

   WC_TITLEBAR       A title-bar control that displays the title of a window
                     across the top of the frame and also allows the user to
                     drag the frame window to a new location.
   ──────────────────────────────────────────────────────────────────────────


   pfnWndProc  Points to the window procedure, which can be NULL if the
   application does not provide its own window procedure.

   flStyle  Specifies the default window style, which can be any of the
   standard CS class styles, in addition to any class-specific styles that
   may be defined. These styles can be augmented when a window of this class
   is created. A public window class is created if the CS_PUBLIC style is
   specified; otherwise, a private class is created. Public classes are
   available for window creation from any process. Private classes are only
   available to the registering process.

   The following list describes the standard classes:

╓┌─┌───────────────────┌─────────────────────────────────────────────────────╖
   Style               Meaning
   ──────────────────────────────────────────────────────────────────────────
   CS_CLIPCHILDREN     Sets the WS_CLIPCHILDREN style for windows created
                       using this class.

   CS_CLIPSIBLINGS     Sets the WS_CLIPSIBLINGS style for windows created
                       using this class.

   CS_FRAME            Identifies windows created using this class as frame
                       windows. Frame windows receive the special
                       WM_FRAMEDESTROY message when they are being destroyed.

   CS_HITTEST          Directs the system to send WM_HITTEST messages to
                       windows of this class whenever the mouse moves in the
                       window.

   CS_MOVENOTIFY       Directs the system to send WM_MOVE messages to the
                       window whenever the window moves.
   Style               Meaning
   ──────────────────────────────────────────────────────────────────────────
                      window whenever the window moves.

   CS_PARENTCLIP       Sets the WS_PARENTCLIP style for windows created using
                       this class.

   CS_PUBLIC           Creates a public window class.

   CS_SAVEBITS         Sets the WS_SAVEBITS style for windows created using
                       this class.

   CS_SIZEREDRAW       Directs the system to invalidate the entire window
                       whenever the size of the window changes.

   CS_SYNCPAINT        Sets the WS_SYNCPAINT style for windows created using
                       this class.
   ──────────────────────────────────────────────────────────────────────────


   cbWindowData  Specifies the number of bytes of storage reserved per window
   created of this class for application use.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Example

   This example calls WinRegisterClass to register a class, return FALSE if
   an error occurs.

   HAB hab;
   CHAR szClassName[] = "Generic"; /* window class name      */

   if (!WinRegisterClass(hab,   /* anchor-block handle       */
           szClassName,         /* class name                */
           GenericWndProc,      /* window procedure          */
           0L,                  /* window style              */
           0))                  /* amount of reserved memory */
       return (FALSE);

 See Also

   WinQueryClassInfo, WinQueryClassName, WinQueryWindowPtr,
   WinQueryWindowULong, WinQueryWindowUShort


 ────────────────────────────────────────────────────────────────────────────
 WinRegisterWindowDestroy
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinRegisterWindowDestroy (hwnd, fRegister)
   HWND hwnd;              /*handle of the window                          */
   BOOL fRegister;         /*register flag                                 */

   The WinRegisterWindowDestroy function notifies other applications when the
   specified window is destroyed.

 Parameters

   hwnd  Identifies the window being destroyed.

   fRegister  Specifies whether the window is to be registered. If fRegister
   is TRUE, this function registers the window so that when it is destroyed,
   a WM_OTHERWINDOWDESTROYED message is broadcast to all main windows of
   other tasks. Registering the window is accomplished by incrementing a
   register count. If fRegister is FALSE, this routine unregisters the window
   by decreasing the register count by one, although the window is not fully
   unregistered until the count reaches zero.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinDestroyWindow


 ────────────────────────────────────────────────────────────────────────────
 WinReleaseHook
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinReleaseHook (hab, hmq, iHook, pfnHook, hmod)
   HAB hab;                /*handle of the anchor block                    */
   HMQ hmq;                /*handle of the message queue                   */
   SHORT iHook;            /*hook identifier                               */
   PFN pfnHook;            /*address of the hook procedure                 */
   HMODULE hmod;           /*handle of the module with hook procedure      */

   The WinReleaseHook function releases an application hook from a hook
   chain.

 Parameters

   hab  Identifies the anchor block.

   hmq  Specifies the message queue from which the hook is to be released. If
   hmq is NULL, the hook is released from the system hook chain. If hmq is
   HMQ_CURRENT, the hook is released from the message queue associated with
   the current thread (calling thread).

   iHook  Specifies the type of hook chain. This parameter can be one of the
   following values:

   Hook type             Description
   ──────────────────────────────────────────────────────────────────────────
   HK_HELP               Monitors the WM_HELP message.

   HK_INPUT              Monitors messages in a message queue.

   HK_JOURNALPLAYBACK    Allows applications to insert events into the system
                         input queue.

   HK_JOURNALRECORD      Allows applications to record system input queue
                         events.

   HK_MSGFILTER          Monitors input events during system modal loops.

   HK_SENDMSG            Monitors messages sent with WinSendMsg.
   ──────────────────────────────────────────────────────────────────────────

   pfnHook  Points to the hook routine.

   hmod  Identifies the module that contains the hook procedure. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If a system hook is called by a process other than the process that set
   the hook, the DLL containing the hook will not be unloaded until every
   process is exited that referenced it. For most system hooks, this applies
   until the machine is rebooted. For the most part, this is not a problem;
   as with swapping, the unused DLL will end up somewhere in your swap space,
   never to be used again. The only complication is that when you are
   developing the hook the DLL containing the hook is still in use, and you
   cannot copy over it or link into it.

 See Also

   DosLoadModule, WinSendMsg, WinSetHook


 ────────────────────────────────────────────────────────────────────────────
 WinReleasePS
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinReleasePS (hps)
   HPS hps;                /*handle of the presentation space              */

   The WinReleasePS function releases a cache presentation space obtained
   using the WinGetPS function.

   Only a cache presentation space should be released using this function.
   The presentation space is returned to the cache for reuse. The
   presentation space handle should not be used following this function.

 Parameters

   hps  Identifies the cache presentation space to release.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   Before an application terminates, it must call WinReleasePS to release any
   cache presentation spaces obtained by using the WinGetPS function.

 Example

   This example processes an application-defined message (IDM_FILL). It calls
   WinGetPS to get a presentation space to the entire window. It gets the
   dimensions of the current window, fills the window, and calls WinReleasePS
   to release the presentation space.

   case IDM_FILL:
       hps = WinGetPS(hwnd);           /* get ps for the entire window */
       WinQueryWindowRect(hwnd, &rcl);    /* get window dimensions     */
       WinFillRect(hps, &rcl, CLR_WHITE); /* clear entire window       */
       WinReleasePS(hps);                 /* release the ps            */

 See Also

   WinGetPS


 ────────────────────────────────────────────────────────────────────────────
 WinRemoveSwitchEntry
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinRemoveSwitchEntry (hSwitch)
   HSWITCH hSwitch;        /*handle of the switch list                     */

   The WinRemoveSwitchEntry function removes a specified entry from the
   switch list.

   Switch-list entries for full-screen applications cannot be removed using
   this function. These entries are removed automatically by the system when
   the application terminates.

 Parameters

   hSwitch  Identifies the switch-list entry for the application to remove.

 Return Value

   The return value is zero if the function is successful. Otherwise, it is
   nonzero, indicating that an error occurred.

 See Also

   WinAddSwitchEntry, WinChangeSwitchEntry


 ────────────────────────────────────────────────────────────────────────────
 WinScrollWindow
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinScrollWindow (hwnd, dx, dy, prclScroll, prclClip, hrgnUpdate,
   prclUpdate, fs)
   HWND hwnd;              /*handle of the window to scroll                */
   SHORT dx;               /*amount of horizontal scrolling                */
   SHORT dy;               /*amount of vertical scrolling                  */
   PRECTL prclScroll;      /*address of structure with scroll rectangle    */
   PRECTL prclClip;        /*address of structure with clip rectangle      */
   HRGN hrgnUpdate;        /*handle of the update region                   */
   PRECTL prclUpdate;      /*address of the structure for the update       */
                           /*rectangle                                     */
   USHORT fs;              /*scrolling flags                               */

   The WinScrollWindow function scrolls the contents of a window rectangle.

   No application should move bits in its own window by any other method than
   by using WinScrollWindow.

   The cursor and the track rectangle are also scrolled when they intersect
   with the scrolled region.

 Parameters

   hwnd  Identifies the window to scroll.

   dx  Specifies the amount of horizontal scrolling (in device units).

   dy  Specifies the amount of vertical scrolling (in device units).

   prclScroll  Points to a RECTL structure that specifies the scroll
   rectangle. If prclScroll is NULL, the entire window will be scrolled. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prclClip  Points to a RECTL structure that specifies the clip rectangle.
   This structure takes precedence over the prclScroll rectangle. Bits
   outside of the prclClip rectangle are not affected even if they are in
   prclScroll.

   hrgnUpdate  Identifies the region that is modified to hold the region
   invalidated by scrolling. This parameter may be NULL.

   prclUpdate  Points to a RECTL structure that receives the boundaries of
   the rectangle invalidated by scrolling. This parameter may be NULL.

   fs  Specifies flags controlling the scrolling. It can be a combination of
   the following values:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   SW_SCROLLCHILDREN All child windows are scrolled.

   SW_INVALIDATERGN  The invalid region created as a result of scrolling will
                     be added to update regions of those windows affected.
                     This may result in the sending of WM_PAINT messages to
                     WS_SYNCPAINT windows before the WinScrollWindow function
                     returns.
   ──────────────────────────────────────────────────────────────────────────

 Return Value

   The return value is a code indicating the type of invalid region created
   by scrolling:

   Value           Meaning
   ──────────────────────────────────────────────────────────────────────────
   ERROR           Error in the passed region.

   NULLREGION      Scrolling produced no invalidation.

   SIMPLEREGION    Scrolling produced rectangular invalidation.

   COMPLEXREGION   Scrolling produced a nonrectangular invalidation.
   ──────────────────────────────────────────────────────────────────────────

 Comments

   To quickly repeat scrolling, omit the SW_INVALIDATERGN flag from the fs
   parameter and accumulate the update area by specifying a region for the
   hrgnUpdate parameter or a rectangle for the prclUpdate parameter. When
   scrolling is completed, you can repaint the window by calling
   WinInvalidateRegion or WinInvalidateRect, depending on whether you
   specified the hrgnUpdate or prclUpdate parameter.

   Typically, an application will set the SW_INVALIDATERGN flag in fs and let
   the system handle the update regions of the affected windows. In this
   case, the hrgnUpdate and prclUpdate parameters can both be set to NULL.

   If the hwnd parameter does not have the WS_CLIPCHILDREN style, the bits of
   any child window falling inside the scrolled area will also be scrolled.
   If this is the case, WinScrollWindow should be called with
   SW_SCROLLCHILDREN.

   The cursor and tracking rectangle are always hidden if they are in the
   window being scrolled or a child of that window, and the cursor is always
   offset by the distance scrolled. The tracking rectangle's position is left
   alone. Both are then shown once scrolling is done.

 See Also

   GpiCombineRegion


 ────────────────────────────────────────────────────────────────────────────
 WinSendDlgItemMsg
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinSendDlgItemMsg (hwndDlg, idItem, msg, mp1, mp2)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*dialog-item identifier                        */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*first message parameter                       */
   MPARAM mp2;             /*second message parameter                      */

   The WinSendDlgItemMsg function sends a message to the specified dialog
   item in the dialog window. The function does not return until the message
   has been processed by the dialog item.

   This function is equivalent to the following:

   WinSendMsg(WinWindowFromID(hwndDlg, idItem), msg, mp1, mp2);

 Parameters

   hwndDlg  Identifies the dialog window.

   idItem  Identifies the dialog item that receives the message.

   msg  Specifies the message.

   mp1  Specifies message parameter 1.

   mp2  Specifies message parameter 2.

 Return Value

   The return value is the result returned by the dialog item to which the
   message was sent.

 See Also

   WinSendMsg, WinWindowFromID


 ────────────────────────────────────────────────────────────────────────────
 WinSendMsg
 ────────────────────────────────────────────────────────────────────────────
   MRESULT WinSendMsg (hwnd, msg, mp1, mp2)
   HWND hwnd;              /*handle of the receiving window                */
   USHORT msg;             /*message                                       */
   MPARAM mp1;             /*first message parameter                       */
   MPARAM mp2;             /*second message parameter                      */

   The WinSendMsg function sends a message to the specified window.

   This function does not return until the message has been processed by the
   window procedure. If the window receiving the message belongs to the same
   thread, the window function is called immediately as a subroutine. If the
   window is of another thread or process, Presentation Manager switches to
   the appropriate thread and calls the appropriate window function, passing
   the message to the window function. The message is not placed in the
   destination thread's queue.

 Parameters

   hwnd  Identifies the window to send the message to.

   msg  Specifies the message.

   mp1  Specifies message parameter 1.

   mp2  Specifies message parameter 2.

 Return Value

   The return value is the result returned by the invoked window procedure.

 Comments

   The WM_USER constant marks the beginning of values you can use for your
   own messages. For example, you might have a section of a header file that
   looks like this:

   #define WM_USERMSG00  (WM_USER + 0)
   #define WM_USERMSG01  (WM_USER + 1)
   #define WM_USERMSG02  (WM_USER + 2)
   #define WM_USERMSG03  (WM_USER + 3)

   The following lists some of the differences between WinPostMsg and
   WinSendMsg:

   ■  WinPostMsg returns immediately. WinSendMsg waits for the receiver to
      return.

   ■  A thread that does not have a message queue can still call WinPostMsg.
      It cannot call WinSendMsg.

   ■  Calling WinSendMsg to send a message to another thread is costly in
      terms of CPU time. This is not true of WinPostMsg.

 Example

   This example gets the window handle of the system menu and calls
   WinSendMsg to send a message to disable the Close menu item.

   HWND hwndSysMenu;

   hwndSysMenu = WinWindowFromID(hwndDlg, FID_SYSMENU);
   WinSendMsg(hwndSysMenu, MM_SETITEMATTR,
       MPFROM2SHORT(SC_CLOSE, TRUE),
       MPFROM2SHORT(MIA_DISABLED, MIA_DISABLED));

 See Also

   WinBroadcastMsg, WinPostMsg


 ────────────────────────────────────────────────────────────────────────────
 WinSetAccelTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetAccelTable (hab, haccel, hwndFrame)
   HAB hab;                /*handle of the anchor block                    */
   HACCEL haccel;          /*handle of the accelerator table               */
   HWND hwndFrame;         /*handle of the frame window                    */

   The WinSetAccelTable function sets the window or queue accelerator table.

 Parameters

   hab  Identifies the anchor block.

   haccel  Identifies the accelerator table. If haccel is NULL, the effect of
   this function is to remove any accelerator table in effect for the window
   or queue.

   hwndFrame  Identifies the frame window. If hwndFrame is NULL, the queue
   accelerator table is set. Otherwise, the window accelerator table is set,
   by sending the WM_SETACCELTABLE message to hwndFrame.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreateAccelTable, WinLoadAccelTable


 ────────────────────────────────────────────────────────────────────────────
 WinSetActiveWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetActiveWindow (hwndDesktop, hwnd)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwnd;              /*handle of the window to make active           */

   The WinSetActiveWindow function makes the frame window of hwnd the active
   window. It does this by finding the first frame window parent of hwnd,
   using hwnd if it is a frame window. It then finds the last window
   associated with this frame window that had the focus. Then the focus is
   set to this window that previously had the focus, using the function
   WinSetFocus. This sets the focus to this window and activates all frame
   windows that are parents of this window.

   The window handle of the window that receives the focus is stored in the
   frame window's reserved memory. This memory can be queried by using a
   QWL_HWNDFOCUSSAVE index with the WinQueryWindowULong function.

   If the active window is changing, the following events occur:

   ■  If the action of setting the active window results in a different
      window receiving the focus, the window that currently has the focus
      will receive a WM_SETFOCUS message indicating the loss of focus.

   ■  If the action of setting the active window results in a different
      window becoming active, a WM_ACTIVATE message is sent to the current
      active window, indicating a loss of the active status.

   ■  The new active window is established.

   ■  A WM_ACTIVATE message indicating the acquisition of active status is
      sent to the new window.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwnd  Identifies either a frame window or the child of a frame window. If
   it is a child, the parent frame window will become the active window.

 Return Value

   The return value is TRUE if the function is successful. Otherwise, it is
   FALSE, indicating that an error occurred.

 See Also

   WinQueryActiveWindow, WinQueryFocus, WinQueryWindowULong, WinSetFocus


 ────────────────────────────────────────────────────────────────────────────
 WinSetCapture
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetCapture (hwndDesktop, hwnd)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwnd;              /*handle of the window to receive all mouse     */
                           /*messages                                      */

   The WinSetCapture function sets the mouse capture to the specified window.
   With the mouse capture set to a window, all mouse input is directed to
   that window, regardless of whether the mouse is over that window. Only one
   window can have the mouse captured at a time.

   When the WinSetCapture function is called to release the mouse capture, a
   WM_MOUSEMOVE message is posted, regardless of whether the mouse pointer
   has actually moved.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwnd  Identifies the window that is to receive all mouse messages. This
   parameter can take the special value HWND_THREADCAPTURE to capture the
   mouse to the current thread rather than to a particular window. If hwnd is
   NULL, mouse capture is released.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs. If an application calls this function while the mouse is
   currently captured by a different window, the function will fail and
   return FALSE.

 See Also

   WinQueryCapture


 ────────────────────────────────────────────────────────────────────────────
 WinSetClipbrdData
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetClipbrdData (hab, ulData, fmt, fsFmtInfo)
   HAB hab;                /*handle of the anchor block                    */
   ULONG ulData;           /*data object                                   */
   USHORT fmt;             /*specifies the format                          */
   USHORT fsFmtInfo;       /*specifies the data type                       */

   The WinSetClipbrdData function puts data into the clipboard. Data of the
   specified format already in the clipboard is freed by this function.

 Parameters

   hab  Identifies an anchor block.

   ulData  Specifies the data object being put into the clipboard. If this
   parameter is NULL, a WM_RENDERFMT message is sent to the clipboard owner
   window, to render the format when the WinQueryClipbrdData function is
   called with the specified format. Once the data object has been put into
   the clipboard, the object it refers to (if given by a reference such as a
   selector or handle) is no longer accessible by the application. To access
   the data after it has been placed into the clipboard, use the
   WinQueryClipbrdData function.

   fmt  Specifies the format of the data object specified by the ulData
   parameter. The following list describes the standard clipboard formats:

╓┌─┌─────────────────┌───────────────────────────────────────────────────────╖
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   CF_BITMAP         The data is a bitmap. The CFI_HANDLE memory-model flag
                     must be set in the fsFmtInfo parameter.

   CF_DSPBITMAP      The data is a bitmap representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
                     CFI_HANDLE must be set in the fsFmtInfo parameter.
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    CFI_HANDLE must be set in the fsFmtInfo parameter.

   CF_METAFILE       The data is a metafile. The CFI_HANDLE memory-model flag
                     must be set in the fsFmtInfo parameter.

   CF_DSPMETAFILE    The data is a metafile representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
                     CFI_HANDLE must be set in the fsFmtInfo parameter.

   CF_TEXT           The data is an array of text characters, which may
                     include newline characters to mark line breaks. The null
                     character indicates the end of the text data. The
                     CFI_SELECTOR memory-model flag must be set in the
                     fsFmtInfo parameter.

   CF_DSPTEXT        The data is a textual representation of a private data
                     format. The clipboard viewer can use this format to
                     display a private format. The memory-model flag
   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
                    display a private format. The memory-model flag
                     CFI_SELECTOR must be set in the fsFmtInfo parameter.
   ──────────────────────────────────────────────────────────────────────────


   fsFmtInfo  Specifies the type of data specified by the ulData parameter.
   This consists of memory-model and usage flags, as follows:

   Memory-model flag  Meaning
   ──────────────────────────────────────────────────────────────────────────
   CFI_HANDLE         Handle is the handle to a metafile or bitmap.

   CFI_SELECTOR       Handle is a selector plus zero offset to a segment in
                      storage.
   ──────────────────────────────────────────────────────────────────────────

   Usage flag         Meaning
   ──────────────────────────────────────────────────────────────────────────
   CFI_OWNERDISPLAY   Format will be drawn by the clipboard owner in the
                      clipboard-viewer window by means of the
                      WM_PAINTCLIPBOARD message. The ulData parameter should
                      be NULL.

   CFI_OWNERFREE      Handle is not freed by the WinEmptyClipboard function.
                      The application must free the data, if necessary.
   ──────────────────────────────────────────────────────────────────────────

   Any number of the usage flags may be specified, but only one of the memory
   models may be specified. When using WinSetClipbrdData for user-defined
   formats, an application puts a user-defined format into the clipboard. It
   may then specify the CFI_SELECTOR memory model. The system then saves the
   selector so that if the calling application terminates, normally or
   abnormally, the data is still available. The system frees the selector
   from the calling process; therefore, the calling process may no longer use
   the selector.

 Return Value

   The return value is TRUE if data is placed in the clipboard, or FALSE if
   an error occurred.

 See Also

   WinEmptyClipbrd, WinQueryClipbrdData


 ────────────────────────────────────────────────────────────────────────────
 WinSetClipbrdOwner
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetClipbrdOwner (hab, hwnd)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of the clipboard owner                 */

   The WinSetClipbrdOwner function sets the current clipboard owner window.
   The clipboard owner window receives the following clipboard-related
   messages at appropriate times:

         WM_RENDERFMT
         WM_DESTROYCLIPBOARD
         WM_SIZECLIPBOARD
         WM_VSCROLLCLIPBOARD
         WM_HSCROLLCLIPBOARD
         WM_PAINTCLIPBOARD

 Parameters

   hab  Identifies an anchor block.

   hwnd  Identifies a new clipboard owner window. If this parameter is NULL,
   the clipboard owner is released and no new owner is established.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryClipbrdOwner, WinSetClipbrdViewer


 ────────────────────────────────────────────────────────────────────────────
 WinSetClipbrdViewer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetClipbrdViewer (hab, hwnd)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of the clipboard viewer                */

   The WinSetClipbrdViewer function sets the current clipboard-viewer window
   to a specified window.

   The clipboard-viewer window receives the WM_DRAWCLIPBOARD message when the
   contents of the clipboard change. This allows the viewer window to display
   an up-to-date version of the clipboard contents.

 Parameters

   hab  Identifies an anchor block.

   hwnd  Identifies a new clipboard viewer window. If this parameter is NULL,
   the clipboard viewer is released and no new viewer is established.

 Return Value

   The return value is TRUE if there is a clipboard-viewer window on
   completion of the function. Otherwise, it is FALSE, indicating that there
   is no clipboard-viewer window.

 See Also

   WinQueryClipbrdViewer, WinSetClipbrdOwner


 ────────────────────────────────────────────────────────────────────────────
 WinSetCp
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetCp (hmq, idcp)
   HMQ hmq;                /*handle of the message queue                   */
   USHORT idcp;            /*code page                                     */

   The WinSetCp function sets the queue code page for the message queue.

 Parameters

   hmq  Identifies a message queue.

   idcp  Specifies a code page. It must be one of the ASCII code pages
   defined in the config.sys file.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   DosSetCp, GpiSetCp, VioSetCp, WinQueryCp, WinQueryCpList


 ────────────────────────────────────────────────────────────────────────────
 WinSetDlgItemShort
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetDlgItemShort (hwndDlg, idItem, usValue, fSigned)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*dialog-item identifier                        */
   USHORT usValue;         /*value to set                                  */
   BOOL fSigned;           /*signed/unsigned flag                          */

   The WinSetDlgItemShort function sets the text of a dialog-box item to the
   string representation of a specified integer value. The item is identified
   by its identifier. The text produced is always an ASCII string.

 Parameters

   hwndDlg  Identifies the dialog-box window.

   idItem  Identifies the dialog item that is changed.

   usValue  Specifies the integer value used to generate the item text.

   fSigned  Specifies whether the usValue parameter is signed or unsigned. If
   this parameter is TRUE, usValue is signed. If it is FALSE, usValue is
   unsigned.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryDlgItemShort


 ────────────────────────────────────────────────────────────────────────────
 WinSetDlgItemText
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetDlgItemText (hwndDlg, idItem, pszText)
   HWND hwndDlg;           /*handle of the dialog box                      */
   USHORT idItem;          /*dialog-item identifier                        */
   PSZ pszText;            /*text to set                                   */

   The WinSetDlgItemText function sets the text in a dialog item. It is
   equivalent to the following:

   WinSetWindowText(WinWindowFromID(hwndDlg, idItem), pszText);

 Parameters

   hwndDlg  Identifies a dialog window.

   idItem  Identifies the identifier of the dialog item.

   pszText  Points to a null-terminated string that contains the text to be
   set for the dialog item.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinSetWindowText, WinWindowFromID


 ────────────────────────────────────────────────────────────────────────────
 WinSetFocus
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetFocus (hwndDesktop, hwndSetFocus)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwndSetFocus;      /*handle of the window receiving the focus      */

   The WinSetFocus function sets the focus window.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwndSetFocus  Identifies the window that receives the focus. This
   parameter must be equal to or be a descendant of the window identified by
   the hwndDesktop parameter. If hwndSetFocus identifies a desktop window or
   is NULL, no window on the device associated with hwndDesktop receives the
   focus.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If hwndSetFocus does not have the focus when this function is called, the
   following events occur:

   ■  If a window currently has the focus, it receives a WM_SETFOCUS message,
      indicating the loss of the focus.

   ■  If a window currently is selected, it receives a WM_SETSELECTION
      message, indicating the window is deselected.

   ■  If changing the focus causes a change in the active window, a
      WM_ACTIVATE message is sent to the active window, indicating the loss
      of active status.

   ■  If a new application is being made the active application, a
      WM_ACTIVATE message is sent to the active application, indicating the
      loss of active status.

   ■  The new active and focus windows and the active application are
      established.

   ■  If a new application is being made the active application, a
      WM_ACTIVATE message is sent to the new application, indicating the
      acquisition of active status.

   ■  If the active window is changing, a WM_ACTIVATE message is sent to the
      new main window, indicating the acquisition of active status.

   ■  If a new window is selected, it receives a WM_SETSELECTION message,
      indicating the window has been selected.

   ■  The new focus window is sent a WM_SETFOCUS message, indicating the
      acquisition of focus.

   Using the WinQueryActiveWindow or the WinQueryFocus function during
   processing of the WinSetFocus function results in the previous active and
   focus windows being returned until the new active and focus windows are
   established. In other words, even though a WM_SETFOCUS message with the
   fFocus parameter set to FALSE or a WM_ACTIVATE message with the fActive
   parameter set to FALSE may have been sent to the previous windows, those
   windows are considered to be active and have the focus until the system
   establishes the new active and focus windows.

   If WinSetFocus is called during WM_ACTIVATE message processing, a
   WM_SETFOCUS message with the fFocus parameter set to FALSE is not sent,
   since no window has the focus.

   If no window has the input focus, then WM_CHAR messages are posted to the
   active window's queue.

 Example

   This example retrieves an integer from a dialog entry field. It then
   checks for a valid number. If not found, it displays a message box
   indicating that an error occurred, and then calls WinSetFocus to set the
   focus back to the entry field that caused the error.

   fError = WinQueryDlgItemShort(hwndDlg, idEntryField, &ivalue, TRUE);
   if (fError || (ivalue < iLoRange) || (ivalue > iHiRange)) {
       WinMessageBox(HWND_DESKTOP, hwndFrame, (PSZ) szErrMsg,
           NULL, idMessageBox, MB_OK );
       WinSetFocus(HWND_DESKTOP, WinWindowFromID(hwndDlg, idEntryField));
   }
   else {

 See Also

   WinFocusChange, WinQueryActiveWindow, WinQueryFocus,
   WinSetActiveWindow


 ────────────────────────────────────────────────────────────────────────────
 WinSetHook
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetHook (hab, hmq, iHook, pfnHook, hmod)
   HAB hab;                /*handle of the anchor block                    */
   HMQ hmq;                /*handle of the message queue                   */
   SHORT iHook;            /*type of hook chain                            */
   PFN pfnHook;            /*address of the hook procedure                 */
   HMODULE hmod;           /*handle of the module with the hook procedure  */

   The WinSetHook function installs an application procedure into a specified
   hook chain. In this function, queue hooks are called before system hooks.

   A call to WinSetHook installs the hook at the head of either the system or
   queue chain. The most recently installed hook is called first.

 Parameters

   hab  Identifies an anchor block.

   hmq  Identifies the queue to which the hook chain belongs. If this param-
   eter is NULL, the hook is installed in the system hook chain. If it is
   HMQ_CURRENT, the hook is installed in the message queue associated with
   the current thread (calling thread).

   iHook  Specifies the type of hook chain. This parameter can be one of the
   following values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Hook type             Description
   ──────────────────────────────────────────────────────────────────────────
   Hook type             Description
   ──────────────────────────────────────────────────────────────────────────
   HK_HELP               Monitors the WM_HELP message. Returns BOOL. If
                         FALSE, next hook in chain is called. If TRUE, the
                         next hook in the chain is not called.

   HK_INPUT              Monitors messages in specified message queue.
                         Returns BOOL. If FALSE, next hook in the chain is
                         called. If TRUE, the message is not passed on to the
                         next hook in the chain.

   HK_JOURNALPLAYBACK    Allows applications to insert events into the system
                         input queue. Returns LONG time-out value. This value
                         is the time to wait (in milliseconds) before
                         processing the current message. Never calls the next
                         hook in the chain.

   HK_JOURNALRECORD      Allows applications to record system input queue
                         events. Returns VOID. Next hook in chain is always
                         called.

   Hook type             Description
   ──────────────────────────────────────────────────────────────────────────

   HK_MSGFILTER          Monitors input events during system modal loops.
                         Returns BOOL. If FALSE, next hook in the chain is
                         called. If TRUE, the message is not passed on to the
                         next hook in the chain.

   HK_SENDMSG            Monitors messages sent with WinSendMsg. Returns
                         VOID. Next hook in chain is always called.
   ──────────────────────────────────────────────────────────────────────────


   pfnHook  Points to an application hook procedure.

   hmod  Identifies the module that contains the hook procedure. This
   parameter can be either the module handle returned by the DosLoadModule
   function or NULL for the application's module.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   You should use the handle returned from WinCreateMsgQueue for the hmq
   parameter. If this is not available, you can use the WinQueryWindowULong
   function with the index QWL_HMQ to obtain the queue handle associated with
   a window handle.

   Note: If a system hook is installed, the procedure must be contained in a
   DLL; the procedure may be called from different applications, which do not
   have access to code segments that are contained in a .exe file.

 See Also

   DosLoadModule, WinCreateMsgQueue, WinQueryWindowULong, WinReleaseHook,
   WinSendMsg


 ────────────────────────────────────────────────────────────────────────────
 WinSetKeyboardStateTable
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetKeyboardStateTable (hwndDesktop, pKeyStateTable, fSet)
   HWND hwndDesktop;       /*handle of the desktop                         */
   PBYTE pKeyStateTable;   /*address of the key table                      */
   BOOL fSet;              /*set/copy flag                                 */

   The WinSetKeyboardStateTable function gets or sets the keyboard state.
   This function does not change the physical state of the keyboard; it
   changes the value returned by the WinGetKeyState function, not the value
   returned by the WinGetPhysKeyState function.

   To set the state of a single key you must get the entire table, modify the
   individual key, and then set the table from the modified value.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   pKeyStateTable  Points to a 256-byte table indexed by virtual-key value.
   For any virtual key, the 0x80 bit is set if the key is down and cleared if
   it is up. The 0x01 bit is set if the key is toggled (pressed an odd number
   of times) and cleared otherwise.

   fSet  Specifies whether the keyboard state is set or copied. If this
   parameter is TRUE, the keyboard state is set from pKeyStateTable. If this
   parameter is FALSE, the keyboard state is copied to pKeyStateTable.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinGetKeyState, WinGetPhysKeyState


 ────────────────────────────────────────────────────────────────────────────
 WinSetMultWindowPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetMultWindowPos (hab, pswp, cswp)
   HAB hab;                /*handle of the anchor block                    */
   PSWP pswp;              /*address of array of SWP structures            */
   USHORT cswp;            /*number of SWP structures                      */

   The WinSetMultWindowPos function performs the WinSetWindowPos function for
   specified windows using the pswp parameter, an array of structures whose
   elements correspond to the input parameters of WinSetWindowPos. All
   windows being positioned must have the same parent window.

   It is more efficient to use this function than to issue multiple
   WinSetWindowPos calls, as it causes less screen updating.

 Parameters

   hab  Identifies an anchor block.

   pswp  Points to an array of SWP data structures whose elements correspond
   to the input parameters of WinSetWindowPos. The SWP structure has the
   following form:

   typedef struct _SWP {
       USHORT fs;
       SHORT  cy;
       SHORT  cx;
       SHORT  y;
       SHORT  x;
       HWND   hwndInsertBehind;
       HWND   hwnd;
   } SWP;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   cswp  Specifies the number of SWP structures.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   This function sends the following messages. If you process these messages,
   you must be careful to not cause an infinite loop by calling the
   WinSetWindowPos or WinSetMultWindowPos functions.

         WM_ACTIVATE
         WM_ADJUSTWINDOWPOS
         WM_CALCVALIDRECTS
         WM_MOVE
         WM_SHOW
         WM_SIZE

 See Also

   WinSetWindowPos


 ────────────────────────────────────────────────────────────────────────────
 WinSetOwner
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetOwner (hwnd, hwndNewOwner)
   HWND hwnd;              /*handle of the window whose owner is changed   */
   HWND hwndNewOwner;      /*handle of the new owner window                */

   The WinSetOwner function changes the owner of a specified window. The
   owner window and the owned window must have been created by the same
   thread.

   The WinQueryWindow function can be used to obtain the handle of the owner
   window.

 Parameters

   hwnd  Identifies the window whose owner is changed.

   hwndNewOwner  Identifies the new owner window. If this parameter is NULL,
   the window's owner is set to NULL.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryWindow, WinSetParent


 ────────────────────────────────────────────────────────────────────────────
 WinSetParent
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetParent (hwnd, hwndNewParent, fRedraw)
   HWND hwnd;              /*handle of the window whose parent is changed  */
   HWND hwndNewParent;     /*handle of the new parent window               */
   BOOL fRedraw;           /*redraw flag                                   */

   The WinSetParent function sets the parent window for the window identified
   by the hwnd parameter to the window identified by the hwndNewParent
   parameter.

 Parameters

   hwnd  Identifies the window whose parent will be changed.

   hwndNewParent  Identifies the new parent window. If this parameter is a
   desktop-window handle or HWND_DESKTOP, the hwnd window becomes a main
   window. The new parent window cannot be a descendant of the hwnd window.
   If hwndNewParent is not equal to HWND_OBJECT, the windows identified by
   the hwndNewParent and hwnd parameters must both be descendants of the same
   desktop window.

   fRedraw  Specifies a redraw indicator. If this parameter is TRUE, any
   necessary redrawing of both the old parent and the new parent windows is
   performed (if the hwnd window is visible). If this parameter is FALSE, no
   redrawing of the old and new parent windows is performed. This avoids an
   extra device update when subsequent calls cause the windows to be redrawn.

 Return Value

   The return value is TRUE if the parent window is successfully changed.
   Otherwise, it is FALSE, indicating that the parent window was not
   successfully changed.

 See Also

   WinIsChild, WinSetOwner


 ────────────────────────────────────────────────────────────────────────────
 WinSetPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetPointer (hwndDesktop, hptrNew)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HPOINTER hptrNew;       /*handle of the pointer                         */

   The WinSetPointer function changes the mouse pointer.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hptrNew  Identifies the new pointer. If the hptrNew parameter is NULL, the
   pointer is removed from the screen.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If you process the WM_MOUSEMOVE message, and you don't call the
   WinDefWindowProc function as part of that processing, then you should call
   this function to set the mouse pointer. This function is quite fast if the
   mouse pointer is not changed.

   The following functions can be used to obtain a handle to a pointer that
   can be used as the mouse pointer:

   Function             Description
   ──────────────────────────────────────────────────────────────────────────
   WinCreatePointer     Creates a pointer from a bitmap.

   WinQueryPointer      Retrieves a handle for the desktop pointer.

   WinLoadPointer       Loads a pointer from a resource file or dynamic-link
                        module.

   WinQuerySysPointer   Retrieves a handle for one of the system pointers.
   ──────────────────────────────────────────────────────────────────────────

 Example

   This example calls WinLoadPointer to load an application-defined pointer.
   When processing the WM_MOUSEMOVE message, the loaded pointer is displayed
   by calling WinSetPointer.

   case WM_CREATE:
       hptrCrossHair = WinLoadPointer(HWND_DESKTOP,
           NULL,              /* load from .exe file    */
           IDP_CROSSHAIR);    /* identifies the pointer */

   case WM_MOUSEMOVE:
       WinSetPointer(HWND_DESKTOP, hptrCrossHair);

 See Also

   WinCreatePointer, WinDefWindowProc, WinLoadPointer, WinQueryPointer,
   WinQuerySysPointer


 ────────────────────────────────────────────────────────────────────────────
 WinSetPointerPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetPointerPos (hwndDesktop, x, y)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT x;                /*horizontal position                           */
   SHORT y;                /*vertical position                             */

   The WinSetPointerPos function sets the mouse pointer position.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   x  Specifies the x position of the pointer (in screen coordinates).

   y  Specifies the y position of the pointer (in screen coordinates).

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryPointerPos


 ────────────────────────────────────────────────────────────────────────────
 WinSetRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetRect (hab, prcl, xLeft, yBottom, xRight, yTop)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of structure with rectangle to set    */
   SHORT xLeft;            /*left side                                     */
   SHORT yBottom;          /*bottom side                                   */
   SHORT xRight;           /*right side                                    */
   SHORT yTop;             /*top side                                      */

   The WinSetRect function sets rectangle coordinates. This function is
   equivalent to assigning the left, top, right, and bottom arguments to the
   appropriate fields of the RECTL structure. The coordinates of the
   rectangle are sign-extended before being placed into the RECTL structure.

 Parameters

   hab  Identifies an anchor block.

   prcl  Points to a RECTL structure that contains the rectangle to be set.
   The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   xLeft  Specifies the left edge of the rectangle.

   yBottom  Specifies the bottom edge of the rectangle.

   xRight  Specifies the right edge of the rectangle.

   yTop  Specifies the top edge of the rectangle.

 Return Value

   The return value is always TRUE.

 See Also

   WinSetRectEmpty


 ────────────────────────────────────────────────────────────────────────────
 WinSetRectEmpty
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetRectEmpty (hab, prcl)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prcl;            /*address of structure with rectangle to set    */
                           /*to empty                                      */

   The WinSetRectEmpty function sets a rectangle to empty. This function is
   equivalent to WinSetRect(hab, prcl, 0, 0, 0, 0).

 Parameters

   hab  Identifies an anchor block.

   prcl  Points to a RECTL structure that contains the rectangle to be set to
   empty. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is always TRUE.

 See Also

   WinCopyRect, WinSetRect


 ────────────────────────────────────────────────────────────────────────────
 WinSetSysColors
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetSysColors (hwndDesktop, flOptions, flFormat, clrFirst, cclr,
   pclr)
   HWND hwndDesktop;       /*handle of the desktop                         */
   ULONG flOptions;        /*color options                                 */
   ULONG flFormat;         /*format options                                */
   COLOR clrFirst;         /*first color to set                            */
   ULONG cclr;             /*number of colors to set                       */
   PCOLOR pclr;            /*address of color definitions                  */

   The WinSetSysColors function sets system color values. This function sends
   a WM_SYSCOLORCHANGE message to all main windows in the system to indicate
   that the colors have changed. When this message is received, applications
   that depend on the system colors can query the new color values by using
   the WinQuerySysColor function.

   After the WM_SYSCOLORCHANGE messages are sent, all windows in the system
   are invalidated so that they will be redrawn with the new system colors.

   WinSetSysColors does not write any system color changes to the os2.ini
   file.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   flOptions  Specifies the following options:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LCOL_PURECOLOR    Indicates that color dithering should not be used to
                     create colors not available in the physical palette. If
                     this option is set, only pure colors will be used and no
                     dithering will be done.

   LCOL_RESET        Indicates that the system colors are all to be reset to
                     default before processing the remainder of the data in
                     this function.
   ──────────────────────────────────────────────────────────────────────────

   flFormat  Specifies the format of entries in the table, as follows:

   Value             Meaning
   ──────────────────────────────────────────────────────────────────────────
   LCOLF_CONSECRGB   Array of RGB values that correspond to color indexes.
                     Each entry is 4 bytes.

   LCOLF_INDRGB      Array of (index, RGB) values. Each pair of entries is 8
                     bytes──4 bytes index and 4 bytes color value.
   ──────────────────────────────────────────────────────────────────────────

   clrFirst  Specifies the starting system color index (this parameter is
   only relevant for the LCOLF_CONSECRGB format). The following system color
   indexes are defined (each successive index is one larger than its
   predecessor):

╓┌─┌──────────────────────────┌──────────────────────────────────────────────╖
   Value                      Meaning
   ──────────────────────────────────────────────────────────────────────────
   SYSCLR_ACTIVEBORDER        Border fill of active window

   SYSCLR_ACTIVETITLE         Title bar of active window

   SYSCLR_APPWORKSPACE        Background of certain main windows

   SYSCLR_BACKGROUND          Screen background

   SYSCLR_HELPBACKGROUND      Background of help panels
   Value                      Meaning
   ──────────────────────────────────────────────────────────────────────────
  SYSCLR_HELPBACKGROUND      Background of help panels

   SYSCLR_HELPHILITE          Highlight of help text

   SYSCLR_HELPTEXT            Help text

   SYSCLR_INACTIVEBORDER      Border fill of inactive window

   SYSCLR_INACTIVETITLE       Title bar of inactive window

   SYSCLR_MENU                Menu background

   SYSCLR_MENUTEXT            Menu text

   SYSCLR_SCROLLBAR           Scroll bar

   SYSCLR_TITLETEXT           Title text

   SYSCLR_WINDOW              Window background
   Value                      Meaning
   ──────────────────────────────────────────────────────────────────────────
  SYSCLR_WINDOW              Window background

   SYSCLR_WINDOWFRAME         Window border line

   SYSCLR_WINDOWSTATICTEXT    Static text

   SYSCLR_WINDOWTEXT          Window text
   ──────────────────────────────────────────────────────────────────────────


   cclr  Specifies the number of elements supplied in pclr. This parameter
   may be zero if, for example, the color table is merely to be reset to the
   default. For LCOLF_INDRGB, this parameter must be an even number. The
   constant SYSCLR_CSYSCOLORS is set to the total number of system colors.

   pclr  Specifies the start address of the application data area containing
   the color-table definition data. The format depends on the value of the
   flFormat parameter. Each color value is a 4-byte integer. The low byte is
   the blue intensity value (0x000000FF), the second byte is the green
   intensity value (0x0000FF00), and the third byte is the red intensity
   value (0x00FF0000). The intensity for each color may range between 0 and
   255.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQuerySysColor


 ────────────────────────────────────────────────────────────────────────────
 WinSetSysModalWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetSysModalWindow (hwndDesktop, hwnd)
   HWND hwndDesktop;       /*handle of the desktop                         */
   HWND hwnd;              /*handle of the window that becomes system      */
                           /*modal                                         */

   The WinSetSysModalWindow function makes a window the system modal window
   or ends the system modal state.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   hwnd  Identifies the window that is to become the system modal window. If
   this parameter is NULL, the system modal state terminates and input
   processing returns to its normal state.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   Input processing can enter a system modal state. In this state, all mouse
   and keyboard input is directed to a special main window, called the system
   modal window, or to one of its child windows. All other main windows act
   as if they are disabled and no interaction is possible with them.

   The disabled windows are not actually disabled but rather made
   noninteractive. No messages are sent to these windows when the system
   modal state is entered or left, and their WS_DISABLE style bits are not
   changed.

   Where a system modal window exists and another window is explicitly made
   the active window, the newly activated window becomes the system modal
   window, replacing the previous system modal window, which then becomes a
   noninteractive window. When the system modal window is destroyed, the
   window activated as a result becomes the system modal window.

   This function should be called only while processing keyboard or mouse
   input.

   The new system modal window is not locked during the processing of this
   function.

 See Also

   WinQuerySysModalWindow


 ────────────────────────────────────────────────────────────────────────────
 WinSetSysValue
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetSysValue (hwndDesktop, iSysValue, lValue)
   HWND hwndDesktop;       /*handle of the desktop                         */
   SHORT iSysValue;        /*system value to change                        */
   LONG lValue;            /*new system value                              */

   The WinSetSysValue function sets the system value.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   iSysValue  Specifies the system value. This parameter must be a valid SV
   value. For a complete list of possible system values, see the following
   "Comments" section.

   lValue  Specifies the system value. Durations are in milliseconds.
   Frequencies are in hertz, with values between 25H and 7FFFH being valid.

 Return Value

   The return value is TRUE if the system value is successfully set.
   Otherwise, it is FALSE, indicating that an error occurred.

 Comments

   The following list describes the system values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   SV_CMOUSEBUTTONS      Specifies the number of mouse buttons: 1, 2, or 3.

   SV_MOUSEPRESENT       Specifies whether the mouse is present. A value of
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_MOUSEPRESENT       Specifies whether the mouse is present. A value of
                         TRUE means the mouse is present.

   SV_SWAPBUTTON         Specifies if the mouse buttons are swapped. TRUE if
                         mouse buttons are swapped.

   SV_CXDBLCLK           Specifies the mouse double click horizontal spacing.
                         The horizontal spatial requirement for considering
                         two mouse clicks a double click is met if the
                         horizontal distance between two mouse clicks is less
                         than this value.

   SV_CYDBLCLK           Specifies the mouse double click vertical spacing.
                         The vertical spatial requirement for considering two
                         mouse clicks a double click is met if the vertical
                         distance between two mouse clicks is less than this
                         value.

   SV_DBLCLKTIME         Specifies the mouse double click time in
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_DBLCLKTIME         Specifies the mouse double click time in
                         milliseconds. The temporal requirement for
                         considering two mouse clicks a double click is met
                         if the time between two mouse clicks is less than
                         this value.

   SV_CXSIZEBORDER       Specifies the count of pels along the x-axis in the
                         left and right parts of a window sizing border.

   SV_CYSIZEBORDER       Specifies the count of pels along the y-axis in the
                         top and bottom sections of a window sizing border.

   SV_ALARM              Specifies whether calls to WinAlarm generate a
                         sound. A value of TRUE means sound is generated.

   SV_CURSORRATE         Specifies the cursor blinking rate in milliseconds.
                         The blinking rate is the time that the cursor
                         remains visible or invisible. Twice this value is
                         the length of a complete cursor visible/invisible
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        the length of a complete cursor visible/invisible
                         cycle.

   SV_FIRSTSCROLLRATE    Specifies the delay (in milliseconds) until scroll
                         bar autorepeat activity begins when the mouse is
                         held down on a scroll bar arrow or within a scroll
                         bar.

   SV_SCROLLRATE         Specifies the delay (in milliseconds) between scroll
                         bar autorepeat events.

   SV_NUMBEREDLISTS      Reserved.

   SV_ERRORFREQ          Specifies the frequency (in cycles per second) of a
                         WinAlarm WA_ERROR sound.

   SV_NOTEFREQ           Specifies the frequency (in cycles per second) of a
                         WinAlarm WA_NOTE sound.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_WARNINGFREQ        Specifies the frequency (in cycles per second) of a
                         WinAlarm WA_WARNING sound.

   SV_ERRORDURATION      Specifies the duration (in milliseconds) of a
                         WinAlarm WA_ERROR sound.

   SV_NOTEDURATION       Specifies the duration (in milliseconds) of a
                         WinAlarm WA_NOTE sound.

   SV_WARNINGDURATION    Specifies the duration (in milliseconds) of a
                         WinAlarm WA_WARNING sound.

   SV_CXSCREEN           Specifies the count of pels along the screen's
                         x-axis.

   SV_CYSCREEN           Specifies the count of pels along the screen's
                         y-axis.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_CXVSCROLL          Specifies the count of pels along the x-axis of a
                         vertical scroll bar.

   SV_CYHSCROLL          Specifies the count of pels along the y-axis of a
                         horizontal scroll bar.

   SV_CXHSCROLLARROW     Specifies the count of pels along the x-axis of a
                         horizontal scroll bar arrow.

   SV_CYVSCROLLARROW     Specifies the count of pels along the y-axis of a
                         vertical scroll bar arrow.

   SV_CXBORDER           Specifies the count of pels along the x-axis of a
                         window border.

   SV_CYBORDER           Specifies the count of pels along the y-axis of a
                         window border.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_CXDLGFRAME         Specifies the count of pels along the x-axis of a
                         dialog frame.

   SV_CYDLGFRAME         Specifies the count of pels along the y-axis of a
                         dialog frame.

   SV_CYTITLEBAR         Specifies the count of pels along the y-axis of a
                         title bar window.

   SV_CXHSLIDER          Specifies the count of pels along the x-axis of a
                         horizontal scroll bar slider.

   SV_CYVSLIDER          Specifies the count of pels along the y-axis of a
                         vertical scroll bar slider.

   SV_CXMINMAXBUTTON     Specifies the width (in pels) of a minimize/
                         maximize button.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_CYMINMAXBUTTON     Specifies the height (in pels) of a minimize/
                         maximize button.

   SV_CYMENU             Specifies the height (in pels) of a menu.

   SV_CXFULLSCREEN       Specifies the count of pels along the x-axis of a
                         maximized frame window's client window.

   SV_CYFULLSCREEN       Specifies the count of pels along the y-axis of a
                         maximized frame window's client window.

   SV_CXICON             Specifies the count of pels along an icon's x-axis.

   SV_CYICON             Specifies the count of pels along an icon's y-axis.

   SV_CXPOINTER          Specifies the count of pels along the mouse
                         pointer's x-axis.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   SV_CYPOINTER          Specifies the count of pels along the mouse
                         pointer's y-axis.

   SV_DEBUG              Reserved.

   SV_CURSORLEVEL        Specifies the cursor display count. The cursor is
                         visible only when the display count is zero.

   SV_POINTERLEVEL       Specifies the mouse pointer display count. The mouse
                         is visible only when the display count is zero.

   SV_TRACKRECTLEVEL     Specifies the tracking rectangle display count. The
                         tracking rectangle is visible only when the display
                         count is zero.

   SV_CTIMERS            Specifies the number of available timers.

   SV_CXBYTEALIGN        Set by a device driver at initialization time to
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
  SV_CXBYTEALIGN        Set by a device driver at initialization time to
                         indicate any horizontal alignment that is more
                         efficient for the driver.

   SV_CYBYTEALIGN        Set by a device driver at initialization time to
                         indicate any vertical alignment that is more
                         efficient for the driver.

   SV_CSYSVALUES         Specifies the number of system values.
   ──────────────────────────────────────────────────────────────────────────


 See Also

   WinQuerySysValue


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowBits
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowBits (hwnd, index, flData, flMask)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index of the bits                             */
   ULONG flData;           /*data to set                                   */
   ULONG flMask;           /*mask of bits to set                           */

   The WinSetWindowBits function sets particular bits in the reserved memory
   of a window.

 Parameters

   hwnd  Identifies the window whose reserved memory is to be changed.

   index  Specifies the zero-based index of the ULONG value to set. Valid
   values are in the range zero through the number of bytes of window data
   (for example, a value of 8 would be an index to the third long integer),
   or any of the QWL values described in the WinSetWindowULong function.

   flData  Specifies the data to be written into the window's reserved
   memory.

   flMask  Specifies a mask value. The mask contains 1 where data is to be
   written and 0 where the data is to be unchanged.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinSetWindowULong


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowPos
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowPos (hwnd, hwndInsertBehind, x, y, cx, cy, fs)
   HWND hwnd;              /*handle of the window being set                */
   HWND hwndInsertBehind;  /*placement-order handle                        */
   SHORT x;                /*horizontal position                           */
   SHORT y;                /*vertical position                             */
   SHORT cx;               /*width                                         */
   SHORT cy;               /*height                                        */
   USHORT fs;              /*window-positioning flags                      */

   The WinSetWindowPos function sets the position of a window.

 Parameters

   hwnd  Identifies the window whose position is being set.

   hwndInsertBehind  Identifies relative window-placement order. This
   parameter is ignored if the fs parameter's SWP_ZORDER option is not
   selected. Values that can be specified are as follows:

   Value        Meaning
   ──────────────────────────────────────────────────────────────────────────
   HWND_BOTTOM  Places the hwnd window behind all sibling windows.

   HWND_TOP     Places the hwnd window on top of all sibling windows.

   Other        Identifies the sibling window behind which the hwnd window is
                to be placed.
   ──────────────────────────────────────────────────────────────────────────

   x  Specifies the x position of the hwnd window in window coordinates
   relative to the lower-left corner of its parent window. This parameter is
   ignored if the fs parameter's SWP_MOVE option is not selected.

   y  Specifies the y position of the hwnd window in window coordinates
   relative to the lower-left corner of its parent window. This parameter is
   ignored if the fs parameter's SWP_MOVE option is not selected.

   cx  Specifies the horizontal window size (in device units). This parameter
   is ignored if the fs parameter's SWP_SIZE option is not selected.

   cy  Specifies the vertical window size (in device units). This parameter
   is ignored if the fs parameter's SWP_SIZE option is not selected.

   fs  Identifies the window-positioning options. One or more of the
   following options can be specified:

╓┌─┌───────────────────────┌─────────────────────────────────────────────────╖
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
   SWP_ACTIVATE            Causes the window to be activated and the focus to
                           be set to the window that lost the focus the last
                           time the frame window was deactivated. The
                           activated window may not become the top window if
                           it owns other frame windows.

   SWP_DEACTIVATE          Deactivate the window, if it is the active window.

   SWP_EXTSTATECHANGE      This flag is for application use. It is used to
                           pass an additional flag to the portion of code
                           that is handling messages.

   SWP_FOCUSACTIVATE       Specifies that a frame window is receiving the
                           focus. This flag is set so that an application
                           that is processing the WM_ADJUSTWINDOWPOS message
                           can tell if the message was sent as the result of
                           a focus change.

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────

   SWP_FOCUSDEACTIVATE     Specifies that a frame window is losing the focus.

   SWP_HIDE                Specifies that the window is to be hidden when
                           created.

   SWP_MAXIMIZE            With SWP_MINIMIZE, causes a window to be
                           minimized, maximized, or restored. SWP_MAXIMIZE
                           and SWP_MINIMIZE are mutually exclusive. If either
                           SWP_MINIMIZE or SWP_MAXIMIZE is specified, then
                           both SWP_MOVE and SWP_SIZE must also be specified.
                           WinSetWindowPos and WinSetMultWindowPos depend on
                           the previous state of the window; these flags
                           cause the appropriate state to be toggled, as
                           follows: the x, y, cx, and cy parameters specify
                           the size and position to which the window will be
                           restored if it is subsequently restored. This
                           should be the normal size of the window.

   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────

   SWP_MINIMIZE            See SWP_MAXIMIZE.

   SWP_MOVE                Change the window x,y position.

   SWP_NOADJUST            Do not send a WM_ADJUSTWINDOWPOS message to the
                           window while processing (in other words, don't
                           give the window a chance to readjust itself).

   SWP_NOREDRAW            Do not redraw changes.

   SWP_RESTORE             Restore a minimized or maximized window.

   SWP_SHOW                Specifies that the window is to be shown when
                           created.

   SWP_SIZE                Change the window size.

   SWP_ZORDER              Change the relative window placement.
   Value                   Meaning
   ──────────────────────────────────────────────────────────────────────────
  SWP_ZORDER              Change the relative window placement.
   ──────────────────────────────────────────────────────────────────────────


 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If a window created with the CS_SAVEBITS style is moved, reduced in size,
   or hidden, the saved screen image is used to redraw the area uncovered
   when the window size changes, if those bits are still valid.

   If the CS_SIZEREDRAW style is present, the entire window area is assumed
   invalid if sized. Otherwise, a WM_CALCVALIDRECTS message is sent to the
   window to inform the window manager which bits it may be possible to
   preserve.

   Messages sent from WinSetWindowPos and WinSetMultWindowPos have specific
   orders within the window positioning process. The process begins with
   redundancy checks and precalculations on every window for each requested
   operation. For example, if SWP_SHOW is present but the window is already
   visible, then SWP_SHOW is turned off. If SWP_SIZE is present and the new
   size is equal to the previous size, SWP_SIZE is turned off. If the
   operations will create new results, the information is calculated and
   stored. For example, if being sized or moved, the new window rectangle is
   stored for later use. It is at this point that the WM_ADJUSTWINDOWPOS
   message is sent to any window that is being sized or moved. It is also at
   this point that the WM_CALCVALIDRECTS message is sent to any window that
   is being sized and does not have the CS_SIZEREDRAW window style.

   When the new window state is calculated, the window-management process
   begins. Window areas that can be preserved are moved from the old to the
   new positions, window areas that are invalidated by these operations are
   calculated and distributed as update regions, and so forth. When this is
   finished, and before any synchronous-paint windows are repainted, the
   WM_SIZE message is sent to any windows that have changed size. Next, all
   the synchronous-paint windows that can be repainted are repainted and the
   entire process is complete.

   If a synchronous-paint parent window has a size-sensitive area displayed
   that includes synchronous-paint child windows, the parent window will
   reposition those windows when it receives the WM_SIZE message. Their
   invalid regions will be added to the parent window's invalid region,
   resulting in one update after the parent window's WM_SIZE message, rather
   than many independent and subsequently duplicated updates.

   The following messages are sent by this function:

   Value                  Meaning
   ──────────────────────────────────────────────────────────────────────────
   WM_CALCVALIDRECTS      Sent to determine the area of a window that it may
                          be possible to preserve as the window is sized.

   WM_SIZE                Sent if the size of the window has changed, after
                          the change has been effected.

   WM_MOVE                Sent when a window with CS_MOVENOTIFY class style
                          moves its absolute position.

   WM_ACTIVATE            Sent if a different window becomes the active
                          window. For more information, see the
                          WinSetActiveWindow function.

   WM_ADJUSTWINDOWPOS     Sent if SWP_NOADJUST is not specified. The
                          message's mp1 parameter points to an SWP structure
                          that has been filled in by the WinSetWindowPos
                          function with the proposed move/size data. The
                          window can adjust this new position by changing the
                          contents of the SWP structure.
   ──────────────────────────────────────────────────────────────────────────

 Example

   This example gets the dimensions of the desktop window, and calls
   WinSetWindowPos to place the application's frame window in the upper left
   corner. By positioning the window relative to the desktop window, the
   window position is device-independent; it will work on any display adapter
   now matter what the vertical and horizontal resolution is.

   RECTL rcl;

   WinQueryWindowRect(HWND_DESKTOP, &rcl);
   WinSetWindowPos(hwndFrame, HWND_TOP,
       rcl.xLeft,                                      /* x pos  */
       rcl.yTop - 60,                                  /* y pos  */
       140,                                            /* x size */
       60,                                             /* y size */
       SWP_ACTIVATE | SWP_MOVE | SWP_SIZE | SWP_SHOW); /* flags  */

 See Also

   WinSetActiveWindow, WinSetMultWindowPos


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowPtr
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowPtr (hwnd, index, p)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index of the reserved memory                  */
   PVOID p;                /*pointer to place into reserved memory         */

   The WinSetWindowPtr function places a pointer value into the reserved
   memory of a window.

 Parameters

   hwnd  Identifies the window whose reserved memory will be changed.

   index  Specifies the zero-based index of the pointer value to set. Valid
   values are in the range zero through the number of bytes of window data
   (for example, a value of 8 would be an index to the third pointer). The
   value QWP_PFNWP can be used as the index for the address of the window
   procedure for the window.

   p  Specifies the pointer to store in the window's reserved memory.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryWindowPtr, WinSetWindowULong


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowText
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowText (hwnd, pszText)
   HWND hwnd;              /*handle of the window                          */
   PSZ pszText;            /*points to the text to set                     */

   The WinSetWindowText function sets the window text for a window to the
   specified text. This function sends a WM_SETWINDOWPARAMS message to the
   hwnd window.

   If this function is called with a frame-window handle, the text of the
   title-bar-frame control is changed.

 Parameters

   hwnd  Identifies the window to set the text for.

   pszText  Points to the window text.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQueryWindowText


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowULong
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowULong (hwnd, index, ul)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index into reserved memory                    */
   ULONG ul;               /*value to place in reserved memory             */

   The WinSetWindowULong function places an unsigned long integer value into
   the reserved memory of a window.

 Parameters

   hwnd  Identifies the window whose reserved memory is to be changed.

   index  Specifies the zero-based index of the ULONG value to set. Valid
   values are in the range zero through the number of bytes of window data
   (for example, a value of 8 would be an index to the third long integer),
   or any of the following QWL values:

╓┌─┌─────────────────────┌───────────────────────────────────────────────────╖
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   QWL_HHEAP             Handle of the heap.

   QWL_HMQ               Handle of the message queue of the window.

   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────

   QWL_HWNDFOCUSSAVE     Handle of the window that last had the focus.

   QWL_STYLE             Window style.

   QWL_USER              ULONG value present in windows of the following
                         preregistered window classes:

                             WC_BUTTON
                             WC_DIALOG
                             WC_ENTRYFIELD
                             WC_FRAME
                             WC_LISTBOX
                             WC_MENU
                             WC_SCROLLBAR
                             WC_STATIC

                         This value can be used to retrieve
                         application-specific data in controls.
   Value                 Meaning
   ──────────────────────────────────────────────────────────────────────────
                        application-specific data in controls.
   ──────────────────────────────────────────────────────────────────────────


   ul  Specifies the unsigned long integer to place in the window's reserved
   memory.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   The specified index is valid only if all the bytes referenced are within
   the reserved memory. For example, this function would fail if an index
   value of zero was specified and only 2 bytes had been reserved.

 See Also

   WinQueryWindowULong, WinRegisterClass, WinSetWindowBits,
   WinSetWindowUShort


 ────────────────────────────────────────────────────────────────────────────
 WinSetWindowUShort
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSetWindowUShort (hwnd, index, us)
   HWND hwnd;              /*handle of the window                          */
   SHORT index;            /*index into reserved memory                    */
   USHORT us;              /*value to place in reserved memory             */

   The WinSetWindowUShort function places an unsigned short integer into the
   reserved memory of a window.

 Parameters

   hwnd  Identifies the window whose reserved memory is to be changed.

   index  Specifies the zero-based index of the USHORT value to set. Valid
   values are in the range zero through the number of bytes of window data
   (for example, a value of 8 would be an index to the fifth short integer),
   or any of the following QWS values:

   Value     Meaning
   ──────────────────────────────────────────────────────────────────────────
   QWS_ID    Index of the window identifier (as passed by the WinCreateWindow
             function).

   QWS_USER  Index of an unsigned short value present in windows of the
             following preregistered window classes:

                 WC_BUTTON
                 WC_DIALOG
                 WC_ENTRYFIELD
                 WC_FRAME
                 WC_LISTBOX
                 WC_MENU
                 WC_SCROLLBAR
                 WC_STATIC

             This value can be used to set application-specific data in
             controls.
   ──────────────────────────────────────────────────────────────────────────

   us  Specifies the unsigned short integer to place in the window's reserved
   memory.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreateWindow, WinQueryWindowUShort, WinRegisterClass,
   WinSetWindowULong


 ────────────────────────────────────────────────────────────────────────────
 WinShowCursor
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinShowCursor (hwnd, fShow)
   HWND hwnd;              /*handle of the window                          */
   BOOL fShow;             /*show/hide flag                                */

   The WinShowCursor function displays or hides the cursor associated with a
   specified window. A cursor show level count is kept internally. (You can
   retrieve this value using the WinQuerySysValue function with
   SV_CURSORLEVEL as the system value.) It is incremented by a hide operation
   and decremented by a show operation. The cursor is visible only if the
   count is zero.

 Parameters

   hwnd  Identifies the window to which the cursor belongs.

   fShow  Specifies whether the cursor is shown or hidden. If TRUE, the
   cursor is made visible. If FALSE, the cursor is made invisible.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinCreateCursor, WinDestroyCursor, WinQueryCursorInfo,
   WinQuerySysValue


 ────────────────────────────────────────────────────────────────────────────
 WinShowPointer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinShowPointer (hwndDesktop, fShow)
   HWND hwndDesktop;       /*handle of the desktop                         */
   BOOL fShow;             /*show/hide flag                                */

   The WinShowPointer function shows or hides the mouse pointer. A pointer
   show level count is kept internally. (You can retrieve this value using
   the WinQuerySysValue function with SV_POINTERLEVEL as the system value.)
   It is incremented by a hide operation and decremented by a show operation.
   The pointer is visible only if the count is zero. If a mouse exists, the
   initial setting of the pointer display level is 0. Otherwise, it is 1.

 Parameters

   hwndDesktop  Identifies the desktop window. This parameter can be
   HWND_DESKTOP or the desktop window handle.

   fShow  Specifies whether the pointer is shown or hidden. If TRUE, the
   pointer is made visible. If FALSE, the pointer is made invisible.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinQuerySysValue


 ────────────────────────────────────────────────────────────────────────────
 WinShowTrackRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinShowTrackRect (hwnd, fShow)
   HWND hwnd;              /*handle of the window                          */
   BOOL fShow;             /*show/hide flag                                */

   The WinShowTrackRect function hides or shows the tracking rectangle. A
   track rectangle show level count is kept internally. (You can retrieve
   this value using the WinQuerySysValue function with SV_TRACTRECTLEVEL as
   the system value.) It is incremented by a hide operation and decremented
   by a show operation. The track rectangle is visible only if the count is
   zero.

 Parameters

   hwnd  Identifies the window passed to the WinTrackRect function.

   fShow  Specifies whether the rectangle is shown or hidden. If fShow is
   TRUE, the function shows the tracking rectangle. If fShow is FALSE, the
   function hides the tracking rectangle.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   An application must call this function to hide a rectangle it is tracking
   if there is a possibility of corrupting the track rectangle while drawing
   (showing it afterward). Since rclTrack in the TRACKINFO structure is
   updating continuously, the application can examine the current tracking
   rectangle coordinates to determine whether temporary hiding is necessary.

   An application needs to call WinShowTrackRect only during asynchronous
   drawing. If an application is drawing on one thread and issuing the
   WinTrackRect function on another, pieces of a tracking rectangle may be
   left behind. The drawing thread should call WinShowTrackRect when tracking
   may be in progress. The application should provide for communication
   between the two threads to ensure that if one thread is tracking, the
   drawing thread will issue WinShowTrackRect. This can be achieved with a
   semaphore.

 See Also

   WinQuerySysValue, WinTrackRect


 ────────────────────────────────────────────────────────────────────────────
 WinShowWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinShowWindow (hwnd, fShow)
   HWND hwnd;              /*handle of the window                          */
   BOOL fShow;             /*show/hide flag                                */

   The WinShowWindow function sets the window visibility state.

 Parameters

   hwnd  Identifies the window whose visibility state is being set.

   fShow  Identifies the new visibility state. If fShow is TRUE, the function
   sets the window state to visible. If fShow is FALSE, the function sets the
   window state to invisible.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   A window possesses a visibility state indicated by the WS_VISIBLE style
   bit. When the WS_VISIBLE style bit is set, the window is shown and
   subsequent drawing into the window is displayed, as long as the window or
   any of the windows in the parent chain have the WS_VISIBLE style.

   When the WS_VISIBLE style bit is not set, the window is not shown (hidden)
   and subsequent drawing into the window is not displayed.

   If the value of the WS_VISIBLE style bit has been changed, the
   WM_WINDOWPOSCHANGED message is sent to the window of the hwnd parameter
   before the function returns.

   Drawing to a window with a WS_VISIBLE style will not be displayed if the
   window is covered by other windows or clipped by its parent.

 See Also

   WinIsWindowVisible


 ────────────────────────────────────────────────────────────────────────────
 WinStartTimer
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinStartTimer (hab, hwnd, idTimer, lTimeOut)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of the window                          */
   USHORT idTimer;         /*timer identifier                              */
   USHORT lTimeOut;        /*time-out value                                */

   The WinStartTimer function starts a timer. A time-out value is specified,
   and every time a time-out occurs, a WM_TIMER message is posted to the
   specified window.

   A second call to WinStartTimer for a timer that already exists will reset
   that timer.

 Parameters

   hab  Identifies the anchor block.

   hwnd  Identifies the window that is part of the timer identification. If
   the hwnd parameter is NULL, then the idTimer parameter is ignored and
   WinStartTimer returns a unique nonzero identification value that
   identifies the timer. The timer message is posted in the queue associated
   with the current thread, with the hwnd parameter equal to NULL.

   idTimer  Identifies the timer. If hwnd is NULL, this parameter is ignored.

   lTimeOut  Specifies the timer delay, in milliseconds. An lTimeOut value of
   zero will cause the timer to time out as fast as possible; generally, this
   is about 1/18 of a second.

 Return Value

   The return value is TRUE if the function is successful and if hwnd is not
   NULL. Otherwise, it is FALSE, indicating that an error occurred. If hwnd
   is NULL, the return value is a unique nonzero value, or zero if an error
   occurs.

 Comments

   If the hwnd parameter is NULL, then the return value from this function
   must be used as the idTimer parameter in any subsequent call to
   WinStopTimer.

 See Also

   WinStopTimer


 ────────────────────────────────────────────────────────────────────────────
 WinStopTimer
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinStopTimer (hab, hwnd, idTimer)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of the window                          */
   USHORT idTimer;         /*timer identifier                              */

   The WinStopTimer function stops a timer. When this function is called, no
   further messages are received from the stopped timer, even if it has timed
   out since the last call to the WinGetMsg function.

 Parameters

   hab  Identifies the anchor block.

   hwnd  Identifies the window containing the timer.

   idTimer  Identifies the timer.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinGetMsg, WinStartTimer


 ────────────────────────────────────────────────────────────────────────────
 WinSubclassWindow
 ────────────────────────────────────────────────────────────────────────────
   PFNWP WinSubclassWindow (hwnd, pfnwp)
   HWND hwnd;              /*handle of the window to subclass              */
   PFNWP pfnwp;            /*address of new window procedure               */

   The WinSubclassWindow function subclasses a window by replacing its window
   procedure with another window procedure specified by the pfnwp parameter.

 Parameters

   hwnd  Identifies the window to subclass.

   pfnwp  Points to the address of the procedure used to subclass the window.

 Return Value

   The return value, if the function is successful, is the address of the
   previous window procedure that belongs to the window specified by the hwnd
   parameter. Otherwise, the return value is 0L.

 Comments

   To subclass a window effectively, the new window procedure should call the
   old window procedure, rather than the WinDefWindowProc function, for those
   messages it does not process itself.

   To reverse the effect of subclassing, call WinSubclassWindow again using
   the old window procedure address.

   It is not possible to subclass a window created by another process.

 See Also

   WinDefWindowProc


 ────────────────────────────────────────────────────────────────────────────
 WinSubstituteStrings
 ────────────────────────────────────────────────────────────────────────────
   SHORT WinSubstituteStrings (hwnd, pszSrc, cchDstMax, pszDst)
   HWND hwnd;              /*handle of the window                          */
   PSZ pszSrc;             /*address of the source string                  */
   SHORT cchDstMax;        /*size of destination string buffer             */
   PSZ pszDst;             /*address of buffer for destination string      */

   The WinSubstituteStrings function performs a substitution process on a
   text string, replacing certain marker characters with text supplied by the
   application. The WinSubstituteStrings function is particularly useful for
   displaying variable information in dialog boxes, menus, and other
   user-interface functions. Variable information can include things such as
   filenames, which cannot be statically declared within resource files.

   This function is called by the system while creating the child windows in
   a dialog box. It allows the child windows to perform substitutions in
   their window text.

 Parameters

   hwnd  Identifies the window that processes the function.

   pszSrc  Points to the null-terminated text string to perform the
   substitution.

   cchDstMax  Specifies the maximum number of characters that can be returned
   in the pszDst parameter.

   pszDst  Points to the null-terminated text string produced by the
   substitution process. The string is truncated if it would otherwise
   contain more than the number of characters specified by the cchDstMax
   parameter. When truncation occurs, the last character of the truncated
   string is always the NULL termination character.

 Return Value

   The return value is the number of characters returned in pszDst, not
   including the terminating NULL character. The maximum value is (cchDstMax
   - 1). It is zero if an error occurred.

 Comments

   When a string of the form %n is encountered in the source string, where n
   is a digit from 0 through 9, a WM_SUBSTITUTESTRING message is sent to the
   specified window. This message returns a text string to use as a
   substitution for the %n in the destination string, which is otherwise an
   exact copy of the source string.

   If % is encountered in the source, % is copied to the destination, but no
   other substitution occurs. If %x occurs in the source, where x is neither
   a digit nor %, then the source is copied to the destination unchanged.

   The source and destination strings must not overlap in memory.

   To use this function, your application must process WM_SUBSTITUTESTRING
   messages and perform the requested string substitution.


 ────────────────────────────────────────────────────────────────────────────
 WinSubtractRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinSubtractRect (hab, prclDst, prclSrc1, prclSrc2)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prclDst;         /*address of the destination rectangle          */
                           /*structure                                     */
   PRECTL prclSrc1;        /*address of the first rectangle structure      */
   PRECTL prclSrc2;        /*address of the second rectangle structure     */

   The WinSubtractRect function subtracts one rectangle from another by
   subtracting the prclSrc2 parameter from the prclSrc1 parameter.
   Subtracting one rectangle from another does not always result in a
   rectangular area; in this case, WinSubtractRect returns prclSrc1 in the
   prclDst parameter. For this reason, WinSubtractRect provides only an
   approximation of subtraction. However, the area described by prclDst is
   always greater than or equal to the "true" result of the subtraction. You
   can use the GpiCombineRegion function to calculate the true result of the
   subtraction of two rectangular areas, although WinSubtractRect does it
   much faster.

 Parameters

   hab  Identifies an anchor block.

   prclDst  Points to a RECTL structure that contains the result of the
   subtraction of the prclSrc2 parameter from the prclSrc1 parameter. The
   RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prclSrc1  Points to a RECTL structure that contains the first source
   rectangle.

   prclSrc2  Points to a RECTL structure that contains the second source
   rectangle.

 Return Value

   The return value is TRUE if the prclDst parameter points to a nonempty
   rectangle. Otherwise, it is FALSE, indicating that prclDst is an empty
   rectangle.

 See Also

   GpiCombineRegion, WinUnionRect


 ────────────────────────────────────────────────────────────────────────────
 WinTerminate
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinTerminate (hab)
   HAB hab;                /*handle of the anchor block                    */

   The WinTerminate function terminates an application thread's use of
   Presentation Manager and releases all its associated resources. It is
   recommended that you call this function prior to termination of your
   application. However, if it is not issued, all Presentation Manager
   resources allocated to the thread are deallocated when the program
   terminates──whether normally or abnormally──by Presentation Manager code
   executed as part of the exit-list processing.

 Parameters

   hab  Identifies the anchor block.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 See Also

   WinInitialize


 ────────────────────────────────────────────────────────────────────────────
 WinThrow
 ────────────────────────────────────────────────────────────────────────────
   VOID WinThrow (pctchbf, sErrorReturn)
   PCATCHBUF pctchbf;      /*address of structure with execution           */
                           /*environment                                   */
   SHORT sErrorReturn;     /*error code to return                          */

   The WinThrow function restores the execution environment to the values
   saved in the buffer pointed to by the pctchbf parameter. Execution then
   transfers to the WinCatch function that copied the environment to pctchbf.

 Parameters

   pctchbf  Points to a CATCHBUF structure that contains the execution
   environment. It must have been set by a previous WinCatch function call.
   The CATCHBUF structure has the following form:

   typedef struct _CATCHBUF {
       ULONG reserved[4];
   } CATCHBUF;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   sErrorReturn  Specifies the value to be returned to the WinCatch function.
   The meaning of the value is determined by the application.

 Return Value

   This function does not return a value.

 Comments

   The routine that calls WinCatch is responsible for freeing any resources
   allocated between the time WinCatch was called and the time WinThrow was
   called.

 Example

   This example calls WinCatch to save the current execution environment
   before calling a recursive sort function. The first return from WinCatch
   is zero. If the doSort function calls WinThrow, execution will again
   return to the WinCatch function. This time, WinCatch will return the
   STACKOVERFLOW error passed by the doSort function. The doSort function is
   recursive, that is, it calls itself. It maintains a variable,
   usStackCheck, that is used to check to see how much stack space has been
   used. If more then 3K of the stack has been used, it calls WinThrow to
   drop out of all the nested function calls back into the function that
   called WinCatch.

   USHORT usStackCheck
   CATCHBUF ctchbf;

   main() {
       SHORT sErrorReturn;

       sErrorReturn = WinCatch(&ctchbf); /* save execution environment */
       if (sErrorReturn) {
           .
           . /* error processing */
           .
       }
       usStackCheck = 0;               /* initialize stack usage count */
       doSort(1, 1000);                /* call sort function           */
   }

   VOID doSort(sLeft, sRight)
   SHORT sLeft, sRight;
   {
       SHORT i, sLast;

       /*
        * check to see if more then 3K of the stack has been used, and if
        * so, call WinThrow to drop back into the original calling program
        */

       usStackCheck += 10;
       if (usStackCheck > (3 * 1024))
           WinThrow(&ctchbf, STACKOVERFLOW);
       .
       . /* sorting algorithm */
       .
       doSort(sLeft, sLast - 1);         /* note recursive call         */
       usStackCheck -= 10;               /* update stack check variable */
   }

 See Also

   WinCatch


 ────────────────────────────────────────────────────────────────────────────
 WinTrackRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinTrackRect (hwnd, hps, pti)
   HWND hwnd;              /*handle of the window                          */
   HPS hps;                /*presentation-space handle                     */
   PTRACKINFO pti;         /*address of structure for tracking information */

   The WinTrackRect function draws a tracking rectangle.

 Parameters

   hwnd  Identifies the window in which tracking is to take place. If hwnd
   identifies the desktop window or HWND_DESKTOP, tracking will take place
   over the entire screen. It is assumed that the style of this window is not
   WS_CLIPCHILDREN.

   hps  Identifies the presentation space to be used for drawing the clipping
   rectangle. If hps is NULL, the hwnd parameter is used to calculate a
   presentation space for tracking. (It is assumed that tracking takes place
   within the window identified by hwnd and that the style of this window is
   not set to WS_CLIPCHILDREN.) When the drag rectangle appears, it is not
   clipped by any children within the window. If the window style is
   WS_CLIPCHILDREN and the application wants the drag rectangle to be
   clipped, it must explicitly pass an appropriate presentation space.

   pti  Points to a TRACKINFO structure. The TRACKINFO structure has the
   following form:

   typedef struct _TRACKINFO {
       SHORT  cxBorder;
       SHORT  cyBorder;
       SHORT  cxGrid;
       SHORT  cyGrid;
       SHORT  cxKeyboard;
       SHORT  cyKeyboard;
       RECTL  rclTrack;
       RECTL  rclBoundary;
       POINTL ptlMinTrackSize;
       POINTL ptlMaxTrackSize;
       USHORT fs;
   } TRACKINFO;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful. Otherwise, it is
   FALSE, indicating that an error occurred or that the mouse was already
   captured when WinTrackRect was called. Only one tracking rectangle may be
   in use at a time.

 Comments

   This function provides general-purpose mouse tracking. WinTrackRect draws
   a rectangle and allows the user to position the entire rectangle or make a
   specific side or corner smaller or larger. The resulting rectangle is then
   returned to the application, which can use this new information for size
   and position data. For example, to move and size windows by using the wide
   sizing borders, the window manager interface simply calls WinTrackRect.

   WinTrackRect allows the caller to control such limiting values as the
   following:

   ■  A maximum and minimum tracking size

   ■  The widths of the tracking rectangle's sides

   If the TF_SETPOINTERPOS flag is included, the mouse pointer is positioned
   at the center of the tracking rectangle. Otherwise, the mouse pointer is
   not moved from its current position. At this point, there is an
   established distance between the mouse position and the part of the
   tracking rectangle that it moves, the value of which is kept constant.

   While moving or sizing with the keyboard interface, the mouse pointer is
   repositioned along with the tracking rectangle's new size or position.

   During tracking, the following keys are active:

   Value     Meaning
   ──────────────────────────────────────────────────────────────────────────
   ENTER     Accepts the new position or size.

   LEFT      Moves the mouse pointer and tracking rectangle left.

   UP        Moves the mouse pointer and tracking rectangle up.

   RIGHT     Moves the mouse pointer and tracking rectangle right.

   DOWN      Moves the mouse pointer and tracking rectangle down.

   ESC       Cancels the current tracking operation. In this case, the value
             of the tracking rectangle is undefined on exit.
   ──────────────────────────────────────────────────────────────────────────

   The mouse and the keyboard interface can be intermixed. The caller need
   not include the TF_SETPOINTERPOS flag to be able to use the keyboard
   interface; this simply initializes the position of the mouse pointer.

   Tracking movements using the keyboard arrow keys are in increments of the
   cxGrid and cyGrid fields, regardless of whether TF_GRID is specified. If
   TF_GRID is specified, the interior of the tracking rectangle is allowed
   only on multiples of cxGrid and cyGrid. The default value for cxGrid is
   the system-font character width, and the default value for cyGrid is half
   the height of the system font.

   The tracking rectangle is usually logically "on top" of objects it tracks,
   so that the user can see the old size and position while tracking the new.
   Thus, it is possible for a window below the tracking rectangle to update
   while part of the tracking rectangle is above it.

   Since the tracking rectangle is drawn in exclusive-OR mode, no window can
   draw below the tracking rectangle (and thereby obliterate it) without
   first notifying the tracking code, because fragments of the tracking
   rectangle can be left behind. If the window doing the drawing is clipped
   from the window the tracking is occurring in, there is no problem.

   To prevent a window that is currently processing a WM_PAINT message from
   drawing over the tracking rectangle, MS OS/2 treats the tracking rectangle
   as a system-wide resource, only one of which can be in use at any one
   time. If there is a risk of the currently updating window drawing on the
   tracking rectangle, MS OS/2 removes the tracking rectangle while that
   window and its child windows update, and then replaces it. This is done
   specifically by the WinBeginPaint and WinEndPaint functions. If the
   tracking rectangle overlaps, it is removed by WinBeginPaint. With the
   WinEndPaint function, all child windows are updated by using the
   WinUpdateWindow function before the tracking rectangle is redrawn.

   WinTrackRect has a modal loop within its function. The modal loop has a
   HK_MSGFILTER hook and hook code MSGF_TRACK. For an explanation of this
   hook type, see the WinSetHook function.

   The rectangle tracked by WinTrackRect is guaranteed to be within the
   specified tracking bounds and dimensions. If the rectangle passed is out
   of these bounds, or is too large or too small, it is modified to a
   rectangle that meets those limits.

 See Also

   WinBeginPaint, WinEndPaint, WinSetHook, WinUpdateWindow


 ────────────────────────────────────────────────────────────────────────────
 WinTranslateAccel
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinTranslateAccel (hab, hwnd, haccel, pqmsg)
   HAB hab;                /*handle of the anchor block                    */
   HWND hwnd;              /*handle of the window                          */
   HACCEL haccel;          /*handle of the accelerator table               */
   PQMSG pqmsg;            /*address of structure with message             */

   The WinTranslateAccel function translates a WM_CHAR message. If it is a
   WM_CHAR message in the specified accelerator table, WinTranslateAccel
   translates the message pointed to by the pqmsg parameter. The message is
   translated into a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message.

 Parameters

   hab  Identifies the anchor block.

   hwnd  Identifies the destination window. Normally, this parameter
   identifies a frame window.

   haccel  Identifies the accelerator table.

   pqmsg  Points to a QMSG structure that contains the message to be
   translated. The QMSG structure has the following form:

   typedef struct _QMSG {
       HWND   hwnd;
       USHORT msg;
       MPARAM mp1;
       MPARAM mp2;
       ULONG  time;
       POINTL ptl;
   } QMSG;

   For a full description, see Chapter 4, "Types, Macros, Structures."

 Return Value

   The return value is TRUE if the function is successful──that is, if the
   message matches an accelerator in the table. Otherwise, it is FALSE,
   indicating that an error occurred.

 Comments

   It is possible to have accelerators that do not correspond to items in a
   menu. If the command value does not match any items in the menu, the
   message is still translated.

   Generally, applications do not have to call this function. It is normally
   called automatically by WinGetMsg and WinPeekMsg when a WM_CHAR message is
   received, with the window handle of the active window as the first
   parameter. The standard frame window procedure always passes WM_COMMAND
   messages to the FID_CLIENT window. Since the message is physically changed
   by WinTranslateAccel, applications will not receive the WM_CHAR messages
   that resulted in WM_COMMAND, WM_SYSCOMMAND, or WM_HELP messages.

 See Also

   WinGetMsg, WinPeekMsg


 ────────────────────────────────────────────────────────────────────────────
 WinUnionRect
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinUnionRect (hab, prclDst, prclSrc1, prclSrc2)
   HAB hab;                /*handle of the anchor block                    */
   PRECTL prclDst;         /*address of the destination rectangle          */
                           /*structure                                     */
   PRECTL prclSrc1;        /*address of the first rectangle structure      */
   PRECTL prclSrc2;        /*address of the second rectangle structure     */

   The WinUnionRect function calculates a rectangle that bounds the two
   source rectangles.

 Parameters

   hab  Identifies an anchor block.

   prclDst  Points to a RECTL structure that will receive a rectangle
   bounding the rectangles pointed to by the prclSrc1 and prclSrc2
   parameters. The RECTL structure has the following form:

   typedef struct _RECTL {
       LONG  xLeft;
       LONG  yBottom;
       LONG  xRight;
       LONG  yTop;
   } RECTL;

   For a full description, see Chapter 4, "Types, Macros, Structures."

   prclSrc1  Points to a RECTL structure that contains the first source
   rectangle.

   prclSrc2  Points to a RECTL structure that contains the second source
   rectangle.

 Return Value

   The return value is TRUE if prclDst is a nonempty rectangle. Otherwise, it
   is FALSE, indicating that an error occurred or that the prclDst rectangle
   is empty. If one of the source rectangles is NULL, the other is returned.

 See Also

   WinIntersectRect, WinSubtractRect


 ────────────────────────────────────────────────────────────────────────────
 WinUpdateWindow
 ────────────────────────────────────────────────────────────────────────────
   BOOL WinUpdateWindow (hwnd)
   HWND hwnd;              /*handle of the window                          */

   The WinUpdateWindow function forces a window and its associated child
   windows to be updated.

 Parameters

   hwnd  Identifies the window to be updated.

 Return Value

   The return value is TRUE if the function is successful or FALSE if an
   error occurs.

 Comments

   If hwnd is a child window of a parent window that was created without the
   WS_CLIPCHILDREN style, the update region of hwnd is removed from the
   update region of the parent window. This is so that after the hwnd window
   is redrawn, the parent window will not draw over what was just drawn for
   hwnd.

 See Also

   WinInvalidateRect


 ────────────────────────────────────────────────────────────────────────────
 WinUpper
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinUpper (hab, idcp, idcc, psz)
   HAB hab;                /*handle of the anchor block                    */
   USHORT idcp;            /*code-page identifier                          */
   USHORT idcc;            /*country-code identifier                       */
   PSZ psz;                /*address of the string to convert              */

   The WinUpper function converts a string to uppercase in place.

 Parameters

   hab  Identifies the anchor block.

   idcp  Identifies the code page. If idcp is NULL, the current process's
   code page is used.

   idcc  Identifies the country code. If idcc is NULL, the default country
   specified in the config.sys file is used.

   psz  Points to the string to be converted.

 Return Value

   The return value is the length of the converted string.

 See Also

   WinUpperChar


 ────────────────────────────────────────────────────────────────────────────
 WinUpperChar
 ────────────────────────────────────────────────────────────────────────────
   USHORT WinUpperChar (hab, idcp, idcc, c)
   HAB hab;