Difference between revisions of "Dialog Examples"
(12 intermediate revisions by 10 users not shown) | |||
Line 2: | Line 2: | ||
= Some useful dialogs= | = Some useful dialogs= | ||
− | Here are some useful dialogs not found in the Component Palette: | + | Here are some useful dialogs not found in the [[Component Palette]]: |
− | * procedure ShowMessage (const Msg: string); | + | * <syntaxhighlight lang="pascal" inline>procedure ShowMessage (const Msg: string);</syntaxhighlight> |
− | * function MessageBox (Text, Caption : PChar; Flags: Word): Integer; | + | * <syntaxhighlight lang="pascal" inline>function MessageBox (Text, Caption : PChar; Flags: Word): Integer;</syntaxhighlight> |
− | * function MessageDlg (const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt): Word; | + | * <syntaxhighlight lang="pascal" inline>function MessageDlg (const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt): Word;</syntaxhighlight> |
− | * function InputBox (const ACaption, APrompt, ADefault: string); string; | + | * <syntaxhighlight lang="pascal" inline>function InputBox (const ACaption, APrompt, ADefault: string); string;</syntaxhighlight> |
− | * function InputQuery (const ACaption, APrompt: string; var Value: string): Boolean; | + | * <syntaxhighlight lang="pascal" inline>function InputQuery (const ACaption, APrompt: string; var Value: string): Boolean;</syntaxhighlight> |
− | * function PasswordBox(const ACaption, APrompt : String) : String; | + | * <syntaxhighlight lang="pascal" inline>function PasswordBox(const ACaption, APrompt : String) : String;</syntaxhighlight> |
Each 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.<br> | Each 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.<br> | ||
− | The 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 or function. | + | The 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. | ||
==Message Dialogs== | ==Message Dialogs== | ||
Line 18: | Line 19: | ||
===ShowMessage=== | ===ShowMessage=== | ||
− | <syntaxhighlight>procedure ShowMessage(const Msg: string);</syntaxhighlight> | + | <syntaxhighlight lang="pascal">procedure ShowMessage(const Msg: string);</syntaxhighlight> |
{ Defined in Dialogs.pp } | { Defined in Dialogs.pp } | ||
− | The simplest message dialog: takes a simple string as parameter, displays it in a stereotyped box, and waits for a mouse-click or | + | The simplest message dialog: takes a simple [[String|string]] as parameter, displays it in a stereotyped box, and waits for a mouse-click or {{keypress|Enter}}-key event before returning to the calling [[Routine|routine]] or [[Program|program]].<br> |
This 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. | This 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. | ||
Example: | Example: | ||
− | <syntaxhighlight>program LazMessage; | + | <syntaxhighlight lang="pascal"> |
+ | program LazMessage; | ||
uses | uses | ||
Dialogs; | Dialogs; | ||
begin | begin | ||
ShowMessage('This is a message from Lazarus'); | ShowMessage('This is a message from Lazarus'); | ||
− | end.</syntaxhighlight> | + | end. |
+ | </syntaxhighlight> | ||
You have the ability to create multilines message using the following line separators, they will all work: | You have the ability to create multilines message using the following line separators, they will all work: | ||
− | *sLineBreak | + | *<syntaxhighlight lang="pascal" inline>sLineBreak</syntaxhighlight> |
− | *LineEnding | + | *[[End_of_Line|<syntaxhighlight lang="pascal" inline>LineEnding</syntaxhighlight>]] |
*or the character code: #13#10 | *or the character code: #13#10 | ||
'''Multiple lines example:''' | '''Multiple lines example:''' | ||
− | <syntaxhighlight>program LazMessage; | + | <syntaxhighlight lang="pascal"> |
+ | program LazMessage; | ||
uses | uses | ||
Dialogs; | Dialogs; | ||
begin | begin | ||
ShowMessage('This is a multilines' + sLineBreak + 'message!' ); | ShowMessage('This is a multilines' + sLineBreak + 'message!' ); | ||
− | end.</syntaxhighlight> | + | end. |
+ | </syntaxhighlight> | ||
===MessageBox=== | ===MessageBox=== | ||
− | <syntaxhighlight>function Application.MessageBox(Text, Caption: PChar; Flags: LongInt): Integer;</syntaxhighlight> | + | <syntaxhighlight lang="pascal">function Application.MessageBox(Text, Caption: PChar; Flags: LongInt): Integer;</syntaxhighlight> |
− | { Defined in Forms.pp as part of TApplication; hence must be called as Application.Messagebox () or using the 'with Application do ...' construct } | + | { Defined in Forms.pp as part of TApplication; hence must be called as Application.Messagebox() or using the '[[With|<syntaxhighlight lang="pascal" inline>with</syntaxhighlight>]] <syntaxhighlight lang="pascal" inline>Application </syntaxhighlight> [[Do|<syntaxhighlight lang="pascal" inline>do</syntaxhighlight>]] ...' construct } |
Parameters include | Parameters include | ||
Line 57: | Line 62: | ||
* Text: the string that is displayed as a prompt or instruction in the Box; | * Text: the string that is displayed as a prompt or instruction in the Box; | ||
* Caption: the string label at the top of the message box; | * Caption: the string label at the top of the message box; | ||
− | * Flags: longint - an integer constructed by adding together various 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. | + | * Flags: [[Longint|longint]] - an [[Integer|integer]] constructed by adding together various [[Constant|constants]] to define the contents and behaviour of the box, for example <syntaxhighlight lang="pascal" inline> MB_ABORTRETRYIGNORE + MR_ICONQUESTION </syntaxhighlight> will cause the application to display a query (?) icon in a box with three buttons: ABORT RETRY IGNORE. |
The function returns an integer value corresponding to the button that was pressed; its value can be determined by reference to the constants [IDOK..IDHELP] | The function returns an integer value corresponding to the button that was pressed; its value can be determined by reference to the constants [IDOK..IDHELP] | ||
− | It can be invoked like a procedure call (ie as a 'MessageBox()' statement rather than as a 'Variable := MessageBox()' function call - see example below) | + | It can be invoked like a procedure call (ie as a 'MessageBox()' [[statement]] rather than as a 'Variable := MessageBox()' function call - see example below) |
Example: | Example: | ||
− | <syntaxhighlight>uses | + | <syntaxhighlight lang="pascal"> |
+ | uses | ||
Forms, Dialogs, LCLType; | Forms, Dialogs, LCLType; | ||
Line 76: | Line 82: | ||
if Reply = IDYES then Application.MessageBox('Yes ', 'Reply',MB_ICONINFORMATION) | if Reply = IDYES then Application.MessageBox('Yes ', 'Reply',MB_ICONINFORMATION) | ||
else Application.MessageBox('No ', 'Reply', MB_ICONHAND); | else Application.MessageBox('No ', 'Reply', MB_ICONHAND); | ||
− | end;</syntaxhighlight> | + | end; |
+ | </syntaxhighlight> | ||
Notice 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 | Notice 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 | ||
− | <center> [[image:MessageBoxDemo.png]] [[image:ReplyYes.png]] | + | <center> [[image:MessageBoxDemo.png]] [[image:ReplyYes.png]]</center> |
− | </center> | ||
===MessageDLG=== | ===MessageDLG=== | ||
− | <syntaxhighlight>function MessageDlg(const aMsg: string; DlgType: TMsgDlgType; | + | <syntaxhighlight lang="pascal"> |
+ | function MessageDlg(const aMsg: string; DlgType: TMsgDlgType; | ||
Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer; | Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer; | ||
function MessageDlg(const aCaption, aMsg: string; DlgType: TMsgDlgType; | function MessageDlg(const aCaption, aMsg: string; DlgType: TMsgDlgType; | ||
− | Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer;</syntaxhighlight> | + | Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer; |
+ | </syntaxhighlight> | ||
Two versions of this function, ie first 'Caption' parameter is optional; if omitted, caption is missing from box | Two versions of this function, ie first 'Caption' parameter is optional; if omitted, caption is missing from box | ||
This is the most complete and elaborate of the message dialogs, and allows the programmer considerable control over the appearance of the dialog box. | This 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 in square brackets eg [mbRetry, mbIgnore, mbAbort, mbCancel]. | + | 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 <syntaxhighlight lang="pascal" inline>[mbRetry, mbIgnore, mbAbort, mbCancel]</syntaxhighlight>. |
The HelpCtx parameter is not currently implemented and should be set to zero. | The HelpCtx parameter is not currently implemented and should be set to zero. | ||
− | The return value from the | + | The return value from the function is the identity of the button pressed, expressed as an integer (see the definitions below, [mrNone..mrAll]). |
Example: | Example: | ||
− | <syntaxhighlight>uses | + | <syntaxhighlight lang="pascal"> |
+ | uses | ||
Forms, Dialogs, LCLType, Controls; | Forms, Dialogs, LCLType, Controls; | ||
Line 107: | Line 116: | ||
[mbYes, mbNo, mbIgnore],0) = mrYes | [mbYes, mbNo, mbIgnore],0) = mrYes | ||
then { Execute rest of Program }; | then { Execute rest of Program }; | ||
− | end;</syntaxhighlight> | + | end; |
+ | </syntaxhighlight> | ||
− | <center> [[image:Question.png]] | + | <center> [[image:Question.png]]</center> |
− | </center> | ||
=== QuestionDlg === | === QuestionDlg === | ||
− | Question dialog allows changing button captions. | + | Question dialog allows changing button captions and setting default and cancel buttons. The 3rd argument in the <tt>QuestionDlg()</tt> call determines the icon shown in the dialog. In some widgetsets, the icon can be suppressed by selecting message type <tt>mtCustom</tt>. |
+ | |||
Example: | Example: | ||
− | <syntaxhighlight> | + | |
− | case QuestionDlg ('Caption','Message', | + | <syntaxhighlight lang="pascal"> |
− | mrYes: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[mrOK,'That is right'],''); | + | case QuestionDlg('Caption', 'Message', mtInformation, [mrYes, 'Positive', mrNo, 'Negative', 'IsDefault'], '') of |
− | mrNo: | + | mrYes: QuestionDlg('Caption', 'So you mean „Yes“', mtCustom, [mrOK, 'That is right'],''); |
+ | mrNo: QuestionDlg('Caption', 'Oh, you mean „No“', mtCustom, [mrOK, 'Exactly'], ''); | ||
+ | mrCancel: QuestionDlg('Caption', 'You cancelled the dialog with ESC or close button.', mtCustom, [mrOK, 'Exactly'], ''); | ||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
− | |||
− | {{Note|If the user cancels the dialog, | + | <center> [[image:QuestionDlg.png]]</center> |
+ | |||
+ | {{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.}} | ||
+ | |||
+ | {{Warning|Do not confuse here the <tt>mrXXXX</tt> button identifiers with the <tt>mbXXXX</tt> identifiers used by MessageDlg, otherwise the return value will not be correct.}} | ||
Advanced examples for buttons (from promptdialog.inc) | Advanced examples for buttons (from promptdialog.inc) | ||
− | <syntaxhighlight> | + | |
− | [mrOk,mrCancel,'Cancel now',mrIgnore,300,'Do it','IsDefault'] | + | <syntaxhighlight lang="pascal"> |
+ | [mrOk, mrCancel, 'Cancel now', mrIgnore, 300, 'Do it', 'IsDefault'] | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | |||
This will result in 4 buttons: | This will result in 4 buttons: | ||
* 'Ok' returning mrOk | * 'Ok' returning mrOk | ||
Line 137: | Line 153: | ||
* 'Do it' returning 300. This will be the default button (focused) | * 'Do it' returning 300. This will be the default button (focused) | ||
− | + | Usually 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: | |
− | |||
− | Usually buttons in Lazarus | ||
− | <syntaxhighlight> | + | <syntaxhighlight lang="pascal"> |
− | case QuestionDlg ('Caption','Message',mtCustom,[20,'Positive', 21, 'Negative',22,'I do not know'],'') of | + | case QuestionDlg ('Caption','Message',mtCustom,[20,'Positive', 21, 'Negative',22,'I do not know','IsCancel'],'') of |
20: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[20,'That is right'],''); | 20: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[20,'That is right'],''); | ||
− | 21: | + | 21: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[21,'Exactly'],''); |
− | 22: | + | 22: QuestionDlg ('Caption','So, please find out!',mtCustom,[22,'Maybe'],''); |
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | |||
In order to facilitate work, constants can be defined. For example: | In order to facilitate work, constants can be defined. For example: | ||
− | <syntaxhighlight> | + | <syntaxhighlight lang="pascal"> |
const | const | ||
− | mrNoneNI= 20; | + | mrNoneNI= 20; // "NI" to indicate: "no icon" |
mrOkNI= mrNoneNI+1; | mrOkNI= mrNoneNI+1; | ||
mrCancelNI= mrNoneNI+2; | mrCancelNI= mrNoneNI+2; | ||
Line 165: | Line 180: | ||
mrLastNI= mrCloseNI; | mrLastNI= mrCloseNI; | ||
begin | begin | ||
− | case QuestionDlg ('Caption','Message',mtCustom,[mrYesNI,'Positive', mrNoNI, 'Negative',mrCancelNI,'I do not know'],'') of | + | case QuestionDlg ('Caption','Message',mtCustom,[mrYesNI,'Positive', mrNoNI, 'Negative',mrCancelNI,'I do not know','IsCancel'],'') of |
mrYesNI: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[mrYesNI,'That is right'],''); | mrYesNI: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[mrYesNI,'That is right'],''); | ||
− | mrNoNI: | + | mrNoNI: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[mrNoNI,'Exactly'],''); |
− | mrCancelNI: | + | mrCancelNI: QuestionDlg ('Caption','So, please find out!',mtCustom,[mrCancelNI,'Maybe'],''); |
end; //case | end; //case | ||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | |||
<center> [[File:QuestionDlgNoButIcons.png]] </center> | <center> [[File:QuestionDlgNoButIcons.png]] </center> | ||
Line 179: | Line 195: | ||
Text input Dialogs: display a message and await user text input | Text input Dialogs: display a message and await user text input | ||
− | <syntaxhighlight>function InputBox(const ACaption, APrompt, ADefault: String): String;</syntaxhighlight> | + | <syntaxhighlight lang="pascal">function InputBox(const ACaption, APrompt, ADefault: String): String;</syntaxhighlight> |
− | Displays 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. | + | Displays 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. |
Example: | Example: | ||
− | <syntaxhighlight>uses | + | <syntaxhighlight lang="pascal"> |
+ | uses | ||
Forms, LCLType, Dialogs, Controls; | Forms, LCLType, Dialogs, Controls; | ||
Line 195: | Line 212: | ||
'Please type in some information', 'Some sample text'); | 'Please type in some information', 'Some sample text'); | ||
ShowMessage(UserString) | ShowMessage(UserString) | ||
− | end;</syntaxhighlight> | + | end; |
+ | </syntaxhighlight> | ||
===InputQuery=== | ===InputQuery=== | ||
− | <syntaxhighlight>function InputQuery(const ACaption, APrompt : String; | + | |
+ | <syntaxhighlight lang="pascal"> | ||
+ | function InputQuery(const ACaption, APrompt : String; | ||
MaskInput : Boolean; var Value : String) : Boolean; | MaskInput : Boolean; var Value : String) : Boolean; | ||
function InputQuery(const ACaption, APrompt : String; | function InputQuery(const ACaption, APrompt : String; | ||
− | var Value : String) : Boolean;</syntaxhighlight> | + | var Value : String) : Boolean; |
+ | </syntaxhighlight> | ||
− | Two versions of this function which displays a prompt and expects user input of textual data; the first includes a MaskInput 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 | + | Two 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|<syntaxhighlight lang="pascal" inline>true</syntaxhighlight>]] if the OK button was pressed, or |
+ | [[False|<syntaxhighlight lang="pascal" inline>false</syntaxhighlight>]] 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 <syntaxhighlight lang="pascal" inline>false</syntaxhighlight>. | ||
Example: | Example: | ||
− | <syntaxhighlight>uses | + | <syntaxhighlight lang="pascal"> |
+ | uses | ||
Forms, LCLType, Dialogs, Controls; | Forms, LCLType, Dialogs, Controls; | ||
Line 222: | Line 245: | ||
ShowMessage(UserString); | ShowMessage(UserString); | ||
end | end | ||
− | end;</syntaxhighlight> | + | end; |
+ | </syntaxhighlight> | ||
<center> [[image:MessageDlgQuestion.png]] </center> | <center> [[image:MessageDlgQuestion.png]] </center> | ||
Line 229: | Line 253: | ||
===PasswordBox=== | ===PasswordBox=== | ||
− | <syntaxhighlight>Function PasswordBox(const ACaption, APrompt : String) : String;</syntaxhighlight> | + | |
+ | <syntaxhighlight lang="pascal">Function PasswordBox(const ACaption, APrompt : String) : String;</syntaxhighlight> | ||
Behaves 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). | Behaves 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). | ||
Line 235: | Line 260: | ||
==Constants and Types used in message dialogs== | ==Constants and Types used in message dialogs== | ||
− | Several constants and types relevant for use with the dialog boxes are pre-defined in the LCL library: | + | Several constants and types relevant for use with the dialog boxes are pre-defined in the [[LCL]] library: |
const { Defined in LCLType.pp } | const { Defined in LCLType.pp } | ||
Line 242: | Line 267: | ||
and the icon for display in MessageBox | and the icon for display in MessageBox | ||
− | <syntaxhighlight>MB_OK = $00000000; | + | <syntaxhighlight lang="pascal"> |
+ | MB_OK = $00000000; | ||
MB_OKCANCEL = $00000001; | MB_OKCANCEL = $00000001; | ||
MB_ABORTRETRYIGNORE = $00000002; | MB_ABORTRETRYIGNORE = $00000002; | ||
Line 256: | Line 282: | ||
MB_ICONWARNING = MB_ICONEXCLAMATION; | MB_ICONWARNING = MB_ICONEXCLAMATION; | ||
MB_ICONERROR = MB_ICONHAND; | MB_ICONERROR = MB_ICONHAND; | ||
− | MB_ICONINFORMATION = MB_ICONASTERICK;</syntaxhighlight> | + | MB_ICONINFORMATION = MB_ICONASTERICK; |
+ | </syntaxhighlight> | ||
integer constants defining the return value from MessageBox according to which button was pressed | integer constants defining the return value from MessageBox according to which button was pressed | ||
− | <syntaxhighlight>IDOK = 1; ID_OK = IDOK; | + | <syntaxhighlight lang="pascal"> |
+ | IDOK = 1; ID_OK = IDOK; | ||
IDCANCEL = 2; ID_CANCEL = IDCANCEL; | IDCANCEL = 2; ID_CANCEL = IDCANCEL; | ||
IDABORT = 3; ID_ABORT = IDABORT; | IDABORT = 3; ID_ABORT = IDABORT; | ||
Line 268: | Line 296: | ||
IDNO = 7; ID_NO = IDNO; | IDNO = 7; ID_NO = IDNO; | ||
IDCLOSE = 8; ID_CLOSE = IDCLOSE; | IDCLOSE = 8; ID_CLOSE = IDCLOSE; | ||
− | IDHELP = 9; ID_HELP = IDHELP;</syntaxhighlight> | + | IDHELP = 9; ID_HELP = IDHELP; |
+ | </syntaxhighlight> | ||
define whether first, second or third button is default | define whether first, second or third button is default | ||
− | <syntaxhighlight>MB_DEFBUTTON1 = $00000000; | + | <syntaxhighlight lang="pascal"> |
+ | MB_DEFBUTTON1 = $00000000; | ||
MB_DEFBUTTON2 = $00000100; | MB_DEFBUTTON2 = $00000100; | ||
MB_DEFBUTTON3 = $00000200; | MB_DEFBUTTON3 = $00000200; | ||
− | MB_DEFBUTTON4 = $00000300;</syntaxhighlight> | + | MB_DEFBUTTON4 = $00000300; |
+ | </syntaxhighlight> | ||
The Flags parameter of MessageBox is constructed by adding a button constant [MB_OK..MB_RETRYCANCEL], | The Flags parameter of MessageBox is constructed by adding a button constant [MB_OK..MB_RETRYCANCEL], | ||
Line 285: | Line 316: | ||
− | <syntaxhighlight>{ Defined in Dialogs.pp } | + | <syntaxhighlight lang="pascal"> |
+ | { Defined in Dialogs.pp } | ||
type | type | ||
TMsgDlgType = (mtWarning, mtError, mtInformation, mtConfirmation, | TMsgDlgType = (mtWarning, mtError, mtInformation, mtConfirmation, | ||
Line 325: | Line 357: | ||
mrNoToAll = mrNone + 9; | mrNoToAll = mrNone + 9; | ||
mrYesToAll = mrNone + 10; | mrYesToAll = mrNone + 10; | ||
− | mrLast = mrYesToAll;</syntaxhighlight> | + | mrLast = mrYesToAll; |
− | + | </syntaxhighlight> | |
− | |||
− |
Latest revision as of 13:18, 24 November 2021
│
Deutsch (de) │
English (en) │
español (es) │
suomi (fi) │
français (fr) │
日本語 (ja) │
polski (pl) │
русский (ru) │
slovenčina (sk) │
中文(中国大陆) (zh_CN) │
Some useful dialogs
Here are some useful dialogs not found in the Component Palette:
procedure ShowMessage (const Msg: string);
function MessageBox (Text, Caption : PChar; Flags: Word): Integer;
function MessageDlg (const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt): Word;
function InputBox (const ACaption, APrompt, ADefault: string); string;
function InputQuery (const ACaption, APrompt: string; var Value: string): Boolean;
function PasswordBox(const ACaption, APrompt : String) : String;
Each 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.
The 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 or 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.
Message Dialogs
Message dialogs display a message and wait for a key-press or mouse-click response.
ShowMessage
procedure ShowMessage(const Msg: string);
{ Defined in Dialogs.pp }
The simplest message dialog: takes a simple 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 or program.
This 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.
Example:
program LazMessage;
uses
Dialogs;
begin
ShowMessage('This is a message from Lazarus');
end.
You have the ability to create multilines message using the following line separators, they will all work:
sLineBreak
LineEnding
- or the character code: #13#10
Multiple lines example:
program LazMessage;
uses
Dialogs;
begin
ShowMessage('This is a multilines' + sLineBreak + 'message!' );
end.
MessageBox
function Application.MessageBox(Text, Caption: PChar; Flags: LongInt): Integer;
{ Defined in Forms.pp as part of TApplication; hence must be called as Application.Messagebox() or using the 'with
Application
do
...' construct }
Parameters include
- Text: the string that is displayed as a prompt or instruction in the Box;
- Caption: the string label at the top of the message box;
- Flags: longint - an integer constructed by adding together various 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.
The function returns an integer value corresponding to the button that was pressed; its value can be determined by reference to the constants [IDOK..IDHELP]
It can be invoked like a procedure call (ie as a 'MessageBox()' statement rather than as a 'Variable := MessageBox()' function call - see example below)
Example:
uses
Forms, Dialogs, LCLType;
procedure DisplayMessageBox;
var
Reply, BoxStyle: Integer;
begin
BoxStyle := MB_ICONQUESTION + MB_YESNO;
Reply := Application.MessageBox('Press either button', 'MessageBoxDemo', BoxStyle);
if Reply = IDYES then Application.MessageBox('Yes ', 'Reply',MB_ICONINFORMATION)
else Application.MessageBox('No ', 'Reply', MB_ICONHAND);
end;
Notice 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
MessageDLG
function MessageDlg(const aMsg: string; DlgType: TMsgDlgType;
Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer;
function MessageDlg(const aCaption, aMsg: string; DlgType: TMsgDlgType;
Buttons: TMsgDlgButtons; HelpCtx: Longint): Integer;
Two versions of this function, ie first 'Caption' parameter is optional; if omitted, caption is missing from box
This 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 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]).
Example:
uses
Forms, Dialogs, LCLType, Controls;
procedure TryMessageDlg;
begin
if MessageDlg('Question', 'Do you wish to Execute?', mtConfirmation,
[mbYes, mbNo, mbIgnore],0) = mrYes
then { Execute rest of Program };
end;
QuestionDlg
Question 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.
Example:
case QuestionDlg('Caption', 'Message', mtInformation, [mrYes, 'Positive', mrNo, 'Negative', 'IsDefault'], '') of
mrYes: QuestionDlg('Caption', 'So you mean „Yes“', mtCustom, [mrOK, 'That is right'],'');
mrNo: QuestionDlg('Caption', 'Oh, you mean „No“', mtCustom, [mrOK, 'Exactly'], '');
mrCancel: QuestionDlg('Caption', 'You cancelled the dialog with ESC or close button.', mtCustom, [mrOK, 'Exactly'], '');
end;
Warning: Do not confuse here the mrXXXX button identifiers with the mbXXXX identifiers used by MessageDlg, otherwise the return value will not be correct.
Advanced examples for buttons (from promptdialog.inc)
[mrOk, mrCancel, 'Cancel now', mrIgnore, 300, 'Do it', 'IsDefault']
This will result in 4 buttons:
- 'Ok' returning mrOk
- 'Cancel now' returning mrCancel
- 'Ignore' returning mrIgnore
- 'Do it' returning 300. This will be the default button (focused)
Usually 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:
case QuestionDlg ('Caption','Message',mtCustom,[20,'Positive', 21, 'Negative',22,'I do not know','IsCancel'],'') of
20: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[20,'That is right'],'');
21: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[21,'Exactly'],'');
22: QuestionDlg ('Caption','So, please find out!',mtCustom,[22,'Maybe'],'');
end;
In order to facilitate work, constants can be defined. For example:
const
mrNoneNI= 20; // "NI" to indicate: "no icon"
mrOkNI= mrNoneNI+1;
mrCancelNI= mrNoneNI+2;
mrAbortNI= mrNoneNI+3;
mrRetryNI= mrNoneNI+4;
mrIgnoreNI= mrNoneNI+5;
mrYesNI= mrNoneNI+6;
mrNoNI= mrNoneNI+7;
mrAllNI= mrNoneNI+8;
mrYesToAllNI= mrNoneNI+10;
mrCloseNI= mrNoneNI+11;
mrLastNI= mrCloseNI;
begin
case QuestionDlg ('Caption','Message',mtCustom,[mrYesNI,'Positive', mrNoNI, 'Negative',mrCancelNI,'I do not know','IsCancel'],'') of
mrYesNI: QuestionDlg ('Caption','So you mean „Yes“',mtCustom,[mrYesNI,'That is right'],'');
mrNoNI: QuestionDlg ('Caption','Oh, you mean „No“',mtCustom,[mrNoNI,'Exactly'],'');
mrCancelNI: QuestionDlg ('Caption','So, please find out!',mtCustom,[mrCancelNI,'Maybe'],'');
end; //case
end;
Text input Dialogs
InputBox
Text input Dialogs: display a message and await user text input
function InputBox(const ACaption, APrompt, ADefault: String): String;
Displays 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.
Example:
uses
Forms, LCLType, Dialogs, Controls;
procedure TryInputBox;
var
UserString: string;
begin
UserString := InputBox('Get some text input',
'Please type in some information', 'Some sample text');
ShowMessage(UserString)
end;
InputQuery
function InputQuery(const ACaption, APrompt : String;
MaskInput : Boolean; var Value : String) : Boolean;
function InputQuery(const ACaption, APrompt : String;
var Value : String) : Boolean;
Two versions of this function which displays a prompt and expects user input of textual data; the first includes a MaskInput 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
if the OK button was pressed, or
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
.
Example:
uses
Forms, LCLType, Dialogs, Controls;
procedure TryInputQuery;
var
QueryResult: Boolean;
UserString: string;
begin
if InputQuery('Question', 'Type in some data', TRUE, UserString)
then ShowMessage(UserString)
else
begin
InputQuery('Don''t be silly', 'Please try again', UserString);
ShowMessage(UserString);
end
end;
PasswordBox
Function PasswordBox(const ACaption, APrompt : String) : String;
Behaves 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).
Constants and Types used in message dialogs
Several constants and types relevant for use with the dialog boxes are pre-defined in the LCL library:
const { Defined in LCLType.pp }
integer constants for defining the types of buttons and the icon for display in MessageBox
MB_OK = $00000000;
MB_OKCANCEL = $00000001;
MB_ABORTRETRYIGNORE = $00000002;
MB_YESNOCANCEL = $00000003;
MB_YESNO = $00000004;
MB_RETRYCANCEL = $00000005;
MB_ICONHAND = $00000010;
MB_ICONQUESTION = $00000020;
MB_ICONEXCLAMATION = $00000030;
MB_ICONASTERICK = $00000040;
MB_ICONWARNING = MB_ICONEXCLAMATION;
MB_ICONERROR = MB_ICONHAND;
MB_ICONINFORMATION = MB_ICONASTERICK;
integer constants defining the return value from MessageBox according to which button was pressed
IDOK = 1; ID_OK = IDOK;
IDCANCEL = 2; ID_CANCEL = IDCANCEL;
IDABORT = 3; ID_ABORT = IDABORT;
IDRETRY = 4; ID_RETRY = IDRETRY;
IDIGNORE = 5; ID_IGNORE = IDIGNORE;
IDYES = 6; ID_YES = IDYES;
IDNO = 7; ID_NO = IDNO;
IDCLOSE = 8; ID_CLOSE = IDCLOSE;
IDHELP = 9; ID_HELP = IDHELP;
define whether first, second or third button is default
MB_DEFBUTTON1 = $00000000;
MB_DEFBUTTON2 = $00000100;
MB_DEFBUTTON3 = $00000200;
MB_DEFBUTTON4 = $00000300;
The 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]
Types for use in MessageDlg, which needs parameters AType of TMsgDlgType and AButtons of TMSgDlgButtons
{ Defined in Dialogs.pp }
type
TMsgDlgType = (mtWarning, mtError, mtInformation, mtConfirmation,
mtCustom);
TMsgDlgBtn = (mbYes, mbNo, mbOK, mbCancel, mbAbort, mbRetry, mbIgnore,
mbAll, mbNoToAll, mbYesToAll, mbHelp, mbClose);
TMsgDlgButtons = set of TMsgDlgBtn;
const
mbYesNoCancel = [mbYes, mbNo, mbCancel];
mbOKCancel = [mbOK, mbCancel];
mbAbortRetryIgnore = [mbAbort, mbRetry, mbIgnore];
MsgDlgBtnToBitBtnKind: array[TMsgDlgBtn] of TBitBtnKind = (
bkYes, bkNo, bkOK, bkCancel, bkAbort, bkRetry, bkIgnore,
bkAll, bkNoToAll, bkYesToAll, bkHelp, bkClose
);
BitBtnKindToMsgDlgBtn: array[TBitBtnKind] of TMsgDlgBtn = (
mbOk, mbOK, mbCancel, mbHelp, mbYes, mbNo,
mbClose, mbAbort, mbRetry, mbIgnore, mbAll, mbNoToALl, mbYesToAll
);
{ Defined in Controls.pp }
const
mrNone = 0;
mrOK = mrNone + 1;
mrCancel = mrNone + 2;
mrAbort = mrNone + 3;
mrRetry = mrNone + 4;
mrIgnore = mrNone + 5;
mrYes = mrNone + 6;
mrNo = mrNone + 7;
mrAll = mrNone + 8;
mrNoToAll = mrNone + 9;
mrYesToAll = mrNone + 10;
mrLast = mrYesToAll;