NAME
       winfo - Return window-related information

SYNOPSIS
       winfo option ?arg arg ...?


DESCRIPTION
       The winfo command is used to retrieve information about windows managed
       by Tk.  It can take any of a number of different  forms,  depending  on
       the option argument.  The legal forms are:

       winfo atom ?-displayof window? name
              Returns  a  decimal string giving the integer identifier for the
              atom whose name is name.  If no atom exists with the  name  name
              then  a  new  one is created.  If the -displayof option is given
              then the atom is looked up on the display of window;   otherwise
              it is looked up on the display of the application's main window.

       winfo atomname ?-displayof window? id
              Returns the textual name for the atom whose  integer  identifier
              is id.  If the -displayof option is given then the identifier is
              looked up on the display of window;  otherwise it is  looked  up
              on  the  display of the application's main window.  This command
              is the inverse of the winfo atom command.  It generates an error
              if no such atom exists.

       winfo cells window
              Returns a decimal string giving the number of cells in the color
              map for window.

       winfo children window
              Returns a list containing the path names of all the children  of
              window. Top-level windows are returned as children of their log-
              ical parents. The list is in stacking  order,  with  the  lowest
              window  first,  except  for  Top-level  windows  which  are  not
              returned in stacking order. Use the  wm  stackorder  command  to
              query the stacking order of Top-level windows.

       winfo class window
              Returns the class name for window.

       winfo colormapfull window
              Returns 1 if the colormap for window is known to be full, 0 oth-
              erwise.  The colormap for a window is ``known'' to  be  full  if
              the  last  attempt to allocate a new color on that window failed
              and this application hasn't freed any  colors  in  the  colormap
              since the failed allocation.

       winfo containing ?-displayof window? rootX rootY
              Returns  the path name for the window containing the point given
              by rootX and rootY.  RootX and rootY  are  specified  in  screen
              units (i.e.  any form acceptable to Tk_GetPixels) in the coordi-
              nate system of the root window (if a virtual-root window manager
              is  in use then the coordinate system of the virtual root window
              is used).  If the -displayof option is given  then  the  coordi-
              nates  refer  to  the  screen containing window;  otherwise they
              refer to the screen of the application's  main  window.   If  no
              window  in  this  application  contains  the point then an empty
              string is returned.  In selecting the containing  window,  chil-
              dren  are  given higher priority than parents and among siblings
              the highest one in the stacking order is chosen.

       winfo depth window
              Returns a decimal string giving the depth of window  (number  of
              bits per pixel).

       winfo exists window
              Returns  1  if  there exists a window named window, 0 if no such
              window exists.

       winfo fpixels window number
              Returns a floating-point value giving the number  of  pixels  in
              window  corresponding  to  the distance given by number.  Number
              may  be  specified  in  any   of   the   forms   acceptable   to
              Tk_GetScreenMM,  such  as  ``2.0c'' or ``1i''.  The return value
              may be fractional;  for an integer value, use winfo pixels.

       winfo geometry window
              Returns the geometry for window, in the  form  widthxheight+x+y.
              All dimensions are in pixels.

       winfo height window
              Returns a decimal string giving window's height in pixels.  When
              a window is first created its  height  will  be  1  pixel;   the
              height  will eventually be changed by a geometry manager to ful-
              fill the window's needs.  If you need the  true  height  immedi-
              ately after creating a widget, invoke update to force the geome-
              try manager to arrange it, or use winfo  reqheight  to  get  the
              window's requested height instead of its actual height.

       winfo id window
              Returns  a  hexadecimal  string giving a low-level platform-spe-
              cific identifier for window.  On Unix platforms, this is  the  X
              window identifier.  Under Windows, this is the Windows HWND.  On
              the Macintosh the value has no meaning outside Tk.

       winfo interps ?-displayof window?
              Returns a list whose members are the names  of  all  Tcl  inter-
              preters  (e.g.  all  Tk-based applications) currently registered
              for a particular display.  If the  -displayof  option  is  given
              then  the  return value refers to the display of window;  other-
              wise it refers to the display of the application's main  window.

       winfo ismapped window
              Returns 1 if window is currently mapped, 0 otherwise.

       winfo manager window
              Returns  the  name of the geometry manager currently responsible
              for window, or an empty string if window isn't  managed  by  any
              geometry  manager.  The name is usually the name of the Tcl com-
              mand for the geometry manager, such as pack or  place.   If  the
              geometry manager is a widget, such as canvases or text, the name
              is the widget's class command, such as canvas.

       winfo name window
              Returns window's name (i.e.  its  name  within  its  parent,  as
              opposed  to  its full path name).  The command winfo name . will
              return the name of the application.

       winfo parent window
              Returns the path name of window's parent, or an empty string  if
              window is the main window of the application.

       winfo pathname ?-displayof window? id
              Returns  the  path  name of the window whose X identifier is id.
              Id must be a decimal, hexadecimal, or  octal  integer  and  must
              correspond  to  a  window  in  the invoking application.  If the
              -displayof option is given then the identifier is looked  up  on
              the display of window;  otherwise it is looked up on the display
              of the application's main window.

       winfo pixels window number
              Returns the number of pixels in window corresponding to the dis-
              tance  given  by  number.  Number may be specified in any of the
              forms acceptable to Tk_GetPixels, such as  ``2.0c''  or  ``1i''.
              The result is rounded to the nearest integer value;  for a frac-
              tional result, use winfo fpixels.

       winfo pointerx window
              If the mouse pointer is on the same screen  as  window,  returns
              the  pointer's  x coordinate, measured in pixels in the screen's
              root window.  If a virtual root window is in use on the  screen,
              the  position  is  measured  in  the virtual root.  If the mouse
              pointer isn't on the same screen as window then -1 is  returned.

       winfo pointerxy window
              If  the mouse pointer is on the same screen as window, returns a
              list with two elements, which are the pointer's x and y  coordi-
              nates measured in pixels in the screen's root window.  If a vir-
              tual root window is in use on the screen, the position  is  com-
              puted  in  the  virtual root.  If the mouse pointer isn't on the
              same screen as window then both of the returned coordinates  are
              -1.

       winfo pointery window
              If  the  mouse  pointer is on the same screen as window, returns
              the pointer's y coordinate, measured in pixels in  the  screen's
              root  window.  If a virtual root window is in use on the screen,
              the position is computed in the  virtual  root.   If  the  mouse
              pointer  isn't on the same screen as window then -1 is returned.

       winfo reqheight window
              Returns a decimal string giving window's  requested  height,  in
              pixels.   This is the value used by window's geometry manager to
              compute its geometry.

       winfo reqwidth window
              Returns a decimal string giving  window's  requested  width,  in
              pixels.   This is the value used by window's geometry manager to
              compute its geometry.

       winfo rgb window color
              Returns a list containing three decimal values in the range 0 to
              65535,  which are the red, green, and blue intensities that cor-
              respond to color in the window given by window.   Color  may  be
              specified in any of the forms acceptable for a color option.

       winfo rootx window
              Returns  a  decimal  string giving the x-coordinate, in the root
              window of the screen, of the upper-left corner of window's  bor-
              der (or window if it has no border).

       winfo rooty window
              Returns  a  decimal  string giving the y-coordinate, in the root
              window of the screen, of the upper-left corner of window's  bor-
              der (or window if it has no border).

       winfo screen window
              Returns  the  name  of the screen associated with window, in the
              form displayName.screenIndex.

       winfo screencells window
              Returns a decimal string giving  the  number  of  cells  in  the
              default color map for window's screen.

       winfo screendepth window
              Returns  a decimal string giving the depth of the root window of
              window's screen (number of bits per pixel).

       winfo screenheight window
              Returns a decimal string giving the height of  window's  screen,
              in pixels.

       winfo screenmmheight window
              Returns  a  decimal string giving the height of window's screen,
              in millimeters.

       winfo screenmmwidth window
              Returns a decimal string giving the width of window's screen, in
              millimeters.

       winfo screenvisual window
              Returns  one  of  the  following strings to indicate the default
              visual class for window's screen: directcolor, grayscale,  pseu-
              docolor, staticcolor, staticgray, or truecolor.

       winfo screenwidth window
              Returns a decimal string giving the width of window's screen, in
              pixels.

       winfo server window
              Returns a string containing information  about  the  server  for
              window's display.  The exact format of this string may vary from
              platform to platform.  For X servers the  string  has  the  form
              ``XmajorRminor  vendor vendorVersion'' where major and minor are
              the version and revision numbers provided by the  server  (e.g.,
              X11R5),  vendor  is  the  name of the vendor for the server, and
              vendorRelease is an  integer  release  number  provided  by  the
              server.

       winfo toplevel window
              Returns the path name of the top-level window containing window.

       winfo viewable window
              Returns 1 if window and all of  its  ancestors  up  through  the
              nearest  toplevel  window are mapped.  Returns 0 if any of these
              windows are not mapped.

       winfo visual window
              Returns one of the following  strings  to  indicate  the  visual
              class  for  window: directcolor, grayscale, pseudocolor, static-
              color, staticgray, or truecolor.

       winfo visualid window
              Returns the X identifier for the visual for window.

       winfo visualsavailable window ?includeids?
              Returns a list whose elements describe the visuals available for
              window's  screen.   Each element consists of a visual class fol-
              lowed by an integer depth.  The  class  has  the  same  form  as
              returned  by  winfo  visual.  The depth gives the number of bits
              per pixel in the visual.  In addition, if the  includeids  argu-
              ment is provided, then the depth is followed by the X identifier
              for the visual.

       winfo vrootheight window
              Returns the height of the virtual root  window  associated  with
              window  if  there  is one;  otherwise returns the height of win-
              dow's screen.

       winfo vrootwidth window
              Returns the width of the virtual  root  window  associated  with
              window if there is one;  otherwise returns the width of window's
              screen.

       winfo vrootx window
              Returns the x-offset of the virtual root window associated  with
              window, relative to the root window of its screen.  This is nor-
              mally either zero or negative.  Returns 0 if there is no virtual
              root window for window.

       winfo vrooty window
              Returns  the y-offset of the virtual root window associated with
              window, relative to the root window of its screen.  This is nor-
              mally either zero or negative.  Returns 0 if there is no virtual
              root window for window.

       winfo width window
              Returns a decimal string giving window's width in pixels.   When
              a  window is first created its width will be 1 pixel;  the width
              will eventually be changed by a geometry manager to fulfill  the
              window's  needs.   If  you need the true width immediately after
              creating a widget, invoke update to force the  geometry  manager
              to  arrange  it,  or  use  winfo  reqwidth  to  get the window's
              requested width instead of its actual width.

       winfo x window
              Returns a decimal string giving the  x-coordinate,  in  window's
              parent,  of  the upper-left corner of window's border (or window
              if it has no border).

       winfo y window
              Returns a decimal string giving the  y-coordinate,  in  window's
              parent,  of  the upper-left corner of window's border (or window
              if it has no border).

EXAMPLE
       Print where the mouse pointer is and what window it is currently over:
              set x [winfo pointerx .]
              set y [winfo pointery .]
              puts -nonewline "Mouse pointer at ($x,$y) which is "
              set win [winfo containing $x $y]
              if {$win eq ""} {
                  puts "over no window"
              } else {
                  puts "over $win"
              }


KEYWORDS
       atom,  children,  class,  geometry,  height,  identifier,  information,
       interpreters,  mapped,  parent, path name, screen, virtual root, width,
