mouse 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. .TH MOUSE 2
  2. .SH NAME
  3. initmouse, readmouse, closemouse, moveto, 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. .IR thread (2));
  53. programs that wish a more event-driven, single-threaded approach should use
  54. .IR event (2).
  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;
  92. Channel *c; /* chan(Mouse)[16] */
  93. Channel *resizec; /* chan(int)[2] */
  94. char *file;
  95. int mfd; /* to mouse file */
  96. int cfd; /* to cursor file */
  97. int pid; /* of slave proc */
  98. Image* image; /* of associated window/display */
  99. };
  100. .EE
  101. .PP
  102. The arguments to
  103. .I initmouse
  104. are a
  105. .I file
  106. naming the device file connected to the mouse and an
  107. .I Image
  108. (see
  109. .IR draw (2))
  110. on which the mouse will be visible.
  111. Typically the file is
  112. nil,
  113. which requests the default
  114. .BR /dev/mouse ;
  115. and the image is the window in which the program is running, held in the variable
  116. .B screen
  117. after a call to
  118. .IR initdraw .
  119. .PP
  120. Once the
  121. .B Mousectl
  122. is set up,
  123. mouse motion will be reported by messages of type
  124. .B Mouse
  125. sent on the
  126. .B Channel
  127. .BR Mousectl.c .
  128. Typically, a message will be sent every time a read of
  129. .B /dev/mouse
  130. succeeds, which is every time the state of the mouse changes.
  131. .PP
  132. When the window is resized, a message is sent on
  133. .BR Mousectl.resizec .
  134. The actual value sent may be discarded; the receipt of the message
  135. tells the program that it should call
  136. .B getwindow
  137. (see
  138. .IR graphics (2))
  139. to reconnect to the window.
  140. .PP
  141. .I Readmouse
  142. updates the
  143. .B Mouse
  144. structure held in the
  145. .BR Mousectl ,
  146. blocking if the state has not changed since the last
  147. .I readmouse
  148. or message sent on the channel.
  149. It calls
  150. .B flushimage
  151. (see
  152. .IR graphics (2))
  153. before blocking, so any buffered graphics requests are displayed.
  154. .PP
  155. .I Closemouse
  156. closes the file descriptors associated with the mouse, kills the slave processes,
  157. and frees the
  158. .B Mousectl
  159. structure.
  160. .PP
  161. .I Moveto
  162. moves the mouse cursor on the display to the position specified by
  163. .IR pt .
  164. .PP
  165. .I Setcursor
  166. sets the image of the cursor to that specified by
  167. .IR c .
  168. If
  169. .I c
  170. is nil, the cursor is set to the default.
  171. The format of the cursor data is spelled out in
  172. .B <cursor.h>
  173. and described in
  174. .IR graphics (2).
  175. .PP
  176. .I Getrect
  177. returns the dimensions of a rectangle swept by the user, using the mouse,
  178. in the manner
  179. .IR rio (1)
  180. or
  181. .IR sam (1)
  182. uses to create a new window.
  183. The
  184. .I but
  185. argument specifies which button the user must press to sweep the window;
  186. any other button press cancels the action.
  187. The returned rectangle is all zeros if the user cancels.
  188. .PP
  189. .I Getrect
  190. uses successive calls to
  191. .I drawgetrect
  192. to maintain the red rectangle showing the sweep-in-progress.
  193. The rectangle to be drawn is specified by
  194. .I rc
  195. and the
  196. .I up
  197. parameter says whether to draw (1) or erase (0) the rectangle.
  198. .PP
  199. .I Menuhit
  200. provides a simple menu mechanism.
  201. It uses a
  202. .B Menu
  203. structure defined in
  204. .BR <mouse.h> :
  205. .IP
  206. .EX
  207. typedef struct Menu Menu;
  208. struct Menu
  209. {
  210. char **item;
  211. char *(*gen)(int);
  212. int lasthit;
  213. };
  214. .EE
  215. .PP
  216. .IR Menuhit
  217. behaves the same as its namesake
  218. .I emenuhit
  219. described in
  220. .IR event (2),
  221. with two exceptions.
  222. First, it uses a
  223. .B Mousectl
  224. to access the mouse rather than using the event interface;
  225. and second,
  226. it creates the menu as a true window on the
  227. .B Screen
  228. .I scr
  229. (see
  230. .IR window (2)),
  231. permitting the menu to be displayed in parallel with other activities on the display.
  232. If
  233. .I scr
  234. is null,
  235. .I menuhit
  236. behaves like
  237. .IR emenuhit ,
  238. creating backing store for the menu, writing the menu directly on the display, and
  239. restoring the display when the menu is removed.
  240. .PP
  241. .SH SOURCE
  242. .B /sys/src/libdraw
  243. .SH SEE ALSO
  244. .IR graphics (2),
  245. .IR draw (2),
  246. .IR event (2),
  247. .IR keyboard (2),
  248. .IR thread (2).