NAME
Prima::MsgBox - standard message and input dialog boxes
DESCRIPTION
The module contains two methods, "message_box" and "input_box", that
invoke correspondingly the standard message and one line text input
dialog boxes.
SYNOPSIS
use Prima;
use Prima::Application;
use Prima::MsgBox;
my $text = Prima::MsgBox::input_box( 'Sample input box', 'Enter text:', '');
$text = '(none)' unless defined $text;
Prima::MsgBox::message( "You have entered: '$text'", mb::Ok);
API
input_box TITLE, LABEL, INPUT_STRING, [ BUTTONS = mb::OkCancel,
%PROFILES ]
Invokes standard dialog box, that contains an input line, a text
label, and buttons used for ending dialog session. The dialog box
uses TITLE string to display as the window title, LABEL text to
draw next to the input line, and INPUT_STRING, which is the text
present in the input box. Depending on the value of BUTTONS integer
parameter, which can be a combination of the button "mb::XXX"
constants, different combinations of push buttons can be displayed
in the dialog.
PROFILE parameter is a hash, that contains customization parameters
for the buttons and the input line. To access input line
"inputLine" hash key is used. See "Buttons and profiles" for more
information on BUTTONS and PROFILES.
Returns different results depending on the caller context. In
array context, returns two values: the result of
"Prima::Dialog::execute", which is either "mb::Cancel" or one of
"mb::XXX" constants of the dialog buttons; and the text entered.
The input text is not restored to its original value if the dialog
was cancelled. In scalar context returns the text entered, if the
dialog was ended with "mb::OK" or "mb::Yes" result, or "undef"
otherwise.
message TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]
Same as "message_box" call, with application name passed as the
title string.
message_box TITLE, TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]
Invokes standard dialog box, that contains a text label, a
predefined icon, and buttons used for ending dialog session. The
dialog box uses TITLE string to display as the window title, TEXT
to display as a main message. Value of OPTIONS integer parameter is
combined from two different sets of "mb::XXX" constants. The first
set is the buttons constants, - "mb::OK", "mb::Yes" etc. See
"Buttons and profiles" for the explanations. The second set
consists of the following message type constants:
mb::Error
mb::Warning
mb::Information
mb::Question
While there can be several constants of the first set, only one
constant from the second set can be selected. Depending on the
message type constant, one of the predefined icons is displayed and
one of the system sounds is played; if no message type constant is
selected, no icon is displayed and no sound is emitted. In case if
no sound is desired, a special constant "mb::NoSound" can be used.
PROFILE parameter is a hash, that contains customization parameters
for the buttons. See "Buttons and profiles" for the explanations.
Returns the result of "Prima::Dialog::execute", which is either
"mb::Cancel" or one of "mb::XXX" constants of the specified dialog
buttons.
Buttons and profiles
The message and input boxes provide several predefined buttons that
correspond to the following "mb::XXX" constants:
mb::OK
mb::Cancel
mb::Yes
mb::No
mb::Abort
mb::Retry
mb::Ignore
mb::Help
To provide more flexibility, PROFILES hash parameter can be used. In
this hash, predefined keys can be used to tell the dialog methods about
certain customizations:
defButton INTEGER
Selects the default button in the dialog, i.e. the button that
reacts on the return key. Its value must be equal to the "mb::"
constant of the desired button. If this option is not set, the
leftmost button is selected as the default.
helpTopic TOPIC
Used to select the help TOPIC, invoked in the help viewer window if
"mb::Help" button is pressed by the user. If this option is not
set, Prima is displayed.
inputLine HASH
Only for "input_box".
Contains a profile hash, passed to the input line as creation
parameters.
buttons HASH
To modify a button, an integer key with the corresponding "mb::XXX"
constant can be set with the hash reference under "buttons" key.
The hash is a profile, passed to the button as creation parameters.
For example, to change the text and behavior of a button, the
following construct can be used:
Prima::MsgBox::message( 'Hello', mb::OkCancel,
buttons => {
mb::Ok, {
text => '~Hello',
onClick => sub { Prima::message('Hello indeed!'); }
}
}
);
If it is not desired that the dialog must be closed when the user
presses a button, its "::modalResult" property ( see Prima::Buttons
) must be reset to 0.
owner WINDOW
If set, the dialog owner is set to WINDOW, otherwise to
$::main_window. Necessary to maintain window stack order under
some window managers, to disallow windows to be brought over the
message box.
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.