tmouse.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tmouse.3 (4987B)
---
1 .TH MOUSE 3
2 .SH NAME
3 initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor \- mouse control
4 .SH SYNOPSIS
5 .nf
6 .B
7 #include <u.h>
8 .B
9 #include <libc.h>
10 .B
11 #include <draw.h>
12 .B
13 #include <thread.h>
14 .B
15 #include <mouse.h>
16 .B
17 #include <cursor.h>
18 .PP
19 .B
20 Mousectl *initmouse(char *file, Image *i)
21 .PP
22 .B
23 int readmouse(Mousectl *mc)
24 .PP
25 .B
26 int atomouse();
27 .PP
28 .B
29 void closemouse(Mousectl *mc)
30 .PP
31 .B
32 void moveto(Mousectl *mc, Point pt)
33 .PP
34 .B
35 void setcursor(Mousectl *mc, Cursor *c)
36 .PP
37 .B
38 Rectangle getrect(int but, Mousectl *mc)
39 .PP
40 .B
41 void drawgetrect(Rectangle r, int up)
42 .PP
43 .B
44 int menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)
45 .fi
46 .SH DESCRIPTION
47 These functions access and control a mouse in a multi-threaded environment.
48 They use the message-passing
49 .B Channel
50 interface in the threads library
51 (see
52 .MR thread (3) );
53 programs that wish a more event-driven, single-threaded approach should use
54 .MR event (3) .
55 .PP
56 The state of the mouse is recorded in a structure,
57 .BR Mouse ,
58 defined in
59 .BR <mouse.h> :
60 .IP
61 .EX
62 .ta 6n +\w'Rectangle 'u +\w'buttons; 'u
63 typedef struct Mouse Mouse;
64 struct Mouse
65 {
66 int buttons; /* bit array: LMR=124 */
67 Point xy;
68 ulong msec;
69 };
70 .EE
71 .PP
72 The
73 .B Point
74 .B xy
75 records the position of the cursor,
76 .B buttons
77 the state of the buttons (three bits representing, from bit 0 up, the buttons from left to right,
78 0 if the button is released, 1 if it is pressed),
79 and
80 .BR msec ,
81 a millisecond time stamp.
82 .PP
83 The routine
84 .B initmouse
85 returns a structure through which one may access the mouse:
86 .IP
87 .EX
88 typedef struct Mousectl Mousectl;
89 struct Mousectl
90 {
91 Mouse m;
92 Channel *c; /* chan(Mouse)[16] */
93 Channel *resizec; /* chan(int)[2] */
94
95 char *file;
96 int mfd; /* to mouse file */
97 int cfd; /* to cursor file */
98 int pid; /* of slave proc */
99 Image* image; /* of associated window/display */
100 };
101 .EE
102 .PP
103 The arguments to
104 .I initmouse
105 are a
106 .I file
107 naming the device file connected to the mouse and an
108 .I Image
109 (see
110 .MR draw (3) )
111 on which the mouse will be visible.
112 Typically the file is
113 nil,
114 which requests the default
115 .BR /dev/mouse ;
116 and the image is the window in which the program is running, held in the variable
117 .B screen
118 after a call to
119 .IR initdraw .
120 .PP
121 Once the
122 .B Mousectl
123 is set up,
124 mouse motion will be reported by messages of type
125 .B Mouse
126 sent on the
127 .B Channel
128 .BR Mousectl.c .
129 Typically, a message will be sent every time a read of
130 .B /dev/mouse
131 succeeds, which is every time the state of the mouse changes.
132 .PP
133 When the window is resized, a message is sent on
134 .BR Mousectl.resizec .
135 The actual value sent may be discarded; the receipt of the message
136 tells the program that it should call
137 .B getwindow
138 (see
139 .MR graphics (3) )
140 to reconnect to the window.
141 .PP
142 .I Readmouse
143 updates the
144 .B Mouse
145 structure
146 .B m
147 held in the
148 .BR Mousectl ,
149 blocking if the state has not changed since the last
150 .I readmouse
151 or message sent on the channel.
152 It calls
153 .B flushimage
154 (see
155 .MR graphics (3) )
156 before blocking, so any buffered graphics requests are displayed.
157 .PP
158 .I Closemouse
159 closes the file descriptors associated with the mouse, kills the slave processes,
160 and frees the
161 .B Mousectl
162 structure.
163 .PP
164 .I Moveto
165 moves the mouse cursor on the display to the position specified by
166 .IR pt .
167 .PP
168 .I Setcursor
169 sets the image of the cursor to that specified by
170 .IR c .
171 If
172 .I c
173 is nil, the cursor is set to the default.
174 The format of the cursor data is spelled out in
175 .B <cursor.h>
176 and described in
177 .MR graphics (3) .
178 .PP
179 .I Getrect
180 returns the dimensions of a rectangle swept by the user, using the mouse,
181 in the manner
182 .MR rio (1)
183 or
184 .MR sam (1)
185 uses to create a new window.
186 The
187 .I but
188 argument specifies which button the user must press to sweep the window;
189 any other button press cancels the action.
190 The returned rectangle is all zeros if the user cancels.
191 .PP
192 .I Getrect
193 uses successive calls to
194 .I drawgetrect
195 to maintain the red rectangle showing the sweep-in-progress.
196 The rectangle to be drawn is specified by
197 .I rc
198 and the
199 .I up
200 parameter says whether to draw (1) or erase (0) the rectangle.
201 .PP
202 .I Menuhit
203 provides a simple menu mechanism.
204 It uses a
205 .B Menu
206 structure defined in
207 .BR <mouse.h> :
208 .IP
209 .EX
210 typedef struct Menu Menu;
211 struct Menu
212 {
213 char **item;
214 char *(*gen)(int);
215 int lasthit;
216 };
217 .EE
218 .PP
219 .IR Menuhit
220 behaves the same as its namesake
221 .I emenuhit
222 described in
223 .MR event (3) ,
224 with two exceptions.
225 First, it uses a
226 .B Mousectl
227 to access the mouse rather than using the event interface;
228 and second,
229 it creates the menu as a true window on the
230 .B Screen
231 .I scr
232 (see
233 .MR window (3) ),
234 permitting the menu to be displayed in parallel with other activities on the display.
235 If
236 .I scr
237 is null,
238 .I menuhit
239 behaves like
240 .IR emenuhit ,
241 creating backing store for the menu, writing the menu directly on the display, and
242 restoring the display when the menu is removed.
243 .PP
244 .SH SOURCE
245 .B \*9/src/libdraw
246 .SH SEE ALSO
247 .MR graphics (3) ,
248 .MR draw (3) ,
249 .MR event (3) ,
250 .MR keyboard (3) ,
251 .MR thread (3) .