Ada95/html/curs_mouse.3x.html

   1 <HTML>
   2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
   3 <PRE>
   4        <STRONG>getmouse</STRONG>,  <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG> - mouse interface through
   5        curses
   6
   7
   8 </PRE>
   9 <H2>SYNOPSIS</H2><PRE>
  10        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  11
  12        <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
  13
  14        <STRONG>typedef</STRONG> <STRONG>struct</STRONG>
  15        <STRONG>{</STRONG>
  16            <STRONG>short</STRONG> <STRONG>id;</STRONG>         <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM>
  17            <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG>      <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM>
  18            <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG>   <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM>
  19        <STRONG>}</STRONG>
  20        <STRONG>MEVENT;</STRONG>
  21        <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
  22        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
  23        <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <STRONG>newmask,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*oldmask);</STRONG>
  24        <STRONG>bool</STRONG> <STRONG>wenclose(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x)</STRONG>
  25        <STRONG>int</STRONG> <STRONG>mouseinterval(int</STRONG> <STRONG>erval)</STRONG>
  26
  27
  28 </PRE>
  29 <H2>DESCRIPTION</H2><PRE>
  30        These functions provide an interface to mouse events  from
  31        <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.   Mouse  events  are represented by <STRONG>KEY_MOUSE</STRONG>
  32        pseudo-key values in the <STRONG>wgetch</STRONG> input stream.
  33
  34        To make mouse events visible, use the <STRONG>mousemask</STRONG>  function.
  35        This  will  set  the  mouse  events  to  be  reported.  By
  36        default, no mouse events are reported.  The function  will
  37        return  a  mask  to  indicate which of the specified mouse
  38        events can be reported; on complete failure it returns  0.
  39        If  oldmask is non-NULL, this function fills the indicated
  40        location with the previous value  of  the  given  window's
  41        mouse event mask.
  42
  43        As  a  side  effect, setting a zero mousemask may turn off
  44        the mouse pointer; setting a nonzero mask may turn it  on.
  45        Whether this happens is device-dependent.
  46
  47        Here are the mouse event type masks:
  48
  49        l  l  _ _ l l.  <EM>Name</EM> <EM>Description</EM> BUTTON1_PRESSED     mouse
  50        button 1 down BUTTON1_RELEASED    mouse button 1  up  BUT-
  51        TON1_CLICKED        mouse       button      1      clicked
  52        BUTTON1_DOUBLE_CLICKED   mouse  button  1  double  clicked
  53        BUTTON1_TRIPLE_CLICKED   mouse  button  1  triple  clicked
  54        BUTTON2_PRESSED       mouse      button       2       down
  55        BUTTON2_RELEASED    mouse   button  2  up  BUTTON2_CLICKED
  56            mouse button 2 clicked  BUTTON2_DOUBLE_CLICKED   mouse
  57        button  2  double  clicked  BUTTON2_TRIPLE_CLICKED   mouse
  58        button 2 triple clicked BUTTON3_PRESSED     mouse button 3
  59        down BUTTON3_RELEASED    mouse button 3 up BUTTON3_CLICKED
  60        button 3 triple clicked BUTTON4_PRESSED     mouse button 4
  61        down BUTTON4_RELEASED    mouse button 4 up BUTTON4_CLICKED
  62            mouse button 4 clicked  BUTTON4_DOUBLE_CLICKED   mouse
  63        button  4  double  clicked  BUTTON4_TRIPLE_CLICKED   mouse
  64        button 4 triple clicked BUTTON_SHIFT   shift was down dur-
  65        ing  button  state  change BUTTON_CTRL    control was down
  66        during button state  change  BUTTON_ALT     alt  was  down
  67        during  button state change ALL_MOUSE_EVENTS    report all
  68        button state changes REPORT_MOUSE_POSITION    report mouse
  69        movement
  70
  71        Once  a  class of mouse events have been made visible in a
  72        window, calling the <STRONG>wgetch</STRONG> function  on  that  window  may
  73        return  <STRONG>KEY_MOUSE</STRONG>  as  an indicator that a mouse event has
  74        been queued.  To read the event data and pop the event off
  75        the queue, call <STRONG>getmouse</STRONG>.  This function will return <STRONG>OK</STRONG> if
  76        a mouse event is actually visible in the given window, <STRONG>ERR</STRONG>
  77        otherwise.   When  <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited
  78        as y and x in the  event  structure  coordinates  will  be
  79        screen-relative  character-cell coordinates.  The returned
  80        state mask will have exactly one bit set to  indicate  the
  81        event type.
  82
  83        The  <STRONG>ungetmouse</STRONG>  function  behaves analogously to <STRONG>ungetch</STRONG>.
  84        It pushes a <STRONG>KEY_MOUSE</STRONG> event  onto  the  input  queue,  and
  85        associates  with  that  event  the  given  state  data and
  86        screen-relative character-cell coordinates.
  87
  88        The <STRONG>wenclose</STRONG>  function  tests  whether  a  given  pair  of
  89        screen-relative  character-cell coordinates is enclosed by
  90        a given window, returning TRUE if it is and  FALSE  other-
  91        wise.   It  is  useful  for determining what subset of the
  92        screen windows enclose the location of a mouse event.
  93
  94        The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thou-
  95        sands  of  a  second)  that  can  elapse between press and
  96        release events in order for them to  be  recognized  as  a
  97        click.  This function returns the previous interval value.
  98        The default is one fifth of a second.
  99
 100        Note that mouse events will be ignored when  input  is  in
 101        cooked mode, and will cause an error beep when cooked mode
 102        is being simulated in a window by a function such as  <STRONG>get-</STRONG>
 103        <STRONG>str</STRONG> that expects a linefeed for input-loop termination.
 104
 105
 106
 107 </PRE>
 108 <H2>RETURN VALUE</H2><PRE>
 109        All  routines  return  the  integer <STRONG>ERR</STRONG> upon failure or <STRONG>OK</STRONG>
 110        upon successful completion.
 111
 112
 113 </PRE>
 114 <H2>PORTABILITY</H2><PRE>
 115        These calls were designed for  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  and  are  not
 116
 117        The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the
 118        preprocessor  can  be  used to test whether these features
 119        are present (its value is 1).   NOTE:  THIS  INTERFACE  IS
 120        EXPERIMENTAL  AND IS SUBJECT TO CHANGE WITHOUT NOTICE!  If
 121        the interface is changed, the value of  <STRONG>NCURSES_MOUSE_VER-</STRONG>
 122        <STRONG>SION</STRONG> will be incremented.
 123
 124        The  order  of the <STRONG>MEVENT</STRONG> structure members is not guaran-
 125        teed.  Additional fields may be added to the structure  in
 126        the future.
 127
 128        Under  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  these  calls  are  implemented  using
 129        either xterm's built-in mouse-tracking API  or  Alessandro
 130        Rubini's  gpm  server.   If  you are using something other
 131        than xterm there is no gpm daemon running on your machine,
 132        mouse  events  will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> (and the
 133        <STRONG>wmousemask</STRONG> function will always return <STRONG>0</STRONG>).
 134
 135        The z member in the event structure is not presently used.
 136        It  is  intended  for use with touch screens (which may be
 137        pressure-sensitive)   or   with   3D-mice/trackballs/power
 138        gloves.
 139
 140
 141 </PRE>
 142 <H2>BUGS</H2><PRE>
 143        Mouse  events under xterm will not in fact be ignored dur-
 144        ing cooked mode, if they have been enabled by  <STRONG>wmousemask</STRONG>.
 145        Instead,  the  xterm  mouse report sequence will appear in
 146        the string read.
 147
 148        Mouse events under xterm will not be detected correctly in
 149        a window with its keypad bit off.
 150
 151
 152 </PRE>
 153 <H2>SEE ALSO</H2><PRE>
 154        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>.
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172 </PRE>
 173 </BODY>
 174 </HTML>