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
              window  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/minDenom    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 maxDenom (if no  aspect  restrictions
              are in effect, then an empty string is returned).

       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
              specified, 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_COLORMAP_WINDOWS    property,   which   provides
              information to the window  managers  about  windows
              that  have  private 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_WINDOWS    property   should   normally
              contain a  list  of  the  internal  windows  within
              window  whose  colormaps differ from their parents.
              The order of the windows in the property  indicates
              a  priority  order: the window manager will attempt
              to install as many colormaps 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_COLORMAP_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
              command  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
              window.   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.
              Passive 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
              outermost 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
              specified either by manual  resizing  or  in  a  wm
              geometry   command).    NewGeometry  has  the  form
              =widthxheight+-x+-y, where any of =,  widthxheight,
              or  +-x+-y  may  be  omitted.  Width and height are
              positive 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 preceded 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
              relationship 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_GeometryRequest.  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
              window'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
              example,  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;
              otherwise 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_GetBitmap  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 command 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.

       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
              iconified 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_GetBitmap  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  associated 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
              command).

       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
              values, 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
              currently   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
              window.

       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
              window'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.  Otherwise 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
              window's  dimensions to be greater than or equal to
              width  and  height.   If  width  and   height   are
              specified,   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
              currently  set  for  window.  Setting the override-
              redirect 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
              window  managers  ignore  program-requested initial
              positions and ask the user to manually position the
              window;   if  user  is  specified  then  the window
              manager 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.   Otherwise  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 command is invoked, unless the source
              has been set explicitly to program.

       wm protocol window ?name? ?command?
              This command  is  used  to  manage  window  manager
              protocols  such  as  WM_DELETE_WINDOW.  Name is the
              name of an atom corresponding to a  window  manager
              protocol,     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  protocol  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
              window  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
              dimensions.   If  resizing  is  disabled,  then the
              window's size will be the size from the most recent
              interactive  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
              window  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 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).
              Some window managers will use this  information  to
              manage window specially.  If master is specified as
              an empty string then window is marked as not  being
              a   transient   window  any  more.   If  master  is
              specified,  then  the  command  returns  an   empty
              string.   Otherwise  the  command  returns the path
              name of window's current master, or an empty string
              if window isn't currently a transient window.

       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
              window 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  handle windows that are mapped in the withdrawn
              state.  Note: it sometimes seems to be necessary to
              withdraw  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
       window 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
       commands 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
       interactive 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
       scrollbars, 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
       desirable  to  let the user specify the number of lines or
       characters-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,
