   This is a Texinfo GCL TK Manual

   Copyright 1994 William F. Schelter

pack
====

   pack \- Geometry manager that packs around edges of cavity

Synopsis
--------

   pack option arg ?arg ...?

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

   The pack command is used to communicate with the packer, a geometry
manager that arranges the children of a parent by packing them in order
around the edges of the parent.  The pack command can have any of
several forms, depending on the option argument:

pack slave ?slave ...? ?options?
     If the first argument to pack is a window name (any value starting
     with "."), then the command is processed in the same way as pack
     configure.

pack configure slave ?slave ...? ?options?
     The arguments consist of the names of one or more slave windows
     followed by pairs of arguments that specify how to manage the
     slaves.  See "THE PACKER ALGORITHM" below for details on how the
     options are used by the packer.  The following options are
     supported:

:after other
     Other must the name of another window.  Use its master as the
     master for the slaves, and insert the slaves just after other in
     the packing order.

:anchor anchor
     Anchor must be a valid anchor position such as n or sw; it
     specifies where to position each slave in its parcel.  Defaults to
     center.

:before other
     Other must the name of another window.  Use its master as the
     master for the slaves, and insert the slaves just before other in
     the packing order.

:expand boolean
     Specifies whether the slaves should be expanded to consume extra
     space in their master.  Boolean may have any proper boolean value,
     such as 1 or no.  Defaults to 0.

:fill style
     If a slave's parcel is larger than its requested dimensions, this
     option may be used to stretch the slave.  Style must have one of
     the following values:
    none
          Give the slave its requested dimensions plus any internal
          padding requested with :ipadx or :ipady.  This is the default.

    x
          Stretch the slave horizontally to fill the entire width of its
          parcel (except leave external padding as specified by :padx).

    y
          Stretch the slave vertically to fill the entire height of its
          parcel (except leave external padding as specified by :pady).

    both
          Stretch the slave both horizontally and vertically.

:in other
     Insert the slave(s) at the end of the packing order for the master
     window given by other.

:ipadx amount
     Amount specifies how much horizontal internal padding to leave on
     each side of the slave(s).  Amount must be a valid screen
     distance, such as 2 or .5c.  It defaults to 0.

:ipady amount
     Amount specifies how much vertical internal padding to leave on
     each side of the slave(s).  Amount  defaults to 0.

:padx amount
     Amount specifies how much horizontal external padding to leave on
     each side of the slave(s).  Amount defaults to 0.

:pady amount
     Amount specifies how much vertical external padding to leave on
     each side of the slave(s).  Amount defaults to 0.

:side side
     Specifies which side of the master the slave(s) will be packed
     against.  Must be left, right, top, or bottom.  Defaults to top.

   If no :in, :after or :before option is specified then each of the
slaves will be inserted at the end of the packing list for its parent
unless it is already managed by the packer (in which case it will be
left where it is).  If one of these options is specified then all the
slaves will be inserted at the specified point.  If any of the slaves
are already managed by the geometry manager then any unspecified
options for them retain their previous values rather than receiving
default values.  .RE

pack :forget slave ?slave ...?
     Removes each of the slaves from the packing order for its master
     and unmaps their windows.  The slaves will no longer be managed by
     the packer.

pack :newinfo slave
     Returns a list whose elements are the current configuration state
     of the slave given by slave in the same option-value form that
     might be specified to pack configure.  The first two elements of
     the list are ":in master" where master is the slave's master.
     Starting with Tk 4.0 this option will be renamed "pack info".

pack :propagate master ?boolean?
     If boolean has a true boolean value such as 1 or on then
     propagation is enabled for master, which must be a window name
     (see "GEOMETRY PROPAGATION" below).  If boolean has a false
     boolean value then propagation is disabled for master.  In either
     of these cases an empty string is returned.  If boolean is omitted
     then the command returns 0 or 1 to indicate whether propagation is
     currently enabled for master.  Propagation is enabled by default.

pack :slaves master
     Returns a list of all of the slaves in the packing order for
     master.  The order of the slaves in the list is the same as their
     order in the packing order.  If master has no slaves then an empty
     string is returned.

"The Packer Algorithm"
----------------------

   For each master the packer maintains an ordered list of slaves
called the packing list.  The :in, :after, and :before configuration
options are used to specify the master for each slave and the slave's
position in the packing list.  If none of these options is given for a
slave then the slave is added to the end of the packing list for its
parent.

   The packer arranges the slaves for a master by scanning the packing
list in order.  At the time it processes each slave, a rectangular area
within the master is still unallocated.  This area is called the
cavity;  for the first slave it is the entire area of the master.

   For each slave the packer carries out the following steps:
     [1] The packer allocates a rectangular parcel for the slave along
     the side of the cavity given by the slave's :side option.  If the
     side is top or bottom then the width of the parcel is the width of
     the cavity and its height is the requested height of the slave
     plus the :ipady and :pady options.  For the left or right side the
     height of the parcel is the height of the cavity and the width is
     the requested width of the slave plus the :ipadx and :padx options.
     The parcel may be enlarged further because of the :expand option
     (see "EXPANSION" below)

     [2] The packer chooses the dimensions of the slave.  The width
     will normally be the slave's requested width plus twice its :ipadx
     option and the height will normally be the slave's requested
     height plus twice its :ipady option.  However, if the :fill option
     is x or both then the width of the slave is expanded to fill the
     width of the parcel, minus twice the :padx option.  If the :fill
     option is y or both then the height of the slave is expanded to
     fill the width of the parcel, minus twice the :pady option.

     [3] The packer positions the slave over its parcel.  If the slave
     is smaller than the parcel then the :anchor option determines
     where in the parcel the slave will be placed.  If :padx or :pady
     is non-zero, then the given amount of external padding will always
     be left between the slave and the edges of the parcel.

   Once a given slave has been packed, the area of its parcel is
subtracted from the cavity, leaving a smaller rectangular cavity for
the next slave.  If a slave doesn't use all of its parcel, the unused
space in the parcel will not be used by subsequent slaves.  If the
cavity should become too small to meet the needs of a slave then the
slave will be given whatever space is left in the cavity.  If the
cavity shrinks to zero size, then all remaining slaves on the packing
list will be unmapped from the screen until the master window becomes
large enough to hold them again.

"Expansion"
-----------

   If a master window is so large that there will be extra space left
over after all of its slaves have been packed, then the extra space is
distributed uniformly among all of the slaves for which the :expand
option is set.  Extra horizontal space is distributed among the
expandable slaves whose :side is left or right, and extra vertical
space is distributed among the expandable slaves whose :side is top or
bottom.

"Geometry Propagation"
----------------------

   The packer normally computes how large a master must be to just
exactly meet the needs of its slaves, and it sets the requested width
and height of the master to these dimensions.  This causes geometry
information to propagate up through a window hierarchy to a top-level
window so that the entire sub-tree sizes itself to fit the needs of the
leaf windows.  However, the pack propagate command may be used to turn
off propagation for one or more masters.  If propagation is disabled
then the packer will not set the requested width and height of the
packer.  This may be useful if, for example, you wish for a master
window to have a fixed size that you specify.

"Restrictions On Master Windows"
--------------------------------

   The master for each slave must either be the slave's parent (the
default) or a descendant of the slave's parent.  This restriction is
necessary to guarantee that the slave can be placed over any part of
its master that is visible without danger of the slave being clipped by
its parent.

"Packing Order"
---------------

   If the master for a slave is not its parent then you must make sure
that the slave is higher in the stacking order than the master.
Otherwise the master will obscure the slave and it will appear as if
the slave hasn't been packed correctly.  The easiest way to make sure
the slave is higher than the master is to create the master window
first:  the most recently created window will be highest in the
stacking order.  Or, you can use the raise and lower commands to change
the stacking order of either the master or the slave.

Keywords
--------

   geometry manager, location, packer, parcel, propagation, size

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

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

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

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

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

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

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

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

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

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