NAME

Tk::Carp - Redirect warnings and errors to Tk Dialogs

SYNOPSIS

    use Tk::Carp qw/cluck/;

    croak "Ribbit!";
    confess "It was me: $!";
    carp "How could you do that?";
    warn "Duck!";
    die "There's no hope...";
    cluck "Don't do it.";

    use Tk::Carp qw/warningsToDialog/;
    warn "Warnings will be displayed in a pop-up dialog.";

    use Tk::Carp qw/fatalsToDialog/;
    die "Fatal error messages will be displayed in a pop-up dialog.";

    use Tk::Carp qw/tkwarn tkdie/;
    tkwarn "Warning in dialog.";
    tkdie  "Death in dialog.";

DESCRIPTION

When Perl programs are run in a GUI environment, it is often desirable to have them run with no console attached. Unfortunately, this causes any warnings or errors to be lost. Worse, fatal errors can cause your program to silently disappear, forcing you to restart the program, attached to a console, and hope you can reproduce the error.

This module makes it easy to see any errors or warnings your console-less program might produce by catching any errors and/or warnings and displaying them in a pop-up dialog box using Tk. It is similar in spirit to CGI::Carp's fatalsToBrowser and warningsToBrowser special import directives.

To cause errors or warnings to be displayed in a dialog, simply specify one or more of the following options on the use line, as shown in the SYNOPSIS.

IMPORT OPTIONS

warningsToDialog

Show any warnings in a pop-up dialog box.

This option will cause a dialog box to be displayed containing the text of the warnings. The type and style of the dialog box can be configured (see "CONFIGURATION"). Note that warnings are still sent to STDERR as well.

This option can also be activated or deactivated by setting $Tk::Carp::WarningsToDialog to true or false, respectively.

fatalsToDialog

Show any fatal errors in a pop-up dialog box.

This option will cause a dialog box to be displayed containing the text of the fatal error. The type and style of the dialog box can be configured (see "CONFIGURATION"). Note that errors are still sent to STDERR as well.

This option can also be activated or deactivated by setting $Tk::Carp::FatalsToDialog to true or false, respectively.

immediateWarnings

This option controls whether all errors and warnings are displayed in a single dialog box or each get their own.

By default, warnings are buffered and not shown until just before the program terminates. At that point, any warnings and errors are shown together in a single dialog box. This is to cut down on the number of dialogs that have to be clicked through, although it means that you can't tell when a particular warning occurred.

If this option is specified, each warning and error message will get its own dialog box which will be displayed as soon as the warning or error occurs. Note that warnings are always printed to STDERR as soon as they occur, regardless of the state of this option.

Care should be taken when setting this option as it can cause a large number of dialog boxes to be created.

This option can also be activated or deactivated by setting $Tk::Carp::ImmediateWarnings to true or false, respectively.

useTkDialog

This option controls whether the dialog is displayed using MainWindow->messageBox() or $Tk::Carp::ShowTkDialog->().

By default, the dialog that is displayed when errors or warnings are raised is done using MainWindow->messageBox(). Under Win32, this type of dialog seems to be implemented more natively than Tk::Dialog, and so has better support of focus-taking and icons. Unfortunately, this type of dialog must be recreated, along with a parenting MainWindow.

If this option is specified, the dialog box will instead be displayed using $Tk::Carp::ShowTkDialog->() which, by default, displays a Tk::Dialog object. Unlike messageBox(), the Tk::Dialog object is only created the first time it is used. This is more efficient when used with the immediateWarnings option. You can also manipulate or set the Tk::Dialog object used directly, gaining better control over the display. You can even use a completely different type of object instead (see "$Tk::Carp::Dialog" and "$Tk::Carp::ShowTkDialog").

This option can also be activated or deactivated by setting $Tk::Carp::UseTkDialog to true or false, respectively.

tkDeathsNonFatal

This option causes errors generated in Tk callbacks to be treated as warnings.

The default Tk::Error handler converts fatal errors in callbacks to warnings. Unless this option is specified, this module defines a custom Tk::Error handler to allow them to be treated as fatal errors (ie, use the icon and title associated with fatal errors, and displayed immediately, regardless of the state of $Tk::Carp::ImmediateWarnings).

FUNCTIONS

tkwarn

Raises a warning, using a dialog. This function ignores the state of warningsToDialog, although all other options are observed.

tkdie

Raises a fatal error, using a dialog. This function ignores the state of fatalsToDialog, although all other options are observed.

CONFIGURATION

The following variables control the style and type of dialog box used.

$Tk::Carp::DieIcon

Changes the icon displayed in the dialog box for fatal errors. Valid values are any that could be used as the -icon parameter to messageBox(), or as the -bitmap parameter to the Tk::Dialog->configure() method.

The most common values are: 'error', 'info', 'question' and 'warning'. The default value is 'error'.

$Tk::Carp::DieTitle

A string that will be used as the title of the dialog box for fatal errors.

$Tk::Carp::WarnIcon

Changes the icon displayed in the dialog box for warnings. Valid values are the same as for $Tk::Carp::DieIcon.

The default value is 'warning'.

$Tk::Carp::WarnTitle

A string that will be used as the title of the dialog box for warnings.

$Tk::Carp::MainWindow

The Tk::MainWindow object used to create the dialog box. If not defined, one will be created as needed. If your program has a Tk MainWindow, you should set this variable to it.

Note: If you create a MainWindow and enter MainLoop without setting this variable to your MainWindow, and a warning or error is raised with useTkDialog enabled, you MUST call $Tk::Carp::MainWindow->destroy() when your MainWindow is closed, or your application will not exit. It will remain open but without any visible windows. Really, it's just better to make sure you set this variable to your MainWindow if you use useTkDialog.

$Tk::Carp::Dialog

The Tk::Dialog object used if "$Tk::Carp::UseMessageBox" is not true. If not defined, one will be created as needed.

You can use this variable to change the configuration, such as the font or justification, of the object. You can also set this variable to a totally different type of object (such as a Tk::DialogBox, or Tk::Toplevel), though you must also set the $Tk::Carp::ShowTkDialog variable, lest you get "Bad option" errors (or worse).

$Tk::Carp::ShowTkDialog

A pointer to a subroutine that is called to display the dialog box if $Tk::Carp::UseMessageBox is false. This subroutine should accept a list of strings to be displayed in the dialog box. It should probably also use the $Tk::Carp::DialogIcon, $Tk::Carp::DialogTitle, and $Tk::Carp::MainWindow variables.

When used in conjunction with $Tk::Carp::Dialog, changing this variable allows you to use a different type of object as the dialog. For example, you could use a Tk::DialogBox to be able to place other widgets in the dialog box, or a Tk::Toplevel to gain complete control over the appearance of the dialog.

The default subroutine (&Tk::Carp::ShowTkDialog()) creates (if necessary) a Tk::Dialog object in $Tk::Carp::Dialog and calls its configure() and Show() methods.

BUGS

This module installs a signal handler for both __DIE__ and __WARN__. While it does save any previous handlers and chain them properly, any new handler that is installed will effectively disable the fatalsToDialog and warningsToDialog options, respectively. Tk seems to do this during some of its object initializations. This can occasionally cause errors or warnings generated inside Tk widget code to be lost. (Note: this was probably fixed by the use of a Tk::Error sub, but see the next bug.)

The introduction of a Tk::Error sub means that if code that uses this module defines its own Tk::Error sub it will generate a "Subroutine redefined at..." warning. Worse, if the sub is defined before this module is used, this module's Tk::Error sub will not only generate a redefinition warning, but will overwrite the user's sub. If you want to use a custom Tk::Error sub and still want errors to be sent to a dialog, you can use the following (somewhat convoluted) code: use Tk::Carp; BEGIN { $OldTkError = \&Tk::Error; no warnings 'redefine'; # only works in >= 5.6.0 *Tk::Error = sub { $OldTkError->(@_); # Call Tk::Carp's handler so dialog is shown # your code here } }

By default, carp(), croak() and confess() are exported from Carp. If nothing is specified in the import list (including the special *ToDialog, immediateWarnings, and useTkDialog options), then Tk::Carp also exports those functions. As soon as anything is given in the import list, however, Exporter stops exporting the things in @EXPORT, meaning the aforementioned functions.

AUTHORS

Copyright 2001, Cory Johns. All rights reserved.

This module is free software; you can redistribute and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: johnsca@cpan.org

SEE ALSO

Carp, CGI::Carp, Tk, Tk::Dialog

cpanm Tk::Carp

perl -MCPAN -e shell
install Tk::Carp