/ 
Gtk2-Ex-ErrorTextDialog-3
River stage one • 1 direct dependent • 1 total dependent
/ Gtk2::Ex::ErrorTextDialog

NAME

Gtk2::Ex::ErrorTextDialog -- display error messages in a dialog

SYNOPSIS

# explicitly adding a message
use Gtk2::Ex::ErrorTextDialog;
Gtk2::Ex::ErrorTextDialog->add_message ("Something went wrong");

# handler for all Glib exceptions
use Gtk2::Ex::ErrorTextDialog::Handler;
Glib->install_exception_handler
  (\&Gtk2::Ex::ErrorTextDialog::Handler::exception_handler);

WIDGET HIERARCHY

Gtk2::Ex::ErrorTextDialog is a subclass of Gtk2::MessageDialog. But for now don't rely on more than Gtk2::Dialog.

Gtk2::Widget
  Gtk2::Container
    Gtk2::Bin
      Gtk2::Window
        Gtk2::Dialog
          Gtk2::MessageDialog
            Gtk2::Ex::ErrorTextDialog

DESCRIPTION

An ErrorTextDialog presents text error messages to the user in a Gtk2::TextView. It's intended for technical things like Perl errors and warnings, rather than results of normal user operations.

+------------------------------------+
|   !!    An error has occurred      |
| +--------------------------------+ |
| | Something at foo.pl line 123   | |
| | -----                          | |
| | Cannot whatever at Bar.pm line | |
| | 456                            | |
| |                                | |
| +--------------------------------+ |
+------------------------------------+
|                Clear Save-As Close |
+------------------------------------+

Gtk2::Ex::ErrorTextDialog::Handler has functions designed to hook up Glib exceptions and Perl warnings to display in an ErrorTextDialog.

ErrorTextDialog is good if there might be a long cascade of messages from one problem, or errors repeated on every screen draw. In that case the dialog scrolls along but the app might still mostly work.

The Save-As button lets the user save the messages to a file, say for a bug report. Cut-and-paste works in the usual way too of course.

FUNCTIONS

Creation

$errordialog = Gtk2::Ex::ErrorTextDialog->instance ()

Return an ErrorTextDialog object designed to be shared by all parts of the program. This object is used when the methods below are called as class functions.

You can destroy the instance with $errordialog->destroy in the usual way if you want. A subsequent call to instance will create a new one.

$errordialog = Gtk2::Ex::ErrorTextDialog->new (key=>value,...)

Create and return a new ErrorTextDialog. Optional key/value pairs set initial properties as per Glib::Object->new. An ErrorTextDialog created this way is separate from the instance() one above. But it's unusual to want more than one error dialog.

Messages

ErrorTextDialog works with "messages", which are simply strings. A horizontal separator line is added between each message, since it can be hard to tell one from the next when long lines are word-wrapped. Currently the separator is just some dashes, but something slimmer might be possible.

Gtk2::Ex::ErrorTextDialog->add_message ($str)
$errordialog->add_message ($str)

Add a message to the ErrorTextDialog. $str can be either Perl wide chars or raw bytes, and it doesn't have to end with a newline.

If $str is raw bytes it's assumed to be in the locale charset and is converted to unicode for display. Anything invalid in $str is escaped, currently just in PERLQQ style (see "Handling Malformed Data" in Encode) so it will display, though not necessarily very well.

Gtk2::Ex::ErrorTextDialog->get_text()
$errordialog->get_text()

Return a wide-char string of all the messages in the ErrorTextDialog.

Actions

Gtk2::Ex::ErrorTextDialog->clear()
$errordialog->clear()

Remove all messages in the dialog. This is the "Clear" button action.

Gtk2::Ex::ErrorTextDialog->popup_save_dialog()
$errordialog->popup_save_dialog()

Popup the Save dialog, which asks the user for a filename to save the error messages to. This is the "Save As" button action.

SEE ALSO

Gtk2::Ex::ErrorTextDialog::Handler

Gtk2::Ex::Carp (which presents messages one at a time)

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/.