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 '%' substitution (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);