window.3 (5526B)
1 .TH WINDOW 3 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 .MR 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 .MR allocimage (3) ). 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 .MR Rio (1) 203 creates its client windows with backing store, 204 .BR Refbackup . 205 The graphics initialization routine, 206 .B initdraw 207 (see 208 .MR graphics (3) ), 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 \*9/src/libdraw 236 .SH SEE ALSO 237 .MR graphics (3) , 238 .MR draw (3) , 239 .MR cachechars (3) , 240 .MR draw (3) 241 .SH BUGS 242 The refresh method 243 .B Refmesg 244 should be finished.