home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / textmode.zip / mou.doc < prev    next >
Text File  |  1994-08-22  |  34KB  |  1,163 lines
  1. *
  2. * Title: mou.doc
  3. *
  4. * Function:
  5. *     Workplace OS/2 mouse APIs
  6. *
  7. * Copyright:
  8. *     Copyright (C) IBM Corp. 1993
  9. *
  10. * Notes:
  11. *     This is preliminary documentation and subject to change.
  12. *
  13.  
  14.  
  15. MouDrawPtr
  16. ================================================================================
  17. This call allows a process to notify the mouse device driver that an area
  18. previously restricted to the pointer image is now available to the mouse device
  19. driver.
  20.  
  21.  
  22. CALL SYNTAX
  23. -----------
  24.  
  25.  #define INCL_MOU
  26.  
  27.  APIRET  rc = MouDrawPtr(DeviceHandle);
  28.  
  29.  HMOU             DeviceHandle;  /* Mouse device handle */
  30.  
  31.  APIRET           rc;            /* return code */
  32.  
  33.  
  34. PARAMETERS
  35. ----------
  36.  
  37.   DeviceHandle (HMOU) - input
  38.      Reserved value, must be zero
  39.  
  40.  
  41. RETURNS
  42. -------
  43.      Return code descriptions are:
  44.  
  45.      0         NO_ERROR
  46.      385       ERROR_MOUSE_NO_DEVICE
  47.      466       ERROR_MOU_DETACHED
  48.      501       ERROR_MOUSE_NO_CONSOLE
  49.  
  50.  
  51. REMARKS
  52. -------
  53.  
  54. The collision area (the pointer image restricted area) is established by
  55. by MouRemovePtr.  MouDrawPtr nullifies the effect of the MouRemovePtr
  56. command.  If there was no previous MouDrawPtr command or if a previous
  57. MouDrawPtr command has already nullified the collision area, the MouRemovePtr
  58. command is effectively a null operation.
  59.  
  60. This call is required to begin session pointer image drawing.  At session
  61. start the collision area is defined as the size of the display.
  62.  
  63.  
  64.  
  65. MouFlushQue
  66. ================================================================================
  67. This call directs the mouse driver to flush (empty) the mouse event queue.
  68.  
  69.  
  70. CALL SYNTAX
  71. -----------
  72.  
  73.  #define INCL_MOU
  74.  
  75.  APIRET  rc = MouFlushQue(DeviceHandle);
  76.  
  77.  HMOU             DeviceHandle;  /* Mouse device handle */
  78.  
  79.  APIRET           rc;            /* return code */
  80.  
  81.  
  82. PARAMETERS
  83. ----------
  84.   DeviceHandle (HMOU) - input
  85.      Reserved value, must be zero
  86.  
  87.  
  88. RETURNS
  89. -------
  90.      Return code descriptions are:
  91.  
  92.      0         NO_ERROR
  93.      385       ERROR_MOUSE_NO_DEVICE
  94.      466       ERROR_MOU_DETACHED
  95.      501       ERROR_MOUSE_NO_CONSOLE
  96.  
  97.  
  98.  
  99. MouGetDevStatus
  100. ================================================================================
  101. This call returns status flags for the installed mouse device driver.
  102.  
  103.  
  104. CALL SYNTAX
  105. -----------
  106.  
  107.  #define INCL_MOU
  108.  
  109.  APIRET  rc = MouGetDevStatus(DeviceStatus, DeviceHandle);
  110.  
  111.  PULONG           DeviceStatus;  /* Current status flags */
  112.  HMOU             DeviceHandle;  /* Mouse device handle */
  113.  
  114.  APIRET           rc;            /* return code */
  115.  
  116.  
  117. PARAMETERS
  118. ----------
  119.  
  120.   DeviceStatus (PULONG) - output
  121.      Address of the current status flag settings for the installed mouse device
  122.      driver.
  123.  
  124.      The return value is a 4-byte set of bit flags.
  125.  
  126.      Bit       Description
  127.      31-10     Reserved, set to zero.
  128.      9         Set if mouse data returned in mickeys, not pels.
  129.      8         Set if the drawing operations for pointer draw routine are
  130.                disabled.
  131.      7-4       Reserved, set to zero.
  132.      3         Set if pointer draw routine disabled by unsupported mode.
  133.      2         Set if flush in progress.
  134.      1         Set if block read in progress.
  135.      0         Set if event queue busy with I/O.
  136.  
  137.   DeviceHandle (HMOU) - input
  138.      Reserved value, must be zero
  139.  
  140.  
  141. RETURNS
  142. -------
  143.      Return code descriptions are:
  144.  
  145.      0         NO_ERROR
  146.      385       ERROR_MOUSE_NO_DEVICE
  147.      466       ERROR_MOU_DETACHED
  148.      501       ERROR_MOUSE_NO_CONSOLE
  149.  
  150.  
  151.  
  152. MouGetEventMask
  153. ================================================================================
  154. This call returns the current value of the mouse event queue mask.
  155.  
  156.  
  157. CALL SYNTAX
  158. -----------
  159.  
  160.  #define INCL_MOU
  161.  
  162.  APIRET  rc = MouGetEventMask(EventMask, DeviceHandle);
  163.  
  164.  PULONG           EventMask;     /* Event Mask word */
  165.  HMOU             DeviceHandle;  /* Mouse device handle */
  166.  
  167.  APIRET           rc;            /* return code */
  168.  
  169.  
  170. PARAMETERS
  171. ----------
  172.  
  173.   EventMask (PULONG) - output
  174.      Address in application storage where the current mouse device driver's
  175.      event mask is returned to the caller by the mouse device driver.
  176.  
  177.      The EventMask is set by MouSetEventMask, and has the following definition:
  178.  
  179.      Bit     Description
  180.      31-7    Reserved, set to zero.
  181.      6       Report button 3 press/release events, without mouse motion.
  182.      5       Report button 3 press/release events, with mouse motion.
  183.      4       Report button 2 press/release events, without mouse motion.
  184.      3       Report button 2 press/release events, with mouse motion.
  185.      2       Report button 1 press/release events, without mouse motion.
  186.      1       Report button 1 press/release events, with mouse motion.
  187.      0       Report mouse motion events with no button press/release
  188.              events.
  189.  
  190.   DeviceHandle (HMOU) - input
  191.      Reserved value, must be zero
  192.  
  193.  
  194. RETURNS
  195. -------
  196.      Return code descriptions are:
  197.  
  198.      0         NO_ERROR
  199.      385       ERROR_MOUSE_NO_DEVICE
  200.      466       ERROR_MOU_DETACHED
  201.      501       ERROR_MOUSE_NO_CONSOLE
  202.  
  203.  
  204. REMARKS
  205. -------
  206.  
  207.  
  208.  
  209. MouGetNumButtons
  210. ================================================================================
  211. This call returns the number of buttons supported on the installed mouse driver.
  212.  
  213.  
  214. CALL SYNTAX
  215. -----------
  216.  
  217.  #define INCL_MOU
  218.  
  219.  APIRET  rc = MouGetNumButtons(NumberOfButtons, DeviceHandle);
  220.  
  221.  PULONG           NumberOfButtons;  /* Number of mouse buttons */
  222.  HMOU             DeviceHandle;     /* Mouse device handle */
  223.  
  224.  APIRET           rc;               /* return code */
  225.  
  226.  
  227. PARAMETERS
  228. ----------
  229.  
  230.   NumberOfButtons (PULONG) - output
  231.      Address of the number of physical buttons. The return values for the number
  232.      of buttons supported are:
  233.  
  234.      Value     Definition
  235.      1         One mouse button
  236.      2         Two mouse buttons
  237.      3         Three mouse buttons.
  238.  
  239.   DeviceHandle (HMOU) - input
  240.      Reserved value, must be zero
  241.  
  242.  
  243. RETURNS
  244. -------
  245.      Return code descriptions are:
  246.  
  247.      385       ERROR_MOUSE_NO_DEVICE
  248.      466       ERROR_MOU_DETACHED
  249.      501       ERROR_MOUSE_NO_CONSOLE
  250.  
  251.  
  252.  
  253. MouGetNumMickeys
  254. ================================================================================
  255. This call returns the number of mickeys in each centimeter for the installed
  256. mouse driver.
  257.  
  258.  
  259. CALL SYNTAX
  260. -----------
  261.  #define INCL_MOU
  262.  
  263.  APIRET  rc = MouGetNumMickeys(NumberOfMickeys, DeviceHandle);
  264.  
  265.  PULONG           NumberOfMickeys; /* Number mickeys/centimeter */
  266.  HMOU             DeviceHandle;    /* Mouse device handle */
  267.  
  268.  APIRET           rc;              /* return code */
  269.  
  270.  
  271. PARAMETERS
  272. ----------
  273.  
  274.   NumberOfMickeys (PULONG) - output
  275.      Address of the number of physical mouse motion units.  Mouse motion units
  276.      are reported in mickeys in each centimeter.  This value is constant based
  277.      upon the mouse device attached.
  278.  
  279.   DeviceHandle (HMOU) - input
  280.      Reserved value, must be zero.
  281.  
  282.  
  283. RETURNS
  284. -------
  285.      Return code descriptions are:
  286.  
  287.      0         NO_ERROR
  288.      385       ERROR_MOUSE_NO_DEVICE
  289.      466       ERROR_MOU_DETACHED
  290.      501       ERROR_MOUSE_NO_CONSOLE
  291.  
  292.  
  293.  
  294. MouGetNumQueEl
  295. ================================================================================
  296. This call returns the current status for the mouse device driver event queue.
  297.  
  298.  
  299. CALL SYNTAX
  300. -----------
  301.  
  302.  typedef struct _MOUQUEINFO {   /* mouqi */
  303.      ULONG  cEvents;              /* current number of event queue elements */
  304.      ULONG  cmaxEvents;           /* MaxNumQueElements value */
  305.  } MOUQUEINFO;
  306.  
  307.  #define INCL_MOU
  308.  
  309.  APIRET  rc = MouGetNumQueEl(QueDataRecord, DeviceHandle);
  310.  
  311.  PMOUQUEINFO      QueDataRecord; /* Ptr to structure */
  312.  HMOU             DeviceHandle;  /* Mouse device handle */
  313.  
  314.  APIRET           rc;            /* return code */
  315.  
  316.  
  317. PARAMETERS
  318. ----------
  319.  
  320.   QueDataRecord (PMOUQUEINFO) - output
  321.      Address of the mouse queue status structure:
  322.  
  323.      numqelements (ULONG)
  324.         Current number of event queue elements, in the range 0 <> value <>
  325.         maxnumqelements.
  326.  
  327.      maxnumqelements (ULONG)
  328.         Maximum number of queue elements supported.
  329.  
  330.   DeviceHandle (HMOU) - input
  331.      Reserved value, must be zero.
  332.  
  333.  
  334. RETURNS
  335. -------
  336.      Return code descriptions are:
  337.  
  338.      0         NO_ERROR
  339.      385       ERROR_MOUSE_NO_DEVICE
  340.      466       ERROR_MOU_DETACHED
  341.      501       ERROR_MOUSE_NO_CONSOLE
  342.  
  343.  
  344. REMARKS
  345. -------
  346.  
  347. The maxnumqelements returned by this function is established during mouse
  348. device driver configuration.
  349.  
  350.  
  351.  
  352. MouGetPtrPos
  353. ================================================================================
  354. This call queries the mouse driver to determine the current row and column
  355. coordinate position of the mouse pointer.
  356.  
  357.  
  358.  
  359. CALL SYNTAX
  360. -----------
  361.  
  362.  typedef struct _PTRLOC {    /* moupl */
  363.      ULONG  row;               /* pointer row screen position */
  364.      ULONG  col;               /* pointer column screen position */
  365.  } PTRLOC;
  366.  
  367.  #define INCL_MOU
  368.  
  369.  APIRET  rc = MouGetPtrPos(PtrPos, DeviceHandle);
  370.  
  371.  PPTRLOC          PtrPos;        /* Double word structure */
  372.  HMOU             DeviceHandle;  /* Mouse device handle */
  373.  
  374.  APIRET           rc;            /* return code */
  375.  
  376.  
  377. PARAMETERS
  378. ----------
  379.  
  380.   PtrPos (PPTRLOC) - output
  381.      Address of the mouse pointer position structure:
  382.  
  383.      pointerrow (ULONG)
  384.         Current pointer row coordinate (pels or characters).
  385.  
  386.      pointercol (ULONG)
  387.         Current pointer column coordinate (pels or characters).
  388.  
  389.   DeviceHandle (HMOU) - input
  390.      Reserved value, must be zero.
  391.  
  392.  
  393. RETURNS
  394. -------
  395.      Return code descriptions are:
  396.  
  397.      0         NO_ERROR
  398.      385       ERROR_MOUSE_NO_DEVICE
  399.      466       ERROR_MOU_DETACHED
  400.      501       ERROR_MOUSE_NO_CONSOLE
  401.  
  402.  
  403. REMARKS
  404. -------
  405.  
  406.  
  407.  
  408. MouGetPtrShape
  409. ================================================================================
  410. This call allows a process to get the pointer shape for the session.
  411.  
  412.  
  413. CALL SYNTAX
  414. -----------
  415.  
  416.  typedef struct _PTRSHAPE {
  417.      USHORT cb;                 /* total length necessary to build image */
  418.      USHORT col;                /* # of columns in mouse shape */
  419.      USHORT row;                /* number of rows in mouse shape */
  420.      USHORT colHot;             /* column of pointer image hotspot */
  421.      USHORT rowHot;             /* row of pointer image hotspot */
  422.  } PTRSHAPE;
  423.  
  424.  #define INCL_MOU
  425.  
  426.  APIRET  rc = MouGetPtrShape(PtrBuffer, PtrDefRec, DeviceHandle);
  427.  
  428.  PBYTE            PtrBuffer;     /* Pointer shape buffer */
  429.  PPTRSHAPE        PtrDefRec;     /* Pointer definition struct */
  430.  HMOU             DeviceHandle;  /* Mouse device handle */
  431.  
  432.  APIRET           rc;            /* return code */
  433.  
  434.  
  435. PARAMETERS
  436. ----------
  437.  
  438.   PtrBuffer (PBYTE) - output
  439.      Address of an area in application storage where the pointer draw device
  440.      driver returns the pointer bit image.  See MouSetPtrShape for a further
  441.      description of the resulting content of this buffer.
  442.  
  443.   PtrDefRec (PPTRSHAPE) - input/output
  444.      Address of a structure in application storage where the application stores
  445.      the data necessary for the pointer device driver to return information
  446.      about the Row by Col image for each bit plane for the mode the display is
  447.      currently running.  See MouSetPtrShape for a further description of the
  448.      contents of this structure.
  449.  
  450.      TotLength (USHORT)
  451.         Length of the pointer buffer available for the pointer device driver to
  452.         build a Row by Col image for each bit plane for the mode the display is
  453.         currently running.  This value is supplied by the application.  If the
  454.         value is too small, pointer draw places the true length of the image in
  455.         this field, and returns an error.
  456.  
  457.         For all OS/2 system-supported modes, TotLength is specified in bytes and
  458.         is equal to:
  459.  
  460.         Mono & Text Modes
  461.                   For text mode height and width must be 1, so length is always 4.
  462.  
  463.                   TotLength = 4
  464.  
  465.         Graphics Mode
  466.                   Width-in-pels must be a multiple of 8.
  467.  
  468.                   TotLength = (height in pels)*(width in pels)*
  469.                               (bits per pel)*2/8
  470.  
  471.  
  472.      col (USHORT)
  473.         Number of columns in the mouse shape.  In graphics modes, this field
  474.         contains the pel width (columns) of the mouse shape for the session and
  475.         must be greater than or equal to 1. In text modes, col must equal 1.
  476.  
  477.      row (USHORT)
  478.         Number of rows in the mouse shape.  In graphics modes, this field
  479.         contains the pel height (rows) of the mouse shape for the session and
  480.         must be greater than or equal to 1. In text modes, row must equal 1.
  481.  
  482.      coloffset (USHORT)
  483.         This value is returned by the mouse device driver to indicate the
  484.         relative column offset within the pointer image.  The value defines the
  485.         center (hotspot) of the pointer image.  This value is a signed number
  486.         that represents either character or pel offset, depending on the display
  487.         mode.
  488.  
  489.      rowoffset (USHORT)
  490.         This value is returned by the mouse device driver to indicate the
  491.         relative row offset within the pointer image.  The value defines the
  492.         center (hotspot) of the pointer image.  This value is a signed number
  493.         that represents either character or pel offset, depending on the display
  494.         mode.
  495.  
  496.   DeviceHandle (HMOU) - input
  497.      Reserved value, must be zero.
  498.  
  499.  
  500. RETURNS
  501. -------
  502.      Return code descriptions are:
  503.  
  504.      0         NO_ERROR
  505.      385       ERROR_MOUSE_NO_DEVICE
  506.      387       ERROR_MOUSE_INV_PARMS
  507.      466       ERROR_MOU_DETACHED
  508.      501       ERROR_MOUSE_NO_CONSOLE
  509.  
  510.  
  511. REMARKS
  512. -------
  513.  
  514. The application passes a parameter list with the same meaning as defined for
  515. MouSetPtrShape to the mouse device driver.  The mouse device driver copies the
  516. parameters that describe the pointer shape and attributes into the pointer
  517. definition control block pointed to by the PtrDefRec parameter.  The word 0
  518. (buffer length = TotLength) pointer definition record parameter field must
  519. contain the size in bytes of the application buffer where the device driver is
  520. to insert the sessions pointer image.  All other words in the parameter list are
  521. returned to the application by MouGetPtrShape.
  522.  
  523. If the buffer size is insufficient, the TotLength field contains the actual size
  524. in bytes of the returned pointer image.
  525.  
  526. The pointer shape may be set by the application with MouSetPtrShape or may be
  527. the default image provided by the installed Pointer Device Driver.
  528.  
  529.  
  530.  
  531. MouGetScaleFact
  532. ================================================================================
  533. This call returns a pair of 1-word scaling factors for the current mouse device.
  534.  
  535.  
  536. CALL SYNTAX
  537. -----------
  538.  
  539.  typedef struct _SCALEFACT {   /* mousc */
  540.      ULONG  rowScale;            /* row scaling factor */
  541.      ULONG  colScale;            /* column coordinate scaling factor */
  542.  } SCALEFACT;
  543.  
  544.  #define INCL_MOU
  545.  
  546.  APIRET  rc = MouGetScaleFact(ScaleStruct, DeviceHandle);
  547.  
  548.  PSCALEFACT       ScaleStruct;
  549.  HMOU             DeviceHandle;  /* Mouse device handle */
  550.  
  551.  APIRET           rc;            /* return code */
  552.  
  553.  
  554. PARAMETERS
  555. ----------
  556.  
  557.   ScaleStruct (PSCALEFACT) - output
  558.      Address of the control block structure that contains the current row and
  559.      column coordinate scaling factors.  The scaling factors must be greater
  560.      than or equal to 1 and less than or equal to (32K - 1).
  561.  
  562.      rowscale (ULONG)
  563.         Row scaling factor.
  564.  
  565.      colscale (ULONG)
  566.         Column scaling factor.
  567.  
  568.         See MouSetScaleFact for more information.
  569.  
  570.   DeviceHandle (HMOU) - input
  571.      Reserved value, must be zero.
  572.  
  573.  
  574. RETURNS
  575. -------
  576.      Return code descriptions are:
  577.  
  578.      0         NO_ERROR
  579.      385       ERROR_MOUSE_NO_DEVICE
  580.      466       ERROR_MOU_DETACHED
  581.      501       ERROR_MOUSE_NO_CONSOLE
  582.  
  583.  
  584. REMARKS
  585. -------
  586.  
  587. The units of the scale factor depend on the mode of the display screen for the
  588. session.  If the screen is operating in text mode, the scaling units are
  589. relative to characters.  If the screen is operating in graphics mode, the
  590. scaling units are relative to pels.
  591.  
  592.  
  593.  
  594. MouReadEventQue
  595. ================================================================================
  596. This call reads an event from the mouse device FIFO event queue, and places it
  597. in a structure provided by the application.
  598.  
  599.  
  600. CALL SYNTAX
  601. -----------
  602.  
  603.  typedef struct _MOUEVENTINFO {  /* mouev */
  604.      ULONG  fs;                 /* Mouse state         */
  605.      LONG   row;                /* Horizontal position */
  606.      LONG   col;                /* Vertical position   */
  607.      ULONG  time;               /* Timestamp           */
  608.  } MOUEVENTINFO;
  609.  
  610.  #define INCL_MOU
  611.  
  612.  APIRET  rc = MouReadEventQue(Buffer, ReadType, DeviceHandle);
  613.  
  614.  PMOUEVENTINFO    Buffer;        /* 10 byte Structure address */
  615.  PULONG           ReadType;      /* Read type */
  616.  HMOU             DeviceHandle;  /* Mouse device handle */
  617.  
  618.  APIRET           rc;            /* return code */
  619.  
  620.  
  621. PARAMETERS
  622. ----------
  623.  
  624.   Buffer (PMOUEVENTINFO) - output
  625.      Address of the status of the mouse event queue.
  626.  
  627.      fs (ULONG)
  628.         State of the mouse at the time of the event.
  629.  
  630.         Bit       Description
  631.         31-7      Reserved, set to zero.
  632.         6         Set if button 3 is down.
  633.         5         Set if mouse is moving and button 3 is down.
  634.         4         Set if button 2 is down.
  635.         3         Set if mouse is moving and button 2 is down.
  636.         2         Set if button 1 is down.
  637.         1         Set if mouse is moving and button 1 is down.
  638.         0         Set if mouse is moving and no buttons are down.
  639.  
  640.  
  641.      row (ULONG)
  642.         Absolute or relative row position.
  643.  
  644.      col (ULONG)
  645.         Absolute or relative column position.
  646.  
  647.      time (ULONG)
  648.         Time stamp.
  649.  
  650.   ReadType (PULONG) - input
  651.      Address of the action to take when MouReadEventQue is issued and the mouse
  652.      event queue is empty.  If the mouse event queue is not empty, this
  653.      parameter is not examined by the mouse support.  ReadType values are:
  654.  
  655.      Value     Definition
  656.      0         No Wait for data on empty queue (return a NULL record)
  657.      1         WAIT for data on empty queue.
  658.  
  659.   DeviceHandle (HMOU) - input
  660.      Reserved value, must be zero.
  661.  
  662.  
  663. RETURNS
  664. -------
  665.      Return code descriptions are:
  666.  
  667.      0         NO_ERROR
  668.      385       ERROR_MOUSE_NO_DEVICE
  669.      387       ERROR_MOUSE_INV_PARMS
  670.      393       ERROR_MOUSE_NO_DATA
  671.      466       ERROR_MOU_DETACHED
  672.      501       ERROR_MOUSE_NO_CONSOLE
  673.  
  674.  
  675. REMARKS
  676. -------
  677.  
  678. The types of queued events are directly affected by the current value of the
  679. event mark.  MouSetEventMask is used to indicate the types of events
  680. desired, and MouGetEventMask is used to query the current value of the mask.
  681. Refer to these functions for further explanation of the masking of events.
  682.  
  683. The Row and Column fields in the Buffer Parameter may contain either absolute
  684. display coordinates or relative mouse motion in mickeys.  See MouSetDevStatus
  685. for additional information.
  686.  
  687. At session initialization, the event mask is zero, and thus no mouse events
  688. will be generated until a MouSetEventMask is done.
  689.  
  690. The mouse events can also be read using KbdGetConsole.
  691.  
  692.  
  693.  
  694. MouRemovePtr
  695. ================================================================================
  696. This call allows a process to notify the mouse device driver that the area
  697. defined by the passed parameters is for the exclusive use of the application.
  698. This area is defined as the collision area and is not available to the mouse
  699. device driver when drawing pointer images.
  700.  
  701.  
  702. CALL SYNTAX
  703. -----------
  704.  
  705.  typedef struct _NOPTRRECT {   /* mourt */
  706.      ULONG  row;                 /* upper left row coordinates */
  707.      ULONG  col;                 /* upper left column coordinates */
  708.      ULONG  cRow;
  709.      ULONG  cCol;
  710.  } NOPTRRECT;
  711.  
  712.  #define INCL_MOU
  713.  
  714.  APIRET  rc = MouRemovePtr(PtrArea, DeviceHandle);
  715.  
  716.  PNOPTRRECT       PtrArea;       /* Address of pointer data block */
  717.  HMOU             DeviceHandle;  /* Mouse device handle */
  718.  
  719.  APIRET           rc;            /* return code */
  720.  
  721.  
  722. PARAMETERS
  723. ----------
  724.  
  725.   PtrArea (PNOPTRRECT) - input
  726.      Address of the pointer shape collision area structure:
  727.  
  728.      leftrow (ULONG)
  729.         Upper left row coordinate (pels or characters).
  730.  
  731.      leftcol (ULONG)
  732.         Upper left column coordinate (pels or characters).
  733.  
  734.      rightrow (ULONG)
  735.         Lower right row coordinate (pels or characters).
  736.  
  737.      rightcol (ULONG)
  738.         Lower right column coordinate (pels or characters).
  739.  
  740.   DeviceHandle (HMOU) - input
  741.      Reserved value, must be zero.
  742.  
  743.  
  744. RETURNS
  745. -------
  746.      Return code descriptions are:
  747.  
  748.      0         NO_ERROR
  749.      385       ERROR_MOUSE_NO_DEVICE
  750.      387       ERROR_MOUSE_INV_PARMS
  751.      466       ERROR_MOU_DETACHED
  752.      501       ERROR_MOUSE_NO_CONSOLE
  753.  
  754.  
  755. REMARKS
  756. -------
  757.  
  758. MouRemovePtr may be issued by any process in the session.  However, only one
  759. collision area is active at a time.  Each MouRemovePtr command has the effect of
  760. resetting the collision area to the location and area specified by the current
  761. command.
  762.  
  763. If the logical pointer position is outside of the collision area specified by
  764. the latest MouRemovePtr command, the pointer image is drawn.
  765.  
  766. The MouDrawPtr command effectively cancels the MouRemovePtr command and allows
  767. the pointer to be drawn anywhere on the screen, until a new MouRemovePtr command
  768. is issued.
  769.  
  770.  
  771.  
  772. MouSetDevStatus
  773. ================================================================================
  774. This call sets the mouse device driver status flags for the installed mouse
  775. device driver.
  776.  
  777.  
  778. CALL SYNTAX
  779. -----------
  780.  #define INCL_MOU
  781.  
  782.  APIRET  rc = MouSetDevStatus(DeviceStatus, DeviceHandle);
  783.  
  784.  PULONG           DeviceStatus;  /* Status flags */
  785.  HMOU             DeviceHandle;  /* Mouse device handle */
  786.  
  787.  APIRET           rc;            /* return code */
  788.  
  789.  
  790. PARAMETERS
  791. ----------
  792.  
  793.   DeviceStatus (PULONG) - input
  794.      Address of the desired status flag settings.
  795.  
  796.      The passed parameter is a 4-byte set of flags.  Only the high-order byte
  797.      has meaning.
  798.  
  799.      Bit       Description
  800.      31-10     Reserved, set to zero.
  801.      9         Set if mouse device is to return data in mickeys.
  802.      8         Set if the drawing operations for the pointer draw routine are
  803.                to be disabled.
  804.      7-0       Reserved, set to zero.
  805.  
  806.   DeviceHandle (HMOU) - input
  807.      Reserved value, must be zero.
  808.  
  809.  
  810. RETURNS
  811. -------
  812.      Return code descriptions are:
  813.  
  814.      0         NO_ERROR
  815.      385       ERROR_MOUSE_NO_DEVICE
  816.      387       ERROR_MOUSE_INV_PARMS
  817.      466       ERROR_MOU_DETACHED
  818.      501       ERROR_MOUSE_NO_CONSOLE
  819.  
  820.  
  821. REMARKS
  822. -------
  823.  
  824.  
  825. MouSetDevStatus is the complement to MouGetDevStatus.  However, not all status
  826. flags may be set with MouSetDevStatus.  Only the flags corresponding to the
  827. following functions may be modified:
  828.  
  829. - Return data in mickeys.
  830.     Normally, mouse data is returned to the application with the absolute
  831.     display mode coordinates of the pointer image position on the display
  832.     screen.  By setting this status flag, mouse data is returned in relative
  833.     mickeys, a unit of mouse movement.
  834.  
  835. - Don't call pointer draw device.
  836.     Normally, the pointer draw device driver is called for all drawing
  837.     operations.  By setting this status flag, the mouse device driver does not
  838.     call the pointer draw device driver.  The application must draw any required
  839.     pointer image on the screen.
  840.  
  841. At session initialization, the device status is set to zero.
  842.  
  843.  
  844.  
  845. MouSetEventMask
  846. ================================================================================
  847. This call assigns a new event mask to the current mouse device driver.
  848.  
  849.  
  850. CALL SYNTAX
  851. -----------
  852.  
  853.  #define INCL_MOU
  854.  
  855.  APIRET  rc = MouSetEventMask(EventMask, DeviceHandle);
  856.  
  857.  PULONG           EventMask;     /* Mouse device event mask ptr */
  858.  HMOU             DeviceHandle;  /* Mouse device handle */
  859.  
  860.  APIRET           rc;            /* return code */
  861.  
  862.  
  863. PARAMETERS
  864. ----------
  865.  
  866.   EventMask (PULONG) - input
  867.      Address of a value in application storage used to indicate what mouse
  868.      events are to be placed on the event queue (see MouReadEventQue) and which
  869.      events are to be ignored.
  870.  
  871.      The EventMask bit values are described below:
  872.  
  873.      Bit     Description
  874.      15-7    Reserved, set to zero.
  875.      6       Report button 3 press/release events, without mouse motion
  876.      5       Report button 3 press/release events, with mouse motion
  877.      4       Report button 2 press/release events, without mouse motion
  878.      3       Report button 2 press/release events, with mouse motion
  879.      2       Report button 1 press/release events, without mouse motion
  880.      1       Report button 1 press/release events, with mouse motion
  881.      0       Mouse motion events with no button press/release events.
  882.  
  883.  
  884.      A bit clear setting (set to zero) in an EventMask bit position indicates
  885.      that the associated type of event is not reported to the application.
  886.  
  887.   DeviceHandle (HMOU) - input
  888.      Reserved value, must be zero.
  889.  
  890.  
  891. RETURNS
  892. -------
  893.      Return code descriptions are:
  894.  
  895.      0         NO_ERROR
  896.      385       ERROR_MOUSE_NO_DEVICE
  897.      466       ERROR_MOU_DETACHED
  898.      501       ERROR_MOUSE_NO_CONSOLE
  899.  
  900.  
  901. REMARKS
  902. -------
  903.  
  904. Setting a bit in the event mask means that the associated event is reported on
  905. the mouse FIFO event queue.
  906.  
  907. At session initialization, the event mask is set to zero.
  908.  
  909.  
  910.  
  911. MouSetPtrPos
  912. ================================================================================
  913. This call directs the mouse driver to set a new row and column coordinate
  914. position for the mouse pointer.
  915.  
  916.  
  917. CALL SYNTAX
  918. -----------
  919.  
  920.  typedef struct _PTRLOC {    /* moupl */
  921.      ULONG  row;               /* pointer row screen position */
  922.      ULONG  col;               /* pointer column screen position */
  923.  } PTRLOC;
  924.  
  925.  #define INCL_MOU
  926.  
  927.  APIRET  rc = MouSetPtrPos(PtrPos, DeviceHandle);
  928.  
  929.  PPTRLOC          PtrPos;        /* Double word structure */
  930.  HMOU             DeviceHandle;  /* Mouse device handle */
  931.  
  932.  APIRET           rc;            /* return code */
  933.  
  934.  
  935. PARAMETERS
  936. ----------
  937.  
  938.   PtrPos (PPTRLOC) - input
  939.      Address of the mouse pointer position structure:
  940.  
  941.      pointerrow (ULONG)
  942.         New pointer row coordinate (pels or characters).
  943.  
  944.      pointercol (ULONG)
  945.         New pointer column coordinate (pels or characters).
  946.  
  947.   DeviceHandle (HMOU) - input
  948.      Reserved value, must be zero.
  949.  
  950.  
  951. RETURNS
  952. -------
  953.      Return code descriptions are:
  954.  
  955.      0         NO_ERROR
  956.      385       ERROR_MOUSE_NO_DEVICE
  957.      387       ERROR_MOUSE_INV_PARMS
  958.      466       ERROR_MOU_DETACHED
  959.      501       ERROR_MOUSE_NO_CONSOLE
  960.  
  961.  
  962. REMARKS
  963. -------
  964.  
  965. The application must ensure that the coordinate position specified conforms to
  966. the current display mode orientation for the session.  Pel values must be used
  967. for graphics modes and character values for text modes.
  968.  
  969. This function has no effect on the display's current collision area definition
  970. as specified by the MouDrawPtr call.  If the mouse pointer image is directed
  971. into a defined collision area, the pointer image is not drawn until either the
  972. pointer is moved outside the collision area or the collision area is released by
  973. the MouDrawPtr call.
  974.  
  975. At session initialization, the pointer is set to the center of the screen,
  976. but is not drawn, because the collision area is set to the entire screen.
  977.  
  978.  
  979. MouSetPtrShape
  980. ===============================================================================
  981. This call allows a process to set the pointer shape and size to be used as the
  982. mouse device driver pointer image for all applications in a session.
  983.  
  984.  
  985. CALL SYNTAX
  986. -----------
  987.  
  988.  #define INCL_MOU
  989.  
  990.  APIRET  rc = MouSetPtrShape(PtrBuffer, PtrDefRec, DeviceHandle);
  991.  
  992.  PBYTE            PtrBuffer;     /* Pointer shape buffer */
  993.  PPTRSHAPE        PtrDefRec;     /* Pointer definition record */
  994.  HMOU             DeviceHandle;  /* Mouse device handle */
  995.  
  996.  APIRET           rc;            /* return code */
  997.  
  998.  
  999. PARAMETERS
  1000. ----------
  1001.  
  1002.   PtrBuffer (PBYTE) - input
  1003.      Address of a buffer containing the bit image used by the mouse device
  1004.      driver as the pointer shape for that session.  The buffer consists of AND
  1005.      and XOR pointer masks in a format meaningful to the pointer draw device
  1006.      driver.
  1007.  
  1008.      For text modes (0, 1, 2, and 3) the following describes the AND and XOR
  1009.      pointer mask bit definitions for each character cell of the mask:
  1010.      Bit values are:
  1011.  
  1012.      Bit       Description
  1013.      15        Blinking
  1014.      14-12     Background color
  1015.      11        Intensity
  1016.      10-8      Foreground color
  1017.      7-0       Character
  1018.  
  1019.   PtrDefRec (PPTRSHAPE) - input
  1020.      Address of the structure where the application stores the necessary data
  1021.      for the pointer draw device driver to build a row-by-column image for each
  1022.      bit plane for the current display mode.  The pointer definition record
  1023.      structure follows:
  1024.  
  1025.      TotLength (USHORT)
  1026.         The total length of the data necessary for the pointer draw device
  1027.         driver to build a row-by-column image for each bit plane for the current
  1028.         display mode.
  1029.  
  1030.         For all OS/2 system-supported modes, TotLength is specified in bytes and
  1031.         is equal to:
  1032.  
  1033.         Mono & Text Modes
  1034.                   For text mode height and width must be 1, so length is
  1035.                   always 4.
  1036.  
  1037.         Graphics Mode
  1038.                   Width-in-pels must be a multiple of 8.
  1039.  
  1040.                   TotLength = (height in pels)*(width in pels)*
  1041.                               (bits per pel)*2/8
  1042.  
  1043.      col (USHORT)
  1044.         Number of columns in the mouse shape.  In graphics modes, this field
  1045.         contains the pel width (columns) of the mouse shape for the session and
  1046.         must be greater than or equal to 1. In text modes, col must equal 1.
  1047.  
  1048.      row (USHORT)
  1049.         Number of rows in the mouse shape.  In graphics modes, this field
  1050.         contains the pel height (rows) of the mouse shape for the session and
  1051.         must be greater than or equal to 1. In text modes, row must equal 1.
  1052.  
  1053.      coloffset (USHORT)
  1054.         This value is returned by the mouse device driver to indicate the
  1055.         relative column offset within the pointer image.  The value defines the
  1056.         center (hotspot) of the pointer image.  This value is a signed number
  1057.         that represents either character or pel offset, depending on the display
  1058.         mode.
  1059.  
  1060.      rowoffset (USHORT)
  1061.         This value is returned by the mouse device driver to indicate the
  1062.         relative row offset within the pointer image.  The value defines the
  1063.         center (hotspot) of the pointer image.  This value is a signed number
  1064.         that represents either character or pel offset, depending on the display
  1065.         mode.
  1066.  
  1067.   DeviceHandle (HMOU) - input
  1068.      Reserved value, must be zero.
  1069.  
  1070.  
  1071. RETURNS
  1072. -------
  1073.      Return code descriptions are:
  1074.  
  1075.      0         NO_ERROR
  1076.      385       ERROR_MOUSE_NO_DEVICE
  1077.      387       ERROR_MOUSE_INV_PARMS
  1078.      466       ERROR_MOU_DETACHED
  1079.      501       ERROR_MOUSE_NO_CONSOLE
  1080.  
  1081.  
  1082. REMARKS
  1083. -------
  1084.  
  1085. An application passes a data image to the mouse device driver that the mouse
  1086. driver applies to the screen whenever the logical pointer position is not
  1087. located in the application-defined collision area.  The application synchronizes
  1088. use of the screen with the mouse driver by way of MouRemovePtr and MouDrawPtr.
  1089.  
  1090. The pointer shape is mapped by the Pointer Draw Device Driver and determined
  1091. completely by the application.  The height and width may vary from 1 through the
  1092. pel size of the display screen.
  1093.  
  1094.  
  1095.  
  1096. MouSetScaleFact
  1097. ================================================================================
  1098. This call assigns to the current mouse device driver a new set of scaling factors.
  1099.  
  1100.  
  1101. CALL SYNTAX
  1102. -----------
  1103.  
  1104.  typedef struct _SCALEFACT {
  1105.      ULONG  rowScale;            /* row scaling factor */
  1106.      ULONG  colScale;            /* column coordinate scaling factor */
  1107.  } SCALEFACT;
  1108.  
  1109.  #define INCL_MOU
  1110.  
  1111.  APIRET  rc = MouSetScaleFact(ScaleStruct, DeviceHandle);
  1112.  
  1113.  PSCALEFACT       ScaleStruct;
  1114.  HMOU             DeviceHandle;  /* Mouse device handle */
  1115.  
  1116.  APIRET           rc;            /* return code */
  1117.  
  1118.  
  1119. PARAMETERS
  1120. ----------
  1121.  
  1122.   ScaleStruct (PSCALEFACT) - input
  1123.      Address of the control block structure that contains the current row and
  1124.      column coordinate scaling factors.  The scaling factors must be greater
  1125.      than or equal to 1 and less than or equal to (32K - 1).
  1126.  
  1127.      rowscale (ULONG)
  1128.         Row scaling factor.
  1129.  
  1130.      colscale (ULONG)
  1131.         Column scaling factor.
  1132.  
  1133.   DeviceHandle (HMOU) - input
  1134.      Reserved value, must be zero.
  1135.  
  1136.  
  1137. RETURNS
  1138. -------
  1139.      Return code descriptions are:
  1140.  
  1141.      0         NO_ERROR
  1142.      385       ERROR_MOUSE_NO_DEVICE
  1143.      387       ERROR_MOUSE_INV_PARMS
  1144.      466       ERROR_MOU_DETACHED
  1145.      501       ERROR_MOUSE_NO_CONSOLE
  1146.  
  1147.  
  1148. REMARKS
  1149. -------
  1150.  
  1151. MouSetScaleFact sets the mickey-to-pixel ratio for mouse motion.  The row scale
  1152. and column scale ratios specify a number of mickeys for each 8 pixels.  The
  1153. default value for the row scale is 16 mickeys for each 8 pixels.  The default
  1154. value for the column scale is 8 mickeys to 8 pixels.
  1155.  
  1156. The number of pixels moved does not have to correspond 1-to-1 with the number of
  1157. mickeys the mouse moves.  The scaling factor defines a sensitivity for the mouse
  1158. that is a ratio of the number of mickeys required to move the cursor 8 pixels on
  1159. the screen.  The sensitivity determines at what rate the cursor moves on the
  1160. screen.
  1161.  
  1162.  
  1163.