.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::MsgBox 3"
.TH Prima::MsgBox 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::MsgBox \- standard message and input dialog boxes
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module contains two methods, \f(CW\*(C`message_box\*(C'\fR and \f(CW\*(C`input_box\*(C'\fR,
that invoke correspondingly the standard message and one line text input
dialog boxes.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&        use Prima;
\&        use Prima::Application;
\&        use Prima::MsgBox;
\&
\&        my $text = Prima::MsgBox::input_box( \*(AqSample input box\*(Aq, \*(AqEnter text:\*(Aq, \*(Aq\*(Aq);
\&        $text = \*(Aq(none)\*(Aq unless defined $text;
\&        Prima::MsgBox::message( "You have entered: \*(Aq$text\*(Aq", mb::Ok);
.Ve
.SH "API"
.IX Header "API"
.ie n .IP "input_box \s-1TITLE\s0, \s-1LABEL\s0, \s-1INPUT_STRING\s0, [ \s-1BUTTONS\s0 = mb::OkCancel, %PROFILES ]" 4
.el .IP "input_box \s-1TITLE\s0, \s-1LABEL\s0, \s-1INPUT_STRING\s0, [ \s-1BUTTONS\s0 = mb::OkCancel, \f(CW%PROFILES\fR ]" 4
.IX Item "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 \s-1TITLE\s0 string to
display as the window title, \s-1LABEL\s0 text to draw next to the input line, and
\&\s-1INPUT_STRING\s0, which is the text present in the input box. Depending on the
value of \s-1BUTTONS\s0 integer parameter, which can be a combination of the button
\&\f(CW\*(C`mb::XXX\*(C'\fR constants, different combinations of push buttons can be displayed
in the dialog.
.Sp
\&\s-1PROFILE\s0 parameter is a hash, that contains customization parameters for the
buttons and the input line. To access input line \f(CW\*(C`inputLine\*(C'\fR hash key is used.
See \*(L"Buttons and profiles\*(R" for more information on \s-1BUTTONS\s0 and \s-1PROFILES\s0.
.Sp
Returns different results depending on the caller context.  In array context,
returns two values: the result of \f(CW\*(C`Prima::Dialog::execute\*(C'\fR, which is either
\&\f(CW\*(C`mb::Cancel\*(C'\fR or one of \f(CW\*(C`mb::XXX\*(C'\fR 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 \f(CW\*(C`mb::OK\*(C'\fR or \f(CW\*(C`mb::Yes\*(C'\fR result, or \f(CW\*(C`undef\*(C'\fR otherwise.
.ie n .IP "message \s-1TEXT\s0, [ \s-1OPTIONS\s0 = mb::Ok | mb::Error, %PROFILES ]" 4
.el .IP "message \s-1TEXT\s0, [ \s-1OPTIONS\s0 = mb::Ok | mb::Error, \f(CW%PROFILES\fR ]" 4
.IX Item "message TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]"
Same as \f(CW\*(C`message_box\*(C'\fR call, with application name passed as the title string.
.ie n .IP "message_box \s-1TITLE\s0, \s-1TEXT\s0, [ \s-1OPTIONS\s0 = mb::Ok | mb::Error, %PROFILES ]" 4
.el .IP "message_box \s-1TITLE\s0, \s-1TEXT\s0, [ \s-1OPTIONS\s0 = mb::Ok | mb::Error, \f(CW%PROFILES\fR ]" 4
.IX Item "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 \s-1TITLE\s0 string to
display as the window title, \s-1TEXT\s0 to display as a main message. Value of
\&\s-1OPTIONS\s0 integer parameter is combined from two different sets of \f(CW\*(C`mb::XXX\*(C'\fR
constants. The first set is the buttons constants, \- \f(CW\*(C`mb::OK\*(C'\fR, \f(CW\*(C`mb::Yes\*(C'\fR etc.
See \*(L"Buttons and profiles\*(R" for the explanations. The second set consists of
the following message type constants:
.Sp
.Vb 4
\&        mb::Error
\&        mb::Warning
\&        mb::Information
\&        mb::Question
.Ve
.Sp
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 \f(CW\*(C`mb::NoSound\*(C'\fR can
be used.
.Sp
\&\s-1PROFILE\s0 parameter is a hash, that contains customization parameters for the
buttons.  See \*(L"Buttons and profiles\*(R" for the explanations.
.Sp
Returns the result of \f(CW\*(C`Prima::Dialog::execute\*(C'\fR, which is either \f(CW\*(C`mb::Cancel\*(C'\fR
or one of \f(CW\*(C`mb::XXX\*(C'\fR constants of the specified dialog buttons.
.SS "Buttons and profiles"
.IX Subsection "Buttons and profiles"
The message and input boxes provide several predefined buttons that correspond
to the following \f(CW\*(C`mb::XXX\*(C'\fR constants:
.PP
.Vb 8
\&        mb::OK
\&        mb::Cancel
\&        mb::Yes
\&        mb::No
\&        mb::Abort
\&        mb::Retry
\&        mb::Ignore
\&        mb::Help
.Ve
.PP
To provide more flexibility, \s-1PROFILES\s0 hash parameter can be used.  In this
hash, predefined keys can be used to tell the dialog methods about certain
customizations:
.IP "defButton \s-1INTEGER\s0" 4
.IX Item "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 \f(CW\*(C`mb::\*(C'\fR constant of the desired
button. If this option is not set, the leftmost button is selected as the
default.
.IP "helpTopic \s-1TOPIC\s0" 4
.IX Item "helpTopic TOPIC"
Used to select the help \s-1TOPIC\s0, invoked in the help viewer window if \f(CW\*(C`mb::Help\*(C'\fR
button is pressed by the user.  If this option is not set, Prima is
displayed.
.IP "inputLine \s-1HASH\s0" 4
.IX Item "inputLine HASH"
Only for \f(CW\*(C`input_box\*(C'\fR.
.Sp
Contains a profile hash, passed to the input line as creation parameters.
.IP "buttons \s-1HASH\s0" 4
.IX Item "buttons HASH"
To modify a button, an integer key with the corresponding \f(CW\*(C`mb::XXX\*(C'\fR constant
can be set with the hash reference under \f(CW\*(C`buttons\*(C'\fR 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:
.Sp
.Vb 8
\&        Prima::MsgBox::message( \*(AqHello\*(Aq, mb::OkCancel,
\&                buttons => {
\&                        mb::Ok, {
\&                                text     => \*(Aq~Hello\*(Aq,
\&                                onClick  => sub { Prima::message(\*(AqHello indeed!\*(Aq); }
\&                        }
\&                }
\&        );
.Ve
.Sp
If it is not desired that the dialog must be closed when the user presses a
button, its \f(CW\*(C`::modalResult\*(C'\fR property ( see Prima::Buttons ) must be reset
to 0.
.IP "owner \s-1WINDOW\s0" 4
.IX Item "owner WINDOW"
If set, the dialog owner is set to \s-1WINDOW\s0, otherwise to \f(CW$::main_window\fR.
Necessary to maintain window stack order under some window managers, to disallow
windows to be brought over the message box.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.