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 qw(Application);
15               use Prima::MsgBox qq(input_box message);
16
17               my $text = input_box( 'Sample input box', 'Enter text:', '') // '(none)';
18               message( \ "You have entered: 'B<Q<< $text >>>'", mb::Ok);
19

API

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

AUTHOR

140       Dmitry Karasik, <dmitry@karasik.eu.org>.
141

SEE ALSO

143       Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.
144
145
146
147perl v5.34.0                      2021-07-22                  Prima::MsgBox(3)
Impressum