1wm(n)                        Tk Built-In Commands                        wm(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       wm - Communicate with window manager
9

SYNOPSIS

11       wm option window ?args?
12______________________________________________________________________________
13

DESCRIPTION

15       The  wm  command  is  used to interact with window managers in order to
16       control such things as the title for a window,  its  geometry,  or  the
17       increments  in  terms  of  which it may be resized.  The wm command can
18       take any of a number of different forms, depending on the option  argu‐
19       ment.   All  of the forms expect at least one additional argument, win‐
20       dow, which must be the path name of a top-level window.
21
22       The legal forms for the wm command are:
23
24       wm aspect window ?minNumer minDenom maxNumer maxDenom?
25              If minNumer, minDenom, maxNumer, and maxDenom are all specified,
26              then  they  will  be passed to the window manager and the window
27              manager should use them to enforce a range of acceptable  aspect
28              ratios  for  window.   The aspect ratio of window (width/length)
29              will be constrained to lie between minNumer/minDenom and  maxNu‐
30              mer/maxDenom.   If  minNumer  etc.  are  all  specified as empty
31              strings,  then  any  existing  aspect  ratio  restrictions   are
32              removed.   If  minNumer  etc.  are  specified,  then the command
33              returns an empty string.  Otherwise, it returns a Tcl list  con‐
34              taining four elements, which are the current values of minNumer,
35              minDenom, maxNumer, and maxDenom (if no aspect restrictions  are
36              in effect, then an empty string is returned).
37
38       wm attributes window
39
40       wm attributes window ?option?
41
42       wm attributes window ?option value option value...?
43              This  subcommand  returns  or  sets platform specific attributes
44              associated with a window. The first form returns a list  of  the
45              platform  specific  flags  and  their  values.  The  second form
46              returns the value for the specific option. The third  form  sets
47              one or more of the values. The values are as follows:
48
49              All platforms support the following attributes (though X11 users
50              should see the notes below):
51
52              -alpha Specifies the alpha transparency level of  the  toplevel.
53                     It  accepts  a  value from 0.0 (fully transparent) to 1.0
54                     (opaque).  Values outside that range will be constrained.
55                     Where not supported, the -alpha value remains at 1.0.
56
57              -fullscreen
58                     Places  the  window  in  a  mode that takes up the entire
59                     screen, has no borders, and covers the general  use  area
60                     (i.e. Start menu and taskbar on Windows, dock and menubar
61                     on OSX, general window decorations on X11).
62
63              -topmost
64                     Specifies whether this  is  a  topmost  window  (displays
65                     above all other windows).
66
67              On Windows, the following attributes may be set.
68
69              -disabled
70                     Specifies whether the window is in a disabled state.
71
72              -toolwindow
73                     Specifies  a  toolwindow  style window (as defined in the
74                     MSDN).
75
76              -transparentcolor
77                     Specifies the transparent color index  of  the  toplevel.
78                     It takes any color value accepted by Tk_GetColor.  If the
79                     empty string is specified (default), no transparent color
80                     is  used.   This is supported on Windows 2000/XP+.  Where
81                     not supported, the -transparentcolor value remains at {}.
82
83              On Mac OS X, the following attributes may be set.
84
85              -modified
86                     Specifies the modification state of  the  window  (deter‐
87                     mines  whether the window close widget contains the modi‐
88                     fication indicator and whether the proxy  icon  is  drag‐
89                     gable).
90
91              -notify
92                     Specifies  process  notification  state  (bouncing of the
93                     application dock icon).
94
95              -titlepath
96                     Specifies the path of the file referenced as  the  window
97                     proxy  icon  (which can be dragged and dropped in lieu of
98                     the file's finder icon).
99
100              -transparent
101                     Makes the window content area transparent and  turns  off
102                     the  window shadow. For the transparency to be effective,
103                     the toplevel background needs to be set to a  color  with
104                     some alpha, e.g.  “systemTransparent”.
105
106              On  X11, the following attributes may be set. These are not sup‐
107              ported by all window managers, and will  have  no  effect  under
108              older WMs.
109
110              -type  Requests  that  the  window  should be interpreted by the │
111                     window manager as being of the  specified  type(s).  This │
112                     may  cause  the window to be decorated in a different way │
113                     or otherwise managed  differently,  though  exactly  what │
114                     happens  is  entirely up to the window manager. A list of │
115                     types may be used, in order of preference. The  following │
116                     values are mapped to constants defined in the EWMH speci‐ │
117                     fication (using others is possible, but not advised):     │
118
119                     desktop                                                   
120                            indicates a desktop feature,                       │
121
122                     dock                                                      
123                            indicates a dock/panel feature,                    │
124
125                     toolbar                                                   
126                            indicates a toolbar window that should  be  acting │
127                            on  behalf of another window, as indicated with wm 
128                            transient,                                         │
129
130                     menu                                                      
131                            indicates a torn-off menu that should be acting on │
132                            behalf  of  another  window,  as indicated with wm 
133                            transient,                                         │
134
135                     utility                                                   
136                            indicates a utility window (e.g., palette or tool‐ │
137                            box)  that  should  be acting on behalf of another │
138                            window, as indicated with wm transient,            │
139
140                     splash                                                    
141                            indicates a splash screen, displayed during appli‐ │
142                            cation start up,                                   │
143
144                     dialog                                                    
145                            indicates  a general dialog window, that should be │
146                            acting on behalf of another window,  as  indicated │
147                            with wm transient,                                 │
148
149                     dropdown_menu                                             
150                            indicates  a  menu summoned from a menu bar, which │
151                            should usually also be set  to  be  override-redi‐ │
152                            rected (with wm overrideredirect),                 │
153
154                     popup_menu                                                
155                            indicates  a popup menu, which should usually also │
156                            be set to be override-redirected (with wm overrid‐ 
157                            eredirect),                                        │
158
159                     tooltip                                                   
160                            indicates  a  tooltip window, which should usually │
161                            also be set to  be  override-redirected  (with  wm 
162                            overrideredirect),                                 │
163
164                     notification                                              
165                            indicates  a  window  that  provides  a background │
166                            notification of some event, which  should  usually │
167                            also  be  set  to  be override-redirected (with wm 
168                            overrideredirect),                                 │
169
170                     combo                                                     
171                            indicates the drop-down list of a combobox widget, │
172                            which  should  usually also be set to be override- │
173                            redirected (with wm overrideredirect),             │
174
175                     dnd                                                       
176                            indicates a window that represents something being │
177                            dragged,  which  should  usually also be set to be │
178                            override-redirected (with wm overrideredirect),    │
179
180                     normal                                                    
181                            indicates a window that has no special interpreta‐ │
182                            tion.                                              │
183
184              -zoomed
185                     Requests that the window should be maximized. This is the
186                     same as wm state zoomed on Windows and Mac OS X.
187
188              On  X11,  changes  to  window  attributes  are  performed  asyn‐
189              chronously.  Querying the value of an attribute returns the cur‐
190              rent state, which will  not  be  the  same  as  the  value  most
191              recently  set  if  the  window manager has not yet processed the
192              request or if it does not support the attribute.
193
194       wm client window ?name?
195              If name is specified, this command stores name (which should  be
196              the  name  of the host on which the application is executing) in
197              window's WM_CLIENT_MACHINE property for use by the  window  man‐
198              ager or session manager.  The command returns an empty string in
199              this case.  If name is not specified, the  command  returns  the
200              last  name  set  in  a wm client command for window.  If name is
201              specified  as  an  empty  string,  the   command   deletes   the
202              WM_CLIENT_MACHINE property from window.
203
204       wm colormapwindows window ?windowList?
205              This command is used to manipulate the WM_COLORMAP_WINDOWS prop‐
206              erty, which provides information to the  window  managers  about
207              windows that have private colormaps.
208
209              If windowList is not specified, the command returns a list whose
210              elements are the names of the windows in the WM_COLORMAP_WINDOWS
211              property.   If windowList is specified, it consists of a list of
212              window path names;  the command overwrites the  WM_COLORMAP_WIN‐
213              DOWS  property  with  the  given  windows  and  returns an empty
214              string.  The WM_COLORMAP_WINDOWS property should  normally  con‐
215              tain  a  list  of  the internal windows within window whose col‐
216              ormaps differ from their parents.
217
218              The order of the windows in the property  indicates  a  priority
219              order:  the  window manager will attempt to install as many col‐
220              ormaps as possible from the head of this list when  window  gets
221              the colormap focus.  If window is not included among the windows
222              in windowList, Tk implicitly adds it at the end of  the  WM_COL‐
223              ORMAP_WINDOWS property, so that its colormap is lowest in prior‐
224              ity.  If wm colormapwindows is not invoked,  Tk  will  automati‐
225              cally  set  the  property  for  each top-level window to all the
226              internal windows whose colormaps differ from their parents, fol‐
227              lowed  by  the top-level itself;  the order of the internal win‐
228              dows is undefined.  See the ICCCM documentation for more  infor‐
229              mation on the WM_COLORMAP_WINDOWS property.
230
231       wm command window ?value?
232              If  value  is  specified,  this command stores value in window's
233              WM_COMMAND property for use by the  window  manager  or  session
234              manager  and  returns  an  empty string.  Value must have proper
235              list structure;  the elements should contain the  words  of  the
236              command  used to invoke the application.  If value is not speci‐
237              fied then the command returns the last value set in a wm command
238              command  for  window.  If value is specified as an empty string,
239              the command deletes the WM_COMMAND property from window.
240
241       wm deiconify window
242              Arrange for window to be  displayed  in  normal  (non-iconified)
243              form.   This  is  done by mapping the window.  If the window has
244              never been mapped then this command will not map the window, but
245              it  will  ensure that when the window is first mapped it will be
246              displayed in de-iconified form.  On Windows, a deiconified  win‐
247              dow  will also be raised and be given the focus (made the active
248              window).  Returns an empty string.
249
250       wm focusmodel window ?active|passive?
251              If active or passive is supplied as an optional argument to  the
252              command,  then it specifies the focus model for window.  In this
253              case the command returns an  empty  string.   If  no  additional
254              argument is supplied, then the command returns the current focus
255              model for window.
256
257              An active focus model means that window  will  claim  the  input
258              focus  for  itself  or  its  descendants, even at times when the
259              focus is currently in some  other  application.   Passive  means
260              that  window  will never claim the focus for itself:  the window
261              manager should give the focus to window  at  appropriate  times.
262              However,  once  the focus has been given to window or one of its
263              descendants, the application may re-assign the focus among  win‐
264              dow's  descendants.   The  focus  model defaults to passive, and
265              Tk's focus command assumes a passive model of focusing.
266
267       wm forget window
268              The window will be unmapped from the screen and will  no  longer
269              be  managed  by  wm.   Windows created with the toplevel command
270              will be treated like frame windows once they are no longer  man‐
271              aged  by wm, however, the -menu configuration will be remembered
272              and the menus will return once the widget is managed again.
273
274       wm frame window
275              If window has been reparented by the window manager into a deco‐
276              rative  frame,  the command returns the platform specific window
277              identifier for the outermost frame  that  contains  window  (the
278              window whose parent is the root or virtual root).  If window has
279              not been reparented by  the  window  manager  then  the  command
280              returns the platform specific window identifier for window.
281
282       wm geometry window ?newGeometry?
283              If  newGeometry  is  specified,  then  the geometry of window is
284              changed and an empty string is returned.  Otherwise the  current
285              geometry  for window is returned (this is the most recent geome‐
286              try specified either by manual resizing or in a wm geometry com‐
287              mand).  NewGeometry has the form =widthxheight±x±y, where any of
288              =, widthxheight, or ±x±y may be omitted.  Width and  height  are
289              positive  integers  specifying the desired dimensions of window.
290              If window is gridded (see  GRIDDED  GEOMETRY  MANAGEMENT  below)
291              then the dimensions are specified in grid units;  otherwise they
292              are specified in pixel units.
293
294              X and y specify the desired location of window on the screen, in
295              pixels.   If x is preceded by +, it specifies the number of pix‐
296              els between the left edge of the screen and  the  left  edge  of
297              window's  border;   if preceded by - then x specifies the number
298              of pixels between the right edge of the  screen  and  the  right
299              edge  of  window's border.  If y is preceded by + then it speci‐
300              fies the number of pixels between the top of the screen and  the
301              top of window's border;  if y is preceded by - then it specifies
302              the number of pixels between the bottom of window's  border  and
303              the bottom of the screen.
304
305              If newGeometry is specified as an empty string then any existing
306              user-specified geometry for window is cancelled, and the  window
307              will revert to the size requested internally by its widgets.
308
309              Note  that  this is related to winfo geometry, but not the same.
310              That can only query the geometry, and always reflects Tk's  cur‐
311              rent  understanding  of  the actual size and location of window,
312              whereas wm geometry allows both setting and querying of the win‐
313              dow manager's understanding of the size and location of the win‐
314              dow. This can vary significantly, for  example  to  reflect  the
315              addition  of  decorative  elements to window such as title bars,
316              and window managers are not required  to  precisely  follow  the
317              requests made through this command.
318
319       wm grid window ?baseWidth baseHeight widthInc heightInc?
320              This command indicates that window is to be managed as a gridded
321              window.  It also specifies the relationship between  grid  units
322              and pixel units.  BaseWidth and baseHeight specify the number of
323              grid units  corresponding  to  the  pixel  dimensions  requested
324              internally  by  window  using  Tk_GeometryRequest.  WidthInc and
325              heightInc specify the number of pixels in  each  horizontal  and
326              vertical  grid  unit.   These  four  values determine a range of
327              acceptable sizes for window, corresponding to grid-based  widths
328              and  heights  that are non-negative integers.  Tk will pass this
329              information to the window manager;  during manual resizing,  the
330              window  manager  will restrict the window's size to one of these
331              acceptable sizes.
332
333              Furthermore, during manual resizing the window manager will dis‐
334              play  the  window's  current  size in terms of grid units rather
335              than pixels.  If baseWidth  etc.  are  all  specified  as  empty
336              strings, then window will no longer be managed as a gridded win‐
337              dow.  If baseWidth etc. are specified then the return  value  is
338              an empty string.
339
340              Otherwise  the  return  value is a Tcl list containing four ele‐
341              ments  corresponding  to  the  current  baseWidth,   baseHeight,
342              widthInc,  and  heightInc;   if window is not currently gridded,
343              then an empty string is returned.
344
345              Note: this command should not be needed very  often,  since  the
346              Tk_SetGrid library procedure and the setGrid option provide eas‐
347              ier access to the same functionality.
348
349       wm group window ?pathName?
350              If pathName is specified, it gives the path name for the  leader
351              of  a group of related windows.  The window manager may use this
352              information, for example, to unmap all of the windows in a group
353              when the group's leader is iconified.  PathName may be specified
354              as an empty string to remove window from any group  association.
355              If  pathName  is  specified  then  the  command returns an empty
356              string;  otherwise it returns the path name of window's  current
357              group  leader,  or  an empty string if window is not part of any
358              group.
359
360       wm iconbitmap window ?bitmap?
361              If bitmap is specified, then it names a bitmap in  the  standard
362              forms  accepted  by  Tk  (see  the Tk_GetBitmap manual entry for
363              details).  This bitmap is passed to the  window  manager  to  be
364              displayed  in  window's  icon,  and the command returns an empty
365              string.  If an empty string is specified for  bitmap,  then  any
366              current icon bitmap is cancelled for window.  If bitmap is spec‐
367              ified then the command returns an empty  string.   Otherwise  it
368              returns the name of the current icon bitmap associated with win‐
369              dow, or an empty string if window has no icon  bitmap.   On  the
370              Windows operating system, an additional flag is supported:
371
372              wm iconbitmap window ?-default? ?image?
373                     If the -default flag is given, the icon is applied to all
374                     toplevel windows (existing and future) to which no  other
375                     specific  icon has yet been applied.  In addition to bit‐
376                     map image types, a full path specification  to  any  file
377                     which  contains  a  valid  Windows  icon is also accepted
378                     (usually .ico or .icr files), or any file for  which  the
379                     shell  has  assigned an icon.  Tcl will first test if the
380                     file contains an icon, then if it has an  assigned  icon,
381                     and finally, if that fails, test for a bitmap.
382
383       wm iconify window
384              Arrange  for window to be iconified.  It window has not yet been
385              mapped for the first time, this command will arrange for  it  to
386              appear in the iconified state when it is eventually mapped.
387
388       wm iconmask window ?bitmap?
389              If  bitmap  is specified, then it names a bitmap in the standard
390              forms accepted by Tk (see  the  Tk_GetBitmap  manual  entry  for
391              details).   This  bitmap  is  passed to the window manager to be
392              used as a mask in conjunction with the iconbitmap option:  where
393              the  mask  has  zeroes  no icon will be displayed;  where it has
394              ones, the bits from the icon bitmap will be  displayed.   If  an
395              empty  string is specified for bitmap then any current icon mask
396              is cancelled for window (this is equivalent to specifying a bit‐
397              map  of  all  ones).   If  bitmap  is specified then the command
398              returns an empty string.  Otherwise it returns the name  of  the
399              current  icon mask associated with window, or an empty string if
400              no mask is in effect.
401
402       wm iconname window ?newName?
403              If newName is specified, then it is passed to  the  window  man‐
404              ager;  the window manager should display newName inside the icon
405              associated with  window.   In  this  case  an  empty  string  is
406              returned  as  result.  If newName is not specified then the com‐
407              mand returns the current icon  name  for  window,  or  an  empty
408              string if no icon name has been specified (in this case the win‐
409              dow manager will normally display the window's title, as  speci‐
410              fied with the wm title command).
411
412       wm iconphoto window ?-default? image1 ?image2 ...?
413              Sets  the  titlebar  icon  for  window  based on the named photo
414              images.  If -default is specified, this is applied to all future
415              created toplevels as well.  The data in the images is taken as a
416              snapshot at the time of invocation.  If  the  images  are  later
417              changed,  this is not reflected to the titlebar icons.  Multiple
418              images are accepted to allow different images sizes (e.g., 16x16
419              and 32x32) to be provided. The window manager may scale provided
420              icons to an appropriate size.
421
422              On Windows, the images are packed into a Windows icon structure.
423              This  will  override an ico specified to wm iconbitmap, and vice
424              versa.
425
426              On X, the images are arranged into the _NET_WM_ICON X  property,
427              which  most modern window managers support.  A wm iconbitmap may
428              exist simultaneously.  It is recommended to use not more than  2
429              icons, placing the larger icon first.
430
431              On  Macintosh,  the  first  image  called is loaded into an OSX-
432              native icon format, and becomes the application icon in dialogs,
433              the  Dock,  and  other contexts. At the script level the command
434              will accept only the first image passed  in  the  parameters  as
435              support  for multiple sizes/resolutions on macOS is outside Tk's
436              scope. Developers should use the largest icon they  can  support
437              (preferably 512 pixels) to ensure smooth rendering on the Mac.
438
439       wm iconposition window ?x y?
440              If  x and y are specified, they are passed to the window manager
441              as a hint about where to position the icon for window.  In  this
442              case  an  empty string is returned.  If x and y are specified as
443              empty strings then any existing icon position hint is cancelled.
444              If  neither x nor y is specified, then the command returns a Tcl
445              list containing two values, which are the current icon  position
446              hints  (if  no  hints  are  in  effect  then  an empty string is
447              returned).
448
449       wm iconwindow window ?pathName?
450              If pathName is specified, it is the path name for  a  window  to
451              use  as  icon for window: when window is iconified then pathName
452              will be mapped to serve as icon, and when window is de-iconified
453              then  pathName will be unmapped again.  If pathName is specified
454              as an empty string then any existing icon window association for
455              window will be cancelled.  If the pathName argument is specified
456              then an empty string is returned.  Otherwise the command returns
457              the path name of the current icon window for window, or an empty
458              string if there is no icon window currently specified  for  win‐
459              dow.   Button press events are disabled for window as long as it
460              is an icon window;  this is needed in order to allow window man‐
461              agers to “own” those events.  Note: not all window managers sup‐
462              port the notion of an icon window.
463
464       wm manage widget
465              The widget specified will become a stand alone top-level window.
466              The window will be decorated with the window managers title bar,
467              etc. Only frame, labelframe and toplevel  widgets  can  be  used
468              with this command. Attempting to pass any other widget type will
469              raise an error. Attempting to manage a toplevel widget is benign
470              and achieves nothing. See also GEOMETRY MANAGEMENT.
471
472       wm maxsize window ?width height?
473              If width and height are specified, they give the maximum permis‐
474              sible dimensions for window.  For gridded windows the dimensions
475              are  specified  in  grid units;  otherwise they are specified in
476              pixel units.  The window  manager  will  restrict  the  window's
477              dimensions  to  be  less  than or equal to width and height.  If
478              width and height are specified,  then  the  command  returns  an
479              empty  string.   Otherwise  it  returns a Tcl list with two ele‐
480              ments, which are the  maximum  width  and  height  currently  in
481              effect.   The  maximum  size defaults to the size of the screen.
482              See the sections on geometry management below for more  informa‐
483              tion.
484
485       wm minsize window ?width height?
486              If width and height are specified, they give the minimum permis‐
487              sible dimensions for window.  For gridded windows the dimensions
488              are  specified  in  grid units;  otherwise they are specified in
489              pixel units.  The window  manager  will  restrict  the  window's
490              dimensions  to be greater than or equal to width and height.  If
491              width and height are specified,  then  the  command  returns  an
492              empty  string.   Otherwise  it  returns a Tcl list with two ele‐
493              ments, which are the  minimum  width  and  height  currently  in
494              effect.   The  minimum size defaults to one pixel in each dimen‐
495              sion.  See the sections on geometry management  below  for  more
496              information.
497
498       wm overrideredirect window ?boolean?
499              If  boolean is specified, it must have a proper boolean form and
500              the override-redirect flag for window is set to that value.   If
501              boolean  is  not  specified  then 1 or 0 is returned to indicate
502              whether or not the override-redirect flag is currently  set  for
503              window.   Setting the override-redirect flag for a window causes
504              it to be ignored by the window  manager;   among  other  things,
505              this  means that the window will not be reparented from the root
506              window into a decorative frame and the user will not be able  to
507              manipulate  the  window  using  the normal window manager mecha‐
508              nisms.
509
510              Note that the override-redirect flag is only  guaranteed  to  be
511              taken  notice  of when the window is first mapped or when mapped
512              after the state is changed from withdrawn to normal.  Some,  but
513              not all, platforms will take notice at additional times.
514
515       wm positionfrom window ?who?
516              If  who  is  specified, it must be either program or user, or an
517              abbreviation of one of these two.  It indicates whether window's
518              current  position  was  requested by the program or by the user.
519              Many window managers ignore program-requested initial  positions
520              and  ask  the  user to manually position the window;  if user is
521              specified then the window manager should position the window  at
522              the  given place without asking the user for assistance.  If who
523              is specified as an  empty  string,  then  the  current  position
524              source  is  cancelled.   If  who  is specified, then the command
525              returns an empty string.  Otherwise it returns user  or  program
526              to  indicate  the source of the window's current position, or an
527              empty string if no source has been specified yet.   Most  window
528              managers  interpret  “no  source”  as equivalent to program.  Tk
529              will automatically set the position source to  user  when  a  wm
530              geometry  command  is  invoked,  unless  the source has been set
531              explicitly to program.
532
533       wm protocol window ?name? ?command?
534              This command is used to manage window manager protocols such  as
535              WM_DELETE_WINDOW.   Name is the name of an atom corresponding to
536              a  window  manager  protocol,  such   as   WM_DELETE_WINDOW   or
537              WM_SAVE_YOURSELF or WM_TAKE_FOCUS.  If both name and command are
538              specified, then command is associated with the  protocol  speci‐
539              fied by name.  Name will be added to window's WM_PROTOCOLS prop‐
540              erty to tell the window manager that the application has a  pro‐
541              tocol  handler  for  name,  and  command  will be invoked in the
542              future whenever the window manager sends a message to the client
543              for  that  protocol.   In this case the command returns an empty
544              string.  If name is specified but command is not, then the  cur‐
545              rent  command  for name is returned, or an empty string if there
546              is no handler defined for name.  If command is specified  as  an
547              empty string then the current handler for name is deleted and it
548              is removed from the WM_PROTOCOLS property on window;   an  empty
549              string  is  returned.   Lastly,  if  neither name nor command is
550              specified, the command returns a list of all the  protocols  for
551              which handlers are currently defined for window.
552
553              Tk  always defines a protocol handler for WM_DELETE_WINDOW, even
554              if  you  have  not  asked  for  one  with  wm  protocol.   If  a
555              WM_DELETE_WINDOW  message  arrives  when  you have not defined a
556              handler, then Tk handles the message by  destroying  the  window
557              for which it was received.
558
559       wm resizable window ?width height?
560              This  command controls whether or not the user may interactively
561              resize a top-level window.  If width and height  are  specified,
562              they  are  boolean  values  that determine whether the width and
563              height of window may be modified by the user.  In this case  the
564              command  returns an empty string.  If width and height are omit‐
565              ted then the command returns a list with two 0/1  elements  that
566              indicate  whether  the  width and height of window are currently
567              resizable.  By default, windows are  resizable  in  both  dimen‐
568              sions.   If resizing is disabled, then the window's size will be
569              the size from the most recent interactive resize or wm  geometry
570              command.   If there has been no such operation then the window's
571              natural size will be used.
572
573       wm sizefrom window ?who?
574              If who is specified, it must be either program or  user,  or  an
575              abbreviation of one of these two.  It indicates whether window's
576              current size was requested by the program or by the user.   Some
577              window  managers ignore program-requested sizes and ask the user
578              to manually size the window;  if user is specified then the win‐
579              dow  manager  should  give the window its specified size without
580              asking the user for assistance.  If who is specified as an empty
581              string,  then  the  current size source is cancelled.  If who is
582              specified, then the command returns an empty string.   Otherwise
583              it returns user or window to indicate the source of the window's
584              current size, or an empty string if no source has been specified
585              yet.   Most  window managers interpret “no source” as equivalent
586              to program.
587
588       wm stackorder window ?isabove|isbelow window?
589              The stackorder command returns a list  of  toplevel  windows  in
590              stacking  order,  from lowest to highest. When a single toplevel
591              window is passed, the returned list recursively includes all  of
592              the  window's  children that are toplevels. Only those toplevels
593              that are currently mapped  to  the  screen  are  returned.   The
594              stackorder command can also be used to determine if one toplevel
595              is positioned above or below a second toplevel.  When two window
596              arguments  separated  by either isabove or isbelow are passed, a
597              boolean result indicates whether or not the first window is cur‐
598              rently above or below the second window in the stacking order.
599
600       wm state window ?newstate?
601              If  newstate  is  specified,  the  window will be set to the new
602              state, otherwise it returns the current state of window:  either
603              normal,  iconic, withdrawn, icon, or (Windows and Mac OS X only)
604              zoomed.  The difference between iconic and icon is  that  iconic
605              refers  to  a  window that has been iconified (e.g., with the wm
606              iconify command) while icon refers to a window whose  only  pur‐
607              pose  is  to serve as the icon for some other window (via the wm
608              iconwindow command).  The icon state cannot be set.
609
610       wm title window ?string?
611              If string is specified, then it will be  passed  to  the  window
612              manager  for  use  as  the  title for window (the window manager
613              should display this string in window's title bar).  In this case
614              the command returns an empty string.  If string is not specified
615              then the command returns the current title for the window.   The
616              title for a window defaults to its name.
617
618       wm transient window ?master?
619              If master is specified, then the window manager is informed that
620              window is a transient window (e.g. pull-down  menu)  working  on
621              behalf  of master (where master is the path name for a top-level
622              window).  If master is specified as an empty string then  window
623              is  marked  as not being a transient window any more.  Otherwise
624              the command returns the path name of window's current master, or
625              an  empty  string if window is not currently a transient window.
626              A transient window will mirror state changes in the  master  and
627              inherit  the  state  of  the  master  when initially mapped. The
628              directed graph with an edge from each transient  to  its  master
629              must  be  acyclic.   In particular, it is an error to attempt to
630              make a window a transient of itself.   The  window  manager  may
631              also decorate a transient window differently, removing some fea‐
632              tures normally present (e.g.,  minimize  and  maximize  buttons)
633              though this is entirely at the discretion of the window manager.
634
635       wm withdraw window
636              Arranges  for  window  to  be  withdrawn  from the screen.  This
637              causes the window to be unmapped and forgotten about by the win‐
638              dow  manager.   If  the  window has never been mapped, then this
639              command causes the window to be mapped in the  withdrawn  state.
640              Not  all  window  managers  appear to know how to handle windows
641              that are mapped in the  withdrawn  state.   Note:  it  sometimes
642              seems  to  be  necessary to withdraw a window and then re-map it
643              (e.g. with wm deiconify) to get  some  window  managers  to  pay
644              attention to changes in window attributes such as group.
645

GEOMETRY MANAGEMENT

647       By  default  a  top-level  window  appears on the screen in its natural
648       size, which is the one determined internally by its widgets and  geome‐
649       try  managers.  If the natural size of a top-level window changes, then
650       the window's size changes to match.  A top-level window can be given  a
651       size  other  than  its  natural  size in two ways.  First, the user can
652       resize the window manually using the facilities of the window  manager,
653       such as resize handles.  Second, the application can request a particu‐
654       lar size for a top-level window using the wm geometry  command.   These
655       two cases are handled identically by Tk;  in either case, the requested
656       size overrides the natural size.  You can return the window to its nat‐
657       ural by invoking wm geometry with an empty geometry string.
658
659       Normally  a  top-level  window can have any size from one pixel in each
660       dimension up to the size of its screen.  However, you can  use  the  wm
661       minsize  and wm maxsize commands to limit the range of allowable sizes.
662       The range set by wm minsize and wm maxsize  applies  to  all  forms  of
663       resizing, including the window's natural size as well as manual resizes
664       and the wm geometry command.  You can also use the command wm resizable
665       to completely disable interactive resizing in one or both dimensions.
666
667       The  wm  manage and wm forget commands may be used to perform undocking
668       and docking of windows.  After a widget is managed by  wm  manage  com‐
669       mand,  all other wm subcommands may be used with the widget.  Only wid‐
670       gets created using the toplevel command may have an attached  menu  via
671       the  -menu  configure option.  A toplevel widget may be used as a frame
672       and managed with any of the other geometry managers after using the  wm
673       forget  command.   Any  menu  associated with a toplevel widget will be
674       hidden when managed by another geometry managers.  The menus will reap‐
675       pear once the window is managed by wm.  All custom bindtags for widgets
676       in a subtree that have their top-level widget changed via a  wm  manage
677       or  wm  forget  command,  must be redone to adjust any top-level widget
678       path in the bindtags. Bindtags that have not  been  customized  do  not
679       have to be redone.
680

GRIDDED GEOMETRY MANAGEMENT

682       Gridded geometry management occurs when one of the widgets of an appli‐
683       cation supports a range of useful sizes.  This occurs, for example,  in
684       a  text  editor  where  the scrollbars, menus, and other adornments are
685       fixed in size but the edit widget can support any number  of  lines  of
686       text  or characters per line.  In this case, it is usually desirable to
687       let the user specify the number of lines or characters-per-line, either
688       with  the  wm geometry command or by interactively resizing the window.
689       In the case of text, and in other interesting cases also, only discrete
690       sizes  of  the window make sense, such as integral numbers of lines and
691       characters-per-line;  arbitrary pixel sizes are not useful.
692
693       Gridded geometry management provides support for this kind of  applica‐
694       tion.   Tk (and the window manager) assume that there is a grid of some
695       sort within the application and that the application should be  resized
696       in terms of grid units rather than pixels.  Gridded geometry management
697       is typically invoked by turning on the setGrid option for a widget;  it
698       can  also be invoked with the wm grid command or by calling Tk_SetGrid.
699       In each of these approaches the particular widget (or sometimes code in
700       the application as a whole) specifies the relationship between integral
701       grid sizes for the window and pixel sizes.  To  return  to  non-gridded
702       geometry management, invoke wm grid with empty argument strings.
703
704       When  gridded  geometry  management  is enabled then all the dimensions
705       specified in wm minsize, wm  maxsize,  and  wm  geometry  commands  are
706       treated as grid units rather than pixel units.  Interactive resizing is
707       also carried out in even numbers of grid units rather than pixels.
708

BUGS

710       Most existing window managers appear to have bugs that affect the oper‐
711       ation  of  the  wm  command.   For  example, some changes will not take
712       effect if the window is already active:  the window  will  have  to  be
713       withdrawn and de-iconified in order to make the change happen.
714

EXAMPLES

716       A fixed-size window that says that it is fixed-size too:
717              toplevel .fixed
718              wm title     .fixed "Fixed-size Window"
719              wm resizable .fixed 0 0
720
721       A simple dialog-like window, centred on the screen:
722              # Create and arrange the dialog contents.
723              toplevel .msg
724              label  .msg.l  -text "This is a very simple dialog demo."
725              button .msg.ok -text OK -default active -command {destroy .msg}
726              pack .msg.ok -side bottom -fill x
727              pack .msg.l  -expand 1    -fill both
728
729              # Now set the widget up as a centred dialog.
730
731              # But first, we need the geometry managers to finish setting
732              # up the interior of the dialog, for which we need to run the
733              # event loop with the widget hidden completely...
734              wm withdraw .msg
735              update
736              set x [expr {([winfo screenwidth .]-[winfo width .msg])/2}]
737              set y [expr {([winfo screenheight .]-[winfo height .msg])/2}]
738              wm geometry  .msg +$x+$y
739              wm transient .msg .
740              wm title     .msg "Dialog demo"
741              wm deiconify .msg
742

SEE ALSO

744       toplevel(n), winfo(n)
745

KEYWORDS

747       aspect  ratio,  deiconify,  focus  model,  geometry, grid, group, icon,
748       iconify, increments, position, size, title,  top-level  window,  units,
749       window manager
750
751
752
753Tk                                    8.5                                wm(n)
Impressum