doc/tkerror.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH tkerror n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 tkerror \- Command invoked to process background errors
  15 .SH SYNOPSIS
  16 \fBtkerror \fImessage\fR
  17 .BE
  18
  19 .SH DESCRIPTION
  20 .PP
  21 The \fBtkerror\fR command doesn't exist as built-in part of Ck.  Instead,
  22 individual applications or users can define a \fBtkerror\fR
  23 command (e.g. as a Tcl procedure) if they wish to handle background
  24 errors.
  25 .PP
  26 A background error is one that occurs in a command that didn't
  27 originate with the application.  For example, if an error occurs
  28 while executing a command specified with a \fBbind\fR or \fBafter\fR
  29 command, then it is a background error.  For a non-background error,
  30 the error can simply be returned up through nested Tcl command
  31 evaluations until it reaches the top-level code in the application;
  32 then the application can report the error in whatever way it
  33 wishes.  When a background error occurs, the unwinding ends in
  34 the Ck library and there is no obvious way for Ck to report
  35 the error.
  36 .PP
  37 When Ck detects a background error, it saves information about the
  38 error and invokes the \fBtkerror\fR command later when Ck is idle.
  39 Before invoking \fBtkerror\fR, Ck restores the \fBerrorInfo\fR
  40 and \fBerrorCode\fR variables to their values at the time the
  41 error occurred, then it invokes \fBtkerror\fR with
  42 the error message as its only argument.
  43 Ck assumes that the application has implemented the \fBtkerror\fR
  44 command, and that the command will report the error in a way that
  45 makes sense for the application.  Ck will ignore any result returned
  46 by the \fBtkerror\fR command.
  47 .PP
  48 If another Tcl error occurs within the \fBtkerror\fR command
  49 (for example, because no \fBtkerror\fR command has been defined)
  50 then Ck reports the error itself by writing a message to stderr.
  51 .PP
  52 If several background errors accumulate before \fBtkerror\fR
  53 is invoked to process them, \fBtkerror\fR will be invoked once
  54 for each error, in the order they occurred.
  55 However, if \fBtkerror\fR returns with a break exception, then
  56 any remaining errors are skipped without calling \fBtkerror\fR.
  57 .PP
  58 The Ck script library includes a default \fBtkerror\fR procedure
  59 that posts a dialog box containing the error message and offers
  60 the user a chance to see a stack trace showing where the
  61 error occurred.
  62
  63 .SH KEYWORDS
  64 background error, reporting