NAME
       wm - Communicate with window manager

SYNOPSIS
       wm option window ?args?


DESCRIPTION
       The wm command is used to interact with window managers in
       order to control such things as the title  for  a  window,
       its  geometry,  or the increments in terms of which it may
       be resized.  The wm command can take any of  a  number  of
       different forms, depending on the option argument.  All of
       the forms expect at least one additional argument, window,
       which must be the path name of a top-level window.

       The legal forms for the wm command are:

       wm aspect window ?minNumer minDenom maxNumer maxDenom?
              If  minNumer,  minDenom, maxNumer, and maxDenom are
              all specified, then they will be passed to the win-
              dow  manager and the window manager should use them
              to enforce a range of acceptable aspect ratios  for
              window.   The aspect ratio of window (width/length)
              will be constrained to lie between  minNumer/minDe-
              nom  and  maxNumer/maxDenom.   If minNumer etc. are
              all specified as empty strings, then  any  existing
              aspect ratio restrictions are removed.  If minNumer
              etc. are specified, then  the  command  returns  an
              empty  string.   Otherwise,  it  returns a Tcl list
              containing four elements,  which  are  the  current
              values  of minNumer, minDenom, maxNumer, and maxDe-
              nom (if no aspect restrictions are in effect,  then
              an empty string is returned).

       wm attributes window

       wm attributes window ?option?

       wm attributes window ?option value option value...?
              This  subcommand  returns or sets platform specific
              attributes associated with a window. The first form
              returns  a  list of the platform specific flags and
              their values. The second form returns the value for
              the  specific  option.  The  third form sets one or
              more of the values. The values are as follows:

              On Windows, -disabled gets or sets whether the win-
              dow  is  in  a  disabled state. -toolwindow gets or
              sets the style of  the  window  to  toolwindow  (as
              defined in the MSDN). -topmost gets or sets whether
              this is a topmost window (displays above all  other
              windows).

              On Macintosh,

              On  Unix,  there are currently no special attribute
              values.

       wm client window ?name?
              If name is  specified,  this  command  stores  name
              (which  should be the name of the host on which the
              application    is    executing)     in     window's
              WM_CLIENT_MACHINE  property  for  use by the window
              manager or session manager.  The command returns an
              empty  string  in  this case.  If name isn't speci-
              fied, the command returns the last name set in a wm
              client command for window.  If name is specified as
              an  empty   string,   the   command   deletes   the
              WM_CLIENT_MACHINE property from window.

       wm colormapwindows window ?windowList?
              This  command  is  used  to  manipulate the WM_COL-
              ORMAP_WINDOWS property, which provides  information
              to the window managers about windows that have pri-
              vate colormaps.  If windowList isn't specified, the
              command returns a list whose elements are the names
              of the windows in the WM_COLORMAP_WINDOWS property.
              If  windowList  is specified, it consists of a list
              of window path names;  the command  overwrites  the
              WM_COLORMAP_WINDOWS property with the given windows
              and returns an empty string.  The  WM_COLORMAP_WIN-
              DOWS property should normally contain a list of the
              internal windows within window whose colormaps dif-
              fer  from  their parents.  The order of the windows
              in the property indicates  a  priority  order:  the
              window manager will attempt to install as many col-
              ormaps as possible from the head of this list  when
              window  gets  the colormap focus.  If window is not
              included  among  the  windows  in  windowList,   Tk
              implicitly  adds  it  at  the  end  of  the WM_COL-
              ORMAP_WINDOWS property, so  that  its  colormap  is
              lowest  in  priority.  If wm colormapwindows is not
              invoked, Tk will automatically set the property for
              each  top-level  window to all the internal windows
              whose colormaps differ from their parents, followed
              by the top-level itself;  the order of the internal
              windows is undefined.  See the ICCCM  documentation
              for  more  information  on  the WM_COLORMAP_WINDOWS
              property.

       wm command window ?value?
              If value is specified, this command stores value in
              window's  WM_COMMAND property for use by the window
              manager or session manager  and  returns  an  empty
              string.   Value  must  have  proper list structure;
              the elements should contain the words of  the  com-
              mand  used  to  invoke  the  application.  If value
              isn't specified then the command returns  the  last
              value  set  in a wm command command for window.  If
              value is specified as an empty string, the  command
              deletes the WM_COMMAND property from window.

       wm deiconify window
              Arrange  for window to be displayed in normal (non-
              iconified) form.  This is done by mapping the  win-
              dow.  If the window has never been mapped then this
              command will not map the window, but it will ensure
              that  when  the  window  is first mapped it will be
              displayed in  de-iconified  form.   On  Windows,  a
              deiconified window will also be raised and be given
              the focus (made the  active  window).   Returns  an
              empty string.

       wm focusmodel window ?active|passive?
              If  active  or  passive  is supplied as an optional
              argument to the  command,  then  it  specifies  the
              focus  model  for window.  In this case the command
              returns an empty string.  If no additional argument
              is  supplied,  then the command returns the current
              focus model for  window.   An  active  focus  model
              means  that  window  will claim the input focus for
              itself or its descendants, even at times  when  the
              focus is currently in some other application.  Pas-
              sive means that window will never claim  the  focus
              for  itself:   the  window  manager should give the
              focus to window  at  appropriate  times.   However,
              once  the  focus has been given to window or one of
              its descendants, the application may re-assign  the
              focus  among window's descendants.  The focus model
              defaults to passive, and Tk's focus command assumes
              a passive model of focusing.

       wm frame window
              If window has been reparented by the window manager
              into a decorative frame, the  command  returns  the
              platform  specific window identifier for the outer-
              most frame that contains window (the  window  whose
              parent  is  the  root  or virtual root).  If window
              hasn't been reparented by the window  manager  then
              the  command  returns  the platform specific window
              identifier for window.

       wm geometry window ?newGeometry?
              If newGeometry is specified, then the  geometry  of
              window  is changed and an empty string is returned.
              Otherwise  the  current  geometry  for  window   is
              returned  (this  is the most recent geometry speci-
              fied either by manual resizing or in a wm  geometry
              command).    NewGeometry   has  the  form  =widthx-
              height+-x+-y, where  any  of  =,  widthxheight,  or
              +-x+-y  may be omitted.  Width and height are posi-
              tive integers specifying the desired dimensions  of
              window.  If window is gridded (see GRIDDED GEOMETRY
              MANAGEMENT below) then the dimensions are specified
              in  grid  units;   otherwise  they are specified in
              pixel units.  X and y specify the desired  location
              of  window  on the screen, in pixels.  If x is pre-
              ceded by +,  it  specifies  the  number  of  pixels
              between  the  left  edge of the screen and the left
              edge of window's border;  if preceded by -  then  x
              specifies  the  number  of pixels between the right
              edge of the screen and the right edge  of  window's
              border.   If  y  is preceded by + then it specifies
              the number of pixels between the top of the  screen
              and  the  top of window's border;  if y is preceded
              by - then it specifies the number of pixels between
              the bottom of window's border and the bottom of the
              screen.  If newGeometry is specified  as  an  empty
              string  then  any  existing user-specified geometry
              for window is cancelled, and the window will revert
              to the size requested internally by its widgets.

       wm grid window ?baseWidth baseHeight widthInc heightInc?
              This command indicates that window is to be managed
              as a gridded window.  It also specifies  the  rela-
              tionship   between  grid  units  and  pixel  units.
              BaseWidth and baseHeight specify the number of grid
              units   corresponding   to   the  pixel  dimensions
              requested internally by window using Tk_GeometryRe-
              quest.   WidthInc  and heightInc specify the number
              of pixels in  each  horizontal  and  vertical  grid
              unit.   These  four  values  determine  a  range of
              acceptable sizes for window, corresponding to grid-
              based  widths  and  heights  that  are non-negative
              integers.  Tk will pass  this  information  to  the
              window manager;  during manual resizing, the window
              manager will restrict the window's size to  one  of
              these acceptable sizes.  Furthermore, during manual
              resizing the window manager will display  the  win-
              dow's  current  size  in terms of grid units rather
              than pixels.  If baseWidth etc. are  all  specified
              as  empty  strings,  then  window will no longer be
              managed as a gridded window.  If baseWidth etc. are
              specified then the return value is an empty string.
              Otherwise the return value is a Tcl list containing
              four   elements   corresponding   to   the  current
              baseWidth, baseHeight, widthInc, and heightInc;  if
              window  is  not  currently  gridded,  then an empty
              string is returned.  Note: this command should  not
              be  needed very often, since the Tk_SetGrid library
              procedure and the  setGrid  option  provide  easier
              access to the same functionality.

       wm group window ?pathName?
              If  pathName  is  specified, it gives the path name
              for the leader of a group of related windows.   The
              window  manager may use this information, for exam-
              ple, to unmap all of the windows in  a  group  when
              the  group's  leader is iconified.  PathName may be
              specified as an empty string to remove window  from
              any  group  association.   If pathName is specified
              then the command returns an empty  string;   other-
              wise  it  returns the path name of window's current
              group leader, or an empty string  if  window  isn't
              part of any group.

       wm iconbitmap window ?bitmap?
              If  bitmap  is specified, then it names a bitmap in
              the standard forms accepted by Tk (see the  Tk_Get-
              Bitmap  manual  entry for details).  This bitmap is
              passed to the window manager  to  be  displayed  in
              window's  icon,  and  the  command returns an empty
              string.   If  an  empty  string  is  specified  for
              bitmap,  then  any current icon bitmap is cancelled
              for window.  If bitmap is specified then  the  com-
              mand returns an empty string.  Otherwise it returns
              the name of the current icon bitmap associated with
              window,  or  an  empty string if window has no icon
              bitmap.  On the Windows operating system, an  addi-
              tional  flag  is  supported:  wm  iconbitmap window
              ?-default? ?image?.  If the -default flag is given,
              the icon is applied to all toplevel windows (exist-
              ing and future) to which no other specific icon has
              yet  been  applied.   In  addition  to bitmap image
              types, a full path specification to any file  which
              contains  a  valid  Windows  icon  is also accepted
              (usually .ico or .icr files), or any file for which
              the  shell  has  assigned  an icon.  Tcl will first
              test if the file contains an icon, then if  it  has
              an  assigned icon, and finally, if that fails, test
              for a bitmap.

       wm iconify window
              Arrange for window  to  be  iconified.   It  window
              hasn't  yet  been  mapped  for the first time, this
              command will arrange for it to appear in the iconi-
              fied state when it is eventually mapped.

       wm iconmask window ?bitmap?
              If  bitmap  is specified, then it names a bitmap in
              the standard forms accepted by Tk (see the  Tk_Get-
              Bitmap  manual  entry for details).  This bitmap is
              passed to the window manager to be used as  a  mask
              in  conjunction  with the iconbitmap option:  where
              the mask has zeroes  no  icon  will  be  displayed;
              where  it  has  ones, the bits from the icon bitmap
              will be displayed.  If an empty string is specified
              for  bitmap then any current icon mask is cancelled
              for window (this  is  equivalent  to  specifying  a
              bitmap  of  all ones).  If bitmap is specified then
              the command returns an empty string.  Otherwise  it
              returns  the  name of the current icon mask associ-
              ated with window, or an empty string if no mask  is
              in effect.

       wm iconname window ?newName?
              If  newName  is specified, then it is passed to the
              window manager;  the window manager should  display
              newName inside the icon associated with window.  In
              this case an empty string is  returned  as  result.
              If newName isn't specified then the command returns
              the current icon  name  for  window,  or  an  empty
              string  if no icon name has been specified (in this
              case the window manager will normally  display  the
              window's title, as specified with the wm title com-
              mand).

       wm iconposition window ?x y?
              If x and y are specified, they are  passed  to  the
              window  manager  as  a hint about where to position
              the icon for window.  In this case an empty  string
              is  returned.   If  x  and y are specified as empty
              strings then any existing  icon  position  hint  is
              cancelled.   If  neither x nor y is specified, then
              the command returns a Tcl list containing two  val-
              ues,  which are the current icon position hints (if
              no hints are in effect  then  an  empty  string  is
              returned).

       wm iconwindow window ?pathName?
              If pathName is specified, it is the path name for a
              window to use as icon for window:  when  window  is
              iconified  then pathName will be mapped to serve as
              icon, and when window is de-iconified then pathName
              will  be  unmapped again.  If pathName is specified
              as an empty string then any  existing  icon  window
              association  for  window will be cancelled.  If the
              pathName argument is specified then an empty string
              is  returned.   Otherwise  the  command returns the
              path name of the current icon window for window, or
              an  empty  string  if  there is no icon window cur-
              rently specified for window.  Button  press  events
              are  disabled  for  window as long as it is an icon
              window;  this is needed in order  to  allow  window
              managers  to  ``own''  those events.  Note: not all
              window managers support the notion of an icon  win-
              dow.

       wm maxsize window ?width height?
              If  width  and  height are specified, they give the
              maximum permissible  dimensions  for  window.   For
              gridded  windows  the  dimensions  are specified in
              grid units;  otherwise they are specified in  pixel
              units.   The  window manager will restrict the win-
              dow's dimensions to be less than or equal to  width
              and  height.   If  width  and height are specified,
              then the command returns an empty  string.   Other-
              wise it returns a Tcl list with two elements, which
              are the  maximum  width  and  height  currently  in
              effect.   The  maximum size defaults to the size of
              the screen.  If resizing has been disabled with the
              wm  resizable  command,  then  this  command has no
              effect.  See the sections  on  geometry  management
              below for more information.

       wm minsize window ?width height?
              If  width  and  height are specified, they give the
              minimum permissible  dimensions  for  window.   For
              gridded  windows  the  dimensions  are specified in
              grid units;  otherwise they are specified in  pixel
              units.   The  window manager will restrict the win-
              dow's dimensions to be greater  than  or  equal  to
              width  and  height.  If width and height are speci-
              fied, then the command  returns  an  empty  string.
              Otherwise  it returns a Tcl list with two elements,
              which are the minimum width and height currently in
              effect.   The minimum size defaults to one pixel in
              each dimension.  If resizing has been disabled with
              the  wm resizable command, then this command has no
              effect.  See the sections  on  geometry  management
              below for more information.

       wm overrideredirect window ?boolean?
              If  boolean  is  specified,  it  must have a proper
              boolean form and  the  override-redirect  flag  for
              window  is  set  to  that value.  If boolean is not
              specified then 1  or  0  is  returned  to  indicate
              whether  or  not the override-redirect flag is cur-
              rently set for window.  Setting the  override-redi-
              rect  flag  for a window causes it to be ignored by
              the window manager;  among other things, this means
              that  the  window  will  not be reparented from the
              root window into a decorative frame  and  the  user
              will not be able to manipulate the window using the
              normal window manager mechanisms.

       wm positionfrom window ?who?
              If who is specified, it must be either  program  or
              user,  or  an abbreviation of one of these two.  It
              indicates whether  window's  current  position  was
              requested by the program or by the user.  Many win-
              dow managers ignore program-requested initial posi-
              tions  and  ask  the  user to manually position the
              window;  if user is specified then the window  man-
              ager  should position the window at the given place
              without asking the user for assistance.  If who  is
              specified  as  an  empty  string,  then the current
              position source is cancelled.  If who is specified,
              then  the  command returns an empty string.  Other-
              wise it returns user or  program  to  indicate  the
              source  of  the  window's  current  position, or an
              empty string if no source has been  specified  yet.
              Most  window  managers  interpret  ``no source'' as
              equivalent to program.  Tk will  automatically  set
              the position source to user when a wm geometry com-
              mand is invoked, unless the  source  has  been  set
              explicitly to program.

       wm protocol window ?name? ?command?
              This  command is used to manage window manager pro-
              tocols such as WM_DELETE_WINDOW.  Name is the  name
              of an atom corresponding to a window manager proto-
              col, such as WM_DELETE_WINDOW  or  WM_SAVE_YOURSELF
              or  WM_TAKE_FOCUS.   If  both  name and command are
              specified, then command is associated with the pro-
              tocol  specified  by  name.   Name will be added to
              window's WM_PROTOCOLS property to tell  the  window
              manager that the application has a protocol handler
              for name, and command will be invoked in the future
              whenever  the window manager sends a message to the
              client for that protocol.  In this case the command
              returns  an empty string.  If name is specified but
              command isn't, then the current command for name is
              returned, or an empty string if there is no handler
              defined for name.  If command is  specified  as  an
              empty  string  then the current handler for name is
              deleted and it is  removed  from  the  WM_PROTOCOLS
              property  on  window;  an empty string is returned.
              Lastly, if neither name nor command  is  specified,
              the command returns a list of all the protocols for
              which handlers are currently defined for window.

              Tk  always   defines   a   protocol   handler   for
              WM_DELETE_WINDOW, even if you haven't asked for one
              with wm protocol.  If  a  WM_DELETE_WINDOW  message
              arrives when you haven't defined a handler, then Tk
              handles the message by destroying  the  window  for
              which it was received.

       wm resizable window ?width height?
              This  command  controls whether or not the user may
              interactively resize a top-level window.  If  width
              and  height  are specified, they are boolean values
              that determine whether the width and height of win-
              dow  may be modified by the user.  In this case the
              command returns an  empty  string.   If  width  and
              height  are omitted then the command returns a list
              with two 0/1 elements  that  indicate  whether  the
              width and height of window are currently resizable.
              By default, windows are resizable  in  both  dimen-
              sions.   If resizing is disabled, then the window's
              size will be the size from the most recent interac-
              tive  resize  or wm geometry command.  If there has
              been no such operation then  the  window's  natural
              size will be used.

       wm sizefrom window ?who?
              If  who  is specified, it must be either program or
              user, or an abbreviation of one of these  two.   It
              indicates   whether   window's   current  size  was
              requested by the program or by the user.  Some win-
              dow managers ignore program-requested sizes and ask
              the user to manually size the window;  if  user  is
              specified  then  the window manager should give the
              window its specified size without asking  the  user
              for  assistance.   If  who is specified as an empty
              string, then the current size source is  cancelled.
              If  who  is  specified, then the command returns an
              empty string.  Otherwise it returns user or  window
              to  indicate  the  source  of  the window's current
              size, or an empty string  if  no  source  has  been
              specified yet.  Most window managers interpret ``no
              source'' as equivalent to program.

       wm stackorder window ?isabove|isbelow window?
              The stackorder command returns a list  of  toplevel
              windows  in stacking order, from lowest to highest.
              When  a  single  toplevel  window  is  passed,  the
              returned  list recursively includes all of the win-
              dow's  children  that  are  toplevels.  Only  those
              toplevels  that  are currently mapped to the screen
              are returned.  The stackorder command can  also  be
              used  to  determine  if  one toplevel is positioned
              above or below a second toplevel.  When two  window
              arguments  separated  by  either isabove or isbelow
              are passed, a boolean result indicates  whether  or
              not  the  first  window is currently above or below
              the second window in the stacking order.

       wm state window ?newstate?
              If newstate is specified, the window will be set to
              the  new  state,  otherwise  it returns the current
              state of window: either normal, iconic,  withdrawn,
              icon,  or  (Windows  only)  zoomed.  The difference
              between iconic and icon is that iconic refers to  a
              window  that  has been iconified (e.g., with the wm
              iconify command) while  icon  refers  to  a  window
              whose only purpose is to serve as the icon for some
              other window (via the wm iconwindow command).   The
              icon state cannot be set.

       wm title window ?string?
              If  string  is specified, then it will be passed to
              the window manager for use as the title for  window
              (the  window  manager should display this string in
              window's title bar).   In  this  case  the  command
              returns an empty string.  If string isn't specified
              then the command returns the current title for  the
              window.   The  title  for  a window defaults to its
              name.

       wm transient window ?master?
              If master is specified, then the window manager  is
              informed  that  window  is a transient window (e.g.
              pull-down menu) working on behalf of master  (where
              master  is  the  path name for a top-level window).
              If master is specified as an empty string then win-
              dow  is  marked as not being a transient window any
              more.  Otherwise the command returns the path  name
              of  window's  current master, or an empty string if
              window isn't currently a transient window.  A tran-
              sient  window will mirror state changes in the mas-
              ter and inherit the state of the master  when  ini-
              tially  mapped. It is an error to attempt to make a
              window a transient of itself.

       wm withdraw window
              Arranges  for  window  to  be  withdrawn  from  the
              screen.   This causes the window to be unmapped and
              forgotten about by the window manager.  If the win-
              dow has never been mapped, then this command causes
              the window to be mapped  in  the  withdrawn  state.
              Not  all window managers appear to know how to han-
              dle windows that are mapped in the withdrawn state.
              Note:  it  sometimes seems to be necessary to with-
              draw a window and then  re-map  it  (e.g.  with  wm
              deiconify)  to  get  some  window  managers  to pay
              attention to changes in window attributes  such  as
              group.


GEOMETRY MANAGEMENT
       By default a top-level window appears on the screen in its
       natural size, which is the one  determined  internally  by
       its widgets and geometry managers.  If the natural size of
       a top-level window changes, then the window's size changes
       to  match.   A  top-level window can be given a size other
       than its natural size in two ways.  First,  the  user  can
       resize  the  window  manually  using the facilities of the
       window manager,  such  as  resize  handles.   Second,  the
       application  can request a particular size for a top-level
       window using the wm geometry command.  These two cases are
       handled  identically by Tk;  in either case, the requested
       size overrides the natural size.  You can return the  win-
       dow  to  its natural by invoking wm geometry with an empty
       geometry string.

       Normally a top-level window can have  any  size  from  one
       pixel  in  each  dimension  up  to the size of its screen.
       However, you can use the wm minsize and  wm  maxsize  com-
       mands  to  limit  the range of allowable sizes.  The range
       set by wm minsize and wm maxsize applies to all  forms  of
       resizing,  including  the window's natural size as well as
       manual resizes and the wm geometry command.  You can  also
       use  the command wm resizable to completely disable inter-
       active resizing in one or both dimensions.


GRIDDED GEOMETRY MANAGEMENT
       Gridded geometry management occurs when one of the widgets
       of  an application supports a range of useful sizes.  This
       occurs, for example, in a text editor  where  the  scroll-
       bars,  menus,  and  other adornments are fixed in size but
       the edit widget can support any number of lines of text or
       characters  per  line.  In this case, it is usually desir-
       able to let the user specify the number of lines or  char-
       acters-per-line, either with the wm geometry command or by
       interactively resizing the window.  In the case  of  text,
       and  in  other interesting cases also, only discrete sizes
       of the window make sense,  such  as  integral  numbers  of
       lines  and characters-per-line;  arbitrary pixel sizes are
       not useful.

       Gridded geometry management provides support for this kind
       of  application.   Tk (and the window manager) assume that
       there is a grid of some sort within  the  application  and
       that  the  application  should be resized in terms of grid
       units rather than pixels.  Gridded geometry management  is
       typically  invoked  by turning on the setGrid option for a
       widget;  it can also be invoked with the wm  grid  command
       or by calling Tk_SetGrid.  In each of these approaches the
       particular widget (or sometimes code in the application as
       a  whole) specifies the relationship between integral grid
       sizes for the window and pixel sizes.  To return  to  non-
       gridded  geometry  management,  invoke  wm grid with empty
       argument strings.

       When gridded geometry management is enabled then  all  the
       dimensions  specified  in  wm  minsize, wm maxsize, and wm
       geometry commands are treated as grid  units  rather  than
       pixel  units.  Interactive resizing is also carried out in
       even numbers of grid units rather than pixels.


BUGS
       Most existing window managers appear  to  have  bugs  that
       affect the operation of the wm command.  For example, some
       changes won't take effect if the window is already active:
       the  window  will have to be withdrawn and de-iconified in
       order to make the change happen.


KEYWORDS
       aspect ratio,  deiconify,  focus  model,  geometry,  grid,
       group,  icon,  iconify, increments, position, size, title,
