mesgbox(3)
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 pro
vided 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 sim
pler, 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 mes
sage. 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 Mes
gBox 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 <Con
trol-$letter>, defaults to true.
"-bindalt" sets the keyboard bindings to include
<Alt-$letter>, defaults to true.
"-bindord" sets the keyboard bindings to include <$let
ter>, 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@perl
press.com> - please include the word 'mesgbox' in the sub
ject line.
The code draws very heavily from Stephen O. Lidie's Dia
log.pm module.
COPYRIGHT
Copyright (c) Mark Summerfield 1999,2000. All Rights
Reserved.
- This module may be used/distributed/modified under the
LGPL.