diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 12:20:49 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 12:20:49 +0000 |
commit | 316ee97c621496b0fe3267f57cce81bee44ca1e6 (patch) | |
tree | cb2cab1192b4f58a7971af19b213e980bceda4b4 /Master/tlpkg/tlperl0/lib/Tk/Error.pod | |
parent | cd0f87b5d39480d85ad9bd4ee37f520f75bed560 (diff) |
Moving old tlperl prior to committing new one
git-svn-id: svn://tug.org/texlive/trunk@21422 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Tk/Error.pod')
-rwxr-xr-x | Master/tlpkg/tlperl0/lib/Tk/Error.pod | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Tk/Error.pod b/Master/tlpkg/tlperl0/lib/Tk/Error.pod new file mode 100755 index 00000000000..9c38f0b7d74 --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/Tk/Error.pod @@ -0,0 +1,145 @@ +# Copyright (c) 1990-1994 The Regents of the University of California. +# Copyright (c) 1994-1996 Sun Microsystems, Inc. +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# + +=head1 NAME + +Tk::Error - Method invoked to process background errors + +=for category Binding Events and Callbacks + +=head1 SYNOPSIS + +Customization: + + require Tk::ErrorDialog; + +or + + sub Tk::Error + { + my ($widget,$error,@locations) = @_; + ... + + } + +=head1 DESCRIPTION + +The B<Tk::Error> 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 B<Tk::Error> +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 L<callback|Tk::callbacks> specified with a +L<bind|Tk::bind> or a L<after|Tk::after> +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 +the error. + +When Tk detects a background error, it saves information about the +error and invokes the B<Tk::Error> method later when Tk is idle. + +B<Tk::Error> is invoked by perl/Tk as if by the perl code: + +S< >I<$mainwindow>-E<gt>B<Tk::Error>(I<"error message">, I<location ...>); + +I<$mainwindow> is the B<MainWindow> associated with widget which +detected the error, I<"error message"> is a string describing the error +that has been detected, I<location> is a list of one or more "locations" +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 B<Tk::Error> method. +If another error occurs within the B<Tk::Error> method +(for example if it calls B<die>) then Tk reports this error +itself by writing a message to stderr (this is to avoid infinite loops +due to any bugs in B<Tk::Error>). + +If several background errors accumulate before B<Tk::Error> +is invoked to process them, B<Tk::Error> will be invoked once +for each error, in the order they occurred. +However, if B<Tk::Error> calls B<Tk-E<gt>break>, then +any remaining errors are skipped without calling B<Tk::Error>. + +The B<Tk> module includes a default B<Tk::Error> subroutine +that simply reports the error on stderr. + +=head1 Tk::ErrorDialog + +An alternate definition is provided via: + +S< >C<require Tk::ErrorDialog;> + +that posts a dialog box containing the error message and offers +the user a chance to see a stack trace showing where the +error occurred. + +This is an OO implementation of the Tcl/Tk command B<bgerror>, with a +twist: since there is only one B<ErrorDialog> widget, you aren't required +to invoke the constructor to create it; it will be created +automatically when the first background error occurs. However, in +order to configure the I<-cleanupcode> and I<-appendtraceback> +B<ErrorDialog> options you must call the constructor and create it +manually. + +The B<ErrorDialog> object essentially consists of two subwidgets: a +B<Dialog> widget to display the background error and a B<Text> widget +for the traceback information. If required, you can invoke various +widget methods to customize these subwidgets - their advertised names +are described below. + +S< >I<$mw>-E<gt>B<ErrorDialog>(-cleanupcode => I<code>, -appendtraceback => I<bool>); + +$mw is a window reference. + +I<code> is a CODE reference if special post-background error +processing is required (default is undefined). The callback subroutine +is called with @_ having the same arguments that B<Tk::Error> was +invoked with. + +I<bool> is a boolean indicating whether or not to append successive +tracebacks (default is 1, do append). + +=head2 Advertised ErrorDialog widgets + +I<error_dialog> is the Dialog widget reference. + +I<text> is the Text widget reference containing the traceback information. + +=head1 BUGS + +If B<after> or B<fileevent> are not invoked as methods of a widget +then perl/Tk is unable to provide a I<$mainwindow> argument. +To support such code from earlier versions of perl/Tk +perl/Tk therefore calls B<Tk::Error> with string 'Tk' instead: +B<Tk-E<gt>Tk::Error\(...\)>. +In this case the B<Tk::Error> in B<Tk::ErrorDialog> and similar +implementations cannot "popup" a window as they don't know which display +to use. A mechanism to supply I<the> B<MainWindow> in applications +which only have one (a very common case) should be provided. + +=head1 SEE ALSO + +L<Tk::bind|Tk::bind> +L<Tk::after|Tk::after> +L<Tk::fileevent|Tk::fileevent> + +=head1 KEYWORDS + +background error, reporting + +=cut + |