/ 
Gtk2-Ex-ErrorTextDialog-4
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, for example for a bug report. Cut-and-paste works in the usual way too.

FUNCTIONS

Creation

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

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

You can destroy this instance with $errordialog->destroy in the usual way if you want. A subsequent call to instance creates 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 so it will display, though not necessarily very well (see "Handling Malformed Data" in Encode).

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