2 '\" Copyright (c
) 1990-1994 The Regents of the University of California
.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of
this file
, and for a DISCLAIMER OF ALL WARRANTIES
.
8 '\" RCS
: @
(#) $Id: bgerror.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
10 '\" The definitions below are
for supplemental macros used
in Tcl
/Tk
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure
.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or
"in/out" to describe whether procedure reads or modifies arg
,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
21 '\" Give maximum sizes of arguments
for setting tab stops
. Type
and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to
.AP later
. If args are omitted
, default tab stops are used
.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed
in one large box
.
30 '\" End of box enclosure.
33 '\" Begin code excerpt
.
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar
, for use
in marking newly
-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version
when the
.VS was added
, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present
, then a line break is forced before starting the sidebar
.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display
.
52 '\" End of indented unfilled display.
55 '\" Start of
list of standard options
for a Tk widget
. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option
. cmdName gives the
64 '\" option's name
as specified
in the
class command
, dbName gives
65 '\" the option's name
in the option database
, and dbClass gives
66 '\" the option's
class in the option database
.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: bgerror.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2
"" .TP
\\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1
'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2
'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l
'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\
(ul
'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box
if the box started on an earlier page
.
131 \h
'-1.5n'\L
'|\\n(^yu-1v'\l
'\\n(^lu+3n\(ul'\L
'\\n(^tu+1v-\\n(^yu'\l
'|0u-1.5n\(ul'
134 \h
'-1.5n'\L
'|\\n(^yu-1v'\h
'\\n(^lu+3n'\L
'\\n(^tu+1v-\\n(^yu'\l
'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter
)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS
"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH bgerror n 7.5 Tcl "Tcl Built
-In Commands
"
248 '\" Note: do not modify the .SH NAME line immediately below!
250 bgerror \- Command invoked to process background errors
252 \fBbgerror \fImessage\fR
257 The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead,
258 individual applications or users can define a \fBbgerror\fR
259 command (e.g. as a Tcl procedure) if they wish to handle background
262 A background error is one that occurs in an event handler or some
263 other command that didn't originate with the application.
264 For example, if an error occurs while executing a command specified
265 with the \fBafter\fR command, then it is a background error.
266 For a non-background error, the error can simply be returned up
267 through nested Tcl command evaluations until it reaches the top-level
268 code in the application; then the application can report the error
269 in whatever way it wishes. When a background error occurs, the
270 unwinding ends in the Tcl library and there is no obvious way for Tcl
273 When Tcl detects a background error, it saves information about the
274 error and invokes the \fBbgerror\fR command later as an idle event
275 handler. Before invoking \fBbgerror\fR, Tcl restores the
276 \fBerrorInfo\fR and \fBerrorCode\fR variables to their values at the
277 time the error occurred, then it invokes \fBbgerror\fR with the error
278 message as its only argument. Tcl assumes that the application has
279 implemented the \fBbgerror\fR command, and that the command will
280 report the error in a way that makes sense for the application. Tcl
281 will ignore any result returned by the \fBbgerror\fR command as long
282 as no error is generated.
284 If another Tcl error occurs within the \fBbgerror\fR command (for
285 example, because no \fBbgerror\fR command has been defined) then Tcl
286 reports the error itself by writing a message to stderr.
288 If several background errors accumulate before \fBbgerror\fR is
289 invoked to process them, \fBbgerror\fR will be invoked once for each
290 error, in the order they occurred. However, if \fBbgerror\fR returns
291 with a break exception, then any remaining errors are skipped without
292 calling \fBbgerror\fR.
294 Tcl has no default implementation for \fBbgerror\fR. However, in
295 applications using Tk there is a default \fBbgerror\fR procedure which
296 posts a dialog box containing the error message and offers the user a
297 chance to see a stack trace showing where the error occurred. In
298 addition to allowing the user to view the stack trace, the dialog
299 provides an additional application configurable button which may be
300 used, for example, to save the stack trace to a file. By default,
301 this is the behavior associated with that button. This behavior can
302 be redefined by setting the option database values
303 \fB*ErrorDialog.function.text\fR, to specify the caption for the
304 function button, and \fB*ErrorDialog.function.command\fR, to specify
305 the command to be run. The text of the stack trace is appended to the
306 command when it is evaluated. If either of these options is set to
307 the empty string, then the additional button will not be displayed in
314 background error, reporting