util/src/TclTk/tk8.6.12/doc/winfo.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH winfo n 4.3 Tk "Tk Built-In Commands"
   9 .so man.macros
  10 .BS
  11 '\" Note:  do not modify the .SH NAME line immediately below!
  12 .SH NAME
  13 winfo \- Return window-related information
  14 .SH SYNOPSIS
  15 \fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR?
  16 .BE
  17 .SH DESCRIPTION
  18 .PP
  19 The \fBwinfo\fR command is used to retrieve information about windows
  20 managed by Tk.  It can take any of a number of different forms,
  21 depending on the \fIoption\fR argument.  The legal forms are:
  22 .TP
  23 \fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR
  24 Returns a decimal string giving the integer identifier for the
  25 atom whose name is \fIname\fR.  If no atom exists with the name
  26 \fIname\fR then a new one is created.
  27 If the \fB\-displayof\fR option is given then the atom is looked
  28 up on the display of \fIwindow\fR;  otherwise it is looked up on
  29 the display of the application's main window.
  30 .TP
  31 \fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR
  32 Returns the textual name for the atom whose integer identifier is
  33 \fIid\fR.
  34 If the \fB\-displayof\fR option is given then the identifier is looked
  35 up on the display of \fIwindow\fR;  otherwise it is looked up on
  36 the display of the application's main window.
  37 This command is the inverse of the \fBwinfo atom\fR command.
  38 It generates an error if no such atom exists.
  39 .TP
  40 \fBwinfo cells \fIwindow\fR
  41 Returns a decimal string giving the number of cells in the
  42 color map for \fIwindow\fR.
  43 .TP
  44 \fBwinfo children \fIwindow\fR
  45 Returns a list containing the path names of all the children
  46 of \fIwindow\fR. Top-level windows are returned as children
  47 of their logical parents. The list is in stacking order, with
  48 the lowest window first, except for Top-level windows which
  49 are not returned in stacking order. Use the \fBwm stackorder\fR
  50 command to query the stacking order of Top-level windows.
  51 .TP
  52 \fBwinfo class \fIwindow\fR
  53 Returns the class name for \fIwindow\fR.
  54 .TP
  55 \fBwinfo colormapfull \fIwindow\fR
  56 Returns 1 if the colormap for \fIwindow\fR is known to be full, 0
  57 otherwise.  The colormap for a window is
  58 .QW known
  59 to be full if the last
  60 attempt to allocate a new color on that window failed and this
  61 application has not freed any colors in the colormap since the
  62 failed allocation.
  63 .TP
  64 \fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR
  65 Returns the path name for the window containing the point given
  66 by \fIrootX\fR and \fIrootY\fR.
  67 \fIRootX\fR and \fIrootY\fR are specified in screen units (i.e.
  68 any form acceptable to \fBTk_GetPixels\fR) in the coordinate
  69 system of the root window (if a virtual-root window manager is in
  70 use then the coordinate system of the virtual root window is used).
  71 If the \fB\-displayof\fR option is given then the coordinates refer
  72 to the screen containing \fIwindow\fR;  otherwise they refer to the
  73 screen of the application's main window.
  74 If no window in this application contains the point then an empty
  75 string is returned.
  76 An empty string is also returned if the point lies in the title bar
  77 or border of its highest containing toplevel in this application.
  78 (Note that with some window managers the borders may be invisible.)
  79 In selecting the containing window, children are given higher priority
  80 than parents and among siblings the highest one in the stacking order is
  81 chosen.
  82 .TP
  83 \fBwinfo depth \fIwindow\fR
  84 Returns a decimal string giving the depth of \fIwindow\fR (number
  85 of bits per pixel).
  86 .TP
  87 \fBwinfo exists \fIwindow\fR
  88 Returns 1 if there exists a window named \fIwindow\fR, 0 if no such
  89 window exists.
  90 .TP
  91 \fBwinfo fpixels \fIwindow\fR \fInumber\fR
  92 Returns a floating-point value giving the number of pixels
  93 in \fIwindow\fR corresponding to the distance given by \fInumber\fR.
  94 \fINumber\fR may be specified in any of the forms acceptable
  95 to \fBTk_GetScreenMM\fR, such as
  96 .QW 2.0c
  97 or
  98 .QW 1i .
  99 The return value may be fractional;  for an integer value, use
 100 \fBwinfo pixels\fR.
 101 .TP
 102 \fBwinfo geometry \fIwindow\fR
 103 Returns the geometry for \fIwindow\fR, in the form
 104 \fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR.  All dimensions are
 105 in pixels.
 106 .TP
 107 \fBwinfo height \fIwindow\fR
 108 Returns a decimal string giving \fIwindow\fR's height in pixels.
 109 When a window is first created its height will be 1 pixel;  the
 110 height will eventually be changed by a geometry manager to fulfil
 111 the window's needs.
 112 If you need the true height immediately after creating a widget,
 113 invoke \fBupdate\fR to force the geometry manager to arrange it,
 114 or use \fBwinfo reqheight\fR to get the window's requested height
 115 instead of its actual height.
 116 .TP
 117 \fBwinfo id \fIwindow\fR
 118 Returns a hexadecimal string giving a low-level platform-specific
 119 identifier for \fIwindow\fR.  On Unix platforms, this is the X
 120 window identifier.  Under Windows, this is the Windows
 121 HWND.  On the Macintosh the value has no meaning outside Tk.
 122 .TP
 123 \fBwinfo interps \fR?\fB\-displayof \fIwindow\fR?
 124 Returns a list whose members are the names of all Tcl interpreters
 125 (e.g. all Tk-based applications) currently registered for a particular display.
 126 If the \fB\-displayof\fR option is given then the return value refers
 127 to the display of \fIwindow\fR;  otherwise it refers to
 128 the display of the application's main window.
 129 .TP
 130 \fBwinfo ismapped \fIwindow\fR
 131 Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise.
 132 .TP
 133 \fBwinfo manager \fIwindow\fR
 134 Returns the name of the geometry manager currently
 135 responsible for \fIwindow\fR, or an empty string if \fIwindow\fR
 136 is not managed by any geometry manager.
 137 The name is usually the name of the Tcl command for the geometry
 138 manager, such as \fBpack\fR or \fBplace\fR.
 139 If the geometry manager is a widget, such as canvases or text, the
 140 name is the widget's class command, such as \fBcanvas\fR.
 141 .TP
 142 \fBwinfo name \fIwindow\fR
 143 Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed
 144 to its full path name).
 145 The command \fBwinfo name .\fR will return the name of the application.
 146 .TP
 147 \fBwinfo parent \fIwindow\fR
 148 Returns the path name of \fIwindow\fR's parent, or an empty string
 149 if \fIwindow\fR is the main window of the application.
 150 .TP
 151 \fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR
 152 Returns the path name of the window whose X identifier is \fIid\fR.
 153 \fIId\fR must be a decimal, hexadecimal, or octal integer and must
 154 correspond to a window in the invoking application.
 155 If the \fB\-displayof\fR option is given then the identifier is looked
 156 up on the display of \fIwindow\fR;  otherwise it is looked up on
 157 the display of the application's main window.
 158 .TP
 159 \fBwinfo pixels \fIwindow\fR \fInumber\fR
 160 Returns the number of pixels in \fIwindow\fR corresponding
 161 to the distance given by \fInumber\fR.
 162 \fINumber\fR may be specified in any of the forms acceptable
 163 to \fBTk_GetPixels\fR, such as
 164 .QW 2.0c
 165 or
 166 .QW 1i .
 167 The result is rounded to the nearest integer value;  for a
 168 fractional result, use \fBwinfo fpixels\fR.
 169 .TP
 170 \fBwinfo pointerx \fIwindow\fR
 171 If the mouse pointer is on the same screen as \fIwindow\fR, returns the
 172 pointer's x coordinate, measured in pixels in the screen's root window.
 173 If a virtual root window is in use on the screen, the position is
 174 measured in the virtual root.
 175 If the mouse pointer is not on the same screen as \fIwindow\fR then
 176 -1 is returned.
 177 .TP
 178 \fBwinfo pointerxy \fIwindow\fR
 179 If the mouse pointer is on the same screen as \fIwindow\fR, returns a list
 180 with two elements, which are the pointer's x and y coordinates measured
 181 in pixels in the screen's root window.
 182 If a virtual root window is in use on the screen, the position
 183 is computed in the virtual root.
 184 If the mouse pointer is not on the same screen as \fIwindow\fR then
 185 both of the returned coordinates are \-1.
 186 .TP
 187 \fBwinfo pointery \fIwindow\fR
 188 If the mouse pointer is on the same screen as \fIwindow\fR, returns the
 189 pointer's y coordinate, measured in pixels in the screen's root window.
 190 If a virtual root window is in use on the screen, the position
 191 is computed in the virtual root.
 192 If the mouse pointer is not on the same screen as \fIwindow\fR then
 193 -1 is returned.
 194 .TP
 195 \fBwinfo reqheight \fIwindow\fR
 196 Returns a decimal string giving \fIwindow\fR's requested height,
 197 in pixels.  This is the value used by \fIwindow\fR's geometry
 198 manager to compute its geometry.
 199 .TP
 200 \fBwinfo reqwidth \fIwindow\fR
 201 Returns a decimal string giving \fIwindow\fR's requested width,
 202 in pixels.  This is the value used by \fIwindow\fR's geometry
 203 manager to compute its geometry.
 204 .TP
 205 \fBwinfo rgb \fIwindow color\fR
 206 Returns a list containing three decimal values in the range 0 to
 207 65535, which are the
 208 red, green, and blue intensities that correspond to \fIcolor\fR in
 209 the window given by \fIwindow\fR.  \fIColor\fR
 210 may be specified in any of the forms acceptable for a color
 211 option.
 212 .TP
 213 \fBwinfo rootx \fIwindow\fR
 214 Returns a decimal string giving the x-coordinate, in the root
 215 window of the screen, of the
 216 upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it
 217 has no border).
 218 .TP
 219 \fBwinfo rooty \fIwindow\fR
 220 Returns a decimal string giving the y-coordinate, in the root
 221 window of the screen, of the
 222 upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it
 223 has no border).
 224 .TP
 225 \fBwinfo screen \fIwindow\fR
 226 Returns the name of the screen associated with \fIwindow\fR, in
 227 the form \fIdisplayName\fR.\fIscreenIndex\fR.
 228 .TP
 229 \fBwinfo screencells \fIwindow\fR
 230 Returns a decimal string giving the number of cells in the default
 231 color map for \fIwindow\fR's screen.
 232 .TP
 233 \fBwinfo screendepth \fIwindow\fR
 234 Returns a decimal string giving the depth of the root window
 235 of \fIwindow\fR's screen (number of bits per pixel).
 236 .TP
 237 \fBwinfo screenheight \fIwindow\fR
 238 Returns a decimal string giving the height of \fIwindow\fR's screen,
 239 in pixels.
 240 .TP
 241 \fBwinfo screenmmheight \fIwindow\fR
 242 Returns a decimal string giving the height of \fIwindow\fR's screen,
 243 in millimeters.
 244 .TP
 245 \fBwinfo screenmmwidth \fIwindow\fR
 246 Returns a decimal string giving the width of \fIwindow\fR's screen,
 247 in millimeters.
 248 .TP
 249 \fBwinfo screenvisual \fIwindow\fR
 250 Returns one of the following strings to indicate the default visual
 251 class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR,
 252 \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or
 253 \fBtruecolor\fR.
 254 .TP
 255 \fBwinfo screenwidth \fIwindow\fR
 256 Returns a decimal string giving the width of \fIwindow\fR's screen,
 257 in pixels.
 258 .TP
 259 \fBwinfo server \fIwindow\fR
 260 Returns a string containing information about the server for
 261 \fIwindow\fR's display.  The exact format of this string may vary
 262 from platform to platform.  For X servers the string
 263 has the form
 264 .QW "\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR"
 265 where \fImajor\fR and \fIminor\fR are the version and revision
 266 numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR
 267 is the name of the vendor for the server, and \fIvendorRelease\fR
 268 is an integer release number provided by the server.
 269 .TP
 270 \fBwinfo toplevel \fIwindow\fR
 271 Returns the path name of the top-of-hierarchy window containing \fIwindow\fR.
 272 In standard Tk this will always be a \fBtoplevel\fR widget, but extensions may
 273 create other kinds of top-of-hierarchy widgets.
 274 .TP
 275 \fBwinfo viewable \fIwindow\fR
 276 Returns 1 if \fIwindow\fR and all of its ancestors up through the
 277 nearest toplevel window are mapped.  Returns 0 if any of these
 278 windows are not mapped.
 279 .TP
 280 \fBwinfo visual \fIwindow\fR
 281 Returns one of the following strings to indicate the visual
 282 class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR,
 283 \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or
 284 \fBtruecolor\fR.
 285 .TP
 286 \fBwinfo visualid \fIwindow\fR
 287 Returns the X identifier for the visual for \fIwindow\fR.
 288 .TP
 289 \fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR?
 290 Returns a list whose elements describe the visuals available for
 291 \fIwindow\fR's screen.
 292 Each element consists of a visual class followed by an integer depth.
 293 The class has the same form as returned by \fBwinfo visual\fR.
 294 The depth gives the number of bits per pixel in the visual.
 295 In addition, if the \fBincludeids\fR argument is provided, then the
 296 depth is followed by the X identifier for the visual.
 297 .TP
 298 \fBwinfo vrootheight \fIwindow\fR
 299 Returns the height of the virtual root window associated with \fIwindow\fR
 300 if there is one;  otherwise returns the height of \fIwindow\fR's screen.
 301 .TP
 302 \fBwinfo vrootwidth \fIwindow\fR
 303 Returns the width of the virtual root window associated with \fIwindow\fR
 304 if there is one;  otherwise returns the width of \fIwindow\fR's screen.
 305 .TP
 306 \fBwinfo vrootx \fIwindow\fR
 307 Returns the x-offset of the virtual root window associated with \fIwindow\fR,
 308 relative to the root window of its screen.
 309 This is normally either zero or negative.
 310 Returns 0 if there is no virtual root window for \fIwindow\fR.
 311 .TP
 312 \fBwinfo vrooty \fIwindow\fR
 313 Returns the y-offset of the virtual root window associated with \fIwindow\fR,
 314 relative to the root window of its screen.
 315 This is normally either zero or negative.
 316 Returns 0 if there is no virtual root window for \fIwindow\fR.
 317 .TP
 318 \fBwinfo width \fIwindow\fR
 319 Returns a decimal string giving \fIwindow\fR's width in pixels.
 320 When a window is first created its width will be 1 pixel;  the
 321 width will eventually be changed by a geometry manager to fulfil
 322 the window's needs.
 323 If you need the true width immediately after creating a widget,
 324 invoke \fBupdate\fR to force the geometry manager to arrange it,
 325 or use \fBwinfo reqwidth\fR to get the window's requested width
 326 instead of its actual width.
 327 .TP
 328 \fBwinfo x \fIwindow\fR
 329 Returns a decimal string giving the x-coordinate, in \fIwindow\fR's
 330 parent, of the
 331 upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it
 332 has no border).
 333 .TP
 334 \fBwinfo y \fIwindow\fR
 335 Returns a decimal string giving the y-coordinate, in \fIwindow\fR's
 336 parent, of the
 337 upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it
 338 has no border).
 339 .SH EXAMPLE
 340 .PP
 341 Print where the mouse pointer is and what window it is currently over:
 342 .CS
 343 lassign [\fBwinfo pointerxy\fR .] x y
 344 puts \-nonewline "Mouse pointer at ($x,$y) which is "
 345 set win [\fBwinfo containing\fR $x $y]
 346 if {$win eq ""} {
 347     puts "over no window"
 348 } else {
 349     puts "over $win"
 350 }
 351 .CE
 352 .SH KEYWORDS
 353 atom, children, class, geometry, height, identifier, information, interpreters,
 354 mapped, parent, path name, screen, virtual root, width, window
 355 '\" Local Variables:
 356 '\" mode: nroff
 357 '\" End: