.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH ERROR 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
Tk::Error \- Method invoked to process background errors
\& require Tk::ErrorDialog;
\& my ($widget,$error,@locations) = @_;
The \fBTk::Error\fR 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 \fBTk::Error\fR
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 callback specified with a
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
When Tk detects a background error, it saves information about the
error and invokes the \fBTk::Error\fR method later when Tk is idle.
\&\fBTk::Error\fR is invoked by perl/Tk as if by the perl code:
\&\ \fI$mainwindow\fR\->\fBTk::Error\fR(\fI\*(L"error message\*(R"\fR, \fIlocation ...\fR);
\&\fI$mainwindow\fR is the \fBMainWindow\fR associated with widget which
detected the error, \fI\*(L"error message\*(R"\fR is a string describing the error
that has been detected, \fIlocation\fR is a list of one or more \*(L"locations\*(R"
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 \fBTk::Error\fR method.
If another error occurs within the \fBTk::Error\fR method
(for example if it calls \fBdie\fR) then Tk reports this error
itself by writing a message to stderr (this is to avoid infinite loops
due to any bugs in \fBTk::Error\fR).
If several background errors accumulate before \fBTk::Error\fR
is invoked to process them, \fBTk::Error\fR will be invoked once
for each error, in the order they occurred.
However, if \fBTk::Error\fR calls \fBTk\->break\fR, then
any remaining errors are skipped without calling \fBTk::Error\fR.
The \fBTk\fR module includes a default \fBTk::Error\fR subroutine
that simply reports the error on stderr.
An alternate definition is provided via :
\&\ \f(CW\*(C`require Tk::ErrorDialog;\*(C'\fR
that posts a dialog box containing the error message and offers
the user a chance to see a stack trace showing where the
If \fBafter\fR or \fBfileevent\fR are not invoked as methods of a widget
then perl/Tk is unable to provide a \fI$mainwindow\fR argument.
To support such code from earlier versions of perl/Tk
perl/Tk therefore calls \fBTk::Error\fR with string 'Tk' instead:
\&\fBTk\->Tk::Error\e(...\e)\fR.
In this case the \fBTk::Error\fR in \fBTk::ErrorDialog\fR and similar
implementations cannot \*(L"popup\*(R" a window as they don't know which display
to use. A mechanism to supply \fIthe\fR \fBMainWindow\fR in applications
which only have one (a very common case) should be provided.
background error, reporting