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