view release on metacpan or  search on metacpan

lib/Gtk2/Ex/ErrorTextDialog/Handler.pm  view on Meta::CPAN

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

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

=head1 DESCRIPTION

This module supplies error and warning handler functions which print to
C<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 F<examples/simple.pl> in the Gtk2-Ex-ErrorTextDialog sources for a
complete program with this sort of error handler.

=head1 FUNCTIONS

=over 4

=item C<< Gtk2::Ex::ErrorTextDialog::Handler::exception_handler ($str) >>

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

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

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

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

=item C<< Gtk2::Ex::ErrorTextDialog::Handler::log_handler ($log_domain, $log_levels, $message) >>

A function suitable for use with C<< Glib::Log->set_handler >> (see
L<Glib::Log>).  It forms a message similar to the Glib default handler and
prints and displays per the C<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 C<warn> calls (see L<Glib::xsapi/GLog> on
C<gperl_handle_logs_for>).  So if you trap C<< $SIG{'__WARN__'} >> then you
already get Glib and Gtk logs without any explicit C<Glib::Log> handlers.

=back

=head1 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.

=head2 Wide Chars

If a message is a byte string then it's assumed to be in the locale charset.
If C<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 (C<add_message> does a conversion if necessary).

If a message is a wide char string but C<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, C<< Glib->warning >> messages with wide chars don't
get through to Perl's C<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.

=head2 Global Destruction

During "global destruction" of objects when Perl or a Perl thread is exiting
(see L<perlobj/Two-Phased Garbage Collection>), messages are printed to
C<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 C<DESTROY> methods on
Perl objects and C<destroy> etc signal emissions on Gtk objects.  Global
destruction is identified using C<Devel::GlobalDestruction>.

=head2 Idle Handler

Messages are printed to C<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 C<$SIG{'__WARN__'}> handler calls which happen while a
Perl compile error is pending (C<< 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
L<perldiag/BEGIN not safe after errors--compilation aborted>).

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
C<STDERR> used.  This shouldn't happen normally but the protection avoids
infinite repetition of errors if it does.

=head1 SEE ALSO

L<Gtk2::Ex::ErrorTextDialog>, L<Glib/EXCEPTIONS>, L<perlvar/%SIG>,
L<Glib::xsapi/GLog>, L<Devel::GlobalDestruction>