MOUSE(2)                                                 MOUSE(2)

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

     SYNOPSIS
          #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)

     DESCRIPTION
          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
          state of the buttons (three bits representing, from bit 0

     Page 1                       Plan 9            (printed 12/25/24)

     MOUSE(2)                                                 MOUSE(2)

          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
               {
                     Mouse;
                     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
          structure.

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

     Page 2                       Plan 9            (printed 12/25/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.

     SOURCE
          /sys/src/libdraw

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

     Page 3                       Plan 9            (printed 12/25/24)