


winfo(n)               Tk Built-In Commands              winfo(n)


NAME
       winfo - Return window-related information

SYNOPSIS
       (winfo option ?arg arg ...?)


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

       (winfo 'atom  name)

       (winfo 'atom :displayof window name)
              Returns  a   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  id)

       (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 procedure
              is  the  inverse  of  the winfo atom procedure.  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
              logical parents.

       (winfo 'class window)
              Returns the class name for window.

       (winfo 'colormapfull window)
              Returns  #t  if  the colormap for window is known to be full, #f
              otherwise.  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  rootX rootY)

       (winfo 'containing :displayof window rootX rootY)
              Returns  the path name for the window containing the point given



STk                            3.1                              1





winfo(n)               Tk Built-In Commands              winfo(n)


              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 list
              is returned.  In selecting the containing window,  children  are
              given  higher priority than parents and among siblings the high-
              est one in the stacking order is chosen.

       (winfo 'depth window)
              Returns an integer giving the depth of window  (number  of  bits
              per pixel).

       (winfo 'exists window)
              Returns  #t if there exists a window named window, #f 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 an integer indicating the X identifier for window.

       (winfo 'interps )

       (winfo 'interps :displayof window)
              Returns  a  list  whose  members are the names of all STk 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 #t if window is currently mapped, #f otherwise.



STk                            3.1                              2





winfo(n)               Tk Built-In Commands              winfo(n)


       (winfo 'manager window)
              Returns the name of the geometry manager  currently  responsible
              for  window,  or  an  empty  list if window isn't managed by any
              geometry manager.  The name is usually the name of the STk  pro-
              cedure  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 procedure, 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  procedure  (winfo  name
              *root*) will return the name of the application.

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

       (winfo 'pathname  id)

       (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,



STk                            3.1                              3





winfo(n)               Tk Built-In Commands              winfo(n)


              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  an integer 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  an  integer 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, which are the
              red, green, and blue intensities that correspond 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 an integer giving the x-coordinate, in the  root  window
              of  the  screen, of the upper-left corner of window's border (or
              window if it has no border).

       (winfo 'rooty window)
              Returns an integer giving the y-coordinate, in the  root  window
              of  the  screen, of the upper-left corner of window's border (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  an  integer  giving  the number of cells in the default
              color map for window's screen.

       (winfo 'screendepth window)
              Returns an integer giving the depth of the root window  of  win-
              dow's screen (number of bits per pixel).

       (winfo 'screenheight window)
              Returns an integer giving the height of window's screen, in pix-
              els.

       (winfo 'screenmmheight window)
              Returns an integer giving the height of window's screen, in mil-
              limeters.

       winfo screenmmwidth window
              Returns  an integer giving the width of window's screen, in mil-
              limeters.





STk                            3.1                              4





winfo(n)               Tk Built-In Commands              winfo(n)


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

       (winfo 'screenwidth window)
              Returns an integer giving the width of window's screen, in  pix-
              els.

       (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  #t  if  window  and all of its ancestors up through the
              nearest toplevel window are mapped.  Returns #f 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)

       (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



STk                            3.1                              5





winfo(n)               Tk Built-In Commands              winfo(n)


              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 an integer giving window's width in pixels.  When a win-
              dow is first created its width will be 1 pixel;  the width  will
              eventually  be changed by a geometry manager to fulfill the win-
              dow's needs.  If you need the true width immediately after  cre-
              ating  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  an integer 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  an integer giving the y-coordinate, in window's parent,
              of the upper-left corner of window's border (or window if it has
              no border).

























STk                            3.1                              6


