/usr/lib/perl5/Tk/Error.pod is in perl-tk 1:804.029-1.1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | # Copyright (c) 1990-1994 The Regents of the University of California.
# Copyright (c) 1994-1996 Sun Microsystems, Inc.
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#
=head1 NAME
Tk::Error - Method invoked to process background errors
=for category Binding Events and Callbacks
=head1 SYNOPSIS
Customization:
require Tk::ErrorDialog;
or
sub Tk::Error
{
my ($widget,$error,@locations) = @_;
...
}
=head1 DESCRIPTION
The B<Tk::Error> method is invoked by perl/Tk when a background
error occurs. Two possible implementations are provided in the
distribution and individual applications or users can (re)define a B<Tk::Error>
method (e.g. as a perl sub) if they wish to handle background
errors in some other manner.
A background error is one that occurs in a command that didn't
originate with the application. For example, if an error occurs
while executing a L<callback|Tk::callbacks> specified with a
L<bind|Tk::bind> or a L<after|Tk::after>
command, then it is a background error. For a non-background error,
the error can simply be returned up through nested subroutines
until it reaches the top-level code in the application;
then the application can report the error in whatever way it
wishes. When a background error occurs, the unwinding ends in
the Tk library and there is no obvious way for Tk to report
the error.
When Tk detects a background error, it saves information about the
error and invokes the B<Tk::Error> method later when Tk is idle.
B<Tk::Error> is invoked by perl/Tk as if by the perl code:
S< >I<$mainwindow>-E<gt>B<Tk::Error>(I<"error message">, I<location ...>);
I<$mainwindow> is the B<MainWindow> associated with widget which
detected the error, I<"error message"> is a string describing the error
that has been detected, I<location> is a list of one or more "locations"
which describe the call sequence at the point the error was detected.
The locations are a typically a mixture of perl location reports giving
script name and line number, and simple strings describing locations in
core Tk or perl/Tk C code.
Tk will ignore any result returned by the B<Tk::Error> method.
If another error occurs within the B<Tk::Error> method
(for example if it calls B<die>) then Tk reports this error
itself by writing a message to stderr (this is to avoid infinite loops
due to any bugs in B<Tk::Error>).
If several background errors accumulate before B<Tk::Error>
is invoked to process them, B<Tk::Error> will be invoked once
for each error, in the order they occurred.
However, if B<Tk::Error> calls B<Tk-E<gt>break>, then
any remaining errors are skipped without calling B<Tk::Error>.
The B<Tk> module includes a default B<Tk::Error> subroutine
that simply reports the error on stderr.
=head1 Tk::ErrorDialog
An alternate definition is provided via:
S< >C<require Tk::ErrorDialog;>
that posts a dialog box containing the error message and offers
the user a chance to see a stack trace showing where the
error occurred.
This is an OO implementation of the Tcl/Tk command B<bgerror>, with a
twist: since there is only one B<ErrorDialog> widget, you aren't required
to invoke the constructor to create it; it will be created
automatically when the first background error occurs. However, in
order to configure the I<-cleanupcode> and I<-appendtraceback>
B<ErrorDialog> options you must call the constructor and create it
manually.
The B<ErrorDialog> object essentially consists of two subwidgets: a
B<Dialog> widget to display the background error and a B<Text> widget
for the traceback information. If required, you can invoke various
widget methods to customize these subwidgets - their advertised names
are described below.
S< >I<$mw>-E<gt>B<ErrorDialog>(-cleanupcode => I<code>, -appendtraceback => I<bool>);
$mw is a window reference.
I<code> is a CODE reference if special post-background error
processing is required (default is undefined). The callback subroutine
is called with @_ having the same arguments that B<Tk::Error> was
invoked with.
I<bool> is a boolean indicating whether or not to append successive
tracebacks (default is 1, do append).
=head2 Advertised ErrorDialog widgets
I<error_dialog> is the Dialog widget reference.
I<text> is the Text widget reference containing the traceback information.
=head1 BUGS
If B<after> or B<fileevent> are not invoked as methods of a widget
then perl/Tk is unable to provide a I<$mainwindow> argument.
To support such code from earlier versions of perl/Tk
perl/Tk therefore calls B<Tk::Error> with string 'Tk' instead:
B<Tk-E<gt>Tk::Error\(...\)>.
In this case the B<Tk::Error> in B<Tk::ErrorDialog> and similar
implementations cannot "popup" a window as they don't know which display
to use. A mechanism to supply I<the> B<MainWindow> in applications
which only have one (a very common case) should be provided.
=head1 SEE ALSO
L<Tk::bind|Tk::bind>
L<Tk::after|Tk::after>
L<Tk::fileevent|Tk::fileevent>
=head1 KEYWORDS
background error, reporting
=cut
|