This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: Tk/UserGuide,  Next: Tk/WaitBox,  Prev: Tk/TreeGraph,  Up: Module List

Writing Tk applications in perl5.
*********************************

NAME
====

   perl/Tk - Writing Tk applications in perl5.

   This manual page is for beginners.  It assumes you know some perl, and
have got perl+Tk running.  Please run the 'widget' demo before reading
this text; it will teach you the various widget types supported by Tk.

Some background
===============

   Tk GUI programming is event-driven.  (This may already be familiar to
you.)  In event-driven programs, the main GUI loop is outside of the user
program and inside the GUI library.  This loop will watch all events of
interest, and activate the correct handler procedures to handle these
events.  Some of these handler procedures may be user-supplied; others
will be part of the library.

   For a programmer, this means that you're not watching what is happening;
instead, you are requested by the toolkit to perform actions whenever
necessary.  So, you're not watching for 'raise window / close window /
redraw window' requests, but you tell the toolkit which routine will
handle such cases, and the toolkit will call the procedures when required.

First requirements
==================

   Any perl program that uses Tk needs to include `use Tk'.  A program
should also use `use strict' and the -w switch to ensure the program is
working without common errors.

   Any Tk application starts by creating the Tk main window.  You then
create items inside the main window, or create new windows, before
starting the mainloop.  (You can also create more items and windows while
you're running.)  The items will be shown on the display after you pack
them; more info on this later.  Then you do a Tk mainloop; this will start
the GUI and handle all events.  That's your application.  A trivial
one-window example is show below:

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     my $main = MainWindow->new;
     $main->Label(-text => 'Hello, world!')->pack;
     $main->Button(-text => 'Quit',
                   -command => [$main => 'destroy']
                   )->pack;
     MainLoop;

   Please run this example.  It shows you two items types also shown in the
widget demo; it also shows you how items are created and packed.  Finally,
note the typical Tk style using `-option' => value pairs.

Item creation
=============

   Tk windows and widgets are hierarchical, i.e. one includes one or more
others.  You create the first Tk window using `MainWindow->new'.  This
returns a window handle, assigned to `$main' in the example above.  Keep
track of the main handle.

   You can use any Tk handle to create sub-items within the window or
widget.  This is done by calling the Tk constructor method on the variable.
In the example above, the Label method called from `$main' creates a label
widget inside the main window.  In the constructor call, you can specify
various options; you can later add or change options for any widget using
the configure method, which takes the same parameters as the constructor.
The one exception to the hierarchical structure is the Toplevel
constructor, which creates a new outermost window.

   After you create any widget, you must render it by calling pack.  (This
is not entirely true; more info later).  If you do not need to refer to
the widget after construction and packing, call pack off the constructor
results, as shown for the label and button in the example above.  Note
that the result of the compound call is the result of pack, which is a
valid Tk handle.

   Windows and widgets are deleted by calling destroy on them; this will
delete and un-draw the widget and all its children.

Standard Tk types
=================

Button
Radiobutton
Checkbutton
Listbox
Scrollbar
Entry
Text
Canvas
Frame
Toplevel
Scale
Menu
Menubutton
Variables and callback routines
===============================

   Most graphical interfaces are used to set up a set of values and
conditions, and then perform the appropriate action.  The Tk toolkit is
different from your average text-based prompting or menu driven system in
that you do not collect settings yourself, and decide on an action based
on an input code; instead, you leave these values to your toolkit and only
get them when the action is performed.

   So, where a traditional text-based system would look like this: (yes,
this is obviously dumb code)

     #! /usr/bin/perl5 -w

     use strict;

     print "Please type a font name\n";
     my $font = <>; chomp $font;
     # Validate font

     print "Please type a file name\n";
     my $filename = <>; chomp $filename;
     # Validate filename

     print "Type <1> to fax, <2> to print\n";
     my $option = <>; chomp $option;
     if ($option eq 1) {
         print "Faxing $filename in font $font\n";
     } elsif ($option eq 2) {
         print "Now sending $filename to printer in font $font\n";
     }

   The (slightly larger) example below shows how to do this is Tk.  Note
the use of callbacks.  Note, also, that Tk handles the values, and the
subroutine uses get to get at the values.  If a user changes his mind and
wants to change the font again, the application never notices; it's all
handled by Tk.

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     my $main = MainWindow->new;
     $main->Label(-text => 'Print file')->pack;
     my $font = $main->Entry(-width => 10);
     $font->pack;
     my $filename = $main->Entry(-width => 10);
     $filename->pack;
     $main->Button(-text => 'Fax',
                   -command => sub{do_fax($filename, $font)}
                   )->pack;
     $main->Button(-text => 'Print',
                   -command => sub{do_print($filename, $font)}
                   )->pack;
     MainLoop;

     sub do_fax {
         my ($file, $font) = @_;
         my $file_val = $file->get;
         my $font_val = $font->get;
         print "Now faxing $file_val in $font_val\n";
     }

     sub do_print {
         my ($file, $font) = @_;
         my $file_val = $file->get;
         my $font_val = $font->get;
         print "Sending file $file_val to printer in $font_val\n";
     }

The packer.  Grouping and frames.
=================================

   In the examples above, you must have noticed the `pack|Tk::pack' in
this node calls.  This is one of the more complicated parts of Tk.  The
basic idea is that any window or widget should be subject to a Tk widget
placement manager; the *packer* is one of the placement managers.

   The actions of the packer are rather simple: when applied to a widget,
the packer positions that widget on the indicated position within the
remaining space in its parent.  By default, the position is on top; this
means the next items will be put below.  You can also specify the left,
right, or bottom positions.  Specify position using *-side => 'right'*.

   Additional packing parameters specify the behavior of the widget when
there is some space left in the frame or when the window size is
increased.  If widgets should maintain a fixed size, specify nothing; this
is the default.  For widgets that you want to fill up the current
horizontal space, specify *-fill => 'x'*, y, or both; for widgets that
should grow, specify *-expand => 1*.  These parameters are not shown in
the example below; see the widget demo.

   If you want to group some items within a window that have a different
packing order than others, you can include them in a Frame.  This is a
do-nothing window type that is meant for packing (and to play games with
borders and colors).

   The example below shows the use of pack and frames:

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     # Take top, the bottom -> now implicit top is in the middle
     my $main = MainWindow->new;
     $main->Label(-text => 'At the top (default)')->pack;
     $main->Label(-text => 'At the bottom')->pack(-side => 'bottom');
     $main->Label(-text => 'The middle remains')->pack;

     # Since left and right are taken, bottom will not work...
     my $top1 = $main->Toplevel;
     $top1->Label(-text => 'Left')->pack(-side => 'left');
     $top1->Label(-text => 'Right')->pack(-side => 'right');
     $top1->Label(-text => '?Bottom?')->pack(-side => 'bottom');

     # But when you use frames, things work quite alright
     my $top2 = $main->Toplevel;
     my $frame = $top2->Frame;
     $frame->pack;
     $frame->Label(-text => 'Left2')->pack(-side => 'left');
     $frame->Label(-text => 'Right2')->pack(-side => 'right');
     $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom');

     MainLoop;

More than one window
====================

   Most real applications require more than one window.  As you read
before, you can create more outermost windows by using Toplevel.  Each
window is independent; destroying a toplevel window does not affect the
others as long as they are not a child of the closed toplevel.  Exiting
the main window will end the application.  The example below shows a
trivial three-window application:

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     my $main = MainWindow->new;
     fill_window($main, 'Main');
     my $top1 = $main->Toplevel;
     fill_window($top1, 'First top-level');
     my $top2 = $main->Toplevel;
     fill_window($top2, 'Second top-level');
     MainLoop;

     sub fill_window {
         my ($window, $header) = @_;
         $window->Label(-text => $header)->pack;
         $window->Button(-text => 'close',
                         -command => [$window => 'destroy']
                         )->pack(-side => 'left');
         $window->Button(-text => 'exit',
                         -command => [$main => 'destroy']
                         )->pack(-side => 'right');
     }

More callbacks
==============

   So far, all callback routines shown called a user procedure.  You can
also have a callback routine call another Tk routine.  This is the way
that scroll bars are implemented: scroll-bars can call a Tk item or a user
procedure, whenever their position has changed.  The Tk item that has a
scrollbar attached calls the scrollbar when its size or offset has
changed.  In this way, the items are linked.  You can still ask a
scrollbar's position, or set it by hand - but the defaults will be taken
care of.

   The example below shows a listbox with a scroll bar.  Moving the
scrollbar moves the listbox.  Scanning a listbox (dragging an item with
the left mouse button) moves the scrollbar.

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     my $main = MainWindow->new;
     my $box = $main->Listbox(-relief => 'sunken',
                              -width => -1, # Shrink to fit
                              -height => 5,
                              -setgrid => 1);
     my @items = qw(One Two Three Four Five Six Seven
                    Eight Nine Ten Eleven Twelve);
     foreach (@items) {
        $box->insert('end', $_);
     }
     my $scroll = $main->Scrollbar(-command => ['yview', $box]);
     $box->configure(-yscrollcommand => ['set', $scroll]);
     $box->pack(-side => 'left', -fill => 'both', -expand => 1);
     $scroll->pack(-side => 'right', -fill => 'y');

     MainLoop;

Canvases and tags
=================

   One of the most powerful window types in Tk is the Canvas window.  In a
canvas window, you can draw simple graphics and include other widgets.
The canvas area may be larger than the visible window, and may then be
scrolled.  Any item you draw on the canvas has its own id, and may
optionally have one or more tags.  You may refer to any item by its id,
and may refer to any group of items by a common tag; you can move, delete,
or change groups of items using these tags, and you can bind actions to
tags.  For a properly designed (often structured) canvas, you can specify
powerful actions quite simply.

   In the example below, actions are bound to circles (single click) and
blue items (double-click); obviously, this can be extended to any tag or
group of tags.

     #! /usr/bin/perl5 -w

     use strict;
     use Tk;

     # Create main window and canvas
     my $main = MainWindow->new;
     my $canvas = $main->Canvas;
     $canvas->pack(-expand => 1, -fill => 'both');

     # Create various items
     create_item($canvas, 1, 1, 'circle', 'blue', 'Jane');
     create_item($canvas, 4, 4, 'circle', 'red', 'Peter');
     create_item($canvas, 4, 1, 'square', 'blue', 'James');
     create_item($canvas, 1, 4, 'square', 'red', 'Patricia');

     # Single-clicking with left on a 'circle' item invokes a procedure
     $canvas->bind('circle', '<1>' => sub {handle_circle($canvas)});
     # Double-clicking with left on a 'blue' item invokes a procedure
     $canvas->bind('blue', '<Double-1>' => sub {handle_blue($canvas)});
     MainLoop;

     # Create an item; use parameters as tags (this is not a default!)
     sub create_item {
         my ($can, $x, $y, $form, $color, $name) = @_;

     my $x2 = $x + 1;
     my $y2 = $y + 1;
     my $kind;
     $kind = 'oval' if ($form eq 'circle');
     $kind = 'rectangle' if ($form eq 'square');
     $can->create(($kind, "$x" . 'c', "$y" . 'c',
                   "$x2" . 'c', "$y2" . 'c'),
                  -tags => [$form, $color, $name],
                  -fill => $color);
             }

     # This gets the real name (not current, blue/red, square/circle)
     # Note: you'll want to return a list in realistic situations...
     sub get_name {
         my ($can) = @_;
         my $item = $can->find('withtag', 'current');
         my @taglist = $can->gettags($item);
         my $name;
         foreach (@taglist) {
             next if ($_ eq 'current');
             next if ($_ eq 'red' or $_ eq 'blue');
             next if ($_ eq 'square' or $_ eq 'circle');
             $name = $_;
             last;
         }
         return $name;
     }

     sub handle_circle {
         my ($can) = @_;
         my $name = get_name($can);
         print "Action on circle $name...\n";
     }

     sub handle_blue {
         my ($can) = @_;
         my $name = get_name($can);
         print "Action on blue item $name...\n";
     }


File: pm.info,  Node: Tk/WaitBox,  Next: Tk/Widget,  Prev: Tk/UserGuide,  Up: Module List

An Object Oriented Wait Dialog for Perl/Tk, of the Please Wait variety.
***********************************************************************

NAME
====

   Tk::WaitBox - An Object Oriented Wait Dialog for Perl/Tk, of the Please
Wait variety.

DESCRIPTION
===========

   A WaitBox consists of a number of subwidgets:


bitmap
------

   A bitmap (configurable via the *-bitmap* command, the default is an
hourglass) on the left side of the WaitBox

label
-----

   A label (configurable via the *-txt1* command), with text in the upper
portion of the right hand frame

secondary label
---------------

   Another label (configurable via the *-txt2* command, the default is
'Please Wait'), with text in the lower portion of the right hand frame

userframe
---------

   A frame displayed, if required, between the label and the secondary
label.  For details, see the example code and the Advertised Widget section

cancel button
-------------

   If a cancelroutine (configured via the *-cancelroutine* command) is
defined, a frame will be packed below the labels and bitmap, with a single
button.  The text of the button will be 'Cancel' (configurable via the
*-canceltext* command), and the button will call the supplied subroutine
when pressed.

SYNOPSIS
========

Usage Description

Basic Usage
-----------

   To use, create your WaitDialog objects during initialization, or at
least before a Show.  When you wish to display the WaitDialog object,
invoke the 'Show' method on the WaitDialog object; when you wish to cease
displaying the WaitDialog object, invoke the 'unShow' method on the object.

Configuration
-------------

   Configuration may be done at creation or via the configure method.

Example Code
------------


          #!/usr/local/bin/perl -w

          use Tk;
          use Tk::WaitBox;
          use strict;

          my($root) = MainWindow->new;
          my($utxt) = "Initializing...";

          my($wd) = $root->WaitBox(
          	-bitmap =>'questhead', # Default would be 'hourglass'
          	-txt2 => 'tick-tick-tick', #default would be 'Please Wait'
          	-title => 'Takes forever to get service around here',
          	-cancelroutine => sub {
          	    print "\nI'm canceling....\n";
          	    $wd->unShow;
          	    $utxt = undef;
          	});
          $wd->configure(-txt1 => "Hurry up and Wait, my Drill Sergeant told me");
          $wd->configure(-foreground => 'blue',-background => 'white');

          ### Do something quite boring with the user frame
          my($u) = $wd->{SubWidget}(uframe);
          $u->pack(-expand => 1, -fill => 'both');
          $u->Label(-textvariable => \$utxt)->pack(-expand => 1, -fill => 'both');

          ## It would definitely be better to do this with a canvas... this is dumb
          my($base) = $u->Frame(-background =>'gray',
          		       -relief => 'sunken',
          		       -borderwidth => 2,
          		       -height => 20)
          	 ->pack(-side => 'left', -anchor => 'w',-expand => 1,
          		-fill => 'both');
          my($bar) = $base->Frame(-borderwidth => 2,
          			 -relief => 'raised', -height => 20,
          			 -width => 0, -background => 'blue')
          	 ->pack(-fill => 'y', -side => 'left');

          $wd->configure(-canceltext => 'Halt, Cease, Desist'); # default is 'Cancel'

          $wd->Show;

          for (1..15) {
              sleep(1);
              $bar->configure(-width => int($_/15*$base->Width));
              $utxt = 100*$_/15 . "% Complete";
              $root->update;
              last if !defined($utxt);
          }

          $wd->unShow;

Advertised Subwidgets
=====================

uframe
     uframe is a frame created between the two messages.  It may be used
     for anything the user has in mind... including exciting cycle wasting
     displays of sand dropping through an hour glass, Zippy riding either
     a Gnu or a bronc, et cetera.

     Assuming that the WaitBox is referenced by $w, the uframe may be
     addressed as $w->subwidget{'uframe'}.  Having gotten the address, you
     can do anything (I think) you would like with it

Author
======

   *Brent B. Powers, Merrill Lynch (B2Pi)*  powers@ml.com

   This code may be distributed under the same conditions as perl itself.


File: pm.info,  Node: Tk/Widget,  Next: Tk/WidgetDemo,  Prev: Tk/WaitBox,  Up: Module List

Base class of all widgets
*************************

NAME
====

   Tk::Widget - Base class of all widgets

SYNOPSIS
========

     package Tk::Whatever;
     require Tk::Widget;
     @ISA = qw(Tk::Widget);
     Construct Tk::Widget 'Whatever';

     sub Tk_cmd { \&Tk::whatever }

      $widget->method(?*arg, arg, ...*?)

DESCRIPTION
===========

   The *Tk::Widget* is an abstract base class for all Tk widgets.

   Generic methods available to all widgets include the methods based on
core `winfo' mechanism and are used to retrieve information about windows
managed by Tk. They can take any of a number of different forms, depending
on the method.  The legal forms are:

$widget->*appname*?(*newName*)?
     If *newName* isn't specified, this method returns the name of the
     application (the name that may be used in send commands to
     communicate with the application).  If *newName* is specified, then
     the name of the application is changed to *newName*.  If the given
     name is already in use, then a suffix of the form "* #2*" or "* #3*"
     is appended in order to make the name unique.  The method's result is
     the name actually chosen.  *newName* should not start with a capital
     letter.  This will interfere with `option|Tk::option' in this node
     processing, since names starting with capitals are assumed to be
     classes;  as a result, Tk may not be able to find some options for
     the application.  If sends have been disabled by deleting the send
     command, this command will reenable them and recreate the send
     command.

$widget->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.

$widget->*atomname*(id)
     Returns the textual name for the atom whose integer identifier is id.
     This command is the inverse of the $widget->atom command.  It
     generates an error if no such atom exists.

$widget->*bell*
     This command rings the bell on the display for $widget and returns an
     empty string.  The command uses the current bell-related settings for
     the display, which may be modified with programs such as *xset*.

     This command also resets the screen saver for the screen.  Some
     screen savers will ignore this, but others will reset so that the
     screen becomes visible again.

$widget->*Busy*?(?-recurse => 1?*-option =* value>?)?
     This method configures a *-cursor* option for $widget and (if
     *-recurse =* 1> is specified) all its descendants. The cursor to be
     set may be passed as *-cursor* = cursor> or defaults to 'watch'.
     Additional configure options are applied to $widget only.  It also
     adds a special tag *'Busy'* to the *bindtags* of the widgets so
     configured so that  *KeyPress*, *KeyRelease*, *ButtonPress* and
     ButtonRelease events are ignored (with press events generating a call
     to *bell*). It then acquires a local *grab* for $widget.  The state
     of the widgets and the grab is restored by a call to
     $widget->*Unbusy*.

$widget->*cells*
     Returns a decimal string giving the number of cells in the color map
     for $widget.

$widget->children
     *$widget-*>children Returns a list containing all the children of
     $widget.  The list is in stacking order, with the lowest window
     first.  Top-level windows are returned as children of their logical
     parents.

$widget->class
     Returns the class name for $widget.

$widget->*colormapfull*
     Returns 1 if the colormap for $widget is known to be full, 0
     otherwise.  The colormap for a window is "known" to be full if the
     last attempt to allocate a new color on that window failed and this
     application hasn't freed any colors in the colormap since the failed
     allocation.

$widget->*containing*(*rootX,rootY*)
     Returns 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.

$widget->depth
     Returns a decimal string giving the depth of $widget (number of bits
     per pixel).

$widget->destroy
     This command deletes the window related to $widget, plus all its
     descendants.  If all the *MainWindows* are deleted then the entire
     application will be destroyed.

     The perl object $widget continues to exist while references to it
     still exist, e.g. until variable goes out of scope.  However any
     attempt to use Tk methods on the object will fail.  Exists($widget)
     will return false on such objects.

     Note however that while a window exists for $widget the perl object
     is maintained (due to "references" in perl/Tk internals) even though
     original variables may have gone out of scope.  (Normally this is
     intuitive.)

Exists($widget)
     Returns 1 if there exists a window for $widget, 0 if no such window
     exists.

$widget->font(option?, *arg, arg, ...*?)
     Create and inspect fonts. See *Note Tk/Font: Tk/Font, for further
     details.

$widget->*fpixels*(number)
     Returns a floating-point value giving the number of pixels in $widget
     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 $widget->*pixels*.

$widget->*Getimage*(name)
     Given name, look for an image file with that base name and return a
     *Note Tk/Image: Tk/Image,.  File extensions are tried in this order:
     `xpm', gif, `ppm', `xbm' until a valid iamge is found.  If no image is
     found, try a builtin image with that name.

$widget->*geometry*
     Returns the geometry for $widget, in the form widthxheight+x+y.  All
     dimensions are in pixels.

$widget->height
     Returns a decimal string giving $widget'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 $widget->*reqheight* to get the window's requested height instead
     of its actual height.

$widget->id
     Returns a hexadecimal string giving a low-level platform-specific
     identifier for $widget.  On Unix platforms, this is the X window
     identifier.  Under Windows, this is the Windows HWND.  On the
     Macintosh the value has no meaning outside Tk.

$widget->*idletasks*
     One of two methods which are used to bring the application "up to
     date" by entering the event loop repeated until all pending events
     (including idle callbacks) have been processed.

     If the *idletasks* method is specified, then no new events or errors
     are processed; only idle callbacks are invoked. This causes operations
     that are normally deferred, such as display updates and window layout
     calculations, to be performed immediately.

     The *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. Most display updates are performed as idle callbacks, so
     *idletasks* will cause them to run. However, there are some kinds of
     updates that only happen in response to events, such as those
     triggered by window size changes; these updates will not occur in
     *idletasks*.

$widget->*interps*
     Returns a list whose members are the names of all Tcl interpreters
     (e.g. all Tk-based applications) currently registered for a
     particular display.  The return value refers to the display of
     $widget.

$widget->*ismapped*
     Returns 1 if $widget is currently mapped, 0 otherwise.

*$widget-*>*lower*(?*belowThis*?)
     If the *belowThis* argument is omitted then the command lowers
     $widget so that it is below all of its siblings in the stacking order
     (it will be obscured by any siblings that overlap it and will not
     obscure any siblings).  If *belowThis* is specified then it must be
     the path name of a window that is either a sibling of $widget or the
     descendant of a sibling of $widget.  In this case the *lower* command
     will insert $widget into the stacking order just below *belowThis*
     (or the ancestor of *belowThis* that is a sibling of $widget); this
     could end up either raising or lowering $widget.

$widget->*MapWindow*
     Cause $widget to be "mapped" i.e. made visible on the display.  May
     confuse the geometry manager (pack, grid, place, ...)  that thinks it
     is managing the widget.

$widget->manager
     Returns the name of the geometry manager currently responsible for
     $widget, or an empty string if $widget isn't managed by any geometry
     manager.  The name is usually the name of the method for the geometry
     manager, such as pack or *place*.  If the geometry manager is a
     widget, such as canvases or text, the name is the widget's class
     command, such as canvas.

$widget->name
     Returns $widget's name (i.e. its name within its parent, as opposed
     to its full path name).  The command *$mainwin*->name will return the
     name of the application.

$widget->OnDestroy(callback);
     OnDestroy accepts a standard perl/Tk callback.  When the window
     associated with $widget is destroyed then the callback is invoked.
     Unlike *$widget-*>bind('<Destroy>',...)  the widgets methods are
     still available when callback is executed, so (for example) a Text
     widget can save its contents to a file.

     OnDestroy was required for new after mechanism.

$widget->parent
     Returns $widget's parent, or an empty string if $widget is the main
     window of the application.

$widget->*PathName*
     Returns the tk path name of $widget. (This is an import from the C
     interface.)

$widget->*pathname*(id)
     Returns an object whose X identifier is id.  The identifier is looked
     up on the display of $widget.  Id must be a decimal, hexadecimal, or
     octal integer and must correspond to a window in the invoking
     application, or an error occurs which can be trapped with `eval { }'
     or `Tk::catch { }'.  If the window belongs to the application, but is
     not an object (for example wrapper windows, HList header, etc.) then
     undef is returned.

$widget->*pixels*(number)
     Returns the number of pixels in $widget 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
     $widget->*fpixels*.

$widget->*pointerx*
     If the mouse pointer is on the same screen as $widget, returns the
     pointer's x coordinate, measured in pixels in the screen's root
     window.  If a virtual root window is in use on the screen, the
     position is measured in the virtual root.  If the mouse pointer isn't
     on the same screen as $widget then -1 is returned.

$widget->*pointerxy*
     If the mouse pointer is on the same screen as $widget, returns a list
     with two elements, which are the pointer's x and y coordinates
     measured in pixels in the screen's root window.  If a virtual root
     window is in use on the screen, the position is computed in the
     virtual root.  If the mouse pointer isn't on the same screen as
     $widget then both of the returned coordinates are -1.

$widget->*pointery*
     If the mouse pointer is on the same screen as $widget, returns the
     pointer's y coordinate, measured in pixels in the screen's root
     window.  If a virtual root window is in use on the screen, the
     position is computed in the virtual root.  If the mouse pointer isn't
     on the same screen as $widget then -1 is returned.

$widget->raise(?*aboveThis*?)
     If the *aboveThis* argument is omitted then the command raises
     $widget 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 $widget or
     the descendant of a sibling of $widget.  In this case the raise
     command will insert $widget into the stacking order just above
     *aboveThis* (or the ancestor of *aboveThis* that is a sibling of
     $widget); this could end up either raising or lowering $widget.

$widget->*reqheight*
     Returns a decimal string giving $widget's requested height, in
     pixels.  This is the value used by $widget's geometry manager to
     compute its geometry.

$widget->*reqwidth*
     Returns a decimal string giving $widget's requested width, in pixels.
     This is the value used by $widget's geometry manager to compute its
     geometry.

$widget->*rgb*(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 $widget.  Color may be specified in any of the forms
     acceptable for a color option.

$widget->*rootx*
     Returns a decimal string giving the x-coordinate, in the root window
     of the screen, of the upper-left corner of $widget's border (or
     $widget if it has no border).

$widget->*rooty*
     Returns a decimal string giving the y-coordinate, in the root window
     of the screen, of the upper-left corner of $widget's border (or
     $widget if it has no border).

scaling
$widget->scaling?(number)?
     Sets and queries the current scaling factor used by Tk to convert
     between physical units (for example, points, inches, or millimeters)
     and pixels.  The number argument is a floating point number that
     specifies the number of pixels per point on $widget's display. If the
     number argument is omitted, the current value of the scaling factor
     is returned.

     A "point" is a unit of measurement equal to 1/72 inch.  A scaling
     factor of 1.0 corresponds to 1 pixel per point, which is equivalent
     to a standard 72 dpi monitor.  A scaling factor of 1.25 would mean
     1.25 pixels per point, which is the setting for a 90 dpi monitor;
     setting the scaling factor to 1.25 on a 72 dpi monitor would cause
     everything in the application to be displayed 1.25 times as large as
     normal.  The initial value for the scaling factor is set when the
     application starts, based on properties of the installed monitor (as
     reported via the window system), but it can be changed at any time.
     Measurements made after the scaling factor is changed will use the
     new scaling factor, but it is undefined whether existing widgets will
     resize themselves dynamically to accomodate the new scaling factor.

$widget->*screen*
     Returns the name of the screen associated with $widget, in the form
     *displayName*.*screenIndex*.

$widget->*screencells*
     Returns a decimal string giving the number of cells in the default
     color map for $widget's screen.

$widget->*screendepth*
     Returns a decimal string giving the depth of the root window of
     $widget's screen (number of bits per pixel).

$widget->*screenheight*
     Returns a decimal string giving the height of $widget's screen, in
     pixels.

$widget->*screenmmheight*
     Returns a decimal string giving the height of $widget's screen, in
     millimeters.

$widget->*screenmmwidth*
     Returns a decimal string giving the width of $widget's screen, in
     millimeters.

$widget->*screenvisual*
     Returns one of the following strings to indicate the default visual
     class for $widget's screen: *directcolor*, *grayscale*,
     *pseudocolor*, *staticcolor*, *staticgray*, or *truecolor*.

$widget->*screenwidth*
     Returns a decimal string giving the width of $widget's screen, in
     pixels.

$widget->server
     Returns a string containing information about the server for
     $widget's display.  The exact format of this string may vary from
     platform to platform.  For X servers the string has the form
     "X*major*R*minor vendor vendorVersion*" where *major* and *minor* are
     the version and revision numbers provided by the server (e.g.,
     *X11R5*), *vendor* is the name of the vendor for the server, and
     *vendorRelease* is an integer release number provided by the server.

$widget->toplevel
     Returns the reference of the top-level window containing $widget.

$widget->*UnmapWindow*
     Cause $widget to be "unmapped" i.e. removed from the display.  This
     does for any widget what $widget->withdraw does for toplevel widgets.
     May confuse the geometry manager (pack, grid, place, ...)  that
     thinks it is managing the widget.

$widget->update
     One of two methods which are used to bring the application "up to
     date" by entering the event loop repeated until all pending events
     (including idle callbacks) have been processed.

     The update method is useful in scripts where you are performing a
     long-running computation but you still want the application to respond
     to events such as user interactions; if you occasionally call update
     then user input will be processed during the next call to update.

$widget->*Unbusy*
     Restores widget state after a call to  $widget->*Busy*.

$widget->*viewable*
     Returns 1 if $widget and all of its ancestors up through the nearest
     toplevel window are mapped.  Returns 0 if any of these windows are
     not mapped.

$widget->*visual*
     Returns one of the following strings to indicate the visual class for
     $widget: *directcolor*, *grayscale*, *pseudocolor*, *staticcolor*,
     *staticgray*, or *truecolor*.

$widget->*visualid*
     Returns the X identifier for the visual for $widget.

$widget->*visualsavailable*(?*includeids*?)
     Returns a list whose elements describe the visuals available for
     $widget's screen.  Each element consists of a visual class followed
     by an integer depth.  The class has the same form as returned by
     $widget->*visual*.  The depth gives the number of bits per pixel in
     the visual.  In addition, if the *includeids* argument is provided,
     then the depth is followed by the X identifier for the visual.

$widget->*vrootheight*
     Returns the height of the virtual root window associated with $widget
     if there is one;  otherwise returns the height of $widget's screen.

$widget->*vrootwidth*
     Returns the width of the virtual root window associated with $widget
     if there is one;  otherwise returns the width of $widget's screen.

$widget->*vrootx*
     Returns the x-offset of the virtual root window associated with
     $widget, 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 $widget.

$widget->*vrooty*
     Returns the y-offset of the virtual root window associated with
     $widget, 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 $widget.

*$widget-*>*waitVariable*(\$name)
*$widget-*>*waitVisibility*
*$widget-*>*waitWindow*
     The *tk wait* methods wait for one of several things to happen, then
     it returns without taking any other actions.  The return value is
     always an empty string.  *waitVariable* expects a reference to a perl
     variable and the command waits for that variable to be modified.
     This form is typically used to wait for a user to finish interacting
     with a dialog which sets the variable as part (possibly final) part
     of the interaction.  *waitVisibility* waits for a change in $widget's
     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.
     *waitWindow* waits for $widget 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.  Note that creating
     and destroying the window each time a dialog is required makes code
     modular but imposes overhead which can be avoided by *withdrawing*
     the window instead and using *waitVisibility*.

     While the *tk wait* methods are waiting they processes events in the
     normal fashion, so the application will continue to respond to user
     interactions.  If an event handler invokes *tkwait* again, the nested
     call to *tkwait* must complete before the outer call can complete.

$widget->width
     Returns a decimal string giving $widget'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 $widget->*reqwidth* to get the window's requested width instead
     of its actual width.

$widget->x
     Returns a decimal string giving the x-coordinate, in $widget's
     parent, of the upper-left corner of $widget's border (or $widget if
     it has no border).

$widget->y
     Returns a decimal string giving the y-coordinate, in $widget's
     parent, of the upper-left corner of $widget's border (or $widget if it
     has no border).

CAVEATS
=======

   The above documentaion on generic methods is incomplete.

KEYWORDS
========

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


File: pm.info,  Node: Tk/WidgetDemo,  Next: Tk/WinPhoto,  Prev: Tk/Widget,  Up: Module List

create a standard widget demonstration window.
**********************************************

NAME
====

   WidgetDemo() - create a standard widget demonstration window.

SYNOPSIS
========

     use WidgetDemo;
     my $TOP = $MW->WidgetDemo(
         -name             => $demo,
         -text             => 'Learn how to write a widget demonstration!',
         -title            => 'WidgetDemo Demonstration',
         -iconname         => 'WidgetDemo',
         -geometry_manager => 'grid',
         -font             => $FONT,
     );

DESCRIPTION
===========

   This constructor builds a standard widget demonstration window,
composed of three frames.  The top frame contains descriptive
demonstration text.  The bottom frame contains the "Dismiss" and "See
Code" buttons.  The middle frame is demonstration container, which came be
managed by either the pack or grid geometry manager.

   The -text attribute is supplied to a Label widget, which is
left-adjusted with -wraplength set to 4 inches.  If you require different
specifications then pass an array to -text; the first element is the text
string and the remaining array elements are standard Label widget
attributes - WidgetDemo will rearrange things as required..

     -text => ['Hello World!', qw/-wraplength 6i/],

AUTHOR
======

   Steve Lidie <Stephen.O.Lidie@Lehigh.EDU>

HISTORY
=======

   lusol@Lehigh.EDU, LUCC, 97/02/11 lusol@Lehigh.EDU, LUCC, 97/06/07
Stephen.O.Lidie@Lehigh.EDU, LUCC, 97/06/07  . Add Delegates() call that
obviates the need for Top().  Many thanks to    Achim Bohnet for this
patch.   . Fix -title so that it works.

COPYRIGHT
=========

   Copyright (C) 1997 - 1998 Stephen O. Lidie. All rights reserved.

   This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


File: pm.info,  Node: Tk/WinPhoto,  Next: Tk/Wm,  Prev: Tk/WidgetDemo,  Up: Module List

Load a Photo image from a window
********************************

NAME
====

   Tk::WinPhoto - Load a Photo image from a window

     use Tk;
     use Tk::WinPhoto;

     my $image = $mw->Photo(-format => 'Window', -data => oct($mw->id));
     $image->write($path_name, -format => 'BMP|PPM|XPM');

DESCRIPTION
===========

   This is an extension for Tk800.* which will load a Photo image from a
snapshot of an X window specified by the -data option.

   The window must exist and be visible. Because the code allows you to
capture windows not owned by Tk it does not attempt to enforce this. If
you are capturing one of Tk's windows then use `$w->update'.

   If window is mapped, but obscured by other windows then what is
captured is the rectangle the window would occupy. This can be considered
a feature.  For Tk-owned windows `$w->raise' can used to bring window
forward.

   Once the Photo is loaded it can be saved using `$image->write(-format
=> ...)' using any of formats which support writing.

AUTHOR
======

   Nick Ing-Simmons <nick@ni-s.u-net.com>


File: pm.info,  Node: Tk/Wm,  Next: Tk/Workspace,  Prev: Tk/WinPhoto,  Up: Module List

Communicate with window manager
*******************************

NAME
====

   Tk::Wm - Communicate with window manager

       *$toplevel*->method(?args?)

DESCRIPTION
===========

   The *wm* methods are 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* methods can take
any of a number of different forms, depending on the particular method
argument.  All of the forms expect *$toplevel*, which must be a top-level
window object.

   The legal forms for the *wm* methods are:

*$toplevel*->*aspect*(?*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 *$toplevel*.  The aspect ratio of *$toplevel*
     (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
     method returns an empty string.  Otherwise, it returns a array
     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).

*$toplevel*->client(?name?)
     If name is specified, this method stores name (which should be the
     name of the host on which the application is executing) in
     *$toplevel*'s *WM_CLIENT_MACHINE* property for use by the window
     manager or session manager.  The method returns an empty string in
     this case.  If name isn't specified, the method returns the last name
     set in a client method for *$toplevel*.  If name is specified as an
     empty string, the method deletes the *WM_CLIENT_MACHINE* property
     from *$toplevel*.

*$toplevel*->*colormapwindows*(?*windowList*?)
     This method is used to manipulate the *WM_COLORMAP_WINDOWS* property,
     which provides information to the window managers about windows that
     have private colormaps.  If *windowList* isn't specified, the method
     returns a list whose elements are the names of the windows in the
     *WM_COLORMAP_WINDOWS* property.  If *windowList* is specified, it
     consists of a list of widgets; the method overwrites the
     *WM_COLORMAP_WINDOWS* property with the given windows and returns an
     empty string.  The *WM_COLORMAP_WINDOWS* property should normally
     contain a list of the internal windows within *$toplevel* whose
     colormaps differ from their parents.  The order of the windows in the
     property indicates a priority order: the window manager will attempt
     to install as many colormaps as possible from the head of this list
     when $widget gets the colormap focus.  If $widget is not included
     among the windows in *windowList*, Tk implicitly adds it at the end
     of the *WM_COLORMAP_WINDOWS* property, so that its colormap is lowest
     in priority.  If $widget->colormapwindows is not invoked, Tk will
     automatically set the property for each top-level window to all the
     internal windows whose colormaps differ from their parents, followed
     by the top-level itself;  the order of the internal windows is
     undefined.  See the ICCCM documentation for more information on the
     *WM_COLORMAP_WINDOWS* property.

*$toplevel*->command(?value?)
     If value is specified, this method stores value in *$toplevel*'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 method
     returns the last value set in a command method for *$toplevel*.  If
     value is specified as an empty string, the method deletes the
     *WM_COMMAND* property from *$toplevel*.

*$toplevel*->*deiconify*
     Arrange for *$toplevel* to be displayed in normal (non-iconified)
     form.  This is done by mapping the window.  If the window has never
     been mapped then this method 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.

*$toplevel*->*focusmodel*(?active|*passive*?)
     If active or *passive* is supplied as an optional argument to the
     method, then it specifies the focus model for *$toplevel*.  In this
     case the method returns an empty string.  If no additional argument
     is supplied, then the method returns the current focus model for
     *$toplevel*.  An active focus model means that *$toplevel* 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
     *$toplevel* will never claim the focus for itself:  the window manager
     should give the focus to *$toplevel* at appropriate times.  However,
     once the focus has been given to *$toplevel* or one of its
     descendants, the application may re-assign the focus among
     *$toplevel*'s descendants.  The focus model defaults to *passive*,
     and Tk's focus method assumes a passive model of focusing.

*$toplevel*->frame
     If $widget has been reparented by the window manager into a
     decorative frame, the method returns the platform specific window
     identifier for the outermost frame that contains *$toplevel* (the
     window whose parent is the root or virtual root).  If *$toplevel*
     hasn't been reparented by the window manager then the method returns
     the platform specific window identifier for *$toplevel*.

*$toplevel*->*geometry*(?*newGeometry*?)
     If *newGeometry* is specified, then the geometry of *$toplevel* is
     changed and an empty string is returned.  Otherwise the current
     geometry for *$toplevel* is returned (this is the most recent
     geometry specified either by manual resizing or in a *geometry*
     method).  *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
     *$toplevel*.  If *$toplevel* is gridded (see `"GRIDDED GEOMETRY
     MANAGEMENT"' in this node below) then the dimensions are specified in
     grid units;  otherwise they are specified in pixel units.  X and y
     specify the desired location of *$toplevel* 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 *$toplevel*'s border;
     if preceded by - then x specifies the number of pixels between the
     right edge of the screen and the right edge of *$toplevel*'s border.
     If y is preceded by + then it specifies the number of pixels between
     the top of the screen and the top of *$toplevel*'s border;  if y is
     preceded by - then it specifies the number of pixels between the
     bottom of *$toplevel*'s border and the bottom of the screen.  If
     *newGeometry* is specified as an empty string then any existing
     user-specified geometry for *$toplevel* is cancelled, and the window
     will revert to the size requested internally by its widgets.

*$toplevel*->*wmGrid*(?*baseWidth,baseHeight,widthInc,heightInc*?)
     This method indicates that *$toplevel* 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
     *$toplevel* 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
     *$toplevel*, 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 *$toplevel*
     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 array containing four elements corresponding to
     the current *baseWidth*, *baseHeight*, *widthInc*, and *heightInc*;
     if *$toplevel* 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.

*$toplevel*->group(?$widget?)
     If $widget is specified, it is the 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.  $widget may be specified as an empty string to remove
     *$toplevel* from any group association.  If $widget is specified then
     the method returns an empty string;  otherwise it returns the
     *$toplevel*'s current group leader, or an empty string if *$toplevel*
     isn't part of any group.

*$toplevel*->*iconbitmap*(?bitmap?)
     If bitmap is specified, then it names a bitmap in the standard forms
     accepted by Tk (see the *Tk_GetBitmap* documentation for details).
     This *black and white* bitmap is passed to the window manager to be
     displayed in *$toplevel*'s icon, and the method returns an empty
     string.  If an empty string is specified for bitmap, then any current
     icon bitmap or image is cancelled for *$toplevel*.  If bitmap is
     specified then the method returns an empty string.  Otherwise it
     returns the name of the current icon bitmap associated with
     *$toplevel*, or an empty string if *$toplevel* has no icon bitmap.

*$toplevel*->iconify
     Arrange for *$toplevel* to be iconified.  It *$toplevel* hasn't yet
     been mapped for the first time, this method will arrange for it to
     appear in the iconified state when it is eventually mapped.

*$toplevel*->*iconimage*(?image?)
     If image is specified, then it names a normal Tk image.  This image
     is rendered into a private *coloured* bitmap which is passed to the
     window manager to be displayed in *$toplevel*'s icon, and the method
     returns an empty string. If an empty string is specified for image,
     then any current icon bitmap or image is cancelled for *$toplevel*.
     If image is specified then the method returns an empty string.
     Otherwise it returns the name of the current icon image associated
     with *$toplevel*, or an empty string if *$toplevel* has no icon image.
     The private pixmap is not pre-cleared so images which are partly
     "transparent" display rubbish in their transparent parts.

     The sizes of images that can be used as icons in this manner are
     platform dependant. On Win32 this sets the "large" icon, which should
     be 32x32, it will automatically be scaled down to 16x16 for use as a
     small icon.

*$toplevel*->*iconmask*(?bitmap?)
     If bitmap is specified, then it names a bitmap in the standard forms
     accepted by Tk (see the *Tk_GetBitmap* documentation 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 *$toplevel* (this is
     equivalent to specifying a bitmap of all ones).  If bitmap is
     specified then the method returns an empty string.  Otherwise it
     returns the name of the current icon mask associated with
     *$toplevel*, or an empty string if no mask is in effect.

*$toplevel*->*iconname*(?*newName*?)
     If *newName* is specified, then it is passed to the window manager;
     the window manager should display *newName* inside the icon
     associated with *$toplevel*.  In this case an empty string is
     returned as result.  If *newName* isn't specified then the method
     returns the current icon name for *$toplevel*, 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 title
     method).

*$toplevel*->*iconposition*(?*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 *$toplevel*.  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 method returns a array
     containing two values, which are the current icon position hints (if
     no hints are in effect then an empty string is returned).

*$toplevel*->*iconwindow*(?$widget?)
     If $widget is specified, it is a window to use as icon for
     *$toplevel*: when *$toplevel* is iconified then $widget will be
     mapped to serve as icon, and when *$toplevel* is de-iconified then
     $widget will be unmapped again.  If $widget is specified as an empty
     string then any existing icon window association for *$toplevel* will
     be cancelled.  If the $widget argument is specified then an empty
     string is returned.  Otherwise the method returns the current icon
     window for *$toplevel*, or an empty string if there is no icon window
     currently specified for *$toplevel*.  Button press events are
     disabled for *$toplevel* as long as it is an icon window;  this is
     needed in order to allow window managers to "own" those events.
     Note: not all window managers support the notion of an icon window.

*$toplevel*->*maxsize*(?*width,height*?)
     If width and height are specified, they give the maximum permissible
     dimensions for *$toplevel*.  For gridded windows the dimensions are
     specified in grid units;  otherwise they are specified in pixel units.
     The window manager will restrict the window's dimensions to be less
     than or equal to width and height.  If width and height are
     specified, then the method returns an empty string.  Otherwise it
     returns a array with two elements, which are the maximum width and
     height currently in effect.  The maximum size defaults to the size of
     the screen.  If resizing has been disabled with the *resizable*
     method, then this method has no effect.  See the sections on geometry
     management below for more information.

*$toplevel*->*minsize*(?*width,height*?)
     If width and height are specified, they give the minimum permissible
     dimensions for *$toplevel*.  For gridded windows the dimensions are
     specified in grid units;  otherwise they are specified in pixel units.
     The window manager will restrict the window's dimensions to be
     greater than or equal to width and height.  If width and height are
     specified, then the method returns an empty string.  Otherwise it
     returns a array with two elements, which are the minimum width and
     height currently in effect.  The minimum size defaults to one pixel
     in each dimension.  If resizing has been disabled with the
     *resizable* method, then this method has no effect.  See the sections
     on geometry management below for more information.

*$toplevel*->*overrideredirect(?*boolean?)
     If boolean is specified, it must have a proper boolean form and the
     override-redirect flag for *$toplevel* 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 *$toplevel*.
     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.

*$toplevel*->*positionfrom*(?who?)
     If who is specified, it must be either program or user, or an
     abbreviation of one of these two.  It indicates whether *$toplevel*'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 method returns an empty string.  Otherwise it
     returns user or $widget 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 *geometry* method is invoked, unless the source has been set
     explicitly to program.

*$toplevel*->protocol(?name?,?callback?)
     This method 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 callback are
     specified, then callback is associated with the protocol specified by
     name.  Name will be added to *$toplevel*'s *WM_PROTOCOLS* property to
     tell the window manager that the application has a protocol handler
     for name, and callback will be invoked in the future whenever the
     window manager sends a message to the client for that protocol.  In
     this case the method returns an empty string.  If name is specified
     but callback isn't, then the current callback for name is returned,
     or an empty string if there is no handler defined for name.  If
     callback is specified as an empty string then the current handler for
     name is deleted and it is removed from the *WM_PROTOCOLS* property on
     *$toplevel*;  an empty string is returned.  Lastly, if neither name
     nor callback is specified, the method returns a list of all the
     protocols for which handlers are currently defined for *$toplevel*.

     Tk always defines a protocol handler for *WM_DELETE_WINDOW*, even if
     you haven't asked for one with 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.

*$toplevel*->*resizable*(?*width,height*?)
     This method controls whether or not the user may interactively resize
     a top-level window.  If width and height are specified, they are
     boolean values that determine whether the width and height of
     *$toplevel* may be modified by the user.  In this case the method
     returns an empty string.  If width and height are omitted then the
     method returns a list with two 0/1 elements that indicate whether the
     width and height of *$toplevel* are currently resizable.  By default,
     windows are resizable in both dimensions.  If resizing is disabled,
     then the window's size will be the size from the most recent
     interactive resize or *geometry* method.  If there has been no such
     operation then the window's natural size will be used.

*$toplevel*->*sizefrom*(?who?)
     If who is specified, it must be either program or user, or an
     abbreviation of one of these two.  It indicates whether *$toplevel*'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
     method returns an empty string.  Otherwise it returns user or $widget
     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.

*$toplevel*->state
     Returns the current state of $widget:  either normal, *iconic*,
     *withdrawn*, or icon.  The difference between *iconic* and icon is
     that *iconic* refers to a window that has been iconified (e.g., with
     the iconify method) while icon refers to a window whose only purpose
     is to serve as the icon for some other window (via the *iconwindow*
     method).

*$toplevel*->title(?string?)
     If string is specified, then it will be passed to the window manager
     for use as the title for *$toplevel* (the window manager should
     display this string in *$toplevel*'s title bar).  In this case the
     method returns an empty string.  If string isn't specified then the
     method returns the current title for the *$toplevel*.  The title for
     a window defaults to its name.

*$toplevel*->*transient*(?master?)
     If master is specified, then the window manager is informed that
     *$toplevel* is a transient window (e.g. pull-down menu) working on
     behalf of master (where master is a top-level window).  Some window
     managers will use this information to manage *$toplevel* specially.
     If master is specified as an empty string then *$toplevel* is marked
     as not being a transient window any more.  If master is specified,
     then the method returns an empty string.  Otherwise the method
     returns the path name of *$toplevel*'s current master, or an empty
     string if *$toplevel* isn't currently a transient window.

*$toplevel*->*withdraw*
     Arranges for *$toplevel* 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 method
     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 *deiconify*) to get
     some window managers to pay attention to changes in window attributes
     such as group.

*$toplevel*->*wrapper*
     Returns the window id of the wrapper window in which Tk has placed
     *$toplevel*. This is the id by which window manager will know
     *$toplevel*, and so is appropriate place to add X properties.

ICON SIZES
==========

   The sizes of bitmaps/images that can be used as icons in this manner
are platform and window manager dependant. Unix window managers are
typically more tolerant than Win32. It is possible that coloured
`iconimage' icons may cause problems on some X window managers.

   * Win32

     `iconimage' and `iconbitmap' set the "large" icon, which should be
     32x32, it will automatically be scaled down to 16x16 for use as a
     small icon.  Win32 ignores `iconwin' requests.

   * KDE's "kwm"                   Accepts coloured `iconimage' and black
     and white `iconbitmap' but  will scale either to a small (14x14?)
     icon. Kwm ignores `iconwin'.

   * Sun's "olwm" or "olvwm"

     Honours `iconwin' which will override `iconimage' or `iconbitmap'.
     Coloured images work.

   * Sun's CDE window manager

     Coloured images work. ...

GEOMETRY MANAGEMENT
===================

   By default a top-level window appears on the screen in its *natural
size*, which is the one determined internally by its widgets and geometry
managers.  If the natural size of a top-level window changes, then the
window's size changes to match.  A top-level window can be given a size
other than its natural size in two ways.  First, the user can resize the
window manually using the facilities of the window manager, such as resize
handles.  Second, the application can request a particular size for a
top-level window using the *geometry* method.  These two cases are handled
identically by Tk;  in either case, the requested size overrides the
natural size.  You can return the window to its natural by invoking
*geometry* with an empty *geometry* string.

   Normally a top-level window can have any size from one pixel in each
dimension up to the size of its screen.  However, you can use the
*minsize* and *maxsize* methods to limit the range of allowable sizes.
The range set by *minsize* and *maxsize* applies to all forms of resizing,
including the window's natural size as well as manual resizes and the
*geometry* method.  You can also use the method *resizable* to completely
disable interactive resizing in one or both dimensions.

GRIDDED GEOMETRY MANAGEMENT
===========================

   Gridded geometry management 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
*geometry* method 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 *wmGrid* method 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 grid with empty argument strings.

   When gridded geometry management is enabled then all the dimensions
specified in *minsize*, *maxsize*, and *geometry* methods are treated as
grid units rather than pixel units.  Interactive resizing is also carried
out in even numbers of grid units rather than pixels.

BUGS
====

   Most existing window managers appear to have bugs that affect the
operation of the *wm* methods.  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.

SEE ALSO
========

   `Tk::Widget|Tk::Widget' in this node `Tk::tixWm|Tk::tixWm' in this node
`Tk::Mwm|Tk::Mwm' in this node

KEYWORDS
========

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