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