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   minNu-
              mer/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  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 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.  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 focussing.

       wm frame window
              If window has been reparented by the window manager
              into a decorative frame, the command returns the  X
              window identifier for the outermost frame that con-
              tains 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
              X 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_GeometryRequest.  WidthInc and heightInc specify
              the  number of pixels in each horizontal and verti-
              cal 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_GetBitmap  manual  entry  for  details).    This
              bitmap  is  passed to the window manager to be dis-
              played 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.

       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_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 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 should be mapped  to  serve
              as icon, and when window is de-iconified then path-
              Name will be unmapped again.  If pathName is speci-
              fied as an empty string then any existing icon win-
              dow 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 win-
              dow, or an empty string if there is no icon  window
              currently specified for window.  Note: not all win-
              dow managers support the notion of an icon  window.

       wm maxsize window ?width height?
              If  width  and  height  are  specified, then window
              becomes resizable and width  and  height  give  its
              maximum  permissible  dimensions.  For gridded win-
              dows the dimensions are specified  in  grid  units;
              otherwise  they are specified in pixel units.  Dur-
              ing  manual  sizing,  the  window  manager   should
              restrict the window's dimensions to be less than or
              equal to width and height.  If width and height are
              specified  as  empty strings, then the maximum size
              option is  cancelled  for  window.   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;  if no  maximum  dimen-
              sions are in effect for window then an empty string
              is returned.  See the sections on geometry  manage-
              ment below for more information.

       wm minsize window ?width height?
              If  width  and  height  are  specified, then window
              becomes resizable and width  and  height  give  its
              minimum  permissible  dimensions.  For gridded win-
              dows the dimensions are specified  in  grid  units;
              otherwise  they are specified in pixel units.  Dur-
              ing  manual  sizing,  the  window  manager   should
              restrict the window's dimensions to be greater than
              or equal to width and height.  If width and  height
              are  specified  as  empty strings, then the minimum
              size option is cancelled for window.  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;  if no  minimum  dimen-
              sions are in effect for window then an empty string
              is returned.  See the sections on geometry  manage-
              ment 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-
              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 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  window  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
              protocol,    such    as     WM_DELETE_WINDOW     or
              WM_SAVE_YOURSELF  or  WM_TAKE_FOCUS.   If both name
              and command are specified, then command is  associ-
              ated  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 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 state window
              Returns  the  current state of window:  either nor-
              mal, iconic, or withdrawn.

       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  speci-
              fied,  then  the  command  returns an empty string.
              Otherwise the command returns the path name of win-
              dow'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 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.


SOURCES OF GEOMETRY INFORMATION
       Size-related  information  for  top-level windows can come
       from three sources.  First, geometry  requests  come  from
       the  widgets  that  are descendants of a top-level window.
       Each widget requests a particular size for itself by call-
       ing  Tk_GeometryRequest.   This  information  is passed to
       geometry managers, which then request large  enough  sizes
       for  parent  windows  so that they can layout the children
       properly.  Geometry information passes upwards through the
       window  hierarchy  until  eventually  a particular size is
       requested for each top-level window.  These  requests  are
       called  internal  requests  in  the discussion below.  The
       second source of width and height information  is  through
       the  wm  geometry  command.  Third, the user can request a
       particular size for a window using the interactive facili-
       ties of the window manager.  The second and third types of
       geometry requests are called external requests in the dis-
       cussion  below;   Tk  treats  these  two kinds of requests
       identically.
UNGRIDDED GEOMETRY MANAGEMENT
       Tk allows the geometry of a top-level window to be managed
       in  either of two general ways: ungridded or gridded.  The
       ungridded form occurs if  no  wm  grid  command  has  been
       issued  for  a top-level window.  Ungridded management has
       several variants.  In the simplest  variant  of  ungridded
       windows,  no  wm  geometry, wm minsize, or wm maxsize com-
       mands have been invoked either.  In this  case,  the  win-
       dow's  size is determined totally by the internal requests
       emanating from the widgets inside the window:  Tk will ask
       the  window  manager  not to permit the user to resize the
       window interactively.

       If a wm geometry command is invoked on an  ungridded  win-
       dow,  then  the  size  in  that command overrides any size
       requested by the window's widgets;  from now on, the  win-
       dow's  size will be determined entirely by the most recent
       information from wm geometry  commands.   To  go  back  to
       using  the size requested by the window's widgets, issue a
       wm geometry command with an empty geometry string.

       To enable interactive resizing of an ungridded window, one
       or  both of the wm maxsize and wm minsize commands must be
       issued.  The  information  from  these  commands  will  be
       passed  to the window manager, and size changes within the
       specified range will be permitted.  For ungridded  windows
       the  limits  refer to the top-level window's dimensions in
       pixels.  If only a wm maxsize command is issued  then  the
       minimum  dimensions  default  to  1;  if only a wm minsize
       command is issued then the maximum dimensions  default  to
       the  size  of  the  display.   If  the size of a window is
       changed interactively, it has the same  effect  as  if  wm
       geometry had been invoked:  from now on, internal geometry
       requests will be ignored.  To return to  internal  control
       over  the  window's size, issue a wm geometry command with
       an empty geometry argument.  If a window has been manually
       resized  or moved, the wm geometry command will return the
       geometry that was requested interactively.


GRIDDED GEOMETRY MANAGEMENT
       The second style of geometry management is called gridded.
       This  approach occurs when one of the widgets of an appli-
       cation 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 charac-
       ters-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  automatically
       enabled, and it will be carried out  in  even  numbers  of
       grid  units  rather  than pixels.  By default there are no
       limits on the minimum or maximum dimensions of  a  gridded
       window.   As  with ungridded windows, interactive resizing
       has exactly the same effect as invoking  the  wm  geometry
       command.  For gridded windows, internally- and externally-
       requested  dimensions  work  together:   the   externally-
       specified  width and height determine the size of the win-
       dow in grid units, and the information from  the  last  wm
       grid command maps from grid units to pixel units.


BUGS
       The  window  manager  interactions  seem  too complicated,
       especially for managing geometry.  Suggestions on  how  to
       simplify this would be greatly appreciated.
