#  Copyright (c) 1992-1994 The Regents of the University of California.
#  Copyright (c) 1994 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#  @(#) BackgdErr.3 1.6 95/05/06 15:29:07
#

=head1 NAME

Tk_BackgroundError - report Tcl error that occurred in background processing

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

B<Tk_BackgroundError>(I<interp>)

=head1 ARGUMENTS

=over 4

=item Tcl_Interp *interp (in)

Interpreter in which the error occurred.

=back

=head1 DESCRIPTION

This procedure is typically invoked when a Tcl error occurs during
``background processing'' such as executing a Tcl command in response
to a button press or menu entry invocation.
When such an error occurs, the error condition is reported to Tk
or to a widget or some other C code, and there is not usually any
obvious way for that code to report the error to the user.
In these cases the code calls B<Tk_BackgroundError> with an
I<interp> argument identifying the interpreter in which the
error occurred.
B<Tk_BackgroundError> attempts to invoke the B<tkerror>
Tcl command to report the error in an application-specific fashion.
If no B<tkerror> command exists, or if it returns with an error condition,
then B<Tk_BackgroundError> reports the error itself by printing
a message on the standard error file.

B<Tk_BackgroundError> does not invoke B<tkerror> immediately
(in some cases this could interfere with scripts that are in process
at the time the error occurred).
Instead, it invokes B<tkerror> later as an idle callback.
B<Tk_BackgroundError> saves the values of the B<errorInfo> and
B<errorCode> variables and restores these values just before
invoking B<tkerror>.

It is possible for many background errors to accumulate before
B<tkerror> is invoked.  When this happens, each of the errors
is processed in order.  However, if B<tkerror> returns a
break exception, then all remaining error reports for the
interpreter are skipped.

=head1 KEYWORDS

background, error, tkerror