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
30       originate with the application.  For example, if an error occurs while
31       executing a callback specified with a bind or a after command, then it
32       is a background error.  For a non-background error, the error can
33       simply be returned up through nested subroutines until it reaches the
34       top-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
79       automatically when the first background error occurs.  However, in
80       order to configure the -cleanupcode and -appendtraceback ErrorDialog
81       options you 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
85       traceback information.  If required, you can invoke various widget
86       methods to customize these subwidgets - their advertised names are
87       described 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
98       tracebacks (default is 1, do append).
99
100   Advertised ErrorDialog widgets
101       error_dialog is the Dialog widget reference.
102
103       text is the Text widget reference containing the traceback information.
104

BUGS

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

SEE ALSO

116       Tk::bind Tk::after Tk::fileevent
117

KEYWORDS

119       background error, reporting
120
121
122
123perl v5.28.0                      2018-07-15                          Error(3)
Impressum