twindow.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
twindow.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.