Sign in Join
Wiki copytemporary

Dialog Examples: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11# Some useful dialogs
22
33Here are some useful dialogs not found in the [[Component Palette]]:
44
55- `procedure ShowMessage (const Msg: string);`
66- `function MessageBox (Text, Caption : PChar; Flags: Word): Integer;`
77- `function MessageDlg (const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt): Word;`
88- `function InputBox (const ACaption, APrompt, ADefault: string); string;`
99- `function InputQuery (const ACaption, APrompt: string; var Value: string): Boolean;`
1010- `function PasswordBox(const ACaption, APrompt : String) : String;`
1111
1212Each of these components causes a small popup box to be displayed, which contains some information and requires a user response: either a button press or some text entry or both. The programmer has little control over the format, size or position of these popup boxes, but can influence their textual content.\
1313The reason why there are often several very similar alternatives, is to allow different methods of calling the component and receiving data back from the [[Procedure|procedure]] or [[Function|function]]. These dialogs might be **platform dependent** i.e. they might be displayed differently. For example, strings which are fully displayed in Windows XP, might be truncated in Windows 7.
1414
1515## Message Dialogs
1616
1717Message dialogs display a message and wait for a key-press or mouse-click response.
1818
1919### ShowMessage
2020
2121``` pascal
2222procedure ShowMessage(const Msg: string);
2323```
2424
2525{ Defined in Dialogs.pp }
2626
27-The simplest message dialog: takes a simple [[String|string]] as parameter, displays it in a stereotyped box, and waits for a mouse-click or <span class="kbd">Enter</span>-key event before returning to the calling [[Routine|routine]] or [[Program|program]].\
27+The simplest message dialog: takes a simple [[String|string]] as parameter, displays it in a stereotyped box, and waits for a mouse-click or `Enter`-key event before returning to the calling [[Routine|routine]] or [[Program|program]].\
2828This is a modal procedure call, that is the box is displayed, receives focus, and does not relinquish focus until the OK box is clicked or otherwise selected.
2929
3030Example:
3131
3232``` pascal
3333program LazMessage;
3434uses
3535 Dialogs;
3636begin
3737 ShowMessage('This is a message from Lazarus');
3838end.
3939```
4040
4141You have the ability to create multilines message using the following line separators, they will all work:
4242
4343- `sLineBreak`
4444- [[End of Line|LineEnding]]
4545- or the character code: \#13#10
4646
4747**Multiple lines example:**
4848
4949``` pascal
5050program LazMessage;
5151uses
5252 Dialogs;
5353begin
5454 ShowMessage('This is a multilines' + sLineBreak + 'message!' );
5555end.
5656```
5757
5858### MessageBox
5959
6060``` pascal
6161function Application.MessageBox(Text, Caption: PChar; Flags: LongInt): Integer;
6262```
6363
6464{ Defined in Forms.pp as part of TApplication; hence must be called as Application.Messagebox() or using the '[[With|with]] `Application` [[Do|do]] ...' construct }
6565
6666Parameters include
6767
6868- Text: the string that is displayed as a prompt or instruction in the Box;
6969- Caption: the string label at the top of the message box;
7070- Flags: [[Longint|longint]] - an [[Integer|integer]] constructed by adding together various [[Constant|constants]] to define the contents and behaviour of the box, for example `MB_ABORTRETRYIGNORE + MR_ICONQUESTION` will cause the application to display a query (?) icon in a box with three buttons: ABORT RETRY IGNORE.
7171
7272The function returns an integer value corresponding to the button that was pressed; its value can be determined by reference to the constants \[IDOK..IDHELP\]
7373
7474It can be invoked like a procedure call (ie as a 'MessageBox()' [[statement]] rather than as a 'Variable := MessageBox()' function call - see example below)
7575
7676Example:
7777
7878``` pascal
7979uses
8080 Forms, Dialogs, LCLType;
8181
8282procedure DisplayMessageBox;
8383var
8484 Reply, BoxStyle: Integer;
8585begin
8686 BoxStyle := MB_ICONQUESTION + MB_YESNO;
8787 Reply := Application.MessageBox('Press either button', 'MessageBoxDemo', BoxStyle);
8888 if Reply = IDYES then Application.MessageBox('Yes ', 'Reply',MB_ICONINFORMATION)
8989 else Application.MessageBox('No ', 'Reply', MB_ICONHAND);
9090end;
9191```
9292
9393Notice that in this example the 'Yes' and 'No' strings have been padded out with spaces; otherwise the box would not be wide enough to display the caption properly
9494
95-<center>
96-
9795![](/wiki-images/c/c2/MessageBoxDemo.png) ![](/wiki-images/0/06/ReplyYes.png)
9896
99-</center>
100-
10197### MessageDLG
10298
10399``` pascal
104100function MessageDlg(const aMsg: string; DlgType: TMsgDlgType;
105101 Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer;
106102function MessageDlg(const aCaption, aMsg: string; DlgType: TMsgDlgType;
107103 Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer;
108104```
109105
110106Two versions of this function, ie first 'Caption' parameter is optional; if omitted, caption is missing from box
111107
112108This is the most complete and elaborate of the message dialogs, and allows the programmer considerable control over the appearance of the dialog box. The parameters defining the kind of box and its icon are types rather than integer constants, and the buttons can be specified as a [[Set|set]] in [[square brackets]] eg `[mbRetry, mbIgnore, mbAbort, mbCancel]`. The HelpCtx parameter is not currently implemented and should be set to zero. The return value from the function is the identity of the button pressed, expressed as an integer (see the definitions below, \[mrNone..mrAll\]).
113109
114110Example:
115111
116112``` pascal
117113uses
118114 Forms, Dialogs, LCLType, Controls;
119115
120116procedure TryMessageDlg;
121117begin
122118 if MessageDlg('Question', 'Do you wish to Execute?', mtConfirmation,
123119 [mbYes, mbNo, mbIgnore],0) = mrYes
124120 then { Execute rest of Program };
125121end;
126122```
127123
128-<center>
129-
130-<figure>
131-<img src="Question.png" title="Question.png" />
132-<figcaption>Question.png</figcaption>
133-</figure>
134-
135-</center>
124+![](/wiki-images/3/30/Question.png)
136125
137126### QuestionDlg
138127
139128Question dialog allows changing button captions and setting default and cancel buttons. The 3rd argument in the `QuestionDlg()` call determines the icon shown in the dialog. In some widgetsets, the icon can be suppressed by selecting message type `mtCustom`.
140129
141130Example:
142131
143132``` pascal
144133 case QuestionDlg('Caption', 'Message', mtInformation, [mrYes, 'Positive', mrNo, 'Negative', 'IsDefault'], '') of
145134 mrYes: QuestionDlg('Caption', 'So you mean „Yes“', mtCustom, [mrOK, 'That is right'],'');
146135 mrNo: QuestionDlg('Caption', 'Oh, you mean „No“', mtCustom, [mrOK, 'Exactly'], '');
147136 mrCancel: QuestionDlg('Caption', 'You cancelled the dialog with ESC or close button.', mtCustom, [mrOK, 'Exactly'], '');
148137 end;
149138```
150139
151-<center>
152-
153-<figure>
154-<img src="QuestionDlg.png" title="QuestionDlg.png" />
155-<figcaption>QuestionDlg.png</figcaption>
156-</figure>
157-
158-</center>
140+![](/wiki-images/a/ac/QuestionDlg.png)
159141
160142> **Note:** If the user cancels the dialog and there is no 'IsCancel' button defined, mrCancel is returned! If you want to redirect ESC/close to a defined button use the 'IsCancel' parameter just after the cancel button.
161143
162144> **Warning:** Do not confuse here the `mrXXXX` button identifiers with the `mbXXXX` identifiers used by MessageDlg, otherwise the return value will not be correct.
163145
164146Advanced examples for buttons (from promptdialog.inc)
165147
166148``` pascal
167149 [mrOk, mrCancel, 'Cancel now', mrIgnore, 300, 'Do it', 'IsDefault']
168150```
169151
170152This will result in 4 buttons:
171153
172154- 'Ok' returning mrOk
173155- 'Cancel now' returning mrCancel
174156- 'Ignore' returning mrIgnore
175157- 'Do it' returning 300. This will be the default button (focused)
176158
177159Usually buttons in Lazarus dialogs have icons. In order to prevent icons from being shown non standardize values for message results can be used. Currently highest standardized value is 11. For example:
178160
179161``` pascal
180162 case QuestionDlg ('Caption','Message',mtCustom,[20,'Positive', 21, 'Negative',22,'I do not know','IsCancel'],'') of
181163 20: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[20,'That is right'],'');
182164 21: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[21,'Exactly'],'');
183165 22: QuestionDlg ('Caption','So, please find out!',mtCustom,[22,'Maybe'],'');
184166 end;
185167```
186168
187169In order to facilitate work, constants can be defined. For example:
188170
189171``` pascal
190172const
191173 mrNoneNI= 20; // "NI" to indicate: "no icon"
192174 mrOkNI= mrNoneNI+1;
193175 mrCancelNI= mrNoneNI+2;
194176 mrAbortNI= mrNoneNI+3;
195177 mrRetryNI= mrNoneNI+4;
196178 mrIgnoreNI= mrNoneNI+5;
197179 mrYesNI= mrNoneNI+6;
198180 mrNoNI= mrNoneNI+7;
199181 mrAllNI= mrNoneNI+8;
200182 mrYesToAllNI= mrNoneNI+10;
201183 mrCloseNI= mrNoneNI+11;
202184 mrLastNI= mrCloseNI;
203185begin
204186 case QuestionDlg ('Caption','Message',mtCustom,[mrYesNI,'Positive', mrNoNI, 'Negative',mrCancelNI,'I do not know','IsCancel'],'') of
205187 mrYesNI: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[mrYesNI,'That is right'],'');
206188 mrNoNI: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[mrNoNI,'Exactly'],'');
207189 mrCancelNI: QuestionDlg ('Caption','So, please find out!',mtCustom,[mrCancelNI,'Maybe'],'');
208190 end; //case
209191end;
210192```
211193
212-<center>
213-
214-<figure>
215-<img src="QuestionDlgNoButIcons.png" title="QuestionDlgNoButIcons.png" />
216-<figcaption>QuestionDlgNoButIcons.png</figcaption>
217-</figure>
218-
219-</center>
194+![](/wiki-images/1/15/QuestionDlgNoButIcons.png)
220195
221196## Text input Dialogs
222197
223198### InputBox
224199
225200Text input Dialogs: display a message and await user text input
226201
227202``` pascal
228203function InputBox(const ACaption, APrompt, ADefault: String): String;
229204```
230205
231206Displays a box with defined title and prompt, and expects user input in a text box. A default string can optionally be displayed in the text box. The user-entered or default string is returned as the function result. If user clicks Cancel, default string is returned as the function result.
232207
233208Example:
234209
235210``` pascal
236211uses
237212 Forms, LCLType, Dialogs, Controls;
238213
239214procedure TryInputBox;
240215var
241216 UserString: string;
242217begin
243218 UserString := InputBox('Get some text input',
244219 'Please type in some information', 'Some sample text');
245220 ShowMessage(UserString)
246221end;
247222```
248223
249224### InputQuery
250225
251226``` pascal
252227function InputQuery(const ACaption, APrompt : String;
253228 MaskInput : Boolean; var Value : String) : Boolean;
254229function InputQuery(const ACaption, APrompt : String;
255230 var Value : String) : Boolean;
256231```
257232
258233Two versions of this function which displays a prompt and expects user input of textual data; the first includes a MaskInput [[Boolean|boolean]] parameter which determines whether the user input is masked out by [[*|asterisks (*)]] in the text-input box (like during entry of a password), while the second omits this property. The text entered by the user is returned in the variable parameter 'Value'; the function result is a boolean which returns [[True|true]] if the OK button was pressed, or [[False|false]] if the box was closed by any other mechanism (such as clicking the 'Close' icon on the top title bar). Omitting the MaskInput parameter is equivalent to setting it `false`.
259234
260235Example:
261236
262237``` pascal
263238uses
264239 Forms, LCLType, Dialogs, Controls;
265240
266241procedure TryInputQuery;
267242var
268243 QueryResult: Boolean;
269244 UserString: string;
270245begin
271246 if InputQuery('Question', 'Type in some data', TRUE, UserString)
272247 then ShowMessage(UserString)
273248 else
274249 begin
275250 InputQuery('Don''t be silly', 'Please try again', UserString);
276251 ShowMessage(UserString);
277252 end
278253end;
279254```
280255
281-<center>
282-
283-<figure>
284-<img src="MessageDlgQuestion.png" title="MessageDlgQuestion.png" />
285-<figcaption>MessageDlgQuestion.png</figcaption>
286-</figure>
287-
288-</center>
289-
290-<center>
291-
292-<figure>
293-<img src="DontBeSillly.png" title="DontBeSillly.png" />
294-<figcaption>DontBeSillly.png</figcaption>
295-</figure>
256+![](/wiki-images/d/d0/MessageDlgQuestion.png)
296257
297-</center>
258+![](/wiki-images/c/ce/DontBeSillly.png)
298259
299260### PasswordBox
300261
301262``` pascal
302263Function PasswordBox(const ACaption, APrompt : String) : String;
303264```
304265
305266Behaves very similarly to the InputQuery function with MaskInput = TRUE; the difference is that the password that was typed in is returned as the result of the function (like InputBox).
306267
307268## Constants and Types used in message dialogs
308269
309270Several constants and types relevant for use with the dialog boxes are pre-defined in the [[LCL]] library:
310271
311272const { Defined in LCLType.pp }
312273
313274integer constants for defining the types of buttons and the icon for display in MessageBox
314275
315276``` pascal
316277MB_OK = $00000000;
317278MB_OKCANCEL = $00000001;
318279MB_ABORTRETRYIGNORE = $00000002;
319280MB_YESNOCANCEL = $00000003;
320281MB_YESNO = $00000004;
321282MB_RETRYCANCEL = $00000005;
322283
323284
324285MB_ICONHAND = $00000010;
325286MB_ICONQUESTION = $00000020;
326287MB_ICONEXCLAMATION = $00000030;
327288MB_ICONASTERICK = $00000040;
328289MB_ICONWARNING = MB_ICONEXCLAMATION;
329290MB_ICONERROR = MB_ICONHAND;
330291MB_ICONINFORMATION = MB_ICONASTERICK;
331292```
332293
333294integer constants defining the return value from MessageBox according to which button was pressed
334295
335296``` pascal
336297IDOK = 1; ID_OK = IDOK;
337298IDCANCEL = 2; ID_CANCEL = IDCANCEL;
338299IDABORT = 3; ID_ABORT = IDABORT;
339300IDRETRY = 4; ID_RETRY = IDRETRY;
340301IDIGNORE = 5; ID_IGNORE = IDIGNORE;
341302IDYES = 6; ID_YES = IDYES;
342303IDNO = 7; ID_NO = IDNO;
343304IDCLOSE = 8; ID_CLOSE = IDCLOSE;
344305IDHELP = 9; ID_HELP = IDHELP;
345306```
346307
347308define whether first, second or third button is default
348309
349310``` pascal
350311MB_DEFBUTTON1 = $00000000;
351312MB_DEFBUTTON2 = $00000100;
352313MB_DEFBUTTON3 = $00000200;
353314MB_DEFBUTTON4 = $00000300;
354315```
355316
356317The Flags parameter of MessageBox is constructed by adding a button constant \[MB_OK..MB_RETRYCANCEL\], an optional icon constant \[MB_ICONHAND..MB_ICONINFORMATION\] and an optional default button constant \[MB_DEFBUTTON1..MB_DEFBUTTON3\]
357318
358319Types for use in MessageDlg, which needs parameters AType of TMsgDlgType and AButtons of TMSgDlgButtons
359320
360321``` pascal
361322{ Defined in Dialogs.pp }
362323type
363324 TMsgDlgType = (mtWarning, mtError, mtInformation, mtConfirmation,
364325 mtCustom);
365326 TMsgDlgBtn = (mbYes, mbNo, mbOK, mbCancel, mbAbort, mbRetry, mbIgnore,
366327 mbAll, mbNoToAll, mbYesToAll, mbHelp, mbClose);
367328 TMsgDlgButtons = set of TMsgDlgBtn;
368329
369330
370331const
371332 mbYesNoCancel = [mbYes, mbNo, mbCancel];
372333 mbOKCancel = [mbOK, mbCancel];
373334 mbAbortRetryIgnore = [mbAbort, mbRetry, mbIgnore];
374335
375336
376337 MsgDlgBtnToBitBtnKind: array[TMsgDlgBtn] of TBitBtnKind = (
377338 bkYes, bkNo, bkOK, bkCancel, bkAbort, bkRetry, bkIgnore,
378339 bkAll, bkNoToAll, bkYesToAll, bkHelp, bkClose
379340 );
380341
381342
382343 BitBtnKindToMsgDlgBtn: array[TBitBtnKind] of TMsgDlgBtn = (
383344 mbOk, mbOK, mbCancel, mbHelp, mbYes, mbNo,
384345 mbClose, mbAbort, mbRetry, mbIgnore, mbAll, mbNoToALl, mbYesToAll
385346 );
386347
387348
388349{ Defined in Controls.pp }
389350const
390351 mrNone = 0;
391352 mrOK = mrNone + 1;
392353 mrCancel = mrNone + 2;
393354 mrAbort = mrNone + 3;
394355 mrRetry = mrNone + 4;
395356 mrIgnore = mrNone + 5;
396357 mrYes = mrNone + 6;
397358 mrNo = mrNone + 7;
398359 mrAll = mrNone + 8;
399360 mrNoToAll = mrNone + 9;
400361 mrYesToAll = mrNone + 10;
401362 mrLast = mrYesToAll;
402363```
403364
404365---
405366*From the Free Pascal wiki, page "Dialog Examples", as it stood on 2021-11-24 after a change by Wp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history