1Error(3)              User Contributed Perl Documentation             Error(3)
2
3
4

NAME

6       Tk::Error - Method invoked to process background errors
7

SYNOPSIS

9       Customization:
10
11           require Tk::ErrorDialog;
12
13       or
14
15           sub Tk::Error
16           {
17             my ($widget,$error,@locations) = @_;
18             ...
19
20           }
21

DESCRIPTION

23       The Tk::Error method is invoked by perl/Tk when a background error
24       occurs. Two possible implementations are provided in the distribution
25       and individual applications or users can (re)define a Tk::Error method
26       (e.g. as a perl sub) if they wish to handle background errors in some
27       other manner.
28
29       A background error is one that occurs in a command that didn't origi‐
30       nate with the application.  For example, if an error occurs while exe‐
31       cuting a callback specified with a bind or a after command, then it is
32       a background error.  For a non-background error, the error can simply
33       be returned up through nested subroutines until it reaches the top-
34       level code in the application; then the application can report the
35       error in whatever way it wishes.  When a background error occurs, the
36       unwinding ends in the Tk library and there is no obvious way for Tk to
37       report the error.
38
39       When Tk detects a background error, it saves information about the
40       error and invokes the Tk::Error method later when Tk is idle.
41
42       Tk::Error is invoked by perl/Tk as if by the perl code:
43
44        $mainwindow->Tk::Error("error message", location ...);
45
46       $mainwindow is the MainWindow associated with widget which detected the
47       error, "error message" is a string describing the error that has been
48       detected, location is a list of one or more "locations" which describe
49       the call sequence at the point the error was detected.
50
51       The locations are a typically a mixture of perl location reports giving
52       script name and line number, and simple strings describing locations in
53       core Tk or perl/Tk C code.
54
55       Tk will ignore any result returned by the Tk::Error method.  If another
56       error occurs within the Tk::Error method (for example if it calls die)
57       then Tk reports this error itself by writing a message to stderr (this
58       is to avoid infinite loops due to any bugs in Tk::Error).
59
60       If several background errors accumulate before Tk::Error is invoked to
61       process them, Tk::Error will be invoked once for each error, in the
62       order they occurred.  However, if Tk::Error calls Tk->break, then any
63       remaining errors are skipped without calling Tk::Error.
64
65       The Tk module includes a default Tk::Error subroutine that simply
66       reports the error on stderr.
67

Tk::ErrorDialog

69       An alternate definition is provided via:
70
71        "require Tk::ErrorDialog;"
72
73       that posts a dialog box containing the error message and offers the
74       user a chance to see a stack trace showing where the error occurred.
75
76       This is an OO implementation of the Tcl/Tk command bgerror, with a
77       twist: since there is only one ErrorDialog widget, you aren't required
78       to invoke the constructor to create it; it will be created automati‐
79       cally when the first background error occurs.  However, in order to
80       configure the -cleanupcode and -appendtraceback ErrorDialog options you
81       must call the constructor and create it manually.
82
83       The ErrorDialog object essentially consists of two subwidgets: a Dialog
84       widget to display the background error and a Text widget for the trace‐
85       back information.  If required, you can invoke various widget methods
86       to customize these subwidgets - their advertised names are described
87       below.
88
89        $mw->ErrorDialog(-cleanupcode => code, -appendtraceback => bool);
90
91       $mw is a window reference.
92
93       code is a CODE reference if special post-background error processing is
94       required (default is undefined). The callback subroutine is called with
95       @_ having the same arguments that Tk::Error was invoked with.
96
97       bool is a boolean indicating whether or not to append successive trace‐
98       backs (default is 1, do append).
99
100       Advertised ErrorDialog widgets
101
102       error_dialog is the Dialog widget reference.
103
104       text is the Text widget reference containing the traceback information.
105

BUGS

107       If after or fileevent are not invoked as methods of a widget then
108       perl/Tk is unable to provide a $mainwindow argument.  To support such
109       code from earlier versions of perl/Tk perl/Tk therefore calls Tk::Error
110       with string 'Tk' instead: Tk->Tk::Error\(...\).  In this case the
111       Tk::Error in Tk::ErrorDialog and similar implementations cannot "popup"
112       a window as they don't know which display to use.  A mechanism to sup‐
113       ply the MainWindow in applications which only have one (a very common
114       case) should be provided.
115

SEE ALSO

117       Tk::bind Tk::after Tk::fileevent
118

KEYWORDS

120       background error, reporting
121
122
123
124perl v5.8.8                       2008-02-05                          Error(3)