home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _001f16e4a2006b985c43312110a5ecae next >
Encoding:
Text File  |  2004-06-01  |  5.1 KB  |  146 lines
  1. #  Copyright (c) 1990-1994 The Regents of the University of California.
  2. #  Copyright (c) 1994-1996 Sun Microsystems, Inc.
  3. #  See the file "license.terms" for information on usage and redistribution
  4. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  5. #
  6. #
  7.  
  8. =head1 NAME
  9.  
  10. Tk::Error - Method invoked to process background errors
  11.  
  12. =for category Binding Events and Callbacks
  13.  
  14. =head1 SYNOPSIS
  15.  
  16. Customization:
  17.  
  18.     require Tk::ErrorDialog;
  19.  
  20. or
  21.  
  22.     sub Tk::Error
  23.     {
  24.       my ($widget,$error,@locations) = @_;
  25.       ...
  26.  
  27.     }
  28.  
  29. =head1 DESCRIPTION
  30.  
  31. The B<Tk::Error> method is invoked by perl/Tk when a background
  32. error occurs. Two possible implementations are provided in the
  33. distribution and individual applications or users can (re)define a B<Tk::Error>
  34. method (e.g. as a perl sub) if they wish to handle background
  35. errors in some other manner.
  36.  
  37. A background error is one that occurs in a command that didn't
  38. originate with the application.  For example, if an error occurs
  39. while executing a L<callback|Tk::callbacks> specified with a
  40. L<bind|Tk::bind> or a L<after|Tk::after>
  41. command, then it is a background error.  For a non-background error,
  42. the error can simply be returned up through nested subroutines
  43. until it reaches the top-level code in the application;
  44. then the application can report the error in whatever way it
  45. wishes.  When a background error occurs, the unwinding ends in
  46. the Tk library and there is no obvious way for Tk to report
  47. the error.
  48.  
  49. When Tk detects a background error, it saves information about the
  50. error and invokes the B<Tk::Error> method later when Tk is idle.
  51.  
  52. B<Tk::Error> is invoked by perl/Tk as if by the perl code:
  53.  
  54. S<    >I<$mainwindow>-E<gt>B<Tk::Error>(I<"error message">, I<location ...>);
  55.  
  56. I<$mainwindow> is the B<MainWindow> associated with widget which
  57. detected the error, I<"error message"> is a string describing the error
  58. that has been detected, I<location> is a list of one or more "locations"
  59. which describe the call sequence at the point the error was detected.
  60.  
  61. The locations are a typically a mixture of perl location reports giving
  62. script name and line number, and simple strings describing locations in
  63. core Tk or perl/Tk C code.
  64.  
  65. Tk will ignore any result returned by the B<Tk::Error> method.
  66. If another error occurs within the B<Tk::Error> method
  67. (for example if it calls B<die>) then Tk reports this error
  68. itself by writing a message to stderr (this is to avoid infinite loops
  69. due to any bugs in B<Tk::Error>).
  70.  
  71. If several background errors accumulate before B<Tk::Error>
  72. is invoked to process them, B<Tk::Error> will be invoked once
  73. for each error, in the order they occurred.
  74. However, if B<Tk::Error> calls B<Tk-E<gt>break>, then
  75. any remaining errors are skipped without calling B<Tk::Error>.
  76.  
  77. The B<Tk> module includes a default B<Tk::Error> subroutine
  78. that simply reports the error on stderr.
  79.  
  80. =head1 Tk::ErrorDialog
  81.  
  82. An alternate definition is provided via:
  83.  
  84. S<    >C<require Tk::ErrorDialog;>
  85.  
  86. that posts a dialog box containing the error message and offers
  87. the user a chance to see a stack trace showing where the
  88. error occurred.
  89.  
  90. This is an OO implementation of the Tcl/Tk command B<bgerror>, with a
  91. twist: since there is only one B<ErrorDialog> widget, you aren't required
  92. to invoke the constructor to create it; it will be created
  93. automatically when the first background error occurs.  However, in
  94. order to configure the I<-cleanupcode> and I<-appendtraceback>
  95. B<ErrorDialog> options you must call the constructor and create it
  96. manually.
  97.  
  98. The B<ErrorDialog> object essentially consists of two subwidgets: a
  99. B<Dialog> widget to display the background error and a B<Text> widget
  100. for the traceback information.  If required, you can invoke various
  101. widget methods to customize these subwidgets - their advertised names
  102. are described below.
  103.  
  104. S<    >I<$mw>-E<gt>B<ErrorDialog>(-cleanupcode => I<code>, -appendtraceback => I<bool>);
  105.  
  106. $mw is a window reference.
  107.  
  108. I<code> is a CODE reference if special post-background error
  109. processing is required (default is undefined). The callback subroutine
  110. is called with @_ having the same arguments that B<Tk::Error> was
  111. invoked with.
  112.  
  113. I<bool> is a boolean indicating whether or not to append successive
  114. tracebacks (default is 1, do append).
  115.  
  116. =head2 Advertised ErrorDialog widgets
  117.  
  118. I<error_dialog> is the Dialog widget reference.
  119.  
  120. I<text> is the Text widget reference containing the traceback information.
  121.  
  122. =head1 BUGS
  123.  
  124. If B<after> or B<fileevent> are not invoked as methods of a widget
  125. then perl/Tk is unable to provide a I<$mainwindow> argument.
  126. To support such code from earlier versions of perl/Tk
  127. perl/Tk therefore calls B<Tk::Error> with string 'Tk' instead:
  128. B<Tk-E<gt>Tk::Error\(...\)>.
  129. In this case the B<Tk::Error> in B<Tk::ErrorDialog> and similar
  130. implementations cannot "popup" a window as they don't know which display
  131. to use.  A mechanism to supply I<the> B<MainWindow> in applications
  132. which only have one (a very common case) should be provided.
  133.  
  134. =head1 SEE ALSO
  135.  
  136. L<Tk::bind|Tk::bind>
  137. L<Tk::after|Tk::after>
  138. L<Tk::fileevent|Tk::fileevent>
  139.  
  140. =head1 KEYWORDS
  141.  
  142. background error, reporting
  143.  
  144. =cut
  145.  
  146.