Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1991-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Wm - Communicate with window manager | |
11 | ||
12 | =for category Tk Geometry Management | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | S< >I<$toplevel>-E<gt>I<method>(?I<args>?) | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | The B<wm> methods are used to interact with window managers in | |
21 | order to control such things as the title for a window, its geometry, | |
22 | or the increments in terms of which it may be resized. | |
23 | The B<wm> methods can take any of a number of different forms, depending on | |
24 | the particular I<method> argument. | |
25 | All of the forms expect I<$toplevel>, which must be a | |
26 | top-level window object. | |
27 | ||
28 | The legal forms for the B<wm> methods are: | |
29 | ||
30 | =over 4 | |
31 | ||
32 | =item I<$toplevel>-E<gt>B<aspect>(?I<minNumer minDenom maxNumer maxDenom>?) | |
33 | ||
34 | If I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom> | |
35 | are all specified, then they will be passed to the window manager | |
36 | and the window manager should use them to enforce a range of | |
37 | acceptable aspect ratios for I<$toplevel>. The aspect ratio of | |
38 | I<$toplevel> (width/length) will be constrained to lie | |
39 | between I<minNumer>/I<minDenom> and I<maxNumer>/I<maxDenom>. | |
40 | If I<minNumer> etc. are all specified as empty strings, then | |
41 | any existing aspect ratio restrictions are removed. | |
42 | If I<minNumer> etc. are specified, then the method returns an | |
43 | empty string. Otherwise, it returns | |
44 | a array containing four elements, which are the current values | |
45 | of I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom> | |
46 | (if no aspect restrictions are in effect, then an empty string is | |
47 | returned). | |
48 | ||
49 | =item I<$toplevel>-E<gt>B<client>(?I<name>?) | |
50 | ||
51 | If I<name> is specified, this method stores I<name> (which | |
52 | should be the name of | |
53 | the host on which the application is executing) in I<$toplevel>'s | |
54 | B<WM_CLIENT_MACHINE> property for use by the window manager or | |
55 | session manager. | |
56 | The method returns an empty string in this case. | |
57 | If I<name> isn't specified, the method returns the last name | |
58 | set in a B<client> method for I<$toplevel>. | |
59 | If I<name> is specified as an empty string, the method deletes the | |
60 | B<WM_CLIENT_MACHINE> property from I<$toplevel>. | |
61 | ||
62 | =item I<$toplevel>-E<gt>B<colormapwindows>(?I<windowList>?) | |
63 | ||
64 | This method is used to manipulate the B<WM_COLORMAP_WINDOWS> | |
65 | property, which provides information to the window managers about | |
66 | windows that have private colormaps. | |
67 | If I<windowList> isn't specified, the method returns a list | |
68 | whose elements are the names of the windows in the B<WM_COLORMAP_WINDOWS> | |
69 | property. | |
70 | If I<windowList> is specified, it consists of a list of widgets; | |
71 | the method overwrites the B<WM_COLORMAP_WINDOWS> | |
72 | property with the given windows and returns an empty string. | |
73 | The B<WM_COLORMAP_WINDOWS> property should normally contain a | |
74 | list of the internal windows within I<$toplevel> whose colormaps differ | |
75 | from their parents. | |
76 | The order of the windows in the property indicates a priority order: | |
77 | the window manager will attempt to install as many colormaps as possible | |
78 | from the head of this list when I<$widget> gets the colormap focus. | |
79 | If I<$widget> is not included among the windows in I<windowList>, | |
80 | Tk implicitly adds it at the end of the B<WM_COLORMAP_WINDOWS> | |
81 | property, so that its colormap is lowest in priority. | |
82 | If I<$widget>-E<gt>colormapwindows is not invoked, Tk will automatically set | |
83 | the property for each top-level window to all the internal windows | |
84 | whose colormaps differ from their parents, followed by the top-level | |
85 | itself; the order of the internal windows is undefined. | |
86 | See the ICCCM documentation for more information on the | |
87 | B<WM_COLORMAP_WINDOWS> property. | |
88 | ||
89 | =item I<$toplevel>-E<gt>B<command>(?I<value>?) | |
90 | ||
91 | If I<value> is specified, this method stores I<value> in I<$toplevel>'s | |
92 | B<WM_COMMAND> property for use by the window manager or | |
93 | session manager and returns an empty string. | |
94 | I<Value> must have proper list structure; the elements should | |
95 | contain the words of the command used to invoke the application. | |
96 | If I<value> isn't specified then the method returns the last value | |
97 | set in a B<command> method for I<$toplevel>. | |
98 | If I<value> is specified as an empty string, the method | |
99 | deletes the B<WM_COMMAND> property from I<$toplevel>. | |
100 | ||
101 | =item I<$toplevel>-E<gt>B<deiconify> | |
102 | ||
103 | Arrange for I<$toplevel> to be displayed in normal (non-iconified) form. | |
104 | This is done by mapping the window. If the window has never been | |
105 | mapped then this method will not map the window, but it will ensure | |
106 | that when the window is first mapped it will be displayed | |
107 | in de-iconified form. Returns an empty string. | |
108 | ||
109 | =item I<$toplevel>-E<gt>B<focusmodel>(?B<active>|B<passive>?) | |
110 | ||
111 | If B<active> or B<passive> is supplied as an optional argument | |
112 | to the method, then it specifies the focus model for I<$toplevel>. | |
113 | In this case the method returns an empty string. If no additional | |
114 | argument is supplied, then the method returns the current focus | |
115 | model for I<$toplevel>. | |
116 | An B<active> focus model means that I<$toplevel> will claim the | |
117 | input focus for itself or its descendants, even at times when | |
118 | the focus is currently in some other application. B<Passive> means that | |
119 | I<$toplevel> will never claim the focus for itself: the window manager | |
120 | should give the focus to I<$toplevel> at appropriate times. However, | |
121 | once the focus has been given to I<$toplevel> or one of its descendants, | |
122 | the application may re-assign the focus among I<$toplevel>'s descendants. | |
123 | The focus model defaults to B<passive>, and Tk's B<focus> method | |
124 | assumes a passive model of focusing. | |
125 | ||
126 | =item I<$toplevel>-E<gt>B<frame> | |
127 | ||
128 | If I<$widget> has been reparented by the window manager into a | |
129 | decorative frame, the method returns the platform specific window | |
130 | identifier for the outermost frame that contains I<$toplevel> (the | |
131 | window whose parent is the root or virtual root). If I<$toplevel> | |
132 | hasn't been reparented by the window manager then the method returns | |
133 | the platform specific window identifier for I<$toplevel>. | |
134 | ||
135 | =item I<$toplevel>-E<gt>B<geometry>(?I<newGeometry>?) | |
136 | ||
137 | If I<newGeometry> is specified, then the geometry of I<$toplevel> | |
138 | is changed and an empty string is returned. Otherwise the current | |
139 | geometry for I<$toplevel> is returned (this is the most recent | |
140 | geometry specified either by manual resizing or | |
141 | in a B<geometry> method). I<NewGeometry> has | |
142 | the form B<=>I<width>B<x>I<height>B<+->I<x>B<+->I<y>, where | |
143 | any of B<=>, I<width>B<x>I<height>, or B<+->I<x>B<+->I<y> | |
144 | may be omitted. I<Width> and I<height> are positive integers | |
145 | specifying the desired dimensions of I<$toplevel>. If I<$toplevel> | |
146 | is gridded (see L<"GRIDDED GEOMETRY MANAGEMENT"> below) then the dimensions | |
147 | are specified in grid units; otherwise they are specified in pixel | |
148 | units. I<X> and I<y> specify the desired location of | |
149 | I<$toplevel> on the screen, in pixels. | |
150 | If I<x> is preceded by B<+>, it specifies | |
151 | the number of pixels between the left edge of the screen and the left | |
152 | edge of I<$toplevel>'s border; if preceded by B<-> then | |
153 | I<x> specifies the number of pixels | |
154 | between the right edge of the screen and the right edge of I<$toplevel>'s | |
155 | border. If I<y> is preceded by B<+> then it specifies the | |
156 | number of pixels between the top of the screen and the top | |
157 | of I<$toplevel>'s border; if I<y> is preceded by B<-> then | |
158 | it specifies the number of pixels between the bottom of I<$toplevel>'s | |
159 | border and the bottom of the screen. | |
160 | If I<newGeometry> is specified as an empty string then any | |
161 | existing user-specified geometry for I<$toplevel> is cancelled, and | |
162 | the window will revert to the size requested internally by its | |
163 | widgets. | |
164 | ||
165 | =item I<$toplevel>-E<gt>B<wmGrid>(?I<baseWidth,baseHeight,widthInc,heightInc>?) | |
166 | ||
167 | This method indicates that I<$toplevel> is to be managed as a | |
168 | gridded window. | |
169 | It also specifies the relationship between grid units and pixel units. | |
170 | I<BaseWidth> and I<baseHeight> specify the number of grid | |
171 | units corresponding to the pixel dimensions requested internally | |
172 | by I<$toplevel> using B<Tk_GeometryRequest>. I<WidthInc> | |
173 | and I<heightInc> specify the number of pixels in each horizontal | |
174 | and vertical grid unit. | |
175 | These four values determine a range of acceptable sizes for | |
176 | I<$toplevel>, corresponding to grid-based widths and heights | |
177 | that are non-negative integers. | |
178 | Tk will pass this information to the window manager; during | |
179 | manual resizing, the window manager will restrict the window's size | |
180 | to one of these acceptable sizes. | |
181 | Furthermore, during manual resizing the window manager will display | |
182 | the window's current size in terms of grid units rather than pixels. | |
183 | If I<baseWidth> etc. are all specified as empty strings, then | |
184 | I<$toplevel> will no longer be managed as a gridded window. If | |
185 | I<baseWidth> etc. are specified then the return value is an | |
186 | empty string. | |
187 | Otherwise the return value is a array containing | |
188 | four elements corresponding to the current I<baseWidth>, | |
189 | I<baseHeight>, I<widthInc>, and I<heightInc>; if | |
190 | I<$toplevel> is not currently gridded, then an empty string | |
191 | is returned. | |
192 | Note: this command should not be needed very often, since the | |
193 | B<Tk_SetGrid> library procedure and the B<-setgrid> option | |
194 | provide easier access to the same functionality. | |
195 | ||
196 | =item I<$toplevel>-E<gt>B<group>(?I<$widget>?) | |
197 | ||
198 | If I<$widget> is specified, it is the the leader of | |
199 | a group of related windows. The window manager may use this information, | |
200 | for example, to unmap all of the windows in a group when the group's | |
201 | leader is iconified. I<$widget> may be specified as an empty string to | |
202 | remove I<$toplevel> from any group association. If I<$widget> is | |
203 | specified then the method returns an empty string; otherwise it | |
204 | returns the I<$toplevel>'s current group leader, or an empty | |
205 | string if I<$toplevel> isn't part of any group. | |
206 | ||
207 | =item I<$toplevel>-E<gt>B<iconbitmap>(?I<bitmap>?) | |
208 | ||
209 | If I<bitmap> is specified, then it names a bitmap in the standard | |
210 | forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details). | |
211 | This I<black and white> bitmap is passed to the window manager to be displayed | |
212 | in I<$toplevel>'s icon, and the method returns an empty string. If | |
213 | an empty string is specified for I<bitmap>, then any current icon | |
214 | bitmap or image is cancelled for I<$toplevel>. | |
215 | If I<bitmap> is specified then the method returns an empty string. | |
216 | Otherwise it returns the name of | |
217 | the current icon bitmap associated with I<$toplevel>, or an empty | |
218 | string if I<$toplevel> has no icon bitmap. | |
219 | ||
220 | =item I<$toplevel>-E<gt>B<iconify> | |
221 | ||
222 | Arrange for I<$toplevel> to be iconified. It I<$toplevel> hasn't | |
223 | yet been mapped for the first time, this method will arrange for | |
224 | it to appear in the iconified state when it is eventually mapped. | |
225 | ||
226 | =item I<$toplevel>-E<gt>B<iconimage>(?I<image>?) | |
227 | ||
228 | If I<image> is specified, then it names a normal Tk image. | |
229 | This image is rendered into a private I<coloured> bitmap which is passed to | |
230 | the window manager to be displayed in I<$toplevel>'s icon, and the method returns | |
231 | an empty string. If an empty string is specified for I<image>, then any current | |
232 | icon bitmap or image is cancelled for I<$toplevel>. | |
233 | If I<image> is specified then the method returns an empty string. | |
234 | Otherwise it returns the name of | |
235 | the current icon image associated with I<$toplevel>, or an empty | |
236 | string if I<$toplevel> has no icon image. | |
237 | The private pixmap is not pre-cleared so images which are partly "transparent" | |
238 | display rubbish in their transparent parts. | |
239 | ||
240 | The sizes of images that can be used as icons in this manner are platform | |
241 | dependant. On Win32 this sets the "large" icon, which should be 32x32, it | |
242 | will automatically be scaled down to 16x16 for use as a small icon. | |
243 | ||
244 | =item I<$toplevel>-E<gt>B<iconmask>(?I<bitmap>?) | |
245 | ||
246 | If I<bitmap> is specified, then it names a bitmap in the standard | |
247 | forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details). | |
248 | This bitmap is passed to the window manager to be used as a mask | |
249 | in conjunction with the B<iconbitmap> option: where the mask | |
250 | has zeroes no icon will be displayed; where it has ones, the bits | |
251 | from the icon bitmap will be displayed. If | |
252 | an empty string is specified for I<bitmap> then any current icon | |
253 | mask is cancelled for I<$toplevel> (this is equivalent to specifying | |
254 | a bitmap of all ones). If I<bitmap> is specified | |
255 | then the method returns an empty string. Otherwise it | |
256 | returns the name of the current icon mask associated with | |
257 | I<$toplevel>, or an empty string if no mask is in effect. | |
258 | ||
259 | =item I<$toplevel>-E<gt>B<iconname>(?I<newName>?) | |
260 | ||
261 | If I<newName> is specified, then it is passed to the window | |
262 | manager; the window manager should display I<newName> inside | |
263 | the icon associated with I<$toplevel>. In this case an empty | |
264 | string is returned as result. If I<newName> isn't specified | |
265 | then the method returns the current icon name for I<$toplevel>, | |
266 | or an empty string if no icon name has been specified (in this | |
267 | case the window manager will normally display the window's title, | |
268 | as specified with the B<title> method). | |
269 | ||
270 | =item I<$toplevel>-E<gt>B<iconposition>(?I<x y>?) | |
271 | ||
272 | If I<x> and I<y> are specified, they are passed to the window | |
273 | manager as a hint about where to position the icon for I<$toplevel>. | |
274 | In this case an empty string is returned. If I<x> and I<y> are | |
275 | specified as empty strings then any existing icon position hint is cancelled. | |
276 | If neither I<x> nor I<y> is specified, then the method returns | |
277 | a array containing two values, which are the current icon position | |
278 | hints (if no hints are in effect then an empty string is returned). | |
279 | ||
280 | =item I<$toplevel>-E<gt>B<iconwindow>(?I<$widget>?) | |
281 | ||
282 | If I<$widget> is specified, it is a window to | |
283 | use as icon for I<$toplevel>: when I<$toplevel> is iconified then | |
284 | I<$widget> will be mapped to serve as icon, and when I<$toplevel> | |
285 | is de-iconified then I<$widget> will be unmapped again. If | |
286 | I<$widget> is specified as an empty string then any existing | |
287 | icon window association for I<$toplevel> will be cancelled. If | |
288 | the I<$widget> argument is specified then an empty string is | |
289 | returned. Otherwise the method returns the | |
290 | current icon window for I<$toplevel>, or an empty string if there | |
291 | is no icon window currently specified for I<$toplevel>. | |
292 | Button press events are disabled for I<$toplevel> as long as it is | |
293 | an icon window; this is needed in order to allow window managers | |
294 | to ``own'' those events. | |
295 | Note: not all window managers support the notion of an icon window. | |
296 | ||
297 | =item I<$toplevel>-E<gt>B<maxsize>(?I<width,height>?) | |
298 | ||
299 | If I<width> and I<height> are specified, they give | |
300 | the maximum permissible dimensions for I<$toplevel>. | |
301 | For gridded windows the dimensions are specified in | |
302 | grid units; otherwise they are specified in pixel units. | |
303 | The window manager will restrict the window's dimensions to be | |
304 | less than or equal to I<width> and I<height>. | |
305 | If I<width> and I<height> are | |
306 | specified, then the method returns an empty string. Otherwise | |
307 | it returns a array with two elements, which are the | |
308 | maximum width and height currently in effect. | |
309 | The maximum size defaults to the size of the screen. | |
310 | If resizing has been disabled with the B<resizable> method, | |
311 | then this method has no effect. | |
312 | See the sections on geometry management below for more information. | |
313 | ||
314 | =item I<$toplevel>-E<gt>B<minsize>(?I<width,height>?) | |
315 | ||
316 | If I<width> and I<height> are specified, they give the | |
317 | minimum permissible dimensions for I<$toplevel>. | |
318 | For gridded windows the dimensions are specified in | |
319 | grid units; otherwise they are specified in pixel units. | |
320 | The window manager will restrict the window's dimensions to be | |
321 | greater than or equal to I<width> and I<height>. | |
322 | If I<width> and I<height> are | |
323 | specified, then the method returns an empty string. Otherwise | |
324 | it returns a array with two elements, which are the | |
325 | minimum width and height currently in effect. | |
326 | The minimum size defaults to one pixel in each dimension. | |
327 | If resizing has been disabled with the B<resizable> method, | |
328 | then this method has no effect. | |
329 | See the sections on geometry management below for more information. | |
330 | ||
331 | =item I<$toplevel>-E<gt>B<overrideredirect(?>I<boolean>?) | |
332 | ||
333 | If I<boolean> is specified, it must have a proper boolean form and | |
334 | the override-redirect flag for I<$toplevel> is set to that value. | |
335 | If I<boolean> is not specified then B<1> or B<0> is | |
336 | returned to indicate whether or not the override-redirect flag | |
337 | is currently set for I<$toplevel>. | |
338 | Setting the override-redirect flag for a window causes | |
339 | it to be ignored by the window manager; among other things, this means | |
340 | that the window will not be reparented from the root window into a | |
341 | decorative frame and the user will not be able to manipulate the | |
342 | window using the normal window manager mechanisms. | |
343 | ||
344 | =item I<$toplevel>-E<gt>B<positionfrom>(?I<who>?) | |
345 | ||
346 | If I<who> is specified, it must be either B<program> or | |
347 | B<user>, or an abbreviation of one of these two. It indicates | |
348 | whether I<$toplevel>'s current position was requested by the | |
349 | program or by the user. Many window managers ignore program-requested | |
350 | initial positions and ask the user to manually position the window; if | |
351 | B<user> is specified then the window manager should position the | |
352 | window at the given place without asking the user for assistance. | |
353 | If I<who> is specified as an empty string, then the current position | |
354 | source is cancelled. | |
355 | If I<who> is specified, then the method returns an empty string. | |
356 | Otherwise it returns B<user> or $widget to indicate the | |
357 | source of the window's current position, or an empty string if | |
358 | no source has been specified yet. Most window managers interpret | |
359 | ``no source'' as equivalent to B<program>. | |
360 | Tk will automatically set the position source to B<user> | |
361 | when a B<geometry> method is invoked, unless the source has | |
362 | been set explicitly to B<program>. | |
363 | ||
364 | =item I<$toplevel>-E<gt>B<protocol>(?I<name>?,?I<callback>?) | |
365 | ||
366 | This method is used to manage window manager protocols such as | |
367 | B<WM_DELETE_WINDOW>. | |
368 | I<Name> is the name of an atom corresponding to a window manager | |
369 | protocol, such as B<WM_DELETE_WINDOW> or B<WM_SAVE_YOURSELF> | |
370 | or B<WM_TAKE_FOCUS>. | |
371 | If both I<name> and I<callback> are specified, then I<callback> | |
372 | is associated with the protocol specified by I<name>. | |
373 | I<Name> will be added to I<$toplevel>'s B<WM_PROTOCOLS> | |
374 | property to tell the window manager that the application has a | |
375 | protocol handler for I<name>, and I<callback> will | |
376 | be invoked in the future whenever the window manager sends a | |
377 | message to the client for that protocol. | |
378 | In this case the method returns an empty string. | |
379 | If I<name> is specified but I<callback> isn't, then the current | |
380 | callback for I<name> is returned, or an empty string if there | |
381 | is no handler defined for I<name>. | |
382 | If I<callback> is specified as an empty string then the current | |
383 | handler for I<name> is deleted and it is removed from the | |
384 | B<WM_PROTOCOLS> property on I<$toplevel>; an empty string is | |
385 | returned. | |
386 | Lastly, if neither I<name> nor I<callback> is specified, the | |
387 | method returns a list of all the protocols for which handlers | |
388 | are currently defined for I<$toplevel>. | |
389 | ||
390 | =over 8 | |
391 | ||
392 | Tk always defines a protocol handler for B<WM_DELETE_WINDOW>, even if | |
393 | you haven't asked for one with B<protocol>. | |
394 | If a B<WM_DELETE_WINDOW> message arrives when you haven't defined | |
395 | a handler, then Tk handles the message by destroying the window for | |
396 | which it was received. | |
397 | ||
398 | =back | |
399 | ||
400 | =item I<$toplevel>-E<gt>B<resizable>(?I<width,height>?) | |
401 | ||
402 | This method controls whether or not the user may interactively | |
403 | resize a top-level window. If I<width> and I<height> are | |
404 | specified, they are boolean values that determine whether the | |
405 | width and height of I<$toplevel> may be modified by the user. | |
406 | In this case the method returns an empty string. | |
407 | If I<width> and I<height> are omitted then the method | |
408 | returns a list with two 0/1 elements that indicate whether the | |
409 | width and height of I<$toplevel> are currently resizable. | |
410 | By default, windows are resizable in both dimensions. | |
411 | If resizing is disabled, then the window's size will be the size | |
412 | from the most recent interactive resize or B<geometry> | |
413 | method. If there has been no such operation then | |
414 | the window's natural size will be used. | |
415 | ||
416 | =item I<$toplevel>-E<gt>B<sizefrom>(?I<who>?) | |
417 | ||
418 | If I<who> is specified, it must be either B<program> or | |
419 | B<user>, or an abbreviation of one of these two. It indicates | |
420 | whether I<$toplevel>'s current size was requested by the | |
421 | program or by the user. Some window managers ignore program-requested | |
422 | sizes and ask the user to manually size the window; if | |
423 | B<user> is specified then the window manager should give the | |
424 | window its specified size without asking the user for assistance. | |
425 | If I<who> is specified as an empty string, then the current size | |
426 | source is cancelled. | |
427 | If I<who> is specified, then the method returns an empty string. | |
428 | Otherwise it returns B<user> or $widget to indicate the | |
429 | source of the window's current size, or an empty string if | |
430 | no source has been specified yet. Most window managers interpret | |
431 | ``no source'' as equivalent to B<program>. | |
432 | ||
433 | =item I<$toplevel>-E<gt>B<state> | |
434 | ||
435 | Returns the current state of $widget: either B<normal>, | |
436 | B<iconic>, B<withdrawn>, or B<icon>. The difference | |
437 | between B<iconic> and B<icon> is that B<iconic> refers | |
438 | to a window that has been iconified (e.g., with the B<iconify> | |
439 | method) while B<icon> refers to a window whose only purpose is | |
440 | to serve as the icon for some other window (via the B<iconwindow> | |
441 | method). | |
442 | ||
443 | =item I<$toplevel>-E<gt>B<title>(?I<string>?) | |
444 | ||
445 | If I<string> is specified, then it will be passed to the window | |
446 | manager for use as the title for I<$toplevel> (the window manager | |
447 | should display this string in I<$toplevel>'s title bar). In this | |
448 | case the method returns an empty string. If I<string> isn't | |
449 | specified then the method returns the current title for the | |
450 | I<$toplevel>. The title for a window defaults to its name. | |
451 | ||
452 | =item I<$toplevel>-E<gt>B<transient>(?I<master>?) | |
453 | ||
454 | If I<master> is specified, then the window manager is informed | |
455 | that I<$toplevel> is a transient window (e.g. pull-down menu) working | |
456 | on behalf of I<master> (where I<master> is | |
457 | a top-level window). Some window managers will use | |
458 | this information to manage I<$toplevel> specially. If I<master> | |
459 | is specified as an empty string then I<$toplevel> is marked as not | |
460 | being a transient window any more. If I<master> is specified, | |
461 | then the method returns an empty string. Otherwise the method | |
462 | returns the path name of I<$toplevel>'s current master, or an | |
463 | empty string if I<$toplevel> isn't currently a transient window. | |
464 | ||
465 | =item I<$toplevel>-E<gt>B<withdraw> | |
466 | ||
467 | Arranges for I<$toplevel> to be withdrawn from the screen. This | |
468 | causes the window to be unmapped and forgotten about by the window | |
469 | manager. If the window | |
470 | has never been mapped, then this method | |
471 | causes the window to be mapped in the withdrawn state. Not all | |
472 | window managers appear to know how to handle windows that are | |
473 | mapped in the withdrawn state. | |
474 | Note: it sometimes seems to be necessary to withdraw a | |
475 | window and then re-map it (e.g. with B<deiconify>) to get some | |
476 | window managers to pay attention to changes in window attributes | |
477 | such as group. | |
478 | ||
479 | =item I<$toplevel>-E<gt>B<wrapper> | |
480 | ||
481 | Returns the window id of the wrapper window in which Tk has placed | |
482 | I<$toplevel>. This is the id by which window manager will know | |
483 | I<$toplevel>, and so is appropriate place to add X properties. | |
484 | ||
485 | =back | |
486 | ||
487 | =head1 ICON SIZES | |
488 | ||
489 | The sizes of bitmaps/images that can be used as icons in this manner are platform | |
490 | and window manager dependant. Unix window managers are typically more tolerant | |
491 | than Win32. It is possible that coloured C<iconimage> icons may cause problems | |
492 | on some X window managers. | |
493 | ||
494 | =over 4 | |
495 | ||
496 | =item * Win32 | |
497 | ||
498 | C<iconimage> and C<iconbitmap> set the "large" icon, which should be | |
499 | 32x32, it will automatically be scaled down to 16x16 for use as a small icon. | |
500 | Win32 ignores C<iconwin> requests. | |
501 | ||
502 | =item * KDE's "kwm" | |
503 | ||
504 | Accepts coloured C<iconimage> and black and white C<iconbitmap> but | |
505 | will scale either to a small (14x14?) icon. Kwm ignores C<iconwin>. | |
506 | ||
507 | =item * Sun's "olwm" or "olvwm" | |
508 | ||
509 | Honours C<iconwin> which will override C<iconimage> or C<iconbitmap>. | |
510 | Coloured images work. | |
511 | ||
512 | =item * Sun's CDE window manager | |
513 | ||
514 | Coloured images work. ... | |
515 | ||
516 | =back | |
517 | ||
518 | =head1 GEOMETRY MANAGEMENT | |
519 | ||
520 | By default a top-level window appears on the screen in its | |
521 | I<natural size>, which is the one determined internally by its | |
522 | widgets and geometry managers. | |
523 | If the natural size of a top-level window changes, then the window's size | |
524 | changes to match. | |
525 | A top-level window can be given a size other than its natural size in two ways. | |
526 | First, the user can resize the window manually using the facilities | |
527 | of the window manager, such as resize handles. | |
528 | Second, the application can request a particular size for a | |
529 | top-level window using the B<geometry> method. | |
530 | These two cases are handled identically by Tk; in either case, | |
531 | the requested size overrides the natural size. | |
532 | You can return the window to its natural by invoking B<geometry> | |
533 | with an empty I<geometry> string. | |
534 | ||
535 | Normally a top-level window can have any size from one pixel in each | |
536 | dimension up to the size of its screen. | |
537 | However, you can use the B<minsize> and B<maxsize> methods | |
538 | to limit the range of allowable sizes. | |
539 | The range set by B<minsize> and B<maxsize> applies to | |
540 | all forms of resizing, including the window's natural size as | |
541 | well as manual resizes and the B<geometry> method. | |
542 | You can also use the method B<resizable> to completely | |
543 | disable interactive resizing in one or both dimensions. | |
544 | ||
545 | =head1 GRIDDED GEOMETRY MANAGEMENT | |
546 | ||
547 | Gridded geometry management occurs when one of the widgets of an | |
548 | application supports a range of useful sizes. | |
549 | This occurs, for example, in a text editor where the scrollbars, | |
550 | menus, and other adornments are fixed in size but the edit widget | |
551 | can support any number of lines of text or characters per line. | |
552 | In this case, it is usually desirable to let the user specify the | |
553 | number of lines or characters-per-line, either with the | |
554 | B<geometry> method or by interactively resizing the window. | |
555 | In the case of text, and in other interesting cases also, only | |
556 | discrete sizes of the window make sense, such as integral numbers | |
557 | of lines and characters-per-line; arbitrary pixel sizes are not useful. | |
558 | ||
559 | Gridded geometry management provides support for this kind of | |
560 | application. | |
561 | Tk (and the window manager) assume that there is a grid of some | |
562 | sort within the application and that the application should be | |
563 | resized in terms of I<grid units> rather than pixels. | |
564 | Gridded geometry management is typically invoked by turning on | |
565 | the B<setGrid> option for a widget; it can also be invoked | |
566 | with the B<wmGrid> method or by calling B<Tk_SetGrid>. | |
567 | In each of these approaches the particular widget (or sometimes | |
568 | code in the application as a whole) specifies the relationship between | |
569 | integral grid sizes for the window and pixel sizes. | |
570 | To return to non-gridded geometry management, invoke | |
571 | B<grid> with empty argument strings. | |
572 | ||
573 | When gridded geometry management is enabled then all the dimensions specified | |
574 | in B<minsize>, B<maxsize>, and B<geometry> methods | |
575 | are treated as grid units rather than pixel units. | |
576 | Interactive resizing is also carried out in even numbers of grid units | |
577 | rather than pixels. | |
578 | ||
579 | =head1 BUGS | |
580 | ||
581 | Most existing window managers appear to have bugs that affect the | |
582 | operation of the B<wm> methods. For example, some changes won't | |
583 | take effect if the window is already active: the window will have | |
584 | to be withdrawn and de-iconified in order to make the change happen. | |
585 | ||
586 | =head1 SEE ALSO | |
587 | ||
588 | L<Tk::Widget|Tk::Widget> | |
589 | L<Tk::tixWm|Tk::tixWm> | |
590 | L<Tk::Mwm|Tk::Mwm> | |
591 | ||
592 | =head1 KEYWORDS | |
593 | ||
594 | aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager | |
595 | ||
596 | =cut | |
597 |