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
145
|
# 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
|
