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 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 may never be needed!

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, so 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 (its 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.

Global Destruction

During "global destruction" of objects (see "Two-Phased Garbage Collection" in perlobj) when Perl or a Perl thread is exiting, 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 is 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.

Compilation Errors and Warnings

Messages are printed to STDERR immediately, but for the dialog are instead saved and added later under a high-priority Glib idle handler. The idle 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. In that case it's not possible to load the ErrorTextDialog module (or any further modules). Attempting to do would be a further error (see "BEGIN not safe after errors--compilation aborted" in perldiag).

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 for function gperl_handle_logs_for). 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, "%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 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/.