view release on metacpan or  search on metacpan

lib/Gtk2/Ex/Dialogs/Message.pm  view on Meta::CPAN

#  License along with this library; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
###############################################################################
use strict;

BEGIN {
	use vars qw( $VERSION $parent_window $title $icon $text
                 $destroy_with_parent $modal $no_separator );
    $VERSION = '0.11';
}

use Carp;
use Gtk2;
use Glib;
use Gtk2::Ex::Utils     qw( :main :alter                      );
use Gtk2::Ex::Constants qw( :truth :pad :pack :align :justify );

sub import {
    my $class = shift();
    my $cfg = undef;

    if ( @_ % 2 == 0 ) {
        $cfg = { @_ };
    } elsif ( @_ % 2 >= 1 ) {
        croak( $class . " class received an uneven argument list." );
    } else {
        $cfg = {};
    }

    $Gtk2::Ex::Dialogs::Message::title               =
     $cfg->{title}               || '';
    $Gtk2::Ex::Dialogs::Message::text                =
     $cfg->{text}                || '';
    $Gtk2::Ex::Dialogs::Message::icon                =
     $cfg->{icon}                || '';
    $Gtk2::Ex::Dialogs::Message::modal               =
     $cfg->{modal}               || FALSE;
    $Gtk2::Ex::Dialogs::Message::no_separator        =
     $cfg->{no_separator}        || FALSE;
    $Gtk2::Ex::Dialogs::Message::parent_window       =
     $cfg->{parent_window}       || undef;
    $Gtk2::Ex::Dialogs::Message::destroy_with_parent =
     $cfg->{destroy_with_parent} || FALSE;
}


=head1 NAME

Gtk2::Ex::Dialogs::Message - Provides a simple message dialog.

=head1 SYNOPSIS

 use Gtk2::Ex::Dialogs::Message ( destroy_with_parent => TRUE,
                                  modal => TRUE,
                                  no_separator => FALSE );

 # do some stuff like creating your app's main $window then,
 # to ensure that all messages use the right parent, set it:
 $Gtk2::Ex::Dialogs::Message::parent_window = $window;

 # now popup a new dialog ( blocking the main loop if there is one )
 new_and_run
  Gtk2::Ex::Dialogs::Message ( title => "Dialog Title",
                               text => "This is a simple message" );

 # now popup a somwhat useful dialog that doesn't block any main loop
 # but on the other side of the coin, if there is no main loop the
 # dialog will be completely unresponsive.
 new_show
  Gtk2::Ex::Dialogs::Message ( title => "Uhm",
                               text => "Use when there is a main loop." );

=head1 DESCRIPTION

This module provides a simple dialog api that wraps Gtk2::Dialog objectively.
The objective is a clean and simple message dialog (only an "OK" button).

=head1 OPTIONS

All public methods (and the entire class) support the following options:

=over

=item B<title> => STRING

The title of the dialog window. Defaults to an empty string.

=item B<text> => STRING

The text to be displayed. This is the core purpose of the module and is the
only mandatory argument.

=item B<icon> => /path/to/image || stock-id || Gtk2::Gdk::Pixbuf || Gtk2::Image

The dialog-sized image to place to the left of the text. Note: there are five
aliased stock-ids which correspond to the five gtk-dialog-* ids, "warning",
"question", "info", "error" and "authentication". Defaults to no icon being
created at all.

=item B<parent_window> => Gtk2::Window

Reference to the main application window.

=item B<destroy_with_parent> => BOOL

When the B<parent_window> is destroyed, what do we do? Defaults to FALSE.

=item B<modal> => BOOL

Does this message make the B<parent_window> freeze while the message exists.
Defaults to FALSE.

=item B<no_separator> => BOOL

Draw the horizontal separator between the content area and the button area
below. Defaults to FALSE.

=back

=head1 PUBLIC METHODS

=over

=item OBJECT = B<new> ( OPTIONS | STRING )

Create a new Gtk2::Dialog with only an "OK" button, some text and an optional