NAME

Gtk2::Ex::ErrorTextDialog::Handler -- exception handlers using ErrorTextDialog

SYNOPSIS

 use Gtk2::Ex::ErrorTextDialog::Handler;
 Glib->install_exception_handler
   (\&Gtk2::Ex::ErrorTextDialog::Handler::exception_handler);

 $SIG{'__WARN__'}
   = \&Gtk2::Ex::ErrorTextDialog::Handler::exception_handler;

 Glib::Log->set_handler ('My-Domain', ['warning','info'],
   \&Gtk2::Ex::ErrorTextDialog::Handler::log_handler);

DESCRIPTION

This module supplies error and warning handler functions which print to STDERR and display in an ErrorTextDialog. The handlers are reasonably small and the idea is to keep memory use down by not loading the full ErrorTextDialog until needed. If your program works then the dialog won't be needed at all!

See examples/simple.pl in the Gtk2-Ex-ErrorTextDialog sources for a complete program with this sort of error handler.

FUNCTIONS

Gtk2::Ex::ErrorTextDialog::Handler::exception_handler ($str)

A function suitable for use with Glib->install_exception_handler (see "EXCEPTIONS" in Glib) or with Perl's $SIG{'__WARN__'} (see "%SIG" in perlvar).

    Glib->install_exception_handler
      (\&Gtk2::Ex::ErrorTextDialog::Handler::exception_handler);

    $SIG{'__WARN__'}
      = \&Gtk2::Ex::ErrorTextDialog::Handler::exception_handler;

The given $str is printed to STDERR and displayed in the shared ErrorTextDialog instance. $str can be an exception object too such as a Glib::Error and will be stringized for display.

Gtk2::Ex::ErrorTextDialog::Handler::log_handler ($log_domain, $log_levels, $message)

A function suitable for use with Glib::Log->set_handler (see Glib::Log). It forms a message similar to the Glib default handler and prints and displays per the exception_handler function above.

    Glib::Log->set_handler ('My-Domain', ['warning','info'],
      \&Gtk2::Ex::ErrorTextDialog::Handler::log_handler);

As of Glib-Perl 1.200, various standard log domains are trapped already and turned into Perl warn calls (see "GLog" in Glib::xsapi on gperl_handle_logs_for). So if you trap $SIG{'__WARN__'} then you already get Glib and Gtk logs without any explicit Glib::Log handlers.

DETAILS

When an error occurs an existing ErrorTextDialog is raised so the error is seen but it's not "presented", so it doesn't steal keyboard focus (unless the window manager is focus-follows-mouse style). This also means if the dialog is iconified it's not re-opened for a new message, just the icon is raised (by the window manager). Iconifying is a good way to hide errors if there's a big cascade. But maybe this will change in the future.

The default action on closing the error dialog is to hide it, and past messages are kept. In an application it can be good to have a menu entry etc which pops up the dialog with

    Gtk2::Ex::ErrorTextDialog->instance->present;

or similar, so the user can see past errors again after closing the dialog.

Wide Chars

If a message is a byte string then it's assumed to be in the locale charset. If STDERR takes wide chars (because it has a PerlIO encoding layer) then the message is converted for the print. The dialog always displays wide chars (add_message does a conversion if necessary).

If a message is a wide char string but STDERR only takes raw bytes, then currently they're just printed as normal and will generally provoke a "wide char in print" warning. Perhaps this will change in the future.

As of Perl-Gtk 1.222, Glib->warning messages with wide chars don't get through to Perl's warn as wide but instead end up interpreted here as locale bytes. If your locale is utf8 then that's fine, but if not then expect to see "A-grave" and similar odour of bad utf8, in both the GUI and to STDERR.

Global Destruction

During "global destruction" of objects when Perl or a Perl thread is exiting (see "Two-Phased Garbage Collection" in perlobj), messages are printed to STDERR but not put to the dialog. The dialog is an object and at that point is either already destroyed or about to be destroyed.

Exceptions during global destruction can arise from DESTROY methods on Perl objects and destroy etc signal emissions on Gtk objects. Global destruction is identified using Devel::GlobalDestruction.

Idle Handler

Messages are printed to STDERR immediately, but for the dialog are saved away and added later under a high-priority Glib idle handler. The handler runs before Gtk resizing or redrawing so it should be the next thing seen by the user.

This is important for $SIG{'__WARN__'} handler calls which happen while a Perl compile error is pending (PL_parser->error_count). It's not possible to load the ErrorTextDialog module or any further modules while a compile error is pending and attempting to do so gives a further error (see "BEGIN not safe after errors--compilation aborted" in perldiag).

If the process of adding messages to the dialog is itself causing further errors or warnings then after a few attempts it's disabled and only STDERR used. This shouldn't happen normally but the protection avoids infinite repetition of errors if it does.

SEE ALSO

Gtk2::Ex::ErrorTextDialog, "EXCEPTIONS" in Glib, "%SIG" in perlvar, "GLog" in Glib::xsapi, Devel::GlobalDestruction

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-errortextdialog/

LICENSE

Gtk2-Ex-ErrorTextDialog is Copyright 2007, 2008, 2009, 2010, 2011, 2013 Kevin Ryde

Gtk2-Ex-ErrorTextDialog is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-ErrorTextDialog is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-ErrorTextDialog. If not, see http://www.gnu.org/licenses/.

cpanm Gtk2::Ex::ErrorTextDialog

perl -MCPAN -e shell
install Gtk2::Ex::ErrorTextDialog