diff options
Diffstat (limited to 'tk/doc/winfo.n')
| -rw-r--r-- | tk/doc/winfo.n | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/tk/doc/winfo.n b/tk/doc/winfo.n new file mode 100644 index 00000000000..5272c09adb6 --- /dev/null +++ b/tk/doc/winfo.n @@ -0,0 +1,330 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH winfo n 4.3 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +winfo \- Return window-related information +.SH SYNOPSIS +\fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBwinfo\fR command is used to retrieve information about windows +managed by Tk. It can take any of a number of different forms, +depending on the \fIoption\fR argument. The legal forms are: +.TP +\fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR +Returns a decimal string giving the integer identifier for the +atom whose name is \fIname\fR. If no atom exists with the name +\fIname\fR then a new one is created. +If the \fB\-displayof\fR option is given then the atom is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +.TP +\fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR +Returns the textual name for the atom whose integer identifier is +\fIid\fR. +If the \fB\-displayof\fR option is given then the identifier is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +This command is the inverse of the \fBwinfo atom\fR command. +It generates an error if no such atom exists. +.TP +\fBwinfo cells \fIwindow\fR +Returns a decimal string giving the number of cells in the +color map for \fIwindow\fR. +.TP +\fBwinfo children \fIwindow\fR +Returns a list containing the path names of all the children +of \fIwindow\fR. The list is in stacking order, with the lowest +window first. Top-level windows are returned as children +of their logical parents. +.TP +\fBwinfo class \fIwindow\fR +Returns the class name for \fIwindow\fR. +.TP +\fBwinfo colormapfull \fIwindow\fR +Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 +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. +.TP +\fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR +Returns the path name for the window containing the point given +by \fIrootX\fR and \fIrootY\fR. +\fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. +any form acceptable to \fBTk_GetPixels\fR) in the coordinate +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 \fB\-displayof\fR option is given then the coordinates refer +to the screen containing \fIwindow\fR; 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, children are given higher priority +than parents and among siblings the highest one in the stacking order is +chosen. +.TP +\fBwinfo depth \fIwindow\fR +Returns a decimal string giving the depth of \fIwindow\fR (number +of bits per pixel). +.TP +\fBwinfo exists \fIwindow\fR +Returns 1 if there exists a window named \fIwindow\fR, 0 if no such +window exists. +.TP +\fBwinfo fpixels \fIwindow\fR \fInumber\fR +Returns a floating-point value giving the number of pixels +in \fIwindow\fR corresponding to the distance given by \fInumber\fR. +\fINumber\fR may be specified in any of the forms acceptable +to \fBTk_GetScreenMM\fR, such as ``2.0c'' or ``1i''. +The return value may be fractional; for an integer value, use +\fBwinfo pixels\fR. +.TP +\fBwinfo geometry \fIwindow\fR +Returns the geometry for \fIwindow\fR, in the form +\fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are +in pixels. +.TP +\fBwinfo height \fIwindow\fR +Returns a decimal string giving \fIwindow\fR'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 fulfill +the window's needs. +If you need the true height immediately after creating a widget, +invoke \fBupdate\fR to force the geometry manager to arrange it, +or use \fBwinfo reqheight\fR to get the window's requested height +instead of its actual height. +.TP +\fBwinfo id \fIwindow\fR +.VS +Returns a hexadecimal string giving a low-level platform-specific +identifier for \fIwindow\fR. 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. +.VE +.TP +\fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? +Returns a list whose members are the names of all Tcl interpreters +(e.g. all Tk-based applications) currently registered for a particular display. +If the \fB\-displayof\fR option is given then the return value refers +to the display of \fIwindow\fR; otherwise it refers to +the display of the application's main window. +.TP +\fBwinfo ismapped \fIwindow\fR +Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. +.TP +\fBwinfo manager \fIwindow\fR +Returns the name of the geometry manager currently +responsible for \fIwindow\fR, or an empty string if \fIwindow\fR +isn't managed by any geometry manager. +The name is usually the name of the Tcl command for the geometry +manager, such as \fBpack\fR or \fBplace\fR. +If the geometry manager is a widget, such as canvases or text, the +name is the widget's class command, such as \fBcanvas\fR. +.TP +\fBwinfo name \fIwindow\fR +Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed +to its full path name). +The command \fBwinfo name .\fR will return the name of the application. +.TP +\fBwinfo parent \fIwindow\fR +Returns the path name of \fIwindow\fR's parent, or an empty string +if \fIwindow\fR is the main window of the application. +.TP +\fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR +Returns the path name of the window whose X identifier is \fIid\fR. +\fIId\fR must be a decimal, hexadecimal, or octal integer and must +correspond to a window in the invoking application. +If the \fB\-displayof\fR option is given then the identifier is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +.TP +\fBwinfo pixels \fIwindow\fR \fInumber\fR +Returns the number of pixels in \fIwindow\fR corresponding +to the distance given by \fInumber\fR. +\fINumber\fR may be specified in any of the forms acceptable +to \fBTk_GetPixels\fR, such as ``2.0c'' or ``1i''. +The result is rounded to the nearest integer value; for a +fractional result, use \fBwinfo fpixels\fR. +.TP +\fBwinfo pointerx \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, 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 \fIwindow\fR then +-1 is returned. +.TP +\fBwinfo pointerxy \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, returns a list +with two elements, which are the pointer's x and y coordinates 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 \fIwindow\fR then +both of the returned coordinates are -1. +.TP +\fBwinfo pointery \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, 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 \fIwindow\fR then +-1 is returned. +.TP +\fBwinfo reqheight \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's requested height, +in pixels. This is the value used by \fIwindow\fR's geometry +manager to compute its geometry. +.TP +\fBwinfo reqwidth \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's requested width, +in pixels. This is the value used by \fIwindow\fR's geometry +manager to compute its geometry. +.TP +\fBwinfo rgb \fIwindow color\fR +Returns a list containing three decimal values, which are the +red, green, and blue intensities that correspond to \fIcolor\fR in +the window given by \fIwindow\fR. \fIColor\fR +may be specified in any of the forms acceptable for a color +option. +.TP +\fBwinfo rootx \fIwindow\fR +Returns a decimal string giving the x-coordinate, in the root +window of the screen, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo rooty \fIwindow\fR +Returns a decimal string giving the y-coordinate, in the root +window of the screen, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo screen \fIwindow\fR +Returns the name of the screen associated with \fIwindow\fR, in +the form \fIdisplayName\fR.\fIscreenIndex\fR. +.TP +\fBwinfo screencells \fIwindow\fR +Returns a decimal string giving the number of cells in the default +color map for \fIwindow\fR's screen. +.TP +\fBwinfo screendepth \fIwindow\fR +Returns a decimal string giving the depth of the root window +of \fIwindow\fR's screen (number of bits per pixel). +.TP +\fBwinfo screenheight \fIwindow\fR +Returns a decimal string giving the height of \fIwindow\fR's screen, +in pixels. +.TP +\fBwinfo screenmmheight \fIwindow\fR +Returns a decimal string giving the height of \fIwindow\fR's screen, +in millimeters. +.TP +\fBwinfo screenmmwidth \fIwindow\fR +Returns a decimal string giving the width of \fIwindow\fR's screen, +in millimeters. +.TP +\fBwinfo screenvisual \fIwindow\fR +Returns one of the following strings to indicate the default visual +class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, +\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or +\fBtruecolor\fR. +.TP +\fBwinfo screenwidth \fIwindow\fR +Returns a decimal string giving the width of \fIwindow\fR's screen, +in pixels. +.TP +\fBwinfo server \fIwindow\fR +Returns a string containing information about the server for +\fIwindow\fR's display. The exact format of this string may vary +from platform to platform. For X servers the string +has the form ``\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR'' +where \fImajor\fR and \fIminor\fR are the version and revision +numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR +is the name of the vendor for the server, and \fIvendorRelease\fR +is an integer release number provided by the server. +.TP +\fBwinfo toplevel \fIwindow\fR +Returns the path name of the top-level window containing \fIwindow\fR. +.TP +\fBwinfo viewable \fIwindow\fR +Returns 1 if \fIwindow\fR and all of its ancestors up through the +nearest toplevel window are mapped. Returns 0 if any of these +windows are not mapped. +.TP +\fBwinfo visual \fIwindow\fR +Returns one of the following strings to indicate the visual +class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, +\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or +\fBtruecolor\fR. +.TP +\fBwinfo visualid \fIwindow\fR +Returns the X identifier for the visual for \fIwindow\fR. +.TP +\fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? +Returns a list whose elements describe the visuals available for +\fIwindow\fR's screen. +Each element consists of a visual class followed by an integer depth. +The class has the same form as returned by \fBwinfo visual\fR. +The depth gives the number of bits per pixel in the visual. +In addition, if the \fBincludeids\fR argument is provided, then the +depth is followed by the X identifier for the visual. +.TP +\fBwinfo vrootheight \fIwindow\fR +Returns the height of the virtual root window associated with \fIwindow\fR +if there is one; otherwise returns the height of \fIwindow\fR's screen. +.TP +\fBwinfo vrootwidth \fIwindow\fR +Returns the width of the virtual root window associated with \fIwindow\fR +if there is one; otherwise returns the width of \fIwindow\fR's screen. +.TP +\fBwinfo vrootx \fIwindow\fR +Returns the x-offset of the virtual root window associated with \fIwindow\fR, +relative to the root window of its screen. +This is normally either zero or negative. +Returns 0 if there is no virtual root window for \fIwindow\fR. +.TP +\fBwinfo vrooty \fIwindow\fR +Returns the y-offset of the virtual root window associated with \fIwindow\fR, +relative to the root window of its screen. +This is normally either zero or negative. +Returns 0 if there is no virtual root window for \fIwindow\fR. +.TP +\fBwinfo width \fIwindow\fR +Returns a decimal string giving \fIwindow\fR'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 \fBupdate\fR to force the geometry manager to arrange it, +or use \fBwinfo reqwidth\fR to get the window's requested width +instead of its actual width. +.TP +\fBwinfo x \fIwindow\fR +Returns a decimal string giving the x-coordinate, in \fIwindow\fR's +parent, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo y \fIwindow\fR +Returns a decimal string giving the y-coordinate, in \fIwindow\fR's +parent, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). + +.SH KEYWORDS +atom, children, class, geometry, height, identifier, information, interpreters, +mapped, parent, path name, screen, virtual root, width, window |