1Prima::MsgBox(3)      User Contributed Perl Documentation     Prima::MsgBox(3)
2
3
4

NAME

6       Prima::MsgBox - standard message and input dialog boxes
7

DESCRIPTION

9       The module contains two methods, "message_box" and "input_box", that
10       invoke correspondingly the standard message and one line text input
11       dialog boxes.
12

SYNOPSIS

14               use Prima;
15               use Prima::Application;
16               use Prima::MsgBox;
17
18               my $text = Prima::MsgBox::input_box( 'Sample input box', 'Enter text:', '');
19               $text = '(none)' unless defined $text;
20               Prima::MsgBox::message( "You have entered: '$text'", mb::Ok);
21

API

23       input_box TITLE, LABEL, INPUT_STRING, [ BUTTONS = mb::OkCancel,
24       %PROFILES ]
25           Invokes standard dialog box, that contains an input line, a text
26           label, and buttons used for ending dialog session. The dialog box
27           uses TITLE string to display as the window title, LABEL text to
28           draw next to the input line, and INPUT_STRING, which is the text
29           present in the input box. Depending on the value of BUTTONS integer
30           parameter, which can be a combination of the button "mb::XXX"
31           constants, different combinations of push buttons can be displayed
32           in the dialog.
33
34           PROFILE parameter is a hash, that contains customization parameters
35           for the buttons and the input line. To access input line
36           "inputLine" hash key is used.  See "Buttons and profiles" for more
37           information on BUTTONS and PROFILES.
38
39           Returns different results depending on the caller context.  In
40           array context, returns two values: the result of
41           "Prima::Dialog::execute", which is either "mb::Cancel" or one of
42           "mb::XXX" constants of the dialog buttons; and the text entered.
43           The input text is not restored to its original value if the dialog
44           was cancelled. In scalar context returns the text entered, if the
45           dialog was ended with "mb::OK" or "mb::Yes" result, or "undef"
46           otherwise.
47
48       message TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]
49           Same as "message_box" call, with application name passed as the
50           title string.
51
52       message_box TITLE, TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]
53           Invokes standard dialog box, that contains a text label, a
54           predefined icon, and buttons used for ending dialog session. The
55           dialog box uses TITLE string to display as the window title, TEXT
56           to display as a main message. Value of OPTIONS integer parameter is
57           combined from two different sets of "mb::XXX" constants. The first
58           set is the buttons constants, - "mb::OK", "mb::Yes" etc.  See
59           "Buttons and profiles" for the explanations. The second set
60           consists of the following message type constants:
61
62                   mb::Error
63                   mb::Warning
64                   mb::Information
65                   mb::Question
66
67           While there can be several constants of the first set, only one
68           constant from the second set can be selected.  Depending on the
69           message type constant, one of the predefined icons is displayed and
70           one of the system sounds is played; if no message type constant is
71           selected, no icon is displayed and no sound is emitted.  In case if
72           no sound is desired, a special constant "mb::NoSound" can be used.
73
74           PROFILE parameter is a hash, that contains customization parameters
75           for the buttons.  See "Buttons and profiles" for the explanations.
76
77           Returns the result of "Prima::Dialog::execute", which is either
78           "mb::Cancel" or one of "mb::XXX" constants of the specified dialog
79           buttons.
80
81   Buttons and profiles
82       The message and input boxes provide several predefined buttons that
83       correspond to the following "mb::XXX" constants:
84
85               mb::OK
86               mb::Cancel
87               mb::Yes
88               mb::No
89               mb::Abort
90               mb::Retry
91               mb::Ignore
92               mb::Help
93
94       To provide more flexibility, PROFILES hash parameter can be used.  In
95       this hash, predefined keys can be used to tell the dialog methods about
96       certain customizations:
97
98       defButton INTEGER
99           Selects the default button in the dialog, i.e. the button that
100           reacts on the return key. Its value must be equal to the "mb::"
101           constant of the desired button. If this option is not set, the
102           leftmost button is selected as the default.
103
104       helpTopic TOPIC
105           Used to select the help TOPIC, invoked in the help viewer window if
106           "mb::Help" button is pressed by the user.  If this option is not
107           set, Prima is displayed.
108
109       inputLine HASH
110           Only for "input_box".
111
112           Contains a profile hash, passed to the input line as creation
113           parameters.
114
115       buttons HASH
116           To modify a button, an integer key with the corresponding "mb::XXX"
117           constant can be set with the hash reference under "buttons" key.
118           The hash is a profile, passed to the button as creation parameters.
119           For example, to change the text and behavior of a button, the
120           following construct can be used:
121
122                   Prima::MsgBox::message( 'Hello', mb::OkCancel,
123                           buttons => {
124                                   mb::Ok, {
125                                           text     => '~Hello',
126                                           onClick  => sub { Prima::message('Hello indeed!'); }
127                                   }
128                           }
129                   );
130
131           If it is not desired that the dialog must be closed when the user
132           presses a button, its "::modalResult" property ( see Prima::Buttons
133           ) must be reset to 0.
134
135       owner WINDOW
136           If set, the dialog owner is set to WINDOW, otherwise to
137           $::main_window.  Necessary to maintain window stack order under
138           some window managers, to disallow windows to be brought over the
139           message box.
140

AUTHOR

142       Dmitry Karasik, <dmitry@karasik.eu.org>.
143

SEE ALSO

145       Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.
146
147
148
149perl v5.32.1                      2021-01-27                  Prima::MsgBox(3)
Impressum