| 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 |