MouSetPtrShape

Bindings:  C, MASM 

This call allows a process to set the pointer shape and size to be used as 
the mouse device driver pointer image for all applications in a session. 

 MouSetPtrShape    (PtrBuffer, PtrDefRec, DeviceHandle) 
 

 PtrBuffer (PBYTE) - input 
    Address of a buffer containing the bit image used by the mouse device 
    driver as the pointer shape for that session. The buffer consists of 
    AND and XOR pointer masks in a format meaningful to the pointer draw 
    device driver. 

    For CGA compatible text modes (0, 1, 2, and 3) the following describes 
    the AND and XOR pointer mask bit definitions for each character cell 
    of the masks.  Bit values are: 

    Bit       Description 
    15        Blinking 
    14-12     Background color 
    11        Intensity 
    10-8      Foreground color 
    7-0       Character 

 PtrDefRec (PPTRSHAPE) - input 
    Address of the structure where the application stores the necessary 
    data for the pointer draw device driver to build a row-by-column image 
    for each bit plane for the current display mode.  The pointer 
    definition record structure follows: 

    TotLength (USHORT) 
       The total length of the data necessary for the pointer draw device 
       driver to build a row-by-column image for each bit plane for the 
       current display mode. 

       For all OS/2 system-supported modes, TotLength is specified in 
       bytes and is 
       equal to: 

       Mono & Text Modes 
                 For text mode height and width must be 1, so length is 
                 always 4. 

                 TotLength = (height in chars) * (width in chars) * 2 * 2
                            = 1 * 1 * 2 * 2
                            = 4
                 

       Graphics Mode 
                 Width-in-pels must be a multiple of 8. 

                 TotLength = (height in pels)*(width in pels)*(bits per pel)*2/8
                 

       Modes 4 and 5 (320 X 200) 
                   

                 TotLength = (height) * (width) * 2 * 2 / 8
                 

       Mode 6 (640 X 200) 
                   

                 TotLength = (height) * (width) * 1 * 2 / 8
                 

                 Length calculations produce byte boundary buffer sizes. 

    col (USHORT) 
       Number of columns in the mouse shape. In graphics modes, this field 
       contains the pel width (columns) of the mouse shape for the session 
       and must be greater than or equal to 1. In text modes, col must 
       equal 1. 

    row (USHORT) 
       Number of rows in the mouse shape. In graphics modes, this field 
       contains the pel height (rows) of the mouse shape for the session 
       and must be greater than or equal to 1. In text modes, row must 
       equal 1. 

    coloffset (USHORT) 
       This value is returned by the mouse device driver to indicate the 
       relative column offset within the pointer image.  The value defines 
       the center (hotspot) of the pointer image. This value is a signed 
       number that represents either character or pel offset, depending on 
       the display mode. 

    rowoffset (USHORT) 
       This value is returned by the mouse device driver to indicate the 
       relative row offset within the pointer image.  The value defines 
       the center (hotspot) of the pointer image. This value is a signed 
       number that represents either character or pel offset, depending on 
       the display mode. 

 Programming Note: 
    For other custom displays and for the extended modes of the EGA 
    attachment, it is possible to set the display to modes that require 
    multiple bit planes.  In these cases, the area sized by the row and 
    column limits must be repeated for each bit plane supported in that 
    mode.  Consequently, the calling process must supply enough data to 
    allow the mouse device driver to draw the pointer shape on all 
    currently supported bit planes in that session. For text modes, row 
    and column offset must equal 0. 

 DeviceHandle (HMOU) - input 
    Contains the handle of the mouse device obtained from a previous 
    MouOpen. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    385       ERROR_MOUSE_NO_DEVICE 
    387       ERROR_MOUSE_INV_PARMS 
    466       ERROR_MOU_DETACHED 
    501       ERROR_MOUSE_NO_CONSOLE 
    505       ERROR_MOU_EXTENDED_SG 
 
 Remarks 

 An application passes a data image to the mouse device driver that the 
 mouse driver applies to the screen whenever the logical pointer position 
 is not located in the application-defined collision  area.  The 
 application synchronizes use of the screen with the mouse driver by way 
 of MouRemovePtr and MouDrawPtr. 

 The pointer shape is dependent on the display device driver used to 
 support the display device.  OS/2 supports text and graphics modes. These 
 modes are restricted to modes 0 through 7, depending on the display 
 device.  Character modes (modes 0, 1, 2, 3, and 7) support the pointer 
 cursor only as a reverse block character.  This reverse block character 
 has a character height and width equal to 1. 

 The pointer shape is mapped by the Pointer Draw Device Driver and 
 determined completely by the application.  The height and width may vary 
 from 1 through the pel size of the display screen.  For restrictions 
 concerning the Pointer Draw Device Driver, see IBM Operating System/2 
 Version 1.2 I/O Subsystems And Device Support Volume 1.