This is gcl-tk.info, produced by makeinfo version 6.7 from gcl-tk.texi.

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl-tk: (gcl-tk.info). GNU TK Manual
END-INFO-DIR-ENTRY

This is a Texinfo GCL TK Manual

   Copyright 1994 William F. Schelter



File: gcl-tk.info,  Node: place,  Next: raise,  Prev: pack,  Up: Control

3.15 place
==========

place \- Geometry manager for fixed or rubber-sheet placement

Synopsis
--------

place window option value ?option value ...?

   place configure window option value ?option value ...?

   place forget window

   place info window

   place slaves window

Description
-----------

The placer is a geometry manager for Tk.  It provides simple fixed
placement of windows, where you specify the exact size and location of
one window, called the slave, within another window, called the master.
The placer also provides rubber-sheet placement, where you specify the
size and location of the slave in terms of the dimensions of the master,
so that the slave changes size and location in response to changes in
the size of the master.  Lastly, the placer allows you to mix these
styles of placement so that, for example, the slave has a fixed width
and height but is centered inside the master.

   If the first argument to the place command is a window path name or
configure then the command arranges for the placer to manage the
geometry of a slave whose path name is window.  The remaining arguments
consist of one or more option:value pairs that specify the way in which
window's geometry is managed.  If the placer is already managing window,
then the option:value pairs modify the configuration for window.  In
this form the place command returns an empty string as result.  The
following option:value pairs are supported:

:in master
     Master specifes the path name of the window relative to which
     window is to be placed.  Master must either be window's parent or a
     descendant of window's parent.  In addition, master and window must
     both be descendants of the same top-level window.  These
     restrictions are necessary to guarantee that window is visible
     whenever master is visible.  If this option isn't specified then
     the master defaults to window's parent.
:x location
     Location specifies the x-coordinate within the master window of the
     anchor point for window.  The location is specified in screen units
     (i.e.  any of the forms accepted by Tk_GetPixels) and need not lie
     within the bounds of the master window.
:relx location
     Location specifies the x-coordinate within the master window of the
     anchor point for window.  In this case the location is specified in
     a relative fashion as a floating-point number: 0.0 corresponds to
     the left edge of the master and 1.0 corresponds to the right edge
     of the master.  Location need not be in the range 0.0\-1.0.
:y location
     Location specifies the y-coordinate within the master window of the
     anchor point for window.  The location is specified in screen units
     (i.e.  any of the forms accepted by Tk_GetPixels) and need not lie
     within the bounds of the master window.
:rely location
     Location specifies the y-coordinate within the master window of the
     anchor point for window.  In this case the value is specified in a
     relative fashion as a floating-point number: 0.0 corresponds to the
     top edge of the master and 1.0 corresponds to the bottom edge of
     the master.  Location need not be in the range 0.0\-1.0.
:anchor where
     Where specifies which point of window is to be positioned at the
     (x,y) location selected by the :x, :y, :relx, and :rely options.
     The anchor point is in terms of the outer area of window including
     its border, if any.  Thus if where is se then the lower-right
     corner of window's border will appear at the given (x,y) location
     in the master.  The anchor position defaults to nw.
:width size
     Size specifies the width for window in screen units (i.e.  any of
     the forms accepted by Tk_GetPixels).  The width will be the outer
     width of window including its border, if any.  If size is an empty
     string, or if no :width or :relwidth option is specified, then the
     width requested internally by the window will be used.
:relwidth size
     Size specifies the width for window.  In this case the width is
     specified as a floating-point number relative to the width of the
     master: 0.5 means window will be half as wide as the master, 1.0
     means window will have the same width as the master, and so on.
:height size
     Size specifies the height for window in screen units (i.e.  any of
     the forms accepted by Tk_GetPixels).  The height will be the outer
     dimension of window including its border, if any.  If size is an
     empty string, or if no :height or :relheight option is specified,
     then the height requested internally by the window will be used.
:relheight size
     Size specifies the height for window.  In this case the height is
     specified as a floating-point number relative to the height of the
     master: 0.5 means window will be half as high as the master, 1.0
     means window will have the same height as the master, and so on.
:bordermode mode
     Mode determines the degree to which borders within the master are
     used in determining the placement of the slave.  The default and
     most common value is inside.  In this case the placer considers the
     area of the master to be the innermost area of the master, inside
     any border: an option of :x 0 corresponds to an x-coordinate just
     inside the border and an option of :relwidth 1.0 means window will
     fill the area inside the master's border.  If mode is outside then
     the placer considers the area of the master to include its border;
     this mode is typically used when placing window outside its master,
     as with the options :x 0 :y 0 :anchor ne.  Lastly, mode may be
     specified as ignore, in which case borders are ignored: the area of
     the master is considered to be its official X area, which includes
     any internal border but no external border.  A bordermode of ignore
     is probably not very useful.

     If the same value is specified separately with two different
     options, such as :x and :relx, then the most recent option is used
     and the older one is ignored.

     The place slaves command returns a list of all the slave windows
     for which window is the master.  If there are no slaves for window
     then an empty string is returned.

     The place forget command causes the placer to stop managing the
     geometry of window.  As a side effect of this command window will
     be unmapped so that it doesn't appear on the screen.  If window
     isn't currently managed by the placer then the command has no
     effect.  Place forget returns an empty string as result.

     The place info command returns a list giving the current
     configuration of window.  The list consists of option:value pairs
     in exactly the same form as might be specified to the place
     configure command.  If the configuration of a window has been
     retrieved with place info, that configuration can be restored later
     by first using place forget to erase any existing information for
     the window and then invoking place configure with the saved
     information.

"Fine Points"
-------------

It is not necessary for the master window to be the parent of the slave
window.  This feature is useful in at least two situations.  First, for
complex window layouts it means you can create a hierarchy of subwindows
whose only purpose is to assist in the layout of the parent.  The "real
children" of the parent (i.e.  the windows that are significant for the
application's user interface) can be children of the parent yet be
placed inside the windows of the geometry-management hierarchy.  This
means that the path names of the "real children" don't reflect the
geometry-management hierarchy and users can specify options for the real
children without being aware of the structure of the geometry-management
hierarchy.

   A second reason for having a master different than the slave's parent
is to tie two siblings together.  For example, the placer can be used to
force a window always to be positioned centered just below one of its
siblings by specifying the configuration

     :in sibling :relx 0.5 :rely 1.0 :anchor n :bordermode outside

   Whenever the sibling is repositioned in the future, the slave will be
repositioned as well.

   Unlike many other geometry managers (such as the packer) the placer
does not make any attempt to manipulate the geometry of the master
windows or the parents of slave windows (i.e.  it doesn't set their
requested sizes).  To control the sizes of these windows, make them
windows like frames and canvases that provide configuration options for
this purpose.

Keywords
--------

geometry manager, height, location, master, place, rubber sheet, slave,
width


File: gcl-tk.info,  Node: raise,  Next: selection,  Prev: place,  Up: Control

3.16 raise
==========

raise \- Change a window's position in the stacking order

Synopsis
--------

raise window ?aboveThis?

Description
-----------

If the aboveThis argument is omitted then the command raises window so
that it is above all of its siblings in the stacking order (it will not
be obscured by any siblings and will obscure any siblings that overlap
it).  If aboveThis is specified then it must be the path name of a
window that is either a sibling of window or the descendant of a sibling
of window.  In this case the raise command will insert window into the
stacking order just above aboveThis (or the ancestor of aboveThis that
is a sibling of window); this could end up either raising or lowering
window.

Keywords
--------

obscure, raise, stacking order


File: gcl-tk.info,  Node: selection,  Next: send,  Prev: raise,  Up: Control

3.17 selection
==============

selection \- Manipulate the X selection

Synopsis
--------

selection option ?arg arg ...?

Description
-----------

This command provides a Tcl interface to the X selection mechanism and
implements the full selection functionality described in the X
Inter-Client Communication Conventions Manual (ICCCM), except that it
supports only the primary selection.

   The first argument to selection determines the format of the rest of
the arguments and the behavior of the command.  The following forms are
currently supported:

selection :clear window
     If there is a selection anywhere on window's display, clear it so
     that no window owns the selection anymore.  Returns an empty
     string.
selection :get ?type?
     Retrieves the value of the primary selection and returns it as a
     result.  Type specifies the form in which the selection is to be
     returned (the desired "target" for conversion, in ICCCM
     terminology), and should be an atom name such as STRING or
     FILE_NAME; see the Inter-Client Communication Conventions Manual
     for complete details.  Type defaults to STRING. The selection
     :owner may choose to return the selection in any of several
     different representation formats, such as STRING, ATOM, INTEGER,
     etc.  (this format is different than the selection type; see the
     ICCCM for all the confusing details).  If the selection is returned
     in a non-string format, such as INTEGER or ATOM, the selection
     command converts it to string format as a collection of fields
     separated by spaces: atoms are converted to their textual names,
     and anything else is converted to hexadecimal integers.
selection :handle window command ?type? ?format?
     Creates a handler for selection requests, such that command will be
     executed whenever the primary selection is owned by window and
     someone attempts to retrieve it in the form given by type (e.g.
     type is specified in the selection :get command).  Type defaults to
     STRING. If command is an empty string then any existing handler for
     window and type is removed.

     When the selection is requested and window is the selection :owner
     and type is the requested type, command will be executed as a Tcl
     command with two additional numbers appended to it (with space
     separators).  The two additional numbers are offset and maxBytes:
     offset specifies a starting character position in the selection and
     maxBytes gives the maximum number of bytes to retrieve.  The
     command should return a value consisting of at most maxBytes of the
     selection, starting at position offset.  For very large selections
     (larger than maxBytes) the selection will be retrieved using
     several invocations of command with increasing offset values.  If
     command returns a string whose length is less than maxBytes, the
     return value is assumed to include all of the remainder of the
     selection; if the length of command's result is equal to maxBytes
     then command will be invoked again, until it eventually returns a
     result shorter than maxBytes.  The value of maxBytes will always be
     relatively large (thousands of bytes).

     If command returns an error then the selection retrieval is
     rejected just as if the selection didn't exist at all.

     The format argument specifies the representation that should be
     used to transmit the selection to the requester (the second column
     of Table 2 of the ICCCM), and defaults to STRING. If format is
     STRING, the selection is transmitted as 8-bit ASCII characters
     (i.e.  just in the form returned by command).  If format is ATOM,
     then the return value from command is divided into fields separated
     by white space; each field is converted to its atom value, and the
     32-bit atom value is transmitted instead of the atom name.  For any
     other format, the return value from command is divided into fields
     separated by white space and each field is converted to a 32-bit
     integer; an array of integers is transmitted to the selection
     requester.

     The format argument is needed only for compatibility with selection
     requesters that don't use Tk.  If the Tk toolkit is being used to
     retrieve the selection then the value is converted back to a string
     at the requesting end, so format is irrelevant.  .RE
selection :own ?window? ?command?
     If window is specified, then it becomes the new selection :owner
     and the command returns an empty string as result.  The existing
     owner, if any, is notified that it has lost the selection.  If
     command is specified, it is a Tcl script to execute when some other
     window claims ownership of the selection away from window.  If
     neither window nor command is specified then the command returns
     the path name of the window in this application that owns the
     selection, or an empty string if no window in this application owns
     the selection.

Keywords
--------

clear, format, handler, ICCCM, own, selection, target, type


File: gcl-tk.info,  Node: send,  Next: tk,  Prev: selection,  Up: Control

3.18 send
=========

send \- Execute a command in a different interpreter

Synopsis
--------

send interp cmd ?arg arg ...?

Description
-----------

This command arranges for cmd (and args) to be executed in the
interpreter named by interp.  It returns the result or error from that
command execution.  Interp must be the name of an interpreter registered
on the display associated with the interpreter in which the command is
invoked; it need not be within the same process or application.  If no
arg arguments are present, then the command to be executed is contained
entirely within the cmd argument.  If one or more args are present, they
are concatenated to form the command to be executed, just as for the
eval Tcl command.

Security
--------

The send command is potentially a serious security loophole, since any
application that can connect to your X server can send scripts to your
applications.  These incoming scripts can use Tcl to read and write your
files and invoke subprocesses under your name.  Host-based access
control such as that provided by xhost is particularly insecure, since
it allows anyone with an account on particular hosts to connect to your
server, and if disabled it allows anyone anywhere to connect to your
server.  In order to provide at least a small amount of security, Tk
checks the access control being used by the server and rejects incoming
sends unless (a) xhost-style access control is enabled (i.e.  only
certain hosts can establish connections) and (b) the list of enabled
hosts is empty.  This means that applications cannot connect to your
server unless they use some other form of authorization such as that
provide by xauth.

Keywords
--------

interpreter, remote execution, security, send


File: gcl-tk.info,  Node: tk,  Next: tkerror,  Prev: send,  Up: Control

3.19 tk
=======

tk \- Manipulate Tk internal state

Synopsis
--------

tk option ?arg arg ...?

Description
-----------

The tk command provides access to miscellaneous elements of Tk's
internal state.  Most of the information manipulated by this command
pertains to the application as a whole, or to a screen or display,
rather than to a particular window.  The command can take any of a
number of different forms depending on the option argument.  The legal
forms are:

tk :colormodel window ?newValue?
     If newValue isn't specified, this command returns the current color
     model in use for window's screen, which will be either color or
     monochrome.  If newValue is specified, then it must be either color
     or monochrome or an abbreviation of one of them; the color model
     for window's screen is set to this value.

   The color model is used by Tk and its widgets to determine whether it
should display in black and white only or use colors.  A single color
model is shared by all of the windows managed by one process on a given
screen.  The color model for a screen is set initially by Tk to
monochrome if the display has four or fewer bit planes and to color
otherwise.  The color model will automatically be changed from color to
monochrome if Tk fails to allocate a color because all entries in the
colormap were in use.  An application can change its own color model at
any time (e.g.  it might change the model to monochrome in order to
conserve colormap entries, or it might set the model to color to use
color on a four-bit display in special circumstances), but an
application is not allowed to change the color model to color unless the
screen has at least two bit planes.  .RE

Keywords
--------

color model, internal state


File: gcl-tk.info,  Node: tkerror,  Next: tkvars,  Prev: tk,  Up: Control

3.20 tkerror
============

tkerror \- Command invoked to process background errors

Synopsis
--------

tkerror message

Description
-----------

The tkerror command doesn't exist as built-in part of Tk.  Instead,
individual applications or users can define a tkerror command (e.g.  as
a Tcl procedure) if they wish to handle background errors.

   A background error is one that occurs in a command that didn't
originate with the application.  For example, if an error occurs while
executing a command specified with a bind of after command, then it is a
background error.  For a non-background error, the error can simply be
returned up through nested Tcl command evaluations until it reaches the
top-level code in the application; then the application can report the
error in whatever way it wishes.  When a background error occurs, the
unwinding ends in the Tk library and there is no obvious way for Tk to
report the error.

   When Tk detects a background error, it invokes the tkerror command,
passing it the error message as its only argument.  Tk assumes that the
application has implemented the tkerror command, and that the command
will report the error in a way that makes sense for the application.  Tk
will ignore any result returned by the tkerror command.

   If another Tcl error occurs within the tkerror command then Tk
reports the error itself by writing a message to stderr.

   The Tk script library includes a default tkerror procedure that posts
a dialog box containing the error message and offers the user a chance
to see a stack trace that shows where the error occurred.

Keywords
--------

background error, reporting


File: gcl-tk.info,  Node: tkvars,  Next: tkwait,  Prev: tkerror,  Up: Control

3.21 tkvars
===========

tkvars \- Variables used or set by Tk

Description
-----------

The following Tcl variables are either set or used by Tk at various
times in its execution:

tk_library
     Tk sets this variable hold the name of a directory containing a
     library of Tcl scripts related to Tk.  These scripts include an
     initialization file that is normally processed whenever a Tk
     application starts up, plus other files containing procedures that
     implement default behaviors for widgets.  The value of this
     variable is taken from the TK_LIBRARY environment variable, if one
     exists, or else from a default value compiled into Tk.
tk_patchLevel
     Contains a decimal integer giving the current patch level for Tk.
     The patch level is incremented for each new release or patch, and
     it uniquely identifies an official version of Tk.
tk_priv
     This variable is an array containing several pieces of information
     that are private to Tk.  The elements of tk_priv are used by Tk
     library procedures and default bindings.  They should not be
     accessed by any code outside Tk.
tk_strictMotif
     This variable is set to zero by default.  If an application sets it
     to one, then Tk attempts to adhere as closely as possible to Motif
     look-and-feel standards.  For example, active elements such as
     buttons and scrollbar sliders will not change color when the
     pointer passes over them.
tk_version
     Tk sets this variable in the interpreter for each application.  The
     variable holds the current version number of the Tk library in the
     form major.minor.  Major and minor are integers.  The major version
     number increases in any Tk release that includes changes that are
     not backward compatible (i.e.  whenever existing Tk applications
     and scripts may have to change to work with the new release).  The
     minor version number increases with each new release of Tk, except
     that it resets to zero whenever the major version number changes.
tkVersion
     Has the same value as tk_version.  This variable is obsolete and
     will be deleted soon.

Keywords
--------

variables, version


File: gcl-tk.info,  Node: tkwait,  Next: update,  Prev: tkvars,  Up: Control

3.22 tkwait
===========

tkwait \- Wait for variable to change or window to be destroyed

Synopsis
--------


tkwait :variable name

tkwait :visibility name
tkwait :window name

Description
-----------

The tkwait command waits for one of several things to happen, then it
returns without taking any other actions.  The return value is always an
empty string.  If the first argument is :variable (or any abbreviation
of it) then the second argument is the name of a global variable and the
command waits for that variable to be modified.  If the first argument
is :visibility (or any abbreviation of it) then the second argument is
the name of a window and the tkwait command waits for a change in its
visibility state (as indicated by the arrival of a VisibilityNotify
event).  This form is typically used to wait for a newly-created window
to appear on the screen before taking some action.  If the first
argument is :window (or any abbreviation of it) then the second argument
is the name of a window and the tkwait command waits for that window to
be destroyed.  This form is typically used to wait for a user to finish
interacting with a dialog box before using the result of that
interaction.

   While the tkwait command is waiting it processes events in the normal
fashion, so the application will continue to respond to user
interactions.

Keywords
--------

variable, visibility, wait, window


File: gcl-tk.info,  Node: update,  Next: winfo,  Prev: tkwait,  Up: Control

3.23 update
===========

update \- Process pending events and/or when-idle handlers

Synopsis
--------

update ?:idletasks?

Description
-----------

This command is used to bring the entire application world "up to date."
It flushes all pending output to the display, waits for the server to
process that output and return errors or events, handles all pending
events of any sort (including when-idle handlers), and repeats this set
of operations until there are no pending events, no pending when-idle
handlers, no pending output to the server, and no operations still
outstanding at the server.

   If the idletasks keyword is specified as an argument to the command,
then no new events or errors are processed; only when-idle idlers are
invoked.  This causes operations that are normally deferred, such as
display updates and window layout calculations, to be performed
immediately.

   The update :idletasks command is useful in scripts where changes have
been made to the application's state and you want those changes to
appear on the display immediately, rather than waiting for the script to
complete.  The update command with no options is useful in scripts where
you are performing a long-running computation but you still want the
application to respond to user interactions; if you occasionally call
update then user input will be processed during the next call to update.

Keywords
--------

event, flush, handler, idle, update


File: gcl-tk.info,  Node: winfo,  Next: wm,  Prev: update,  Up: Control

3.24 winfo
==========

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 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.
winfo :atomname id
     Returns the textual name for the atom whose integer identifier is
     id.  This command is the inverse of the winfo :atom command.
     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 :containing 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 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 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.
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 fulfill the window's
     needs.  If you need the true height immediately after creating a
     widget, invoke update to force the geometry 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 indicating the X identifier for
     window.
winfo :interps
     Returns a list whose members are the names of all Tcl interpreters
     (e.g.  all Tk-based applications) currently registered for the
     display of the invoking application.
winfo :ismapped window
     Returns 1 if window is currently mapped, 0 otherwise.
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 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.
winfo :pixels window number
     Returns 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_GetPixels, such as "2.0c" or "1i".  The
     result is rounded to the nearest integer value; for a fractional
     result, use winfo :fpixels.
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, 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 a decimal string 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 a decimal string 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 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
     type for window's screen: directcolor, grayscale, pseudocolor,
     staticcolor, staticgray, or truecolor.
winfo :screenwidth window
     Returns a decimal string giving the width of window's screen, in
     pixels.
winfo :toplevel window
     Returns the path name of the top-level window containing window.
winfo :visual window
     Returns one of the following strings to indicate the visual type
     for window: directcolor, grayscale, pseudocolor, staticcolor,
     staticgray, or truecolor.
winfo :vrootheight window
     Returns the height of the virtual root window associated with
     window if there is one; otherwise returns the height of window'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
     normally 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
     normally 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).

Keywords
--------

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


File: gcl-tk.info,  Node: wm,  Prev: winfo,  Up: Control

3.25 wm
=======

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 window 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 minNumer/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 specified, 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 command
     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 window.  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.  Passive
     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 contains 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 specified
     either by manual resizing or in a wm :geometry command).
     NewGeometry has the form =widthxheight\(+-x\(+-y, where any of =,
     widthxheight, or \(+-x\(+-y may be omitted.  Width and height are
     positive 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 preceded 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 relationship 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 vertical 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 window'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 example, 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;
     otherwise 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
     displayed 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 command 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 iconified 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
     command).
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 values, 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
     pathName will be unmapped again.  If pathName is specified as an
     empty string then any existing icon window 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 window, or an empty string if
     there is no icon window currently specified for window.  Note: not
     all window 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 windows the dimensions are specified in grid units;
     otherwise they are specified in pixel units.  During 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 dimensions are in effect for window then
     an empty string is returned.  See the sections on geometry
     management 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 windows the dimensions are specified in grid units;
     otherwise they are specified in pixel units.  During 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 dimensions are in effect for window then
     an empty string is returned.  See the sections on geometry
     management 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 currently 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
     window managers ignore program-requested initial positions and ask
     the user to manually position the window; if user is specified then
     the window manager 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.
     Otherwise 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 command is invoked, unless the
     source has been set explicitly to program.
wm :protocol window ?name? ?command?
     This command is used to manage window manager protocols 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 associated 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.  .RE

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
     window 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 normal, 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 specified, then the command returns an empty string.
     Otherwise the command returns the path name of window'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 window 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 handle windows that are
     mapped in the withdrawn state.  Note: it sometimes seems to be
     necessary to withdraw 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 calling 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 facilities of the window manager.  The
second and third types of geometry requests are called external requests
in the discussion 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 commands have been
invoked either.  In this case, the window'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 window, then the
size in that command overrides any size requested by the window's
widgets; from now on, the window'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 application 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 characters-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 window 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.

   Most existing window managers appear to have bugs that affect the
operation of the wm command.  For example, some changes won't take
effect if the window is already active: the window will have to be
withdrawn and de-iconified in order to make the change happen.

Keywords
--------

aspect ratio, deiconify, focus model, geometry, grid, group, icon,
iconify, increments, position, size, title, top-level window, units,
window manager

