The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Gtk2-Ex-ErrorTextDialog-11
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 |
    +------------------------------------+

See Gtk2::Ex::ErrorTextDialog::Handler for functions hooking 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 write 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 the 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 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 string messages. A horizontal separator line is added between each message because it can be hard to tell one from the next when long lines are 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 wide chars or raw bytes and 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).

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

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

ACTION SIGNALS

The following are provided both as "action signals" for use from Gtk2::Rc key bindings and methods for use from program code.

clear action signal (no parameters)

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

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

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

Emit the clear or popup-save-dialog signals, respectively. The default handler in those signals does the actual work of clearing or showing the save dialog and as usual for action signals that's the place to override or specialize in a subclass.

$id = Gtk2::Ex::ErrorTextDialog->RESPONSE_CLEAR
$id = Gtk2::Ex::ErrorTextDialog->RESPONSE_SAVE

Return the dialog respond ID for the clear and save actions. These are the responses raised by the clear and save buttons. The clear response could be raised explicitly with

    $errordialog->response ($errordialog->RESPONSE_CLEAR);
    # same as $errordialog->clear()

Key Bindings

The stock Clear and Save-As button mnemonic keys invoke the clear and save actions, but there's no further key bindings by default. You can add keys in the usual way from the Gtk2::Rc mechanism. The class is Gtk2__Ex__ErrorTextDialog so for example in your ~/.gtkrc-2.0 file

    binding "my_error_keys" {
      bind "F5" { "popup-save-dialog" () }
    }
    class "Gtk2__Ex__ErrorTextDialog" binding:rc "my_error_keys"

See examples/keybindings.pl in the sources for a complete program doing this.

PROPERTIES

max-chars (integer, default 200000)

The maximum number of characters of message text to retain, or -1 for unlimited. If this size is exceeded old text is discarded, replaced by a line

    [Older messages discarded]

The idea is to limit memory use if a program is spewing lots of warnings etc. An infinite or near-infinite stream probably still makes the program unusable, but at least it won't consume ever more memory.

Currently truncation chops old text in the middle of a message. This is slightly unattractive but it's fastest and it means if there's a huge message then at least part of it is retained.

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, 2010, 2011, 2013 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/.