Prima::MsgBox - standard message and input dialog boxes
The module contains methods that start standard simple message dialogs
use Prima qw(Application); use Prima::MsgBox qw(input_box message); my $text = input_box( 'Sample input box', 'Enter text:', '') // '(none)'; message( \ "You have entered: 'B<Q<< $text >>>'", mb::Ok);
Invokes a standard dialog box, that contains an input line, a text label, and buttons that end the dialog session. The dialog box uses the TITLE string to display as the window title, the 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 the BUTTONS integer parameter, which can be a combination of the mb::XXX constants, different combinations of push buttons can be displayed in the dialog.
mb::XXX
The PROFILE parameter is a hash, that contains customization parameters for the buttons and the input line. To access the input line parameters the inputLine hash key is used. See "Buttons and profiles" for more information on BUTTONS and PROFILES.
inputLine
Returns different results depending on the call context. In the array context returns two values: the result of Prima::Dialog::execute which is either mb::Cancel or one of the mb::XXX constants of the dialog buttons; and the text entered. The input text is not restored to its original value if the dialog is canceled. In the scalar context returns the text entered, if the dialog ended with mb::OK or mb::Yes result, or undef otherwise.
Prima::Dialog::execute
mb::Cancel
mb::OK
mb::Yes
undef
Same as the message_box call, with the application name passed as the title string.
message_box
Invokes the standard dialog box that contains a text label, a predefined icon, and buttons to end the dialog session. The dialog box uses the TITLE string to display as the window title, and the TEXT to display as the main message. The value of the OPTIONS integer parameter is combined from two different sets of mb::XXX constants. The first set is the button constants mb::OK, mb::Yes, etc. See "Buttons and profiles" for the details. The second set consists of the following 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 no sound is desired, a special constant mb::NoSound can be used.
mb::NoSound
The PROFILE parameter is a hash that contains customization parameters for the buttons. See "Buttons and profiles" for the details.
Returns the result of Prima::Dialog::execute which is either mb::Cancel or one of mb::XXX constants of the specified dialog buttons.
The standard minimalistic exception dialog shown by default when Prima::Application.guiException is 1 and an exception is thrown. Could be reused for other purposes, by supplying a title, error message, and stack trace. If the stack trace is not defined, the corresponding button is not shown.
Prima::Application.guiException
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, the PROFILES hash parameter can be used. In this hash, the following predefined keys tell the dialog methods about certain customizations:
Selects the default button in the dialog, i.e. the button that reacts on the return key. Its value must be to an mb:: constant of the desired button. If this option is not set, the leftmost button is selected as the default.
mb::
Selects the help TOPIC invoked in the help viewer window if the mb::Help button is pressed by the user. If this option is not set, Prima is displayed.
mb::Help
Only for input_box.
input_box
Contains the profile hash passed to the input line as creation parameters.
To modify a button, an integer key with the corresponding mb::XXX constant can be set with the hash reference under the buttons key. The hash is the 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:
buttons
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.
::modalResult
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 other windows to be brought over the message box.
$::main_window
message_box can display the message in two modes. In wordWrap = 1 where the text is expected to be relatively short, plus or minus several lines, the user can resize the dialog if for some reason the text is too big. In wordWrap = 0 mode there is added a scroller, so that even if the text indeed is too big, even when the dialog is maximized.
wordWrap = 1
wordWrap = 0
By default, the function analyzes the message text and decides which of the two modes is suited best. An explicit override is possible with this flag.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.