Cory Johns > Win32GUICarp > Win32::GUI::Carp

Download:
Win32GUICarp-1.01.tar.gz

Dependencies

Annotate this POD

Related Modules

Win32::GUI
X11::Protocol
Tk::Carp
X11::Lib
Win32::GuiTest
Win32::API
Win32::Process
more...
By perlmonks.org
View/Report Bugs
Module Version: 1.01   Source  

NAME ^

Win32::GUI::Carp - Redirect warnings and errors to Win32::GUI MessageBoxes

SYNOPSIS ^

    use Win32::GUI::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 Win32::GUI::Carp qw/warningsToDialog/;
    warn "Warnings will be displayed in a pop-up dialog.";

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

    use Win32::GUI::Carp qw/winwarn windie/;
    winwarn "Warning in dialog.";
    windie  "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 Win32::GUI. 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 $Win32::GUI::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 $Win32::GUI::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 $Win32::GUI::Carp::ImmediateWarnings to true or false, respectively.

FUNCTIONS ^

winwarn

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

windie

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

syscarp

Executes a system command, just like system, but passes its its STDERR through any warn filters. In other words, if the command displays anything on STDERR, it will show up as a warning in the calling program, and thus display in a dialog (respecting warningsToDialog).

Note: The name of this function is subject to change, as I think it is somewhat misleading.

syscroak

Does the same thing as "syscarp" but dies if anything is sent to STDERR. It includes a message with the return value of the process.

Note: The name of this function is subject to change, as I think it is somewhat misleading.

CONFIGURATION ^

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

$Win32::GUI::Carp::DialogTitle

A string that will be used as the title of the dialog box. This defaults to "Warning" when displaying warnings, and "Error" when displaying fatal errors.

$Win32::GUI::Carp::FatalFilter

Set this to a reference to a subroutine that should be called whenever a fatal error is about to be shown in a dialog. The routine receives the error message in @_, and if it returns a true value the error will be sent to the dialog as normal, otherwise the dialog will not be shown (though the error still propagates as normal).

$Win32::GUI::Carp::WarningFilter

Set this to a reference to a subroutine that should be called whenever a warning is about to be shown in a dialog. The routine receives the warning message in @_, and if it returns a true value the warning will be sent to the dialog as normal, otherwise the dialog will not be shown (though the warning still propagates as normal).

DEPENDANCIES ^

This module relies on the following other modules to be installed:

Win32::GUI
Carp
IPC::Open3 (for "syscarp" and "syscroak")

BUGS ^

AUTHOR ^

Copyright 2002, Cory Johns.

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: Cory Johns <johnsca@cpan.org>

SEE ALSO ^

Carp, CGI::Carp, Win32::GUI

syntax highlighting: