.TH MOUSE 2 .SH NAME initmouse, setmousemode, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor, Mfmt \- mouse control .SH SYNOPSIS .nf .B #include .B #include .B #include .B #include .B #include .B #include .PP .B Mousectl *initmouse(char *file, Image *i) .PP .B int setmousemode(Mousectl* mc, int mode) .PP .B int readmouse(Mousectl *mc) .PP .B int atomouse(); .PP .B void closemouse(Mousectl *mc) .PP .B void moveto(Mousectl *mc, Point pt) .PP .B void setcursor(Mousectl *mc, Cursor *c) .PP .B Rectangle getrect(int but, Mousectl *mc) .PP .B void drawgetrect(Rectangle r, int up) .PP .B int menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr) .PP .B int MCHORDB(int buttons, int idx) .PP .B int Mfmt(Fmt*) .fi .SH DESCRIPTION These functions access and control a mouse in a multi-threaded environment. They use the message-passing .B Channel interface in the threads library (see .IR thread (2)); programs that wish a more event-driven, single-threaded approach should use .IR event (2). .PP The state of the mouse is recorded in a structure, .BR Mouse , defined in .BR : .IP .EX .ta 6n +\w'Rectangle 'u +\w'buttons; 'u typedef struct Mouse Mouse; struct Mouse { int buttons; /* bit array: LMR=124 and flags */ Point xy; ulong msec; }; .EE .PP The .B Point .B xy records the position of the cursor, .B buttons the state of the buttons (in raw mode, three bits representing, from bit 0 up, the buttons from left to right, 0 if the button is released, 1 if it is pressed; in cooked mode, it also informs about mouse events, see bellow for more information on mouse modes), and .BR msec , a millisecond time stamp. .PP The routine .B initmouse returns a structure through which one may access the mouse: .IP .EX 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 */ }; .EE .PP The arguments to .I initmouse are a .I file naming the device file connected to the mouse and an .I Image (see .IR draw (2)) on which the mouse will be visible. Typically the file is nil, which requests the default .BR /dev/mouse ; and the image is the window in which the program is running, held in the variable .B screen after a call to .IR initdraw . .PP There are two ways of handling the mouse, in raw mode, messages are sent to .B Channel Mousectl.c every time the state of the mouse changes. In cooked mode, digested mouse events are transmited by .B Channel Mousectl.c. The mouse is initialized by default on raw mode. Once .I initmouse has been successfully called, .I Setmousemode can be used to switch between modes. .I Mode is one of MRAW or MCOOKED. .I Setmousemode returns the new mode, -1 on error. .PP On raw mode, a message will be sent every time a read of .B /dev/mouse succeeds. .PP On cooked mode, .B Channel Mousectl.c will only report complete or partial mouse events. .PP While on cooked mode, .B Mouse.buttons is colored with some additional flags, MCLICK, MCHORD, MDOUBLE, MEND and other info. .PP Mouse events are clicks (MCLICK), selections (MSELECT) and chords (MCHORD). Any event can be double (MDOUBLE). A single click is done by pressing and releasing in quick sucession a mouse button without moving the mouse. A double click is two sucessive clicks of the same button in a short time without moving the mouse. A chord is achieved by pressing two mouse buttons succesively and then releasing them in any order. Pressing a mouse button and moving the mouse gives you a selection. The selection can be terminated by releasing the button or by performing a chord. .PP When an event is completely recognized, it is sent with the MEND flag set. For example, an application interested in double click for the first button would check MDOUBLE|MCLICK|MEND|1. .PP While the event is still in the oven, some other half cooked or partial events may be sent so that the application can, for example draw a selection in the screen. Examples of this are click, chord and slide. Click happens whenever a button starts being pressed and none where pressed before. It marks the start of any event. Slide happens when any button is pressed and the mouse is moved. It sets the rest of the .B Mouse.buttons of the complete event. Chord happens when a second button starts being pressed. Note that the starting click of a slide may not have the MSELECT flag set, as partial events are in a sense independant. .PP Partial and complete chords set additionally the three upper nibbles of .B Mouse.buttons with the order of the first three buttons pressed. The macro MCHORDB returns which button was pressed in idx, for example the first button pressed would be .B MCHORDB(m->buttons,0). .PP The cooked mode is backwards compatible except for chord events where all the buttons which have been pressed until that moment appear as pressed on the .B Mouse.buttons. Another issue is that some libraries wait for events with no buttons pressed. This has to be changed to work with cooked mode. For example pressing button 1 then pressing and releasing button 2 and then (still not releasing button 1), pressing button 3 would give a hard double chord event with the three buttons pressed. In raw mode it would have given just two buttons pressed. .PP The variable verbstate can be set to one to print the state of the interpreter of events for debbuging purposes. The function .B Mfmt can be used to format mouse events to aid debugging. .PP If you are waiting for a MEND flag, changing to raw mode can have unpleasant consecuences. .PP When the window is resized, a message is sent on .BR Mousectl.resizec . The actual value sent may be discarded; the receipt of the message tells the program that it should call .B getwindow (see .IR graphics (2)) to reconnect to the window. .PP .I Readmouse updates the .B Mouse structure held in the .BR Mousectl , blocking if the state has not changed since the last .I readmouse or message sent on the channel. It calls .B flushimage (see .IR graphics (2)) before blocking, so any buffered graphics requests are displayed. .PP .I Closemouse closes the file descriptors associated with the mouse, kills the slave processes, and frees the .B Mousectl structure. .PP .I Moveto moves the mouse cursor on the display to the position specified by .IR pt . .PP .I Setcursor sets the image of the cursor to that specified by .IR c . If .I c is nil, the cursor is set to the default. The format of the cursor data is spelled out in .B and described in .IR graphics (2). .PP .I Getrect returns the dimensions of a rectangle swept by the user, using the mouse, in the manner .IR rio (1) or .IR sam (1) uses to create a new window. The .I 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. .PP .I Getrect uses successive calls to .I drawgetrect to maintain the red rectangle showing the sweep-in-progress. The rectangle to be drawn is specified by .I rc and the .I up parameter says whether to draw (1) or erase (0) the rectangle. .PP .I Menuhit provides a simple menu mechanism. It uses a .B Menu structure defined in .BR : .IP .EX typedef struct Menu Menu; struct Menu { char **item; char *(*gen)(int); int lasthit; }; .EE .PP .IR Menuhit behaves the same as its namesake .I emenuhit described in .IR event (2), with two exceptions. First, it uses a .B Mousectl to access the mouse rather than using the event interface; and second, it creates the menu as a true window on the .B Screen .I scr (see .IR window (2)), permitting the menu to be displayed in parallel with other activities on the display. If .I scr is null, .I menuhit behaves like .IR emenuhit , creating backing store for the menu, writing the menu directly on the display, and restoring the display when the menu is removed. .PP .SH SOURCE .B /sys/src/libdraw .SH SEE ALSO .IR graphics (2), .IR draw (2), .IR event (2), .IR keyboard (2), .IR thread (2).