Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1991-1994 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: wm.n,v 1.11.2.3 2004/11/11 01:26:42 das Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
13 | '\" .AP type name in/out ?indent? | |
14 | '\" Start paragraph describing an argument to a library procedure. | |
15 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
16 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
17 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
18 | '\" needed; use .AS below instead) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
21 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
22 | '\" name are examples of largest possible arguments that will be passed | |
23 | '\" to .AP later. If args are omitted, default tab stops are used. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
38 | '\" .VS ?version? ?br? | |
39 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
40 | '\" of man pages. The first argument is ignored and used for recording | |
41 | '\" the version when the .VS was added, so that the sidebars can be | |
42 | '\" found and removed when they reach a certain age. If another argument | |
43 | '\" is present, then a line break is forced before starting the sidebar. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
62 | '\" .OP cmdName dbName dbClass | |
63 | '\" Start of description of a specific option. cmdName gives the | |
64 | '\" option's name as specified in the class command, dbName gives | |
65 | '\" the option's name in the option database, and dbClass gives | |
66 | '\" the option's class in the option database. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
165 | '\" # Special macro to handle page bottom: finish off current | |
166 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
167 | '\" # page bottom macro. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
174 | .\" Draw three-sided box if this is the box's first page, | |
175 | .\" draw two sides but no top otherwise. | |
176 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
180 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
181 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH wm n 8.4 Tk "Tk Built-In Commands" | |
247 | .BS | |
248 | '\" Note: do not modify the .SH NAME line immediately below! | |
249 | .SH NAME | |
250 | wm \- Communicate with window manager | |
251 | .SH SYNOPSIS | |
252 | \fBwm\fR \fIoption window \fR?\fIargs\fR? | |
253 | .BE | |
254 | ||
255 | .SH DESCRIPTION | |
256 | .PP | |
257 | The \fBwm\fR command is used to interact with window managers in | |
258 | order to control such things as the title for a window, its geometry, | |
259 | or the increments in terms of which it may be resized. The \fBwm\fR | |
260 | command can take any of a number of different forms, depending on | |
261 | the \fIoption\fR argument. All of the forms expect at least one | |
262 | additional argument, \fIwindow\fR, which must be the path name of a | |
263 | top-level window. | |
264 | .PP | |
265 | The legal forms for the \fBwm\fR command are: | |
266 | .TP | |
267 | \fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? | |
268 | If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR | |
269 | are all specified, then they will be passed to the window manager | |
270 | and the window manager should use them to enforce a range of | |
271 | acceptable aspect ratios for \fIwindow\fR. The aspect ratio of | |
272 | \fIwindow\fR (width/length) will be constrained to lie | |
273 | between \fIminNumer\fR/\fIminDenom\fR and \fImaxNumer\fR/\fImaxDenom\fR. | |
274 | If \fIminNumer\fR etc. are all specified as empty strings, then | |
275 | any existing aspect ratio restrictions are removed. | |
276 | If \fIminNumer\fR etc. are specified, then the command returns an | |
277 | empty string. Otherwise, it returns | |
278 | a Tcl list containing four elements, which are the current values | |
279 | of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR | |
280 | (if no aspect restrictions are in effect, then an empty string is | |
281 | returned). | |
282 | .VS 8.4 | |
283 | .TP | |
284 | \fBwm attributes \fIwindow\fR | |
285 | .TP | |
286 | \fBwm attributes \fIwindow\fR ?\fBoption\fR? | |
287 | .TP | |
288 | \fBwm attributes \fIwindow\fR ?\fBoption value option value...\fR? | |
289 | .RS | |
290 | This subcommand returns or sets platform specific attributes associated | |
291 | with a window. The first form returns a list of the platform specific | |
292 | flags and their values. The second form returns the value for the | |
293 | specific option. The third form sets one or more of the values. The | |
294 | values are as follows: | |
295 | .PP | |
296 | On Windows, \fB\-disabled\fR gets or sets whether the window is in a | |
297 | disabled state. \fB\-toolwindow\fR gets or sets the style of the window | |
298 | to toolwindow (as defined in the MSDN). \fB\-topmost\fR gets or sets | |
299 | whether this is a topmost window (displays above all other windows). | |
300 | \fB\-alpha\fR sets the alpha transparency level of the toplevel. It accepts | |
301 | a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values | |
302 | outside that range will be constrained. This is supported on Windows | |
303 | 2000/XP+. Where not supported, the \fB\-alpha\fR value remains at | |
304 | \fB1.0\fR. | |
305 | .PP | |
306 | On Mac OS X, \fB\-modified\fR gets or sets the modification state of the | |
307 | window (determines whether the window close widget contains the modification | |
308 | indicator). \fB\-titlepath\fR gets or sets the path of the file referenced as | |
309 | the window proxy icon (which can be dragged and dropped in lieu of the file's | |
310 | finder icon). \fB\-alpha\fR sets the alpha transparency level of the window, | |
311 | it accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque), | |
312 | values outside that range will be constrained. | |
313 | .PP | |
314 | On Unix, there are currently no special attribute values. | |
315 | .RE | |
316 | .VE 8.4 | |
317 | .TP | |
318 | \fBwm client \fIwindow\fR ?\fIname\fR? | |
319 | If \fIname\fR is specified, this command stores \fIname\fR (which | |
320 | should be the name of | |
321 | the host on which the application is executing) in \fIwindow\fR's | |
322 | \fBWM_CLIENT_MACHINE\fR property for use by the window manager or | |
323 | session manager. | |
324 | The command returns an empty string in this case. | |
325 | If \fIname\fR isn't specified, the command returns the last name | |
326 | set in a \fBwm client\fR command for \fIwindow\fR. | |
327 | If \fIname\fR is specified as an empty string, the command deletes the | |
328 | \fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. | |
329 | .TP | |
330 | \fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? | |
331 | This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR | |
332 | property, which provides information to the window managers about | |
333 | windows that have private colormaps. | |
334 | If \fIwindowList\fR isn't specified, the command returns a list | |
335 | whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR | |
336 | property. | |
337 | If \fIwindowList\fR is specified, it consists of a list of window | |
338 | path names; the command overwrites the \fBWM_COLORMAP_WINDOWS\fR | |
339 | property with the given windows and returns an empty string. | |
340 | The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a | |
341 | list of the internal windows within \fIwindow\fR whose colormaps differ | |
342 | from their parents. | |
343 | The order of the windows in the property indicates a priority order: | |
344 | the window manager will attempt to install as many colormaps as possible | |
345 | from the head of this list when \fIwindow\fR gets the colormap focus. | |
346 | If \fIwindow\fR is not included among the windows in \fIwindowList\fR, | |
347 | Tk implicitly adds it at the end of the \fBWM_COLORMAP_WINDOWS\fR | |
348 | property, so that its colormap is lowest in priority. | |
349 | If \fBwm colormapwindows\fR is not invoked, Tk will automatically set | |
350 | the property for each top-level window to all the internal windows | |
351 | whose colormaps differ from their parents, followed by the top-level | |
352 | itself; the order of the internal windows is undefined. | |
353 | See the ICCCM documentation for more information on the | |
354 | \fBWM_COLORMAP_WINDOWS\fR property. | |
355 | .TP | |
356 | \fBwm command \fIwindow\fR ?\fIvalue\fR? | |
357 | If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's | |
358 | \fBWM_COMMAND\fR property for use by the window manager or | |
359 | session manager and returns an empty string. | |
360 | \fIValue\fR must have proper list structure; the elements should | |
361 | contain the words of the command used to invoke the application. | |
362 | If \fIvalue\fR isn't specified then the command returns the last value | |
363 | set in a \fBwm command\fR command for \fIwindow\fR. | |
364 | If \fIvalue\fR is specified as an empty string, the command | |
365 | deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. | |
366 | .TP | |
367 | \fBwm deiconify \fIwindow\fR | |
368 | Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. | |
369 | This is done by mapping the window. If the window has never been | |
370 | mapped then this command will not map the window, but it will ensure | |
371 | that when the window is first mapped it will be displayed | |
372 | in de-iconified form. On Windows, a deiconified window will also be | |
373 | raised and be given the focus (made the active window). | |
374 | Returns an empty string. | |
375 | .TP | |
376 | \fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? | |
377 | If \fBactive\fR or \fBpassive\fR is supplied as an optional argument | |
378 | to the command, then it specifies the focus model for \fIwindow\fR. | |
379 | In this case the command returns an empty string. If no additional | |
380 | argument is supplied, then the command returns the current focus | |
381 | model for \fIwindow\fR. | |
382 | An \fBactive\fR focus model means that \fIwindow\fR will claim the | |
383 | input focus for itself or its descendants, even at times when | |
384 | the focus is currently in some other application. \fBPassive\fR means that | |
385 | \fIwindow\fR will never claim the focus for itself: the window manager | |
386 | should give the focus to \fIwindow\fR at appropriate times. However, | |
387 | once the focus has been given to \fIwindow\fR or one of its descendants, | |
388 | the application may re-assign the focus among \fIwindow\fR's descendants. | |
389 | The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command | |
390 | assumes a passive model of focusing. | |
391 | .TP | |
392 | \fBwm frame \fIwindow\fR | |
393 | .VS | |
394 | If \fIwindow\fR has been reparented by the window manager into a | |
395 | decorative frame, the command returns the platform specific window | |
396 | identifier for the outermost frame that contains \fIwindow\fR (the | |
397 | window whose parent is the root or virtual root). If \fIwindow\fR | |
398 | hasn't been reparented by the window manager then the command returns | |
399 | the platform specific window identifier for \fIwindow\fR. | |
400 | .VE | |
401 | .TP | |
402 | \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? | |
403 | If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR | |
404 | is changed and an empty string is returned. Otherwise the current | |
405 | geometry for \fIwindow\fR is returned (this is the most recent | |
406 | geometry specified either by manual resizing or | |
407 | in a \fBwm geometry\fR command). \fINewGeometry\fR has | |
408 | the form \fB=\fIwidth\fBx\fIheight\fB\(+-\fIx\fB\(+-\fIy\fR, where | |
409 | any of \fB=\fR, \fIwidth\fBx\fIheight\fR, or \fB\(+-\fIx\fB\(+-\fIy\fR | |
410 | may be omitted. \fIWidth\fR and \fIheight\fR are positive integers | |
411 | specifying the desired dimensions of \fIwindow\fR. If \fIwindow\fR | |
412 | is gridded (see GRIDDED GEOMETRY MANAGEMENT below) then the dimensions | |
413 | are specified in grid units; otherwise they are specified in pixel | |
414 | units. \fIX\fR and \fIy\fR specify the desired location of | |
415 | \fIwindow\fR on the screen, in pixels. | |
416 | If \fIx\fR is preceded by \fB+\fR, it specifies | |
417 | the number of pixels between the left edge of the screen and the left | |
418 | edge of \fIwindow\fR's border; if preceded by \fB\-\fR then | |
419 | \fIx\fR specifies the number of pixels | |
420 | between the right edge of the screen and the right edge of \fIwindow\fR's | |
421 | border. If \fIy\fR is preceded by \fB+\fR then it specifies the | |
422 | number of pixels between the top of the screen and the top | |
423 | of \fIwindow\fR's border; if \fIy\fR is preceded by \fB\-\fR then | |
424 | it specifies the number of pixels between the bottom of \fIwindow\fR's | |
425 | border and the bottom of the screen. | |
426 | If \fInewGeometry\fR is specified as an empty string then any | |
427 | existing user-specified geometry for \fIwindow\fR is cancelled, and | |
428 | the window will revert to the size requested internally by its | |
429 | widgets. | |
430 | .TP | |
431 | \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? | |
432 | This command indicates that \fIwindow\fR is to be managed as a | |
433 | gridded window. | |
434 | It also specifies the relationship between grid units and pixel units. | |
435 | \fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid | |
436 | units corresponding to the pixel dimensions requested internally | |
437 | by \fIwindow\fR using \fBTk_GeometryRequest\fR. \fIWidthInc\fR | |
438 | and \fIheightInc\fR specify the number of pixels in each horizontal | |
439 | and vertical grid unit. | |
440 | These four values determine a range of acceptable sizes for | |
441 | \fIwindow\fR, corresponding to grid-based widths and heights | |
442 | that are non-negative integers. | |
443 | Tk will pass this information to the window manager; during | |
444 | manual resizing, the window manager will restrict the window's size | |
445 | to one of these acceptable sizes. | |
446 | Furthermore, during manual resizing the window manager will display | |
447 | the window's current size in terms of grid units rather than pixels. | |
448 | If \fIbaseWidth\fR etc. are all specified as empty strings, then | |
449 | \fIwindow\fR will no longer be managed as a gridded window. If | |
450 | \fIbaseWidth\fR etc. are specified then the return value is an | |
451 | empty string. | |
452 | Otherwise the return value is a Tcl list containing | |
453 | four elements corresponding to the current \fIbaseWidth\fR, | |
454 | \fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if | |
455 | \fIwindow\fR is not currently gridded, then an empty string | |
456 | is returned. | |
457 | Note: this command should not be needed very often, since the | |
458 | \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option | |
459 | provide easier access to the same functionality. | |
460 | .TP | |
461 | \fBwm group \fIwindow\fR ?\fIpathName\fR? | |
462 | If \fIpathName\fR is specified, it gives the path name for the leader of | |
463 | a group of related windows. The window manager may use this information, | |
464 | for example, to unmap all of the windows in a group when the group's | |
465 | leader is iconified. \fIPathName\fR may be specified as an empty string to | |
466 | remove \fIwindow\fR from any group association. If \fIpathName\fR is | |
467 | specified then the command returns an empty string; otherwise it | |
468 | returns the path name of \fIwindow\fR's current group leader, or an empty | |
469 | string if \fIwindow\fR isn't part of any group. | |
470 | .TP | |
471 | \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? | |
472 | If \fIbitmap\fR is specified, then it names a bitmap in the standard | |
473 | forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). | |
474 | This bitmap is passed to the window manager to be displayed in | |
475 | \fIwindow\fR's icon, and the command returns an empty string. If | |
476 | an empty string is specified for \fIbitmap\fR, then any current icon | |
477 | bitmap is cancelled for \fIwindow\fR. | |
478 | If \fIbitmap\fR is specified then the command returns an empty string. | |
479 | Otherwise it returns the name of | |
480 | the current icon bitmap associated with \fIwindow\fR, or an empty | |
481 | string if \fIwindow\fR has no icon bitmap. On the Windows operating | |
482 | system, an additional flag is supported: | |
483 | \fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?. | |
484 | If the \fB\-default\fR | |
485 | flag is given, the icon is applied to all toplevel windows (existing | |
486 | and future) to which no other specific icon has yet been applied. | |
487 | In addition to bitmap image types, a full path specification to | |
488 | any file which contains a valid | |
489 | Windows icon is also accepted (usually .ico or .icr files), or any | |
490 | file for which the shell has assigned an icon. Tcl will | |
491 | first test if the file contains an icon, then if it has an assigned | |
492 | icon, and finally, if that fails, test for | |
493 | a bitmap. | |
494 | .TP | |
495 | \fBwm iconify \fIwindow\fR | |
496 | Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR hasn't | |
497 | yet been mapped for the first time, this command will arrange for | |
498 | it to appear in the iconified state when it is eventually mapped. | |
499 | .TP | |
500 | \fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? | |
501 | If \fIbitmap\fR is specified, then it names a bitmap in the standard | |
502 | forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). | |
503 | This bitmap is passed to the window manager to be used as a mask | |
504 | in conjunction with the \fBiconbitmap\fR option: where the mask | |
505 | has zeroes no icon will be displayed; where it has ones, the bits | |
506 | from the icon bitmap will be displayed. If | |
507 | an empty string is specified for \fIbitmap\fR then any current icon | |
508 | mask is cancelled for \fIwindow\fR (this is equivalent to specifying | |
509 | a bitmap of all ones). If \fIbitmap\fR is specified | |
510 | then the command returns an empty string. Otherwise it | |
511 | returns the name of the current icon mask associated with | |
512 | \fIwindow\fR, or an empty string if no mask is in effect. | |
513 | .TP | |
514 | \fBwm iconname \fIwindow\fR ?\fInewName\fR? | |
515 | If \fInewName\fR is specified, then it is passed to the window | |
516 | manager; the window manager should display \fInewName\fR inside | |
517 | the icon associated with \fIwindow\fR. In this case an empty | |
518 | string is returned as result. If \fInewName\fR isn't specified | |
519 | then the command returns the current icon name for \fIwindow\fR, | |
520 | or an empty string if no icon name has been specified (in this | |
521 | case the window manager will normally display the window's title, | |
522 | as specified with the \fBwm title\fR command). | |
523 | .TP | |
524 | \fBwm iconposition \fIwindow\fR ?\fIx y\fR? | |
525 | If \fIx\fR and \fIy\fR are specified, they are passed to the window | |
526 | manager as a hint about where to position the icon for \fIwindow\fR. | |
527 | In this case an empty string is returned. If \fIx\fR and \fIy\fR are | |
528 | specified as empty strings then any existing icon position hint is cancelled. | |
529 | If neither \fIx\fR nor \fIy\fR is specified, then the command returns | |
530 | a Tcl list containing two values, which are the current icon position | |
531 | hints (if no hints are in effect then an empty string is returned). | |
532 | .TP | |
533 | \fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? | |
534 | If \fIpathName\fR is specified, it is the path name for a window to | |
535 | use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then | |
536 | \fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR | |
537 | is de-iconified then \fIpathName\fR will be unmapped again. If | |
538 | \fIpathName\fR is specified as an empty string then any existing | |
539 | icon window association for \fIwindow\fR will be cancelled. If | |
540 | the \fIpathName\fR argument is specified then an empty string is | |
541 | returned. Otherwise the command returns the path name of the | |
542 | current icon window for \fIwindow\fR, or an empty string if there | |
543 | is no icon window currently specified for \fIwindow\fR. | |
544 | Button press events are disabled for \fIwindow\fR as long as it is | |
545 | an icon window; this is needed in order to allow window managers | |
546 | to ``own'' those events. | |
547 | Note: not all window managers support the notion of an icon window. | |
548 | .TP | |
549 | \fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? | |
550 | If \fIwidth\fR and \fIheight\fR are specified, they give | |
551 | the maximum permissible dimensions for \fIwindow\fR. | |
552 | For gridded windows the dimensions are specified in | |
553 | grid units; otherwise they are specified in pixel units. | |
554 | The window manager will restrict the window's dimensions to be | |
555 | less than or equal to \fIwidth\fR and \fIheight\fR. | |
556 | If \fIwidth\fR and \fIheight\fR are | |
557 | specified, then the command returns an empty string. Otherwise | |
558 | it returns a Tcl list with two elements, which are the | |
559 | maximum width and height currently in effect. | |
560 | The maximum size defaults to the size of the screen. | |
561 | See the sections on geometry management below for more information. | |
562 | .TP | |
563 | \fBwm minsize \fIwindow\fR ?\fIwidth height\fR? | |
564 | If \fIwidth\fR and \fIheight\fR are specified, they give the | |
565 | minimum permissible dimensions for \fIwindow\fR. | |
566 | For gridded windows the dimensions are specified in | |
567 | grid units; otherwise they are specified in pixel units. | |
568 | The window manager will restrict the window's dimensions to be | |
569 | greater than or equal to \fIwidth\fR and \fIheight\fR. | |
570 | If \fIwidth\fR and \fIheight\fR are | |
571 | specified, then the command returns an empty string. Otherwise | |
572 | it returns a Tcl list with two elements, which are the | |
573 | minimum width and height currently in effect. | |
574 | The minimum size defaults to one pixel in each dimension. | |
575 | See the sections on geometry management below for more information. | |
576 | .TP | |
577 | \fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? | |
578 | If \fIboolean\fR is specified, it must have a proper boolean form and | |
579 | the override-redirect flag for \fIwindow\fR is set to that value. | |
580 | If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is | |
581 | returned to indicate whether or not the override-redirect flag | |
582 | is currently set for \fIwindow\fR. | |
583 | Setting the override-redirect flag for a window causes | |
584 | it to be ignored by the window manager; among other things, this means | |
585 | that the window will not be reparented from the root window into a | |
586 | decorative frame and the user will not be able to manipulate the | |
587 | window using the normal window manager mechanisms. | |
588 | .TP | |
589 | \fBwm positionfrom \fIwindow\fR ?\fIwho\fR? | |
590 | If \fIwho\fR is specified, it must be either \fBprogram\fR or | |
591 | \fBuser\fR, or an abbreviation of one of these two. It indicates | |
592 | whether \fIwindow\fR's current position was requested by the | |
593 | program or by the user. Many window managers ignore program-requested | |
594 | initial positions and ask the user to manually position the window; if | |
595 | \fBuser\fR is specified then the window manager should position the | |
596 | window at the given place without asking the user for assistance. | |
597 | If \fIwho\fR is specified as an empty string, then the current position | |
598 | source is cancelled. | |
599 | If \fIwho\fR is specified, then the command returns an empty string. | |
600 | Otherwise it returns \fBuser\fR or \fBprogram\fR to indicate the | |
601 | source of the window's current position, or an empty string if | |
602 | no source has been specified yet. Most window managers interpret | |
603 | ``no source'' as equivalent to \fBprogram\fR. | |
604 | Tk will automatically set the position source to \fBuser\fR | |
605 | when a \fBwm geometry\fR command is invoked, unless the source has | |
606 | been set explicitly to \fBprogram\fR. | |
607 | .TP | |
608 | \fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? | |
609 | This command is used to manage window manager protocols such as | |
610 | \fBWM_DELETE_WINDOW\fR. | |
611 | \fIName\fR is the name of an atom corresponding to a window manager | |
612 | protocol, such as \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR | |
613 | or \fBWM_TAKE_FOCUS\fR. | |
614 | If both \fIname\fR and \fIcommand\fR are specified, then \fIcommand\fR | |
615 | is associated with the protocol specified by \fIname\fR. | |
616 | \fIName\fR will be added to \fIwindow\fR's \fBWM_PROTOCOLS\fR | |
617 | property to tell the window manager that the application has a | |
618 | protocol handler for \fIname\fR, and \fIcommand\fR will | |
619 | be invoked in the future whenever the window manager sends a | |
620 | message to the client for that protocol. | |
621 | In this case the command returns an empty string. | |
622 | If \fIname\fR is specified but \fIcommand\fR isn't, then the current | |
623 | command for \fIname\fR is returned, or an empty string if there | |
624 | is no handler defined for \fIname\fR. | |
625 | If \fIcommand\fR is specified as an empty string then the current | |
626 | handler for \fIname\fR is deleted and it is removed from the | |
627 | \fBWM_PROTOCOLS\fR property on \fIwindow\fR; an empty string is | |
628 | returned. | |
629 | Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the | |
630 | command returns a list of all the protocols for which handlers | |
631 | are currently defined for \fIwindow\fR. | |
632 | .RS | |
633 | .PP | |
634 | Tk always defines a protocol handler for \fBWM_DELETE_WINDOW\fR, even if | |
635 | you haven't asked for one with \fBwm protocol\fR. | |
636 | If a \fBWM_DELETE_WINDOW\fR message arrives when you haven't defined | |
637 | a handler, then Tk handles the message by destroying the window for | |
638 | which it was received. | |
639 | .RE | |
640 | .TP | |
641 | \fBwm resizable \fIwindow\fR ?\fIwidth height\fR? | |
642 | This command controls whether or not the user may interactively | |
643 | resize a top-level window. If \fIwidth\fR and \fIheight\fR are | |
644 | specified, they are boolean values that determine whether the | |
645 | width and height of \fIwindow\fR may be modified by the user. | |
646 | In this case the command returns an empty string. | |
647 | If \fIwidth\fR and \fIheight\fR are omitted then the command | |
648 | returns a list with two 0/1 elements that indicate whether the | |
649 | width and height of \fIwindow\fR are currently resizable. | |
650 | By default, windows are resizable in both dimensions. | |
651 | If resizing is disabled, then the window's size will be the size | |
652 | from the most recent interactive resize or \fBwm geometry\fR | |
653 | command. If there has been no such operation then | |
654 | the window's natural size will be used. | |
655 | .TP | |
656 | \fBwm sizefrom \fIwindow\fR ?\fIwho\fR? | |
657 | If \fIwho\fR is specified, it must be either \fBprogram\fR or | |
658 | \fBuser\fR, or an abbreviation of one of these two. It indicates | |
659 | whether \fIwindow\fR's current size was requested by the | |
660 | program or by the user. Some window managers ignore program-requested | |
661 | sizes and ask the user to manually size the window; if | |
662 | \fBuser\fR is specified then the window manager should give the | |
663 | window its specified size without asking the user for assistance. | |
664 | If \fIwho\fR is specified as an empty string, then the current size | |
665 | source is cancelled. | |
666 | If \fIwho\fR is specified, then the command returns an empty string. | |
667 | Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the | |
668 | source of the window's current size, or an empty string if | |
669 | no source has been specified yet. Most window managers interpret | |
670 | ``no source'' as equivalent to \fBprogram\fR. | |
671 | .TP | |
672 | \fBwm stackorder \fIwindow\fR ?\fIisabove|isbelow window\fR? | |
673 | The stackorder command returns a list of toplevel windows | |
674 | in stacking order, from lowest to highest. When a single toplevel | |
675 | window is passed, the returned list recursively includes all of the | |
676 | window's children that are toplevels. Only those toplevels | |
677 | that are currently mapped to the screen are returned. | |
678 | The stackorder command can also be used to determine if one | |
679 | toplevel is positioned above or below a second toplevel. | |
680 | When two window arguments separated by either \fIisabove\fR or | |
681 | \fIisbelow\fR are passed, a boolean result indicates whether | |
682 | or not the first window is currently above or below the second | |
683 | window in the stacking order. | |
684 | .TP | |
685 | \fBwm state \fIwindow\fR ?newstate? | |
686 | If \fInewstate\fR is specified, the window will be set to the new state, | |
687 | otherwise it returns the current state of \fIwindow\fR: either | |
688 | \fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows only) | |
689 | \fBzoomed\fR. The difference between \fBiconic\fR and \fBicon\fR is that | |
690 | \fBiconic\fR refers to a window that has been iconified (e.g., with the | |
691 | \fBwm iconify\fR command) while \fBicon\fR refers to a window whose only | |
692 | purpose is to serve as the icon for some other window (via the \fBwm | |
693 | iconwindow\fR command). The \fBicon\fR state cannot be set. | |
694 | .TP | |
695 | \fBwm title \fIwindow\fR ?\fIstring\fR? | |
696 | If \fIstring\fR is specified, then it will be passed to the window | |
697 | manager for use as the title for \fIwindow\fR (the window manager | |
698 | should display this string in \fIwindow\fR's title bar). In this | |
699 | case the command returns an empty string. If \fIstring\fR isn't | |
700 | specified then the command returns the current title for the | |
701 | \fIwindow\fR. The title for a window defaults to its name. | |
702 | .TP | |
703 | \fBwm transient \fIwindow\fR ?\fImaster\fR? | |
704 | If \fImaster\fR is specified, then the window manager is informed | |
705 | that \fIwindow\fR is a transient window (e.g. pull-down menu) working | |
706 | on behalf of \fImaster\fR (where \fImaster\fR is the | |
707 | path name for a top-level window). If \fImaster\fR | |
708 | is specified as an empty string then \fIwindow\fR is marked as not | |
709 | being a transient window any more. Otherwise the command | |
710 | returns the path name of \fIwindow\fR's current master, or an | |
711 | empty string if \fIwindow\fR isn't currently a transient window. | |
712 | A transient window will mirror state changes in the master and | |
713 | inherit the state of the master when initially mapped. It is an | |
714 | error to attempt to make a window a transient of itself. | |
715 | .TP | |
716 | \fBwm withdraw \fIwindow\fR | |
717 | Arranges for \fIwindow\fR to be withdrawn from the screen. This | |
718 | causes the window to be unmapped and forgotten about by the window | |
719 | manager. If the window | |
720 | has never been mapped, then this command | |
721 | causes the window to be mapped in the withdrawn state. Not all | |
722 | window managers appear to know how to handle windows that are | |
723 | mapped in the withdrawn state. | |
724 | Note: it sometimes seems to be necessary to withdraw a | |
725 | window and then re-map it (e.g. with \fBwm deiconify\fR) to get some | |
726 | window managers to pay attention to changes in window attributes | |
727 | such as group. | |
728 | .SH "GEOMETRY MANAGEMENT" | |
729 | .PP | |
730 | By default a top-level window appears on the screen in its | |
731 | \fInatural size\fR, which is the one determined internally by its | |
732 | widgets and geometry managers. | |
733 | If the natural size of a top-level window changes, then the window's size | |
734 | changes to match. | |
735 | A top-level window can be given a size other than its natural size in two ways. | |
736 | First, the user can resize the window manually using the facilities | |
737 | of the window manager, such as resize handles. | |
738 | Second, the application can request a particular size for a | |
739 | top-level window using the \fBwm geometry\fR command. | |
740 | These two cases are handled identically by Tk; in either case, | |
741 | the requested size overrides the natural size. | |
742 | You can return the window to its natural by invoking \fBwm geometry\fR | |
743 | with an empty \fIgeometry\fR string. | |
744 | .PP | |
745 | Normally a top-level window can have any size from one pixel in each | |
746 | dimension up to the size of its screen. | |
747 | However, you can use the \fBwm minsize\fR and \fBwm maxsize\fR commands | |
748 | to limit the range of allowable sizes. | |
749 | The range set by \fBwm minsize\fR and \fBwm maxsize\fR applies to | |
750 | all forms of resizing, including the window's natural size as | |
751 | well as manual resizes and the \fBwm geometry\fR command. | |
752 | You can also use the command \fBwm resizable\fR to completely | |
753 | disable interactive resizing in one or both dimensions. | |
754 | .SH "GRIDDED GEOMETRY MANAGEMENT" | |
755 | .PP | |
756 | Gridded geometry management occurs when one of the widgets of an | |
757 | application supports a range of useful sizes. | |
758 | This occurs, for example, in a text editor where the scrollbars, | |
759 | menus, and other adornments are fixed in size but the edit widget | |
760 | can support any number of lines of text or characters per line. | |
761 | In this case, it is usually desirable to let the user specify the | |
762 | number of lines or characters-per-line, either with the | |
763 | \fBwm geometry\fR command or by interactively resizing the window. | |
764 | In the case of text, and in other interesting cases also, only | |
765 | discrete sizes of the window make sense, such as integral numbers | |
766 | of lines and characters-per-line; arbitrary pixel sizes are not useful. | |
767 | .PP | |
768 | Gridded geometry management provides support for this kind of | |
769 | application. | |
770 | Tk (and the window manager) assume that there is a grid of some | |
771 | sort within the application and that the application should be | |
772 | resized in terms of \fIgrid units\fR rather than pixels. | |
773 | Gridded geometry management is typically invoked by turning on | |
774 | the \fBsetGrid\fR option for a widget; it can also be invoked | |
775 | with the \fBwm grid\fR command or by calling \fBTk_SetGrid\fR. | |
776 | In each of these approaches the particular widget (or sometimes | |
777 | code in the application as a whole) specifies the relationship between | |
778 | integral grid sizes for the window and pixel sizes. | |
779 | To return to non-gridded geometry management, invoke | |
780 | \fBwm grid\fR with empty argument strings. | |
781 | .PP | |
782 | When gridded geometry management is enabled then all the dimensions specified | |
783 | in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands | |
784 | are treated as grid units rather than pixel units. | |
785 | Interactive resizing is also carried out in even numbers of grid units | |
786 | rather than pixels. | |
787 | .SH BUGS | |
788 | .PP | |
789 | Most existing window managers appear to have bugs that affect the | |
790 | operation of the \fBwm\fR command. For example, some changes won't | |
791 | take effect if the window is already active: the window will have | |
792 | to be withdrawn and de-iconified in order to make the change happen. | |
793 | .SH EXAMPLES | |
794 | A fixed-size window that says that it is fixed-size too: | |
795 | .CS | |
796 | toplevel .fixed | |
797 | \fBwm title\fR .fixed "Fixed-size Window" | |
798 | \fBwm resizable\fR .fixed 0 0 | |
799 | .CE | |
800 | .PP | |
801 | A simple dialog-like window, centred on the screen: | |
802 | .CS | |
803 | # Create and arrange the dialog contents. | |
804 | toplevel .msg | |
805 | label .msg.l \-text "This is a very simple dialog demo." | |
806 | button .msg.ok \-text OK \-default active \-command {destroy .msg} | |
807 | pack .msg.ok \-side bottom \-fill x | |
808 | pack .msg.l \-expand 1 \-fill both | |
809 | ||
810 | # Now set the widget up as a centred dialog. | |
811 | ||
812 | # But first, we need the geometry managers to finish setting | |
813 | # up the interior of the dialog, for which we need to run the | |
814 | # event loop with the widget hidden completely... | |
815 | \fBwm withdraw\fR .msg | |
816 | update | |
817 | set x [expr {([winfo screenwidth .]\-[winfo width .msg])/2}] | |
818 | set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] | |
819 | \fBwm geometry\fR .msg +$x+$y | |
820 | \fBwm transient\fR .msg . | |
821 | \fBwm title\fR .msg "Dialog demo" | |
822 | \fBwm deiconify\fR .msg | |
823 | .CE | |
824 | ||
825 | .SH "SEE ALSO" | |
826 | toplevel(n), winfo(n) | |
827 | ||
828 | .SH KEYWORDS | |
829 | aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager |