window 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244
  1. .TH WINDOW 2
  2. .SH NAME
  3. Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow \- window management
  4. .SH SYNOPSIS
  5. .nf
  6. .B
  7. #include <u.h>
  8. .B
  9. #include <libc.h>
  10. .B
  11. #include <draw.h>
  12. .PP
  13. .ft L
  14. .nf
  15. typedef
  16. struct Screen
  17. {
  18. Display *display; /* display holding data */
  19. int id; /* id of system-held Screen */
  20. Image *image; /* unused; for reference only */
  21. Image *fill; /* color to paint behind windows */
  22. } Screen;
  23. .fi
  24. .ta \w'\fLScreen* 'u
  25. .PP
  26. .B
  27. Screen* allocscreen(Image *image, Image *fill, int public)
  28. .PP
  29. .B
  30. Screen* publicscreen(Display *d, int id, ulong chan)
  31. .PP
  32. .B
  33. int freescreen(Screen *s)
  34. .PP
  35. .B
  36. Image* allocwindow(Screen *s, Rectangle r, int ref, int val)
  37. .PP
  38. .B
  39. void bottomwindow(Image *w)
  40. .PP
  41. .B
  42. void bottomnwindows(Image **wp, int nw)
  43. .PP
  44. .B
  45. void topwindow(Image *w)
  46. .PP
  47. .B
  48. void topnwindows(Image **wp, int nw)
  49. .PP
  50. .B
  51. int originwindow(Image *w, Point log, Point scr)
  52. .PP
  53. .ft L
  54. .nf
  55. enum
  56. {
  57. /* refresh methods */
  58. Refbackup = 0,
  59. Refnone = 1,
  60. Refmesg = 2
  61. };
  62. .fi
  63. .ft P
  64. .SH DESCRIPTION
  65. Windows are represented as
  66. .B Images
  67. and may be treated as regular images for all drawing operations.
  68. The routines discussed here permit the creation, deletion, and shuffling
  69. of windows, facilities that do not apply to regular images.
  70. .PP
  71. To create windows, it is first necessary to allocate a
  72. .B Screen
  73. data structure to gather them together.
  74. A
  75. .B Screen
  76. turns an arbitrary image into something that may have windows upon it.
  77. It is created by
  78. .BR allocscreen ,
  79. which takes an
  80. .I image
  81. upon which to place the windows (typically
  82. .BR display->image ),
  83. a
  84. .I fill
  85. image to paint the background behind all the windows on the image,
  86. and a flag specifying whether the result should be publicly visible.
  87. If it is public, an arbitrary other program connected to the same
  88. display may acquire a pointer to the same screen by calling
  89. .B publicscreen
  90. with the
  91. .B Display
  92. pointer and the
  93. .I id
  94. of the published
  95. .BR Screen ,
  96. as well as the expected channel descriptor, as a safety check.
  97. It will usually require some out-of-band coordination for programs to share a screen profitably.
  98. .B Freescreen
  99. releases a
  100. .BR Screen ,
  101. although it may not actually disappear from view until all the windows upon it have also been deallocated.
  102. .PP
  103. Unlike
  104. .BR allocwindow ,
  105. .B allocscreen
  106. does
  107. .I not
  108. initialize the appearance of the
  109. .BR Screen .
  110. .PP
  111. Windows are created by
  112. .BR allocwindow ,
  113. which takes a pointer to the
  114. .B Screen
  115. upon which to create the window, a rectangle
  116. .I r
  117. defining its geometry, an integer pixel value
  118. .I val
  119. to color the window initially, and a refresh method
  120. .BR ref .
  121. The refresh methods are
  122. .BR Refbackup ,
  123. which provides backing store and is the method used by
  124. .IR rio (1)
  125. for its clients;
  126. .BR Refnone ,
  127. which provides no refresh and is designed for temporary uses
  128. such as sweeping a display rectangle, for windows that are
  129. completely covered by other windows, and for windows that
  130. are already protected by backing store; and
  131. .BR Refmesg ,
  132. which causes messages to be delivered to the owner of the window
  133. when it needs to be repainted.
  134. .B Refmesg
  135. is not fully implemented.
  136. .PP
  137. The result of
  138. .B allocwindow
  139. is an
  140. .B Image
  141. pointer that may be treated like any other image.
  142. In particular, it is freed by calling
  143. .B freeimage
  144. (see
  145. .IR allocimage (2)).
  146. The following functions, however, apply only to windows, not regular images.
  147. .PP
  148. .B Bottomwindow
  149. pushes window
  150. .I w
  151. to the bottom of the stack of windows on its
  152. .BR Screen ,
  153. perhaps obscuring it.
  154. .B Topwindow
  155. pulls window
  156. .I w
  157. to the top, making it fully visible on its
  158. .BR Screen .
  159. (This
  160. .B Screen
  161. may itself be within a window that is not fully visible;
  162. .B topwindow
  163. will not affect the stacking of this parent window.)
  164. .B Bottomnwindows
  165. and
  166. .B Topnwindows
  167. are analogous, but push or pull a group of
  168. .I nw
  169. windows listed in the array
  170. .IR wp .
  171. The order within
  172. .IR wp
  173. is unaffected.
  174. .PP
  175. Each window is created as an
  176. .B Image
  177. whose
  178. .B Rectangle
  179. .B r
  180. corresponds to the rectangle given to
  181. .B allocwindow
  182. when it was created. Thus, a newly created window
  183. .I w
  184. resides on its
  185. .B Screen->image
  186. at
  187. .IB w ->r
  188. and has internal coordinates
  189. .IB w ->r .
  190. Both these may be changed by a call to
  191. .BR originwindow .
  192. The two
  193. .B Point
  194. arguments to
  195. .B originwindow
  196. define the upper left corner of the logical coordinate system
  197. .RI ( log )
  198. and screen position
  199. .RI ( scr ).
  200. Their usage is shown in the Examples section.
  201. .PP
  202. .IR Rio (1)
  203. creates its client windows with backing store,
  204. .BR Refbackup .
  205. The graphics initialization routine,
  206. .B initdraw
  207. (see
  208. .IR graphics (2)),
  209. builds a
  210. .B Screen
  211. upon this, and then allocates upon that another window indented
  212. to protect the border. That window is created
  213. .BR Refnone ,
  214. since the backing store created by
  215. .B rio
  216. protects its contents. That window is the one known in the
  217. library by the global name
  218. .B screen
  219. (a historic but confusing choice).
  220. .SH EXAMPLES
  221. To move a window to the upper left corner of the display,
  222. .EX
  223. originwindow(w, w->r.min, Pt(0, 0));
  224. .EE
  225. To leave a window where it is on the screen but change its internal
  226. coordinate system so (0,\ 0) is the upper left corner of the window,
  227. .EX
  228. originwindow(w, Pt(0, 0), w->r.min);
  229. .EE
  230. After this is done,
  231. .B w->r
  232. is translated to the origin and there will be no way to discover the
  233. actual screen position of the window unless it is recorded separately.
  234. .SH SOURCE
  235. .B /sys/src/libdraw
  236. .SH SEE ALSO
  237. .IR graphics (2),
  238. .IR draw (2),
  239. .IR cachechars (2),
  240. .IR draw (3)
  241. .SH BUGS
  242. The refresh method
  243. .B Refmesg
  244. should be finished.