1Prima::MsgBox(3) User Contributed Perl Documentation Prima::MsgBox(3)
2
6 Prima::MsgBox - standard message and input dialog boxes
7
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
14 use Prima qw(Application);
15 use Prima::MsgBox qq(input_box message);
16 my $text = input_box( 'Sample input box', 'Enter text:', '') // '(none)';
18 message( \ "You have entered: 'B<Q<< $text >>>'", mb::Ok);
19
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 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 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 message TEXT, [ OPTIONS = mb::Ok | mb::Error, %PROFILES ]
47 Same as "message_box" call, with application name passed as the
48 title string.
49 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 mb::Error
61 mb::Warning
62 mb::Information
63 mb::Question
64 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 PROFILE parameter is a hash, that contains customization parameters
73 for the buttons. See "Buttons and profiles" for the explanations.
74 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 signal_dialog $TITLE, $ERROR, $STACK_TRACE
80 Standard minimalistic exception dialog shown by default when
81 "Prima::Application.guiException" is 1 and an exception is thrown.
82 Could be reused for other purposes, by supplying title, error
83 message, and stack trace. If the stack trace is not defined, the
84 corresponding button is not shown.
85 Buttons and profiles
87 The message and input boxes provide several predefined buttons that
88 correspond to the following "mb::XXX" constants:
89 mb::OK
91 mb::Cancel
92 mb::Yes
93 mb::No
94 mb::Abort
95 mb::Retry
96 mb::Ignore
97 mb::Help
98 To provide more flexibility, PROFILES hash parameter can be used. In
100 this hash, predefined keys can be used to tell the dialog methods about
101 certain customizations:
102 defButton INTEGER
104 Selects the default button in the dialog, i.e. the button that
105 reacts on the return key. Its value must be equal to the "mb::"
106 constant of the desired button. If this option is not set, the
107 leftmost button is selected as the default.
108 helpTopic TOPIC
110 Used to select the help TOPIC, invoked in the help viewer window if
111 "mb::Help" button is pressed by the user. If this option is not
112 set, Prima is displayed.
113 inputLine HASH
115 Only for "input_box".
116 Contains a profile hash, passed to the input line as creation
118 parameters.
119 buttons HASH
121 To modify a button, an integer key with the corresponding "mb::XXX"
122 constant can be set with the hash reference under "buttons" key.
123 The hash is a profile, passed to the button as creation parameters.
124 For example, to change the text and behavior of a button, the
125 following construct can be used:
126 Prima::MsgBox::message( 'Hello', mb::OkCancel,
128 buttons => {
129 mb::Ok, {
130 text => '~Hello',
131 onClick => sub { Prima::message('Hello indeed!'); }
132 }
133 }
134 );
135 If it is not desired that the dialog must be closed when the user
137 presses a button, its "::modalResult" property ( see Prima::Buttons
138 ) must be reset to 0.
139 owner WINDOW
141 If set, the dialog owner is set to WINDOW, otherwise to
142 $::main_window. Necessary to maintain window stack order under
143 some window managers, to disallow windows to be brought over the
144 message box.
145 wordWrap BOOLEAN=undef
147 message_box can can display the message in two modes. In "wordWrap
148 = 1" where the text is expected to be relatively short, plus minus,
149 several lines, where the user can resize the dialog if for some
150 reason the text is too big. In "wordWrap = 0" mode there is added
151 a scroller, so that even if the text indeed is too big to get on
152 the screen event with the maximized dialog.
153 By default the function analyzes the message text and decides which
155 of the two modes is suited best. The explicit override is possible
156 with this flag.
157
159 Dmitry Karasik, <dmitry@karasik.eu.org>.
160
162 Prima, Prima::Buttons, Prima::InputLine, Prima::Dialog.
163perl v5.36.0 2023-03-20 Prima::MsgBox(3)