/ 
tk-zinc-3.298
River stage zero No dependents
/ Tk::Zinc::Trace

NAME

Tk::Zinc::Trace - A module to trace all Tk::Zinc method calls

SYNOPSIS

use Tk::Zinc::Trace; $Tk::Zinc::Trace:ForReplay = 1;

or

perl -MTk::Zinc::Trace YourZincBasedScript.pl [--code]

DESCRIPTION

When loaded, this module overloads a Tk mechanism so that every Tk::Zinc method call will be traced. Every call will also be followed by a $zinc->update() so that the method call will be effectively treated.

This module can be very effective for debugging when Tk::Zinc core dumps and you have no clue which method call can be responsible for. If you just want to trace Tk::Zinc errors when calling a method you should rather use the Tk::Zinc::TraceErrors module

The global variable $Tk::Zinc::Trace:off can be used to trace some specific blocks. If set to 1, traces are deactivated, if set to 0, traces are reactivated.

If the global variable $Tk::Zinc::Trace:ForReplay is set or if the --code option is set in the second form, the printout will be very close to re-executable code, like this:

 ## following trace should be very close to a replay-script code
 $zinc->configure(-relief => 'sunken', -borderwidth => 3,
		  -width => 700, -font => 10x20, -height => 600);
 $zinc->add('rectangle', 1, [10, 10, 100, 50],
	    -fillcolor => 'green', -filled => 1, -linewidth => 10,
	    -relief => 'roundridge', -linecolor => 'darkgreen');
 $zinc->add('text', 1, -font => -adobe-helvetica-bold-r-normal-*-120-*-*-*-*-*-* =>
	    -text => 'A filled rectangle with a "roundridge" relief border of 10 pixels.',
	    -anchor => 'nw', -position => [120, 20]);
 $zinc->add('track', 1, 6,
	    -labelformat => 'x82x60+0+0 x60a0^0^0 x32a0^0>1 a0a0>2>1 x32a0>3>1 a0a0^0>2',
	    -position => [20, 120], -speedvector => [40, -10], -speedvectormark => 1, -speedvectorticks => 1);
 $zinc->coords(4, [20, 120]);

If not (the default), the printout will be more informtative, giving the following information:

  • the source filename where the method has been invoked

  • the line number in the source file

  • the TkZinc method name

  • the list of arguments in a human-readable form

  • the returned value

The trace will look like:

## Tk::Zinc::Trace ON
TRACE: /usr/lib/perl5/Tk/Widget.pm line 196 configure(-relief => 'sunken', -borderwidth => 3, -width => 700, -font => 10x20, -height => 600)  RETURNS undef
TRACE: Perl/demos/demos/zinc_lib/items.pl line 21 add('rectangle', 1, [10, 10, 100, 50], -fillcolor => 'green', -filled => 1, -linewidth => 10, -relief => 'roundridge', -linecolor => 'darkgreen')  RETURNS 2
TRACE: Perl/demos/demos/zinc_lib/items.pl line 25 add('text', 1, -font => -adobe-helvetica-bold-r-normal-*-120-*-*-*-*-*-* => -text => 'A filled rectangle with a "roundridge" relief border of 10 pixels.', -anchor => 'nw', -position => [120, 20])  RETURNS 3
TRACE: Perl/demos/demos/zinc_lib/items.pl line 36 add('track', 1, 6, -labelformat => 'x82x60+0+0 x60a0^0^0 x32a0^0>1 a0a0>2>1 x32a0>3>1 a0a0^0>2', -position => [20, 120], -speedvector => [40, -10], -speedvectormark => 1, -speedvectorticks => 1)  RETURNS 4

AUTHOR

C.Mertz <mertz@cena.fr> and D.Etienne <etienne@cena.fr>

CAVEATS and BUGS

This module cannot be used when Tk::Zinc::TraceErrors is already in use.

As every Tk::Zinc method call is followed by an ->update call, this may dramatically slowdown an application. The trade-off is between application run-time and developper debug-time.

When using an output "code-like" they are still part of the output which is not executable code. However, the ouptut could be easily and manually edited to be executable perl code.

COPYRIGHT

See Tk::Zinc copyright; LGPL

SEE ALSO

Tk::Zinc(3pm), Tk::Zinc::TraceErrors(3pm). Tk::Zinc::Debug(3pm).