Dialog Examples

│ 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.

Message Dialogs

Message dialogs display a message and wait for a key-press or mouse-click response.

ShowMessage

<delphi>procedure ShowMessage(const Msg: string);</delphi>

{ 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:

<delphi>program LazMessage; uses

 Dialogs;

begin

 ShowMessage('This is a message from Lazarus');

end.</delphi>

MessageBox

<delphi>function Application.MessageBox(Text, Caption: PChar; Flags: LongInt): Integer;</delphi>

{ 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:

<delphi>uses

 Forms, Dialogs, LCLType;

procedure DisplayMessageBox; var

 Reply, BoxStyle: Integer;

begin

 with Application do begin
   BoxStyle := MB_ICONQUESTION + MB_YESNO;
   Reply := MessageBox('Press either button', 'MessageBoxDemo', BoxStyle);
   if Reply = IDYES then MessageBox('Yes       ', 'Reply',MB_ICONINFORMATION)
     else MessageBox('No         ', 'Reply', MB_ICONHAND);
 end;

end;</delphi>

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

http://lazarus-ccr.sourceforge.net/kbdata/MessageBoxDemo.png http://lazarus-ccr.sourceforge.net/kbdata/ReplyYes.png

MessageDLG

<delphi>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;</delphi>

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:

<delphi>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;</delphi>

http://lazarus-ccr.sourceforge.net/kbdata/Question.png

Text input Dialogs

InputBox

Text input Dialogs: display a message and await user text input

<delphi>function InputBox(const ACaption, APrompt, ADefault: String): String;</delphi>

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.

Example:

<delphi>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;</delphi>

InputQuery

<delphi>function InputQuery(const ACaption, APrompt : String;

 MaskInput : Boolean; var Value : String) : Boolean;

function InputQuery(const ACaption, APrompt : String;

 var Value : String) : Boolean;</delphi>

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:

<delphi>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('Dont be silly', 'Please try again', UserString);
   ShowMessage(UserString);
 end

end;</delphi>

http://lazarus-ccr.sourceforge.net/kbdata/MessageDlgQuestion.png http://lazarus-ccr.sourceforge.net/kbdata/DontBeSillly.png

PasswordBox

<delphi>Function PasswordBox(const ACaption, APrompt : String) : String;</delphi>

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

<delphi>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;</delphi>

integer constants defining the return value from MessageBox according to which button was pressed

<delphi>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;</delphi>

define whether first, second or third button is default

<delphi>MB_DEFBUTTON1 = $00000000; MB_DEFBUTTON2 = $00000100; MB_DEFBUTTON3 = $00000200; MB_DEFBUTTON4 = $00000300;</delphi>

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

<delphi>{ 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;</delphi>