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 display their messages in an ErrorTextDialog, as well as printing to STDERR. The handlers are small and the idea is to keep memory use down by not loading the ErrorTextDialog until needed. If your program works then the dialog may never be needed!

When a new error occurs an existing ErrorTextDialog is raised so the error is seen. It's not "presented" though, so the keyboard focus is unchanged (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 the errors if there's a big cascade. Perhaps the way this works will change though.

The default action on closing the error dialog is to hide it, so past messages remain. In an application it can be good to have a menu entry etc which pops up the dialog with Gtk2::Ex::ErrorTextDialog->present or similar, so the user can see past errors after closing the dialog.

Wide Chars

The dialog displays unicode characters; if a message is a byte string then the dialog add_message assumes it's in the locale charset and converts for display. If STDERR takes wide chars (because it has an encoding layer pushed) then the same conversion is used to print to it.

If STDERR only takes raw bytes but a message string has wide chars, 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.

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 is either already destroyed or is about to be destroyed at that point.

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

Compilation Errors and Warnings

In a require etc, if both errors and warnings occur during the compile then $SIG{__WARN__} calls can be made while a compile error is pending. Perl doesn't allow the handler code to load other modules in that case ("BEGIN not safe after errors").

exception_handler below will print to STDERR immediately but if the ErrorTextDialog code hasn't already been loaded then it accumulates messages until it's possible to load and create the dialog. Generally this is a short time later when the compile error comes through the handler.

The prohibition on BEGIN is to protect code which depends on a prior import etc having run. (Perhaps it's possible to load something unrelated like ErrorTextDialog or Encode, or at least attempt it, if the pending errors could somehow be suspended.)

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 perlipc).

    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 gperl_handle_logs_for in Glib::xsapi). So if you trap $SIG{'__WARN__'} then you already get Glib and Gtk logs without any explicit Glib::Log handlers.

SEE ALSO

Gtk2::Ex::ErrorTextDialog, "EXCEPTIONS" in Glib, perlipc, Glib::xsapi, Devel::GlobalDestruction

HOME PAGE

http://www.geocities.com/user42_kevin/gtk2-ex-errortextdialog/

LICENSE

Gtk2-Ex-ErrorTextDialog is Copyright 2007, 2008, 2009 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/.