Contents

The following Help Topics are available:

TInputDialog Component

TMessageDialog Component

Copyright © 1996 Christopher S. Lim. All Rights Reserved.

Christopher S. Lim

517 Cobb Court

La Puente, CA 91746

Compuserve: 74542,1670

Internet: 74542.1670@compuserve.com


TInputDialog Component

The TInputDialog component replaces the Delphi InputQuery function.  The purpose of TInputDialog is to display an input dialog box ready for the user to enter a string in its edit box.

Differences Between InputQuery and TInputDialog

Properties

Caption

Cursor

HelpContext

LineSeparator

MsgBeep

Position

PositionLeft

PositionTop

Prompt

StayOnTop

Text

WaveFile

Methods

Execute

ExecuteFmt


TMessageDialog Component

The TMessageDialog component replaces the Delphi MessageDlg function.  The purpose of TMessageDialog is to display a message dialog box on the screen.

Differences between MessageDlg and TMessageDialog

Properties

Buttons

Caption

Cursor

DefaultButton

HelpContext

LineSeparator

MsgBeep

MsgType

Position

PositionLeft

PositionTop

StayOnTop

Text

WaveFile

Methods

Execute

ExecuteFmt


Caption property (TInputDialog)

property Caption : String;

The Caption property is the text that appears in dialog box's title bar.

Example

   InputDialog1.Caption := 'Hello, World!';


Caption property (TMessageDialog)

property Caption : String;

The Caption property is the text that appears in message box's title bar.

If you leave the Caption blank, the message box displays a default caption according to the value in the MsgType property.

Example

   MessageDialog1.Caption := 'Hello, World!';


Prompt property

property Prompt : String;

The Prompt property is the text that prompts the user to  enter input in the edit box. You can define multi-line prompts by embedding LineSeparator strings within the text.

Example

   InputDialog1.Prompt := 'Enter Your Name:';


Cursor property

property Cursor : TCursor;

The Cursor property specifies the mouse cursor type when the dialog box is visible.

Refer to the description of TCursor in Delphi's on-line help for the different cursor types.

Example

This line of code changes the display of the cursor image to the default cursor when the user moves the mouse pointer over the dialog box.

   Dialog1.Cursor := crDefault;


HelpContext property

property HelpContext: LongInt;

The HelpContext property determines which Help screen is available for  the message box. (For more information on the HelpContext property, refer to the Delphi on-line help.)

Example

The following code associates a Help file with the application, and makes the screen with context number 7 the context-sensitive Help screen for the dialog box.

   Application.HelpFile := 'MYHELP.HLP';

   Dialog1.HelpContext := 7;


LineSeparator property (TMessageDialog)

property LineSeparator: String;

The LineSeparator property allows you to display the value of the Text property as multiple lines. The LineSeparator property defines the string used to indicate the start of a new line.

Example

   MessageDialog1.LineSeparator := '\n';

   MessageDialog1.Text := 'This is Line 1\nThis is Line 2';


LineSeparator property (TInputDialog)

property LineSeparator: String;

The LineSeparator property allows you to display the value of the Prompt property as multiple lines. The LineSeparator property defines the string used to indicate the start of a new line.

Example

   InputDialog1.LineSeparator := '\n';

   InputDialog1.Prompt := 'This is Line 1\nThis is Line 2';


MsgBeep property

property MsgBeep: TMsgDlgBeepType;

The MsgBeep property specifies whether you want an audible sound when the dialog box appears.  Except for the mbWaveFile and mbNone values, you associate a waveform (.WAV) file with each MsgBeep value through the Sound application in the Windows Control Panel. The valid MsgBeep values are:

Value	Meaning
mbNone	No sound
mbStandard	Standard beep
mbCriticalStop	Plays the .WAV file associated with the Critical Stop Event.
mbQuestion	Plays the .WAV file associated with the Question Event.
mbExclamation	Plays the .WAV file associated with the Exclamation Event.
mbAsterisk	Plays the .WAV file associated with the Asterisk Event.
mbInformation	Plays the .WAV file associated with the Information Event.
mbWaveFile	Plays the waveform file specified by the WaveFile property.

Example

This line of code will sound the standard beep whenever dialog box is displayed.

   Dialog1.MsgBeep := mbStandard;


Position property

property Position: TMsgDlgPosition;

The Position property determines the placement of the dialog box when it appears in your application.  These are the possible values:

Value	Meaning
poScreenCenter	The dialog box is positioned in the center of the screen.
poParentCenter	The dialog box is positioned in the center of the owner's form.  If the owner's form is an MDI child window, the dialog box is positioned in the center of the Application's MainForm.
poDesigned	The dialog box is positioned in the coordinates determined by the PositionLeft and PositionTop properties.

NOTE: The Position property takes effect only during run-time.  When you view the dialog box at design-time, the dialog box always appears at the center of the screen.

Example

   Dialog1.Position := poParentCenter;


PositionLeft, PositionTop properties

property PositionLeft, PositionTop: Integer;

The PositionLeft and PositionTop properties determine the top left corner of the dialog box relative to the screen in pixels.  PositionLeft and PositionTop are used only if the Position property is set to poDesigned.

Example

This example displays the dialog box in the top left corner of the screen.

   with Dialog1 do

   begin

     Position := poDesigned;

     PositionLeft := 0;

     PositionTop := 0;

   end;


Text property (TInputDialog)

property Text: String;

The Text property is the string that appears in the edit box when the dialog box first appears.  At run-time, if the user changes the string in the edit box and chooses OK, you can use the Text property to read the new value.

Example

This example initializes the input dialog's edit box to display an empty string.

   InputDialog1.Text := '';


Execute method (TInputDialog)

function Execute : Boolean;

Use the Execute method to display the dialog box.  The Execute method returns TRUE if the user chooses OK, and FALSE if the user chooses CANCEL or presses the Esc key.

Example

This example displays an input dialog box to get the user's name.

   function GetName:String;

   begin

     Result := '';

     with InputDialog1 do

     begin

       Text := Result;

       Prompt := 'Enter your name'

       if Execute then Result := Text;

     end;

   end;


ExecuteFmt method (TInputDialog)

function ExecuteFmt(const Args : array of const) : Boolean;

The ExecuteFmt method is similar to the Execute method except that  the Prompt property is treated as an Object Pascal format string. You pass a series of arguments when you call ExecuteFmt.  For more information on format strings, refer to the description of the Format function in Delphi's on-line help. The ExecuteFmt method returns TRUE if the user chooses OK, and FALSE if the user chooses CANCEL or presses the Esc key.

Example

This example asks for a person's name.

   function GetName(IsMale:Boolean):String;

   begin

     with InputDialog1 do

     begin

       Text := '';

       Prompt := 'Enter %s name:';

       if IsMale then

       begin

         {Prompt = 'Enter his name:' }

         if ExecuteFmt(['his']) then

           Result := Text;

       end

       else

       begin

         {Prompt = 'Enter her name:' }

         if ExecuteFmt(['her']) then

           Result := Text;

       end;

     end;

   end;


Execute method (TMessageDialog)

function Execute : Boolean;

The Execute method displays the dialog box and returns the value of the button that the user selected. These are the possible return values:

Return Value	If the User chose...
mrOK	OK button
mrCancel	Cancel button
mrAbort	Abort button
mrRetry	Retry button
mrIgnore	Ignore button
mrYes	Yes button
mrNo	No button
mrAll	All button

Example

This example displays a "Do you want to abort?" message and generates an Abort exception if the user clicks on the YES button.

   procedure ShowErrorMessage;

   begin

     with MessageDialog1 do

     begin

       Text := 'Do you want to Abort?';

       Buttons := [mbYes, mbNo];

       MsgType := mtConfirmation;

       if Execute then Abort;

     end;

   end;


ExecuteFmt method (TMessageDialog)

function ExecuteFmt(const Args : array of const) : Boolean;

The ExecuteFmt method is similar to the Execute method except that  the Text property is treated as an Object Pascal format string. You pass a series of arguments when you call ExecuteFmt.  For more information on format strings, refer to the description of the Format function in Delphi's on-line help. The ExecuteFmt method returns the value of the button that the user selected. These are the possible return values:

Return Value	If the User chose...
mrOK	OK button
mrCancel	Cancel button
mrAbort	Abort button
mrRetry	Retry button
mrIgnore	Ignore button
mrYes	Yes button
mrNo	No button
mrAll	All button

Example

This example displays an error message and generates an Abort exception if the user clicks on the YES button.

   procedure ShowErrorMessage(AMsg : string);

   begin

     with MessageDialog1 do

     begin

       LineSeparator := '\n';

       Text := 'Error: %s\nDo you want to Abort?';

       Buttons := [mbYes, mbNo];

       MsgType := mtError;

       if ExecuteFmt([AMsg]) then Abort;

     end;

   end;


Buttons property

property Buttons: TMsgDlgButtons;

The Buttons property determines which buttons appear in the message box.  You can use the DefaultButton property to specify which button is the default button in the message box.  Buttons is of type TMsgDlgButtons, which is a set, so you can include multiple buttons within the set.  These are the possible values that can be included in the set:

Value	Meaning
mbYes	Yes button
mbNo	No button
mbOK	OK button
mbCancel	Cancel button
mbHelp	Help button
mbAbort	Abort button
mbRetry	Retry button
mbIgnore	Ignore button
mbAll	All button

Example

This example displays three buttons: Yes, No and Cancel.

   MessageDialog1.Buttons := [mbYes,mbNo,mbCancel];


MsgType property

property MsgType: TMsgDlgType;

The MsgType property determines the type of the message box that appears. These are the possible values:

MsgType	Meaning
mtWarning	A message box containing a yellow exclamation point symbol
mtError	A message box containing a red stop sign.
mtInformation	A message box containing a blue "i"
mtConfirmation	A message box containing a green question mark.
mtCustom	A message box containing no bitmap.

Example

   MessageDialog1.MsgType := mtWarning;


Text property (TMessageDialog)

property Text: String;

The Text property is the message that is displayed in the message box.  You can define multi-line messages by embedding LineSeparator strings within the text.

Example

   MessageDialog1.LineSeparator := '\n';

   MessageDialog1.Text := 'This is Line 1\nThis is Line 2';


Differences Between InputQuery and TInputDialog

The TInputDialog component contains all the functionality of Delphi's InputQuery function plus  these added features:

•	The Prompt string can contain multiple lines.

•	You can specify the Position of the dialog box.

•	You can use formatting strings in the prompt (see ExecuteFmt method).

•	You can generate a sound with the MsgBeep property when the dialog box is displayed.

•	You can define the mouse Cursor shape to be displayed when the dialog box is visible.

•	You can specify a waveform file with the WaveFile property which will be played whenever the dialog box is displayed.

•	You can use the StayOnTop property to make sure the dialog box will always be displayed on top of other forms.

•	In Design mode, you can double click the component at any time to preview the dialog box.


Differences between MessageDlg and TMessageDialog

The TMessageDlg component contains all the functionality of Delphi's MessageDlg function plus these added features:

•	The message (Text property) can contain multiple lines.

•	You can specify the Position of the dialog box.

•	You can use formatting strings in the message (see ExecuteFmt method).

•	You can generate a sound with the MsgBeep property when the dialog box is displayed.

•	You can define the mouse Cursor shape to be displayed when the dialog box is visible.

•	You can specify a waveform file with the WaveFile property which will be played whenever the dialog box is displayed.

•	You can use the StayOnTop property to make sure the dialog box will always be displayed on top of other forms.

•	You can set the default button with the DefaultButton property.

•	In Design mode, you can double click the component at any time to preview the dialog box.


DefaultButton (TMessageDialog)

property DefaultButton: TMsgDlgBtn;

The DefaultButton property determines which of the buttons specified in the Buttons property will be the default button in the message box.  These are the possible values:

Value	Meaning
mbYes	Yes button
mbNo	No button
mbOK	OK button
mbCancel	Cancel button
mbHelp	Help button
mbAbort	Abort button
mbRetry	Retry button
mbIgnore	Ignore button
mbAll	All button

Note:  If the value of DefaultButton is not a visible button (as defined in the Buttons property), the default button will be the leftmost button in the message box.

Example

This example specifies a message box with three buttons (Yes, No and Cancel) and makes the No button the default.

   MessageDialog1.Buttons := [mbYes,mbNo,mbCancel];

   MessageDialog1.DefaultButton := mbNo;


StayOnTop

property StayOnType: TMsgDlgStayOnTop;

The StayOnTop property determines the form style of the dialog box. These are the possible values:

Value	Meaning
stAuto	The dialog box will automatically find the best form style such that the dialog box will appear on top of the parent form.
stAlways	The dialog box will always be on top of other forms.

Example

This line of code forces the dialog box to appear on top of other forms:

   Dialog1.StayOnTop := stAlways;


WaveFile

property WaveFile: String;

The WaveFile property specifies the filename of a waveform (.WAV) file. If the MsgBeep property is set to mbWaveFile, the specified waveform file will be played when the dialog box is displayed.

Example

The following code will play the waveform stored in the file 'WELCOME.WAV' whenver the dialog box is displayed:

   Dialog1.WaveFile := 'WELCOME.WAV';

   Dialog1.MsgBeep := mbWaveFile;