NAME

Tcl::pTk::Callback - Callback Helper class for Tcl::pTk

SYNOPSIS

        # Create Callback - No Arg Subref form
        $cb = Tcl::pTk::Callback->new(\&lots);
        
        # Create Callback - Subref form, with args
        $cb = Tcl::pTk::Callback->new([\&lots, $arg1, $arg2]);
        
        # Create Callback - Object->Method form, with args
        $cb = Tcl::pTk::Callback->new([ $obj, 'method', $arg1, $arg2]);
        
        # Execute/call the callback, with extra args
        $cb->Call($extraArg1, $extraArg2);

DESCRIPTION

Tcl::pTk::Callback is a helper class, modeled after Tk::Callback (documented in Tk::callbacks ), that provides methods for constructing and executing callbacks for the Tcl::pTk package.

ATTRIBUTES

callback

Array ref of components of the callback. This will be of the form:

 # Subref form
 [ $subref, @args ];  # @args are optional
 
 # Object-Method form
 [ $object, $methodname, @args]; # @args are optional
 
 # methodName form (used for bind callbacks, where the event source widget is used in the call,
 #   $widget->methodName(...)
 ['methodName', @args];  @args are optional
 

form

Text indicating what form the callback is in (as defined above). This will be subref or object-method.

EvMapping

Hash ref showing mapping of any Tcl::pTk::Ev objects in the args to their position in the stored callback.

For example, if the callback is supplied as:

  [ $subref, 'arg1', Ev('x'), Ev('y'), 'arg4']; 
  

The EvMapping will be:

 {
    x => 2,
    y => 3
 }
 

noWidgetArg

Flag = 1 to NOT include the widget/event-source as the first arg passed to a binding

This is most always equal to 0, because bindings always include the source widget as the first arg. However, some widgets that provide their own '%' subsitution (like tktable a.k.a. TableMatrix) do not pass the widget as the first arg.

METHODS

new

Constructor: Creates a new Tcl::pTk::Callback instance.

Any args supplied with be fed to the callback when it is executed by the Call method, before any args that are supplied to Call.

Usage:

        # Create Callback - No Arg Subref form
        $cb = Tcl::pTk::Callback->new(\&lots);
        
        # Create Callback - Subref form, with args
        $cb = Tcl::pTk::Callback->new( [\&lots, $arg1, $arg2] );
        
        # Create Callback - Object->Method form, with args
        $cb = Tcl::pTk::Callback->new([ $obj, 'method', $arg1, $arg2]);
        
        Note: The noWidgetArg attribute may be supplied as the second arg in any of the 
          above forms.

Call

Calls/executes a callback, with optional extra args.

Any args supplied to Call will be fed to the callback after any args that were supplied to new.

Usage:

        # Execute/call a callback, with optional extra args
        $cb->Call($extraArg1, $extraArg2);

BindCall

Special Call method for a callback supplied to a bind function. BindCall expects to get the event source (e.g. a button, window, frame, etc that the event occured in) as the first arg of the method. The callback will then be executed with the event source as the first arg (if a subref callback type), or as the object (if a object->method callback type).

The following table shows some examples of how a callback is executed for several different forms of callback supplied to a bind method.

   Callback supplied to bind    Resultant Call
   -------------------------    --------------------------------
   [$subref, arg1, arg2]        $subref->($eventSource, arg1, arg2)
   ['methodname', arg1,arg2]    $eventSource->methodName($arg1, $arg2)
   'methodname'                 $eventSource->methodName()
    $subref                     $subref->($eventSource)
   [$widget, 'methodname',arg1] $widget->methodName($arg1)

Usage:

        # Execute/call a callback, with optional extra args
        $cb->BindCall($eventSource, $extraArg1, $extraArg2);
        

_updateEvArgs

Internal method to update the Ev args of the callback (as defined in the EvMapping attribute) with updated values. This is typically used to populate the Ev args with the actual event information substitutions after a bind event occurs.

Usage:

        $cb->_updateEvArgs(@evArgValues);

createTclBindRef

Method to create a callback array-reference suitable for feeding to the Tcl::call method that will properly execute this Tcl::pTk::Callback when the bind event occurs. Handles any Event pattern substitution thru Tcl.pm's Tcl::Ev() mechanism.

Usage:

        # Create bind ref from the callback object and the widget the 
        #  binding is created from.
        my $bindRef = $callback->createTclBindRef($creatingWidget);
        
        
        # Bind ref created now feed to Tcl::Call (thru the interp)
        $interp->all("bind",$tag, $sequence, $bindRef);
        

cpanm Tcl::pTk

perl -MCPAN -e shell
install Tcl::pTk