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


File: pm.info,  Node: Tk/bindtags,  Next: Tk/callbacks,  Prev: Tk/bind,  Up: Module List

Determine which bindings apply to a window, and order of evaluation
*******************************************************************

NAME
====

   Tk::bindtags - Determine which bindings apply to a window, and order of
evaluation

   $widget->*bindtags*([*tagList*]); *@tags* = $widget->*bindtags*;

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

   When a binding is created with the bind command, it is associated
either with a particular window such as $widget, a class name such as
*Tk::Button*, the keyword all, or any other string.  All of these forms
are called *binding tags*.  Each window has a list of binding tags that
determine how events are processed for the window.  When an event occurs
in a window, it is applied to each of the window's tags in order:  for
each tag, the most specific binding that matches the given tag and event
is executed.  See the *Note Tk/bind: Tk/bind, documentation for more
information on the matching process.

   By default, each window has four binding tags consisting of the the
window's class name, name of the window, the name of the window's nearest
toplevel ancestor, and all, in that order.  Toplevel windows have only
three tags by default, since the toplevel name is the same as that of the
window.

   Note that this order is *different* from order used by Tcl/Tk.  Tcl/Tk
has the window ahead of the class name in the binding order.  This is
because Tcl is procedural rather than object oriented and the normal way
for Tcl/Tk applications to override class bindings is with an instance
binding. However, with perl/Tk the normal way to override a class binding
is to derive a class. The perl/Tk order causes instance bindings to
execute after the class binding, and so instance bind callbacks can make
use of state changes (e.g. changes to the selection) than the class
bindings have made.

   The *bindtags* command allows the binding tags for a window to be read
and modified.

   If $widget->*bindtags* is invoked without an argument, then the current
set of binding tags for $widget is returned as a list.  If the *tagList*
argument is specified to *bindtags*, then it must be a reference to and
array; the tags for $widget are changed to the elements of the array. (A
reference to an anonymous array can be created by enclosin the elements in
*[ ]*.)  The elements of *tagList* may be arbitrary strings or widget
objects, if no window exists for an object at the time an event is
processed, then the tag is ignored for that event.  The order of the
elements in *tagList* determines the order in which binding callbacks are
executed in response to events.  For example, the command

     $b->bindtags([$b,ref($b),$b->toplevel,'all'])

   applies the Tcl/Tk binding order which binding callbacks will be
evaluated for a button (say) $b so that $b's instance bindings are invoked
first, following by bindings for $b's class, followed by bindings for $b's
toplevel, followed by 'all' bindings.

   If *tagList* is an empty list i.e. [], then the binding tags for
$widget are returned to the perl/Tk default state described above.

   The *bindtags* command may be used to introduce arbitrary additional
binding tags for a window, or to remove standard tags.  For example, the
command

     $b->bindtags(['TrickyButton',$b->toplevel,'all'])

   replaces the (say) *Tk::Button* tag for $b with *TrickyButton*.  This
means that the default widget bindings for buttons, which are associated
with the *Tk::Button* tag, will no longer apply to $b, but any bindings
associated with *TrickyButton* (perhaps some new button behavior) will
apply.

BUGS
====

   The current mapping of the 'native' Tk behaviour of this method i.e.
returning a list but only accepting a reference to an array is counter
intuitive. The perl/Tk interface  may be tidied up, returning a list is
sensible so, most likely fix will be to allow a list to be passed to
/fIset/fR the bindtags.

SEE ALSO
========

   `Tk::bind|Tk::bind' in this node `Tk::callbacks|Tk::callbacks' in this
node

KEYWORDS
========

   binding, event, tag


File: pm.info,  Node: Tk/callbacks,  Next: Tk/chooseColor,  Prev: Tk/bindtags,  Up: Module List

Specifying code for Tk to call.
*******************************

NAME
====

   Tk::callbacks - Specifying code for Tk to call.

   One can specify a callback in one of the following ways:

   Without arguments:

     ... => \&subname, ...
     ... => sub { ... }, ...
     ... => 'methodname', ...

   or with arguments:

     ... => [ \&subname ?, args ...? ], ...
     ... => [ sub { ... } ?, args...? ], ...
     ... => [ 'methodname' ?, args...?], ...

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

   Perl/Tk has a callback, where Tcl/Tk has a command string (i.e. a
fragment of Tcl to be executed).  A perl/Tk callback can take one of the
following basic forms:

   * Reference to a subroutine `\E<amp'subname>

   * Anonymous subroutine (closure) `sub { ... }'

   * A method name `'methodname''

   Any of these can be provided with arguments by enclosing them and the
arguments in []. Here are some examples:

   *$mw*->bind(*$class,* *"<Delete>" => 'Delete'*);

   This will call $widget->Delete, the $widget being provided (by bind) as
the one where the Delete key was pressed.

   While having bind provide a widget object for you is ideal in many cases
it can be irritating in others. Using the list form this behaviour can be
modified:

   *$a*->bind(*"<Delete>"*,[$b => 'Delete']);

   because the first element $b is an object bind will call $b->Delete.

   Note that method/object ordering only matters for bind callbacks, the
auto-quoting in perl5.001 makes the first of these a little more readable:

   $w->configure(-yscrollcommand => [ set => $ysb]);

   $w->configure(-yscrollcommand => [ $ysb => 'set' ]);

   but both will call `$ysb'->set(args provided by Tk)

   Another use of arguments allows you to write generalized methods which
are easier to re-use:

   $a->bind("<Next>",['Next','Page']);

   $a->bind("<Down>",['Next','Line']);

   This will call `$a'->Next('Page') or `$a'->Next('Line') respectively.

   Note that the contents of the [] are evaluated by perl when the
callback is created. It is often desirable for the arguments provided to
the callback to depend on the details of the event which caused it to be
executed. To allow for this callbacks can be nested using the `Ev(...)'
"constructor".  `Ev(...)' inserts callback objects into the argument list.
When perl/Tk glue code is preparing the argument list for the callback it
is about to call it spots these special objects and recursively applies
the callback process to them.

EXAMPLES
========

     $entry->bind('<Return>' => [$w , 'validate', Ev(['get'])]);

     $toplevel->bind('all', '<Visibility>', [\&unobscure, Ev('s')]);

     $mw->bind($class, '<Down>', ['SetCursor', Ev('UpDownLine',1)]);

SEE ALSO
========

   `Tk::bind|Tk::bind' in this node `Tk::after|Tk::after' in this node
`Tk::options|Tk::options' in this node `Tk::fileevent|Tk::fileevent' in
this node

KEYWORDS
========

   callback, closure, anonymous subroutine, bind


File: pm.info,  Node: Tk/chooseColor,  Next: Tk/composite,  Prev: Tk/callbacks,  Up: Module List

pops up a dialog box for the user to select a color.
****************************************************

NAME
====

   chooseColor - pops up a dialog box for the user to select a color.

       $color = $widget->*chooseColor*?(*-option*=>value, ...)?;

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

   The method *chooseColor* is implemented as a perl wrapper on the core
tk "command" *tk_chooseColor*. The $widget is passed as the argument to
*-parent* described below.  The implementation of internal
*tk_chooseColor* is platform specific, on Win32 it is a native dialog, and
on UNIX/X it is implemented in terms of `Tk::ColorEditor|Tk::ColorEditor'
in this node.

   The core tk command *tk_chooseColor* pops up a dialog box for the user
to select a color. The following *option-value* pairs are possible as
command line arguments:

*-initialcolor*=>color
     Specifies the color to display in the color dialog when it pops up.
     color must be in a form acceptable to the *Tk_GetColor* function.

*-parent*=>$widget
     Makes $widget the logical parent of the color dialog. The color
     dialog is displayed on top of its parent window.

*-title*=>*titleString*
     Specifies a string to display as the title of the dialog box. If this
     option is not specified, then a default title will be displayed.

   If the user selects a color, *tk_chooseColor* will return the name of
the color in a form acceptable to *Tk_GetColor*.  If the user cancels the
operation, the command will return undef.

EXAMPLE
=======

     $widget->configure(-fg => $parent->chooseColor(-initialcolor => 'gray',
                     -title => "Choose color"));

KEYWORDS
========

   color selection dialog


File: pm.info,  Node: Tk/composite,  Next: Tk/configspec,  Prev: Tk/chooseColor,  Up: Module List

Defining a new composite widget class
*************************************

NAME
====

   Tk::composite - Defining a new composite widget class

     package Tk::Whatever;

     require Tk::Derived;
     require Tk::Frame;                    # or Tk::Toplevel
     @ISA = qw(Tk::Derived Tk::Frame)';    # or Tk::Toplevel

     Construct Tk::Widget 'Whatever';

     sub ClassInit
     {
      my ($class,$mw) = @_;

     #... e.g., class bindings here ...
     $class->SUPER::ClassInit($mw);
         }

     sub Populate
     {
      my ($cw,$args) = @_;

     my $flag = delete $args->{-flag};
     if (defined $flag)
      {
       # handle -flag => xxx which can only be done at create
       # time the delete above ensures that new() does not try
       # and do  $cw->configure(-flag => xxx);
      }

     $cw->SUPER::Populate($args);

     $w = $cw->Component(...);

     $cw->Delegates(...);

     $cw->ConfigSpecs(
     		'-cursor'    => [SELF,'cursor','Cursor',undef],
                '-something' => [METHOD,dbName,dbClass,'default'],
                '-text'      => [$label,dbName,dbClass,'default'],
                '-heading'   => [{-text=>$head},
                                 heading,Heading,'My Heading'],
                );
        }

     sub something
     {
      my ($cw,$value) = @_;
      if (@_ > 1)
       {
        # set it
       }
      return # current value
     }

     1;

     __END__

     # Anything not documented is *private* - your POD is god, so to speak.

     =head1 NAME

     Tk::Whatever - a whatever widget

     =head1 SYNOPSIS

     use Tk::Whatever;

     $widget = $parent->Whatever(...);

     =head1 DESCRIPTION

     You forgot to document your widget, didn't you? :-)

     ...

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

   The intention behind a composite is to create a higher-level widget,
sometimes called a "super-widget" or "meta-widget".  Most often, a
composite will be built upon other widgets by using them, as opposed to
specializing on them.  For example, the supplied composite widget
*LabEntry* is *made of* an Entry and a Label; it is neither a *kind-of*
Label nor is it a *kind-of* Entry.

   Most of the work of a composite widget consist in creating subwidgets,
arrange to dispatch configure options to the proper subwidgets and manage
composite-specific configure options.

GLORY DETAILS
=============

   Depending on your perl/Tk knowledget this section may be enlighting or
confusing.

Composite Widget
----------------

   Since perl/Tk is heavilly using an object-oriented approach, it is no
suprise that creating a composite goes through a new() method.  However,
the composite does not normally define a new() method itself: it is
usually sufficient to simply inherit it from *Tk::Widget*.

   This is what happens when the composite use

     @ISA = qw(Tk::Frame);  # or Tk::Toplevel

   to specify its inheritance chain.  To complete the initialisation of the
widget, it must call the Construct method from class *Widget*.  That
method accepts the name of the new class to create, i.e. the package name
of your composite widget:

     Construct Tk::Widget 'Whatever';

   Here, *Whatever* is the package name (aka the widget's class).  This
will define a constructor method for *Whatever*, normally named after the
widget's class.  Instanciating that composite in client code would the
look like:

     $mw = MainWindow->new();   # Creates a top-level main window

     $cw = $mw->Whatever();     # Creates an instance of the
                                # composite widget Whatever

   Whenever a composite is instanciated in client code,
`Tk::Widget::new()' will be invoked via the widget's class constructor.
That new method will call

     $cw->InitObject(\%args);

   where *%args* is the arguments passed to the widget's constructor.  Note
that InitObject receives a reference to the hash array containing all
arguments.

   For composite widgets that needs an underlying frame, InitObject will
typically be inherited from *Tk::Frame*, that is, no method of this name
will appear in the composite package.  For composites that don't need a
frame, InitObject will typically be defined in the composite class
(package).  Compare the *LabEntry* composite with *Optionmenu*: the former
is Frame based while the latter is *Widget* based.

   In Frame based composites, *Tk::Frame::InitObject()* will call
*Populate()*, which should be defined to create the characteristic
subwidgets of the class.

   *Widget* based composites don't need an extra Populate layer; they
typically have their own InitObject method that will create subwidgets.

Creating Subwidgets
-------------------

   Subwidget creation happens usually in *Populate()* (Frame based) or
*InitObject()* (*Widget* based).  The composite usually calls the
subwidget's constructor method either directly, for "private" subwidgets,
or indirectly through the Component method for subwidgets that should be
advertised to clients.

   Populate may call Delegates to direct calls to methods of chosen
subwidgets. For simple composites, typically most if not all methods are
directed to a single subwidget - e.g. *ScrListbox* directs all methods to
the core Listbox so that *$composite*->get(...) calls *$listbox*->get(...).

Further steps for Frame based composites
----------------------------------------

   Populate should also call *ConfigSpecs()* to specify the way that
configure-like options should be handled in the composite.  Once Populate
returns, method *Tk::Frame::ConfigDefault* walks through the ConfigSpecs
entries and populates %$args hash with defaults for options from X
resources (`.Xdefaults', etc).

   When  *InitObject()* returns to *Tk::Widget::new()*, a call to
*$cw*->configure(%$args) is made which sets *all* the options.

SEE ALSO
========

   `Tk::ConfigSpecs|Tk::ConfigSpecs' in this node
`Tk::Derived|Tk::Derived' in this node


File: pm.info,  Node: Tk/configspec,  Next: Tk/demos/widget_lib/WidgetDemo,  Prev: Tk/composite,  Up: Module List

Defining behaviour of 'configure' for composite widgets.
********************************************************

NAME
====

   Tk::ConfigSpecs - Defining behaviour of 'configure' for composite
widgets.

     sub Populate
     {
      my ($composite,$args) = @_;
      ...
      $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
      $composite->ConfigSpecs('-alias' => '-otherattribute');
      $composite->ConfigSpecs('DEFAULT' => [ where ]);
      ...
     }

     $composite->configure(-attribute => value);

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

   The aim is to make the composite widget configure method look as much
like a regular Tk widget's configure as possible.  (See *Note Tk/options:
Tk/options, for a description of this behaviour.)  To enable this the
attributes that the composite as a whole accepts needs to be defined.

Defining the ConfigSpecs for a class.
-------------------------------------

   Typically a widget will have one or more calls like the following

     $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);

   in its Populate method. When ConfigSpecs is called this way (with
arguments) the arguments are used to construct or augment/replace a hash
table for the widget. (More than one *-option*=>value pair can be
specified to a single call.)

   *dbName*, *dbClass* and default are only used by *ConfigDefault*
described below, or to respond to 'inquiry' configure commands.

   It may be either one of the values below, or a list of such values
enclosed in [].

   The currently permitted values of where are:

'ADVERTISED'
     apply configure to *advertised* subwidgets.

'DESCENDANTS'
     apply configure recursively to all descendants.

'CALLBACK'
     Setting the attribute does `Tk::Callback->new($value)' before storing
     in `$composite->{Configure}{-attribute}'. This is appropriate for
     `-command => ...' attributes that are handled by the composite and not
     forwarded to a subwidget. (E.g. *Tk::Tiler* has `-yscrollcommand' to
     allow it to have scrollbar attached.)

     This may be the first of several 'validating' keywords (e.g. font,
     cursor, anchor etc.) that core Tk makes special for C code.

'CHILDREN'
     apply configure to all children.  (Children are the immediate
     descendants of a widget.)

'METHOD'
     Call `$cw->attribute(value)'

     This is the most general case. Simply have a method of the composite
     class with the same name as the attribute.  The method may do any
     validation and have whatever side-effects you like.  (It is probably
     worth 'queueing' using *afterIdle* for more complex side-effects.)

'PASSIVE'
     Simply store value in `$composite->{Configure}{-attribute}'.

     This form is also a useful placeholder for attributes which you
     currently only handle at create time.

'SELF'
     Apply configure to the core widget (e.g. Frame) that is the basis of
     the composite. (This is the default behaviour for most attributes
     which makes a simple Frame behave the way you would expect.) Note
     that once you have specified ConfigSpecs for an attribute you must
     explicitly include 'SELF' in the list if you want the attribute to
     apply to the composite itself (this avoids nasty infinite recursion
     problems).

$reference (blessed)
     Call $reference->configure(-attribute => value)

     A common case is where $reference is a subwidget.

     $reference may also be result of

          Tk::Config->new(setmethod,getmethod,args,...);

     *Tk::Config* class is used to implement all the above keyword types.
     The class has configure and cget methods so allows higher level code
     to always just call one of those methods on an object of some kind.

*hash reference*
     Defining:

          $cw->ConfigSpecs(
          	...
          	-option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
          			dbname dbclass default ],
          	...
          	);

     So `$cw->configure(-option => value)' actually does

          $w1->configure(-optionX => value);
          $w2->configure(-optionY => value);
          $w3->configure(-optionY => value);

'otherstring'
     Call

          $composite->Subwidget('otherstring')->configure( -attribute => value );

     While this is here for backward compatibility with Tk-b5, it is
     probably better just to use the subwidget reference directly.  The
     only case for retaining this form is to allow an additional layer of
     abstraction - perhaps having a 'current' subwidget - this is unproven.

Aliases
     `ConfigSpecs( -alias => '-otherattribute' )' is used to make `-alias'
     equivalent to `-otherattribute'. For example the aliases

          -fg => '-foreground',
          -bg => '-background'

     are provided automatically (if not already specified).

Default Values
--------------

   When the Populate method returns *ConfigDefault* is called.  This calls

     $composite->ConfigSpecs;

   (with no arguments) to return a reference to a hash. Entries in the hash
take the form:

     '-attribute' => [ where, dbName, dbClass, default ]

   *ConfigDefault* ignores 'where' completely (and also the DEFAULT entry)
and checks the 'options' database on the widget's behalf, and if an entry
is present matching dbName/dbClass

     -attribute => value

   is added to the list of options that new will eventually apply to the
widget. Likewise if there is not a match and default is defined this
default value will be added.

   Alias entries in the hash are used to convert user-specified values for
the alias into values for the real attribute.

New()-time Configure
--------------------

   Once control returns to new, the list of user-supplied options
augmented by those from *ConfigDefault* are applied to the widget using the
configure method below.

   Widgets are most flexible and most Tk-like if they handle the majority
of their attributes this way.

Configuring composites
----------------------

   Once the above have occurred calls of the form:

     $composite->configure( -attribute => value );

   should behave like any other widget as far as end-user code is
concerned.  configure will be handled by *Tk::Derived::configure* as
follows:

     $composite->ConfigSpecs;

   is called (with no arguments) to return a reference to a hash
*-attribute* is looked up in this hash, if *-attribute* is not present in
the hash then *'DEFAULT'* is looked for instead.  (Aliases are tried as
well and cause redirection to the aliased attribute).  The result should
be a reference to a list like:

     [ where, dbName, dbClass, default ]

   at this stage only where is of interest, it maps to a list of object
references (maybe only one) foreach one

     $object->configure( -attribute => value );

   is evaled.

Inquiring attributes of composites
----------------------------------

     $composite->cget( '-attribute' );

   This is handled by  *Tk::Derived::cget* in a similar manner to
configure. At present if where is a list of more than one object it is
ignored completely and the "cached" value in

     $composite->{Configure}{-attribute}.

   is returned.

CAVEATS
=======

   It is the author's intention to port as many of the "Tix" composite
widgets as make sense. The mechanism described above may have to evolve in
order to make this possible, although now aliases are handled I think the
above is sufficient.

SEE ALSO
========

   `Tk::composite|Tk::composite' in this node, `Tk::options|Tk::options'
in this node


File: pm.info,  Node: Tk/demos/widget_lib/WidgetDemo,  Next: Tk/event,  Prev: Tk/configspec,  Up: Module List

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

NAME
====

   WidgetDemo() - create a standard widget demonstration window.

SYNOPSIS
========

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

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/],

METHODS
=======

$demo_widget->Top;
------------------

   Returns the frame container reference for the demonstration.  Treat
this as the top of your window hierarchy, a "main window".

AUTHOR
======

   Stephen O. Lidie <lusol@Lehigh.EDU>

HISTORY
=======

   lusol@Lehigh.EDU, LUCC, 97/02/11 lusol@Lehigh.EDU, LUCC, 97/06/07

COPYRIGHT
=========

   Copyright (C) 1997 - 1997 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/event,  Next: Tk/exit,  Prev: Tk/demos/widget_lib/WidgetDemo,  Up: Module List

Miscellaneous event facilities: define virtual events and generate events
*************************************************************************

NAME
====

   Tk::event - Miscellaneous event facilities: define virtual events and
generate events

   $widget->eventAction(?*arg, arg, ...*?);

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

   The eventAction methods provides several facilities for dealing with
window system events, such as defining virtual events and synthesizing
events.  Virtual events are shared by all widgets of the same
*MainWindow*.  Different `MainWindow|Tk::MainWindow' in this nodes can
have different virtual event.

   The following methods are currently supported:

$widget->*eventAdd*(*'<<**virtual**>>'**, sequence *?,*sequence, ...*?)
     Associates the virtual event *virtual* with the physical event
     sequence(s) given by the sequence arguments, so that the virtual
     event will trigger whenever any one of the sequences occurs.  Virtual
     may be any string value and sequence may have any of the values
     allowed for the sequence argument to the `bind|Tk::bind' in this node
     method.  If *virtual* is already defined, the new physical event
     sequences add to the existing sequences for the event.

$widget->*eventDelete*(*'<<**virtual**>>'* ?,*sequence,* *sequence, ...*?)
     Deletes each of the sequences from those associated with the virtual
     event given by *virtual*.  Virtual may be any string value and
     sequence may have any of the values allowed for the sequence argument
     to the `bind|Tk::bind' in this node method.  Any sequences not
     currently associated with *virtual* are ignored.  If no sequence
     argument is provided, all physical event sequences are removed for
     *virtual*, so that the virtual event will not trigger anymore.

$widget->*eventGenerate*(event ?,*option => value, option => value, ...*?)
     Generates a window event and arranges for it to be processed just as
     if it had come from the window system.  *$window* is a reference to
     the window for which the event will be generated.  Event provides a
     basic description of the event, such as *<Shift-Button-2>* or
     *<<Paste>>*.  If Window is empty the whole screen is meant, and
     coordinates are relative to the screen.  Event may have any of the
     forms allowed for the sequence argument of the `bind|Tk::bind' in
     this node method except that it must consist of a single event
     pattern, not a sequence.  *Option-value* pairs may be used to specify
     additional attributes of the event, such as the x and y mouse
     position; see `"EVENT FIELDS"' in this node below.  If the *-when*
     option is not specified, the event is processed immediately:  all of
     the handlers for the event will complete before the *eventGenerate*
     method returns.  If the *-when* option is specified then it
     determines when the event is processed.

$widget->*eventInfo*(?'*<<**virtual**>>'*?)
     Returns information about virtual events.  If the *<<**virtual**>>*
     argument is omitted, the return value is a list of all the virtual
     events that are currently defined.  If *<<**virtual**>>* is specified
     then the return value is a list whose elements are the physical event
     sequences currently defined for the given virtual event;  if the
     virtual event is not defined then undef is returned.

EVENT FIELDS
============

   The following options are supported for the *eventGenerate* method.
These correspond to the "%" expansions allowed in binding callback for the
`bind|Tk::bind' in this node method.

*-above* => window
     Window specifies the above field for the event, either as a window
     path name or as an integer window id.  Valid for Configure events.
     Corresponds to the `%a|Tk::bind' in this node substitution for
     binding scripts.

*-borderwidth* => size
     Size must be a screen distance;  it specifies the *border_width*
     field for the event.  Valid for Configure events.  Corresponds to the
     `%B|Tk::bind' in this node substitution for binding scripts.

*-button* => number
     Number must be an integer;  it specifies the detail field for a
     *ButtonPress* or ButtonRelease event, overriding any button  number
     provided in the base event argument.  Corresponds to the
     `%b|Tk::bind' in this node substitution for binding scripts.

*-count* => number
     Number must be an integer;  it specifies the count field for the
     event.  Valid for *Expose* events.  Corresponds to the `%c|Tk::bind'
     in this node substitution for binding scripts.

*-detail* => detail
     *Detail* specifies the detail field for the event and must be one of
     the following:

          NotifyAncestor	NotifyNonlinearVirtual
          NotifyDetailNone	NotifyPointer
          NotifyInferior	NotifyPointerRoot
          NotifyNonlinear	NotifyVirtual

     Valid for Enter, *Leave*, *FocusIn* and *FocusOut* events.
     Corresponds to the `%d|Tk::bind' in this node substitution for
     binding scripts.

*-focus** boolean*
     Boolean must be a boolean value;  it specifies the focus field for
     the event.  Valid for Enter and *Leave* events.  Corresponds to the
     `%f|Tk::bind' in this node substitution for binding scripts.

*-height** size*
     Size must be a screen distance;  it specifies the height field for
     the event.  Valid for Configure events.  Corresponds to the
     `%h|Tk::bind' in this node substitution for binding scripts.

*-keycode** number*
     Number  must be an integer;  it specifies the *keycode* field for the
     event.  Valid for *KeyPress* and *KeyRelease* events.  Corresponds to
     the `%k|Tk::bind' in this node substitution for binding scripts.

*-keysym** name*
     Name must be the name of a valid keysym, such as g, space, or Return;
     its corresponding keycode value is used as the *keycode* field for
     event, overriding any detail specified in the base event argument.
     Valid for *KeyPress* and *KeyRelease* events.  Corresponds to the
     `%K|Tk::bind' in this node substitution for binding scripts.

*-mode** notify*
     *Notify* specifies the mode field for the event and must be one of
     *NotifyNormal*, *NotifyGrab*, *NotifyUngrab*, or *NotifyWhileGrabbed*.
     Valid for Enter, *Leave*, *FocusIn*, and *FocusOut* events.
     Corresponds to the `%m|Tk::bind' in this node substitution for
     binding scripts.

*-override** boolean*
     Boolean must be a boolean value;  it specifies the
     *override_redirect* field for the event.  Valid for Map, *Reparent*,
     and Configure events.  Corresponds to the `%o|Tk::bind' in this node
     substitution for binding scripts.

*-place** where*
     Where specifies the *place* field for the event;  it must be either
     *PlaceOnTop* or *PlaceOnBottom*.  Valid for *Circulate* events.
     Corresponds to the `%p|Tk::bind' in this node substitution for
     binding scripts.

*-root** window*
     Window must be either a window path name or an integer window
     identifier;  it specifies the root field for the event.  Valid for
     *KeyPress*, *KeyRelease*, *ButtonPress*, ButtonRelease, Enter,
     *Leave*, and *Motion* events.  Corresponds to the `%R|Tk::bind' in
     this node substitution for binding scripts.

*-rootx** coord*
     *Coord* must be a screen distance;  it specifies the *x_root* field
     for the event.  Valid for *KeyPress*, *KeyRelease*, *ButtonPress*,
     ButtonRelease, Enter, *Leave*, and *Motion* events.  Corresponds to
     the `%X|Tk::bind' in this node substitution for binding scripts.

*-rooty** coord*
     *Coord* must be a screen distance;  it specifies the *y_root* field
     for the event.  Valid for *KeyPress*, *KeyRelease*, *ButtonPress*,
     ButtonRelease, Enter, *Leave*, and *Motion* events.  Corresponds to
     the `%Y|Tk::bind' in this node substitution for binding scripts.

*-sendevent** boolean*
     Boolean must be a boolean value;  it specifies the *send_event* field
     for the event.  Valid for all events.  Corresponds to the
     `%E|Tk::bind' in this node substitution for binding scripts.

*-serial** number*
     Number must be an integer;  it specifies the serial field for the
     event.  Valid for all events.  Corresponds to the `%#|Tk::bind' in
     this node substitution for binding scripts.

*-state** state*
     State specifies the state field for the event.  For *KeyPress*,
     *KeyRelease*, *ButtonPress*, ButtonRelease, Enter, *Leave*, and
     *Motion* events it must be an integer value.  For *Visibility* events
     it must be one of *VisibilityUnobscured*,
     *VisibilityPartiallyObscured*, or *VisibilityFullyObscured*.  This
     option overrides any modifiers such as Meta or Control specified in
     the base event.  Corresponds to the `%s|Tk::bind' in this node
     substitution for binding scripts.

*-subwindow** window*
     Window specifies the *subwindow* field for the event, either as a
     path name for a Tk widget or as an integer window identifier.  Valid
     for *KeyPress*, *KeyRelease*, *ButtonPress*, ButtonRelease, Enter,
     *Leave*, and *Motion* events.  Similar to `%S|Tk::bind' in this node
     substitution for binding scripts.

*-time** integer*
     Integer must be an integer value;  it specifies the time field for
     the event.  Valid for *KeyPress*, *KeyRelease*, *ButtonPress*,
     ButtonRelease, Enter, *Leave*, *Motion*, and Property events.
     Corresponds to the `%t|Tk::bind' in this node substitution for
     binding scripts.

*-warp** boolean*
     boolean must be a boolean value;  it specifies whether the screen
     pointer should be warped as well.  Valid for *KeyPress*,
     *KeyRelease*, *ButtonPress*, ButtonRelease, and *Motion* events.

*-width** size*
     Size must be a screen distance;  it specifies the width field for the
     event.  Valid for Configure events.  Corresponds to the `%w|Tk::bind'
     in this node substitution for binding scripts.

*-when** when*
     When determines when the event will be processed;  it must have one
     of the following values:

    now
          Process the event immediately, before the command returns.  This
          also happens if the *-when* option is omitted.

    tail
          Place the event on perl/Tk's event queue behind any events
          already queued for this application.

    head
          Place the event at the front of perl/Tk's event queue, so that it
          will be handled before any other events already queued.

    mark
          Place the event at the front of perl/Tk's event queue but behind
          any other events already queued with *-when mark*.  This option
          is useful when generating a series of events that should be
          processed in order but at the front of the queue.

-x* coord*
     *Coord* must be a screen distance;  it specifies the x field for the
     event.  Valid for *KeyPress*, *KeyRelease*, *ButtonPress*,
     ButtonRelease, *Motion*, Enter, *Leave*, *Expose*, Configure,
     *Gravity*, and *Reparent* events.  Corresponds to the the
     `%x|Tk::bind' in this node substitution for binding scripts.  If
     Window is empty the coordinate is relative to the screen, and this
     option corresponds to the `%X|Tk::bind' in this node substitution for
     binding scripts.

-y* coord*
     *Coord* must be a screen distance;  it specifies the y field for the
     event.  Valid for *KeyPress*, *KeyRelease*, *ButtonPress*,
     ButtonRelease, *Motion*, Enter, *Leave*, *Expose*, Configure,
     *Gravity*, and *Reparent* events.  Corresponds to the the
     `%y|Tk::bind' in this node substitution for binding scripts.  If
     Window is empty the coordinate is relative to the screen, and this
     option corresponds to the `%Y|Tk::bind' in this node substitution for
     binding scripts.

     Any options that are not specified when generating an event are filled
     with the value 0, except for serial, which is filled with the next X
     event serial number.

VIRTUAL EVENT EXAMPLES
======================

   In order for a virtual event binding to trigger, two things must
happen.  First, the virtual event must be defined with the *eventAdd*
method.  Second, a binding must be created for the virtual event with the
bind method.  Consider the following virtual event definitions:

     $widget->eventAdd('<<Paste>>' => '<Control-y>');
     $widget->eventAdd('<<Paste>>' => '<Button-2>');
     $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>');
     $widget->eventAdd('<<Save>>' => '<Shift-F12>');

   In the bind method, a virtual event can be bound like any other builtin
event type as follows:

     $entry->bind('Tk::Entry', '<<Paste>>' => sub {
     		$entry->Insert($entry->selectionGet) });

   The double angle brackets are used to specify that a virtual event is
being bound.  If the user types Control-y or presses button 2, or if a
*<<Paste>>* virtual event is synthesized with *eventGenerate*, then the
*<<Paste>>* binding will be invoked.

   If a virtual binding has the exact same sequence as a separate physical
binding, then the physical binding will take precedence.  Consider the
following example:

     $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>');
     $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'});
     $mw->bind('Tk::Entry', '<<Paste>>'   => sub{print 'Paste'});

   When the user types Control-y the *<Control-y>* binding will be
invoked, because a physical event is considered more specific than a
virtual event, all other things being equal.  However, when the user types
Meta-Control-y the *<<Paste>>* binding will be invoked, because the Meta
modifier in the physical pattern associated with the virtual binding is
more specific than the *<Control-y*> sequence for the physical event.

   Bindings on a virtual event may be created before the virtual event
exists.  Indeed, the virtual event never actually needs to be defined, for
instance, on platforms where the specific virtual event would meaningless
or ungeneratable.

   When a definition of a virtual event changes at run time, all windows
will respond immediately to the new definition.  Starting from the
preceding example, if the following code is executed:

     $entry->bind(ref($entry), '<Control-y>' => undef);
     $entry->eventAdd('<<Paste>>' => '<Key-F6>');

   the behavior will change such in two ways.  First, the shadowed
*<<Paste>>* binding will emerge.  Typing Control-y will no longer invoke
the *<Control-y>* binding, but instead invoke the virtual event
*<<Paste>>*.  Second, pressing the F6 key will now also invoke the
*<<Paste>>* binding.

SEE ALSO
========

   `Tk::bind|Tk::bind' in this node `Tk::callbacks|Tk::callbacks' in this
node

KEYWORDS
========

   event, binding, define, handle, virtual event


File: pm.info,  Node: Tk/exit,  Next: Tk/fileevent,  Prev: Tk/event,  Up: Module List

End the application
*******************

NAME
====

   Tk::exit - End the application

     use Tk qw(exit);
     ...
     B<exit>?(I<returnCode>)?;

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

   Terminate the process, returning *returnCode* to the system as the exit
status.  If *returnCode* isn't specified then it defaults to 0.

   If calling exit from code invoked via a Tk callback then this Tk
version of exit cleans up more reliably than using the perl exit.

KEYWORDS
========

   exit, process


File: pm.info,  Node: Tk/fileevent,  Next: Tk/focus,  Prev: Tk/exit,  Up: Module List

Execute a callback when a filehandle becomes readable or writable
*****************************************************************

NAME
====

   Tk::fileevent - Execute a callback when a filehandle becomes readable
or writable

   $widget->*fileevent*(*fileHandle*,readable?,callback?)

   $widget->*fileevent*(*fileHandle*,writable?,callback?)

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

   This command is used to create *file event handlers*.  A file event
handler is a binding between a filehandle and a callback, such that the
callback is evaluated whenever the filehandle becomes readable or
writable.  File event handlers are most commonly used to allow data to be
received from another process on an event-driven basis, so that the
receiver can continue to interact with the user while waiting for the data
to arrive.  If an application invokes `<>', sysread or read on a blocking
filehandle when there is no input data available, the process will block;
until the input data arrives, it will not be able to service other events,
so it will appear to the user to "freeze up".  With *fileevent*, the
process can tell when data is present and only invoke gets or read when
they won't block.

   The *fileHandle* argument to *fileevent* refers to an open filehandle,
such as the return value from a previous open or socket command.  If the
callback argument is specified, then *fileevent* creates a new event
handler:  callback will be evaluated whenever the filehandle becomes
readable or writable (depending on the argument to *fileevent*).  In this
case *fileevent* returns an empty string.  The readable and writable event
handlers for a file are independent, and may be created and deleted
separately.  However, there may be at most one readable and one writable
handler for a file at a given time in a given interpreter.  If *fileevent*
is called when the specified handler already exists in the invoking
interpreter, the new callback replaces the old one.

   If the callback argument is not specified, *fileevent* returns the
current callback for *fileHandle*, or an empty string if there is none.
If the callback argument is specified as an empty string then the event
handler is deleted, so that no callback will be invoked.  A file event
handler is also deleted automatically whenever its filehandle is closed or
its interpreter is deleted.

   A filehandle is considered to be readable if there is unread data
available on the underlying device.  A filehandle is also considered to be
readable if an end of file or error condition is present on the underlying
file or device.  It is important for callback to check for these conditions
and handle them appropriately;  for example, if there is no special check
for end of file, an infinite loop may occur where callback reads no data,
returns, and is immediately invoked again.

   A filehandle is considered to be writable if at least one byte of data
can be written to the underlying file or device without blocking, or if an
error condition is present on the underlying file or device.

   Event-driven I/O works best for filehandles that have been placed into
nonblocking mode.  In blocking mode, a print command may block if you give
it more data than the underlying file or device can accept, and a `<>',
sysread or read command will block if you attempt to read more data than
is ready;  no events will be processed while the commands block.  In
nonblocking mode print, `<>', sysread and read never block.  See the
documentation for the individual commands for information on how they
handle blocking and nonblocking filehandles.

   The callback for a file event is executed in the context of $widget
with which *fileevent* was invoked.  If an error occurs while executing
the callback then the *Note Tk/Error: Tk/Error, mechanism is used to
report the error.  In addition, the file event handler is deleted if it
ever returns an error;  this is done in order to prevent infinite loops
due to buggy handlers.

BUGS
====

   On windows platforms *fileevent* is limited in the types of filehandles
that behave correctly. Making filefhandles non-blocking is only implemented
on a subset of UNIX platforms (see *Note Tk/IO: Tk/IO,).

CREDITS
=======

   *fileevent* is based on the *addinput* command created by Mark Diekhans.

SEE ALSO
========

   `Tk::IO|Tk::IO' in this node `Tk::callbacks|Tk::callbacks' in this node

KEYWORDS
========

   asynchronous I/O, blocking, filehandle, event handler, nonblocking,
readable, callback, writable.


File: pm.info,  Node: Tk/focus,  Next: Tk/form,  Prev: Tk/fileevent,  Up: Module List

Manage the input focus
**********************

NAME
====

   focus - Manage the input focus

      $widget->focus

      $widget->focusOption

      $widget->*focusNext*

      $widget->*focusPrev*

      $widget->*focusFollowsMouse*

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

   The focus methods are used to manage the Tk input focus.  At any given
time, one window on each display is designated as the *focus window*;  any
key press or key release events for the display are sent to that window.
It is normally up to the window manager to redirect the focus among the
top-level windows of a display.  For example, some window managers
automatically set the input focus to a top-level window whenever the mouse
enters it;  others redirect the input focus only when the user clicks on a
window.  Usually the window manager will set the focus only to top-level
windows, leaving it up to the application to redirect the focus among the
children of the top-level.

   Tk remembers one focus window for each top-level (the most recent
descendant of that top-level to receive the focus);  when the window
manager gives the focus to a top-level, Tk automatically redirects it to
the remembered window.  Within a top-level Tk uses an explicit focus model
by default.  Moving the mouse within a top-level does not normally change
the focus;  the focus changes only when a widget decides explicitly to
claim the focus (e.g., because of a button click), or when the user types
a key such as Tab that moves the focus.

   The method *focusFollowsMouse* may be invoked to create an *implicit*
focus model:  it reconfigures Tk so that the focus is set to a window
whenever the mouse enters it.  The methods *focusNext* and *focusPrev*
implement a focus order among the windows of a top-level;  they are used
in the default bindings for Tab and Shift-Tab, among other things.

   The focus methods can take any of the following forms:

$widget->*focusCurrent*
     Returns the focus window on the display containing the $widget,  or
     an empty string if no window in this application has the focus on
     that display.

$widget->focus
     If the application currently has the input focus on $widget's
     display, this command resets the input focus for $widget's display to
     $widget and returns an empty string.  If the application doesn't
     currently have the  input focus on $widget's display, $widget will be
     remembered as the focus for its top-level;  the next time the focus
     arrives at the top-level, Tk will redirect it to $widget.

$widget->*focusForce*
     Sets the focus of $widget's display to $widget, even if the
     application doesn't currently have the input focus for the display.
     This command should be used sparingly, if at all.  In normal usage,
     an application should not claim the focus for itself;  instead, it
     should wait for the window manager to give it the focus.

$widget->*focusLast*
     Returns the name of the most recent window to have the input focus
     among all the windows in the same top-level as $widget.  If no window
     in that top-level has ever had the input focus, or if the most recent
     focus window has been deleted, then the top-level is returned.  The
     return value is the window that will receive the input focus the next
     time the window manager gives the focus to the top-level.

$widget->*focusNext*
$widget->*focusPrev*
     *focusNext* is a utility method used for keyboard traversal, but can
     be useful in other contexts.  It sets the focus to the "next" window
     after $widget in focus order.  The focus order is determined by the
     stacking order of windows and the structure of the window hierarchy.
     Among siblings, the focus order is the same as the stacking order,
     with the lowest window being first.  If a window has children, the
     window is visited first, followed by its children (recursively),
     followed by its next sibling.  Top-level windows other than $widget
     are skipped, so that *focusNext* never returns a window in a
     different top-level from $widget.

     After computing the next window, *focusNext* examines the window's
     *-takefocus* option to see whether it should be skipped.  If so,
     *focusNext* continues on to the next window in the focus order, until
     it eventually finds a window that will accept the focus or returns
     back to $widget.

     *focusPrev* is similar to *focusNext* except that it sets the focus
     to the window just before $widget in the focus order.

$widget->*focusFollowsMouse*
     *focusFollowsMouse* changes the focus model for the application to an
     implicit one where the window under the mouse gets the focus.  After
     this procedure is called, whenever the mouse enters a window Tk will
     automatically give it the input focus.  The focus command may be used
     to move the focus to a window other than the one under the mouse, but
     as soon as the mouse moves into a new window the focus will jump to
     that window.  Note: at present there is no built-in support for
     returning the application to an explicit focus model;  to do this
     you'll have to write a script that deletes the bindings created by
     *focusFollowsMouse*.

QUIRKS
======

   When an internal window receives the input focus, Tk doesn't actually
set the X focus to that window;  as far as X is concerned, the focus will
stay on the top-level window containing the window with the focus.
However, Tk generates FocusIn and FocusOut events just as if the X focus
were on the internal window.   This approach gets around a number of
problems that would occur if the X focus were actually moved; the fact
that the X focus is on the top-level is invisible unless you use C code to
query the X server directly.

CAVEATS
=======

   Note that for the Canvas widget, the call to focus has to be fully
qualified. This is because there is already a focus method for the Canvas
widget, which sets the focus on individual canvas tags.

       *$canvas*->*Tk::focus*

KEYWORDS
========

   events, focus, keyboard, top-level, window manager