NAME

MesgBox - Perl/Tk module for message and button dialogue boxes.

SYNOPSIS

    use MesgBox; 

    # Example 1: an 'OK' box.
    # Pressing <Space>, <Return>, <o>, <Control-o> or <Alt-o> will close the box.

    my $msg = $Window->MesgBox(-title => 'Test', -text => 'Test Complete.');
    $msg->Show;

    # Example 2: a 'Yes/No' box.
    # Pressing <Space>, <Return>, <y>, <Control-y> or <Alt-y> 
    # presses the 'Yes' button;
    # pressing <n>, <Control-n> or <Alt-n> presses the 'No' button.

    my $msg = $Window->MesgBox(
        -title     => 'Save File?',
        -text      => "Save '$filename'?",
        -icon      => 'QUESTION',
        -buttons   => ['Yes', 'No'],
        -defbutton => 'Yes',
        );
    my $ans = $msg->Show;
    &save_file if $ans eq 'Yes';

    # Example 3: an 'OK/Cancel' box.
    # Pressing <Space>, <Return>, <o>, <Control-o> or <Alt-o> presses the 'OK'
    # button;
    # pressing <Escape>, <c>, <Control-c> or <Alt-c> presses the 'Cancel'
    # button.

    my $msg = $Window->MesgBox(
        -title   => 'Print',
        -text    => 'Print the page',
        -buttons => ['OK', 'Cancel'],
        );
    my $ans = $msg->Show;
    &print if $ans eq 'OK';

DESCRIPTION

This message box is similar to the MsgBox function provided with Windows. It provides a message text with an optional 'icon' and any buttons required. It is not as versatile as the Dialog box supplied with Tk but is simpler, and it provides automatic keyboard bindings.

All options are optional, although defining a -title and -text is only sensible. Leaving out everything else will provide a simple OK button.

The keyboard is bound such that the first letter of each button is bound both as a letter alone and in conjunction with both Control and Alt. This letter is also displayed underlined. It is recommended that each button's text begins with a unique letter. Any button with the text 'OK' will be the default button responding to <Return>, unless overridden by the -defbutton option. Any button with the text 'Cancel' will be the default cancel button responding to <Escape> unless overridden by the -canbutton option.

-title is the text which appears in the title bar.

-text is the text which appears in the body of the message. It may include newlines which are respected, but it will wrap.

-icon is the 'icon' which appears to the left of the message. It may be one of Tk's standard bitmaps: info 'i', error '(\)', warning '!', question '?'; or one of the MesgBox versions: INFO 'i', ERROR 'E', WARNING '!', QUESTION '?'. It may be undefined meaning no image appears.

-defbutton is the default button. It defaults to the 'OK' button if there is one. The default button is the button 'pressed' when the user presses <Return>.

-canbutton is the cancel button. It defaults to the 'Cancel' button if there is one. The cancel button is the button 'pressed' when the user presses <Escape>.

-buttons is an array of button captions. By default it is set to a list consisting of one element, 'OK'. You may use any text, e.g. 'OK', 'Cancel', 'Yes', 'Retry', etc. You may have as many buttons as you like - although too many might not fit on the screen...

-aspect is the ratio of width to height. Generally increase this past the default of 200, say to 300, 400 or 500 to make the message box wider and shorter.

-justify sets the justification for the -text - may be 'center', 'left' or 'right'. Defaults to 'center'.

-textfg sets the foreground colour for the -text; default is black.

-textbg sets the background colour for the -text; default is lightgrey.

-buttonfont sets the font for the button; default is 12pt Helvetica.

-bindctrl sets the keyboard bindings to include <Control-$letter>, defaults to true.

-bindalt sets the keyboard bindings to include <Alt-$letter>, defaults to true.

-bindord sets the keyboard bindings to include <$letter>, defaults to true.

-buttonpadx sets the left and right padding around the button, defaults to 0.

-buttonpady sets the above and below padding around the button, defaults to 0.

-buttonfg sets the button foreground colour, defaults to black.

-buttonbg sets the button foreground colour, defaults to lightgrey.

-buttonHL sets the button highlight colour, defaults to lightgrey.

INSTALLATION

MesgBox.pm should be placed in any Tk directory in any lib directory in Perl's %INC path, for example, '/usr/lib/perl5/Tk'.

BUGS

MesgBox does almost no error checking.

CHANGES

1999/01/18 First public release.

1999/01/22 Minor documentation changes.

1999/01/23 Tidied up set_icon.

1999/02/23 Should now be Windows compatible.

1999/08/05 Just changed the files to make them more CPAN friendly.

1999/08/08 Changed licence to LGPL.

1999/09/06 Minor change to packaging for CPAN.

1999/10/01 Changed the Show() method so that it is now compatible with Tk800.015 as well as earlier Tk800 versions.

2000/05/05 Minor increment because I accidentally deleted it from CPAN.

2000/09/16 Added new options to control colours and padding: almost all the new code was supplied by Daniel Berger.

AUTHOR

Mark Summerfield. I can be contacted as <summer@perlpress.com> - please include the word 'mesgbox' in the subject line.

The code draws very heavily from Stephen O. Lidie's Dialog.pm module.

COPYRIGHT

Copyright (c) Mark Summerfield 1999,2000. All Rights Reserved.

This module may be used/distributed/modified under the LGPL.

cpanm Tk::MesgBox

perl -MCPAN -e shell
install Tk::MesgBox