MOUSE(2)                                                 MOUSE(2)

          initmouse, readmouse, closemouse, moveto, getrect,
          drawgetrect, menuhit, setcursor, enter - 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)

          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)

          int       enter(char *ask, char *buf, int len,
                         Mousectl *mc, Keyboardctl *kc, Screen *scr)

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

          The state of the mouse is recorded in a structure, Mouse,
          defined in <mouse.h>:

               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

     Page 1                       Plan 9             (printed 7/23/24)

     MOUSE(2)                                                 MOUSE(2)

          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

          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 visible.  Typically the file is nil, which
          requests the default /dev/mouse; and the image is the window
          in which the program is running, 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 reconnect 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 buf-
          fered graphics requests are displayed.

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

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

     Page 2                       Plan 9             (printed 7/23/24)

     MOUSE(2)                                                 MOUSE(2)

          Setcursor sets the image of the cursor to that specified by
          c. If c is nil, the cursor is set to the default.  The for-
          mat 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 rectangle 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 dis-
          played 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 dis-
          play, and restoring the display when the menu is removed.

          Enter is a multithreded version of the eenter function
          described in event(2). Like menuhit, it has a optional scr
          argument to create a window. Keyboard input is read from the
          channel in the Keyboardctl *kc argument (see keyboard(2)).


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

     Page 3                       Plan 9             (printed 7/23/24)