term% ls -F
term% cat index.txt
MOUSE(2)                      System Calls Manual                     MOUSE(2)

       initmouse,   readmouse,   closemouse,   moveto,  getrect,  drawgetrect,
       menuhit, setcursor - mouse control

       #include <u.h>
       #include <libc.h>
       #include <draw.h>
       #include <thread.h>
       #include <mouse.h>
       #include <cursor.h>

       Mousectl  *initmouse(char *file, Image *i)

       int       readmouse(Mousectl *mc)

       int       atomouse();

       void      closemouse(Mousectl *mc)

       void      moveto(Mousectl *mc, Point pt)

       void      setcursor(Mousectl *mc, Cursor *c)

       Rectangle getrect(int but, Mousectl *mc)

       void      drawgetrect(Rectangle r, int up)

       int       menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)

       These functions access and control a mouse in a multi-threaded environ‐
       ment.   They  use  the message-passing Channel interface in the threads
       library (see thread(2)); programs that wish a more  event-driven,  sin‐
       gle-threaded approach should use event(2).

       The  state  of  the mouse is recorded in a structure, Mouse, defined in

              typedef struct Mouse Mouse;
              struct Mouse
                    int       buttons;   /* bit array: LMR=124 */
                    Point     xy;
                    ulong     msec;

       The Point xy records the position of the cursor, buttons the  state  of
       the  buttons  (three bits representing, from bit 0 up, the buttons from
       left to right, 0 if the button is released, 1 if it  is  pressed),  and
       msec, a millisecond time stamp.

       The  routine initmouse returns a structure through which one may access
       the mouse:

              typedef struct Mousectl Mousectl;
              struct Mousectl
                    Channel   *c;        /* chan(Mouse)[16] */
                    Channel   *resizec;  /* chan(int)[2] */

                    char      *file;
                    int       mfd;       /* to mouse file */
                    int       cfd;       /* to cursor file */
                    int       pid;       /* of slave proc */
                    Image*    image;     /* of associated window/display */

       The arguments to initmouse are a file naming the device file  connected
       to the mouse and an Image (see draw(2)) on which the mouse will be vis‐
       ible.   Typically  the  file  is  nil,  which  requests   the   default
       /dev/mouse;  and  the  image is the window in which the program is run‐
       ning, held in the variable screen after a call to initdraw.

       Once the Mousectl is set up, mouse motion will be reported by  messages
       of  type  Mouse  sent  on the Channel Mousectl.c.  Typically, a message
       will be sent every time a read of /dev/mouse succeeds, which  is  every
       time the state of the mouse changes.

       When the window is resized, a message is sent on Mousectl.resizec.  The
       actual value sent may be discarded; the receipt of  the  message  tells
       the  program  that it should call getwindow (see graphics(2)) to recon‐
       nect to the window.

       Readmouse updates the Mouse structure held in the Mousectl, blocking if
       the  state  has not changed since the last readmouse or message sent on
       the channel.  It calls flushimage (see graphics(2)) before blocking, so
       any buffered graphics requests are displayed.

       Closemouse closes the file descriptors associated with the mouse, kills
       the slave processes, and frees the Mousectl structure.

       Moveto moves the mouse cursor on the display to the position  specified
       by pt.

       Setcursor sets the image of the cursor to that specified by c.  If c is
       nil, the cursor is set to the default.  The format of the  cursor  data
       is spelled out in <cursor.h> and described in graphics(2).

       Getrect  returns the dimensions of a rectangle swept by the user, using
       the mouse, in the manner rio(1) or sam(1) uses to create a new  window.
       The  but  argument  specifies which button the user must press to sweep
       the window; any other button press cancels the  action.   The  returned
       rectangle is all zeros if the user cancels.

       Getrect  uses  successive calls to drawgetrect to maintain the red rec‐
       tangle showing the sweep-in-progress.  The rectangle  to  be  drawn  is
       specified  by rc and the up parameter says whether to draw (1) or erase
       (0) the rectangle.

       Menuhit provides a simple menu mechanism.  It  uses  a  Menu  structure
       defined in <mouse.h>:

              typedef struct Menu Menu;
              struct Menu
                    char      **item;
                    char      *(*gen)(int);
                    int       lasthit;

       Menuhit  behaves  the  same  as  its  namesake  emenuhit  described  in
       event(2), with two exceptions.  First, it uses a Mousectl to access the
       mouse rather than using the event interface; and second, it creates the
       menu as a true window on the Screen scr (see window(2)), permitting the
       menu  to be displayed in parallel with other activities on the display.
       If scr is null, menuhit behaves like emenuhit, creating  backing  store
       for  the  menu, writing the menu directly on the display, and restoring
       the display when the menu is removed.


       graphics(2), draw(2), event(2), keyboard(2), thread(2).