home | help 
MOUSE(3)		    Library Functions Manual			MOUSE(3)

NAME
     initmouse,  readmouse,  closemouse,  moveto, cursorswitch, getrect, drawge-
     trect, 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((3)));  programs  that wish a more event-driven, single-threaded ap-
     proach should use event((3)).

     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 up, the buttons from	left  to
     right,  0	if the button is released, 1 if it is pressed), and msec, a mil-
     lisecond time stamp.

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

	    typedef struct Mousectl Mousectl;
	    struct Mousectl
	    {
		  Mouse     m;
		  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((3))) 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 ac-
     tual value sent may be discarded; the receipt of the message tells the pro-
     gram that it should call getwindow (see graphics((3))) to reconnect to  the
     window.

     Readmouse	updates  the Mouse structure m 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((3))) 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((3)).

     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  win-
     dow;  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  rectan-
     gle.

     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((3)),
     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((3))), 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 display, and restoring the display when  the  menu
     is removed.

SOURCE
     /src/libdraw

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

									MOUSE(3)
home | help