diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Error.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Error.pod | 145 |
1 files changed, 0 insertions, 145 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Error.pod b/Master/tlpkg/tlperl/lib/Tk/Error.pod deleted file mode 100644 index 9c38f0b7d74..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Error.pod +++ /dev/null @@ -1,145 +0,0 @@ -# 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 - |