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.