User Dialog documentation (v3.05) (17^th September 1998)
Ó 1998 by Tom Peiffer & Guy Besch

Features - Installation - Info - Usage - Properties - Methods - Authors - Thanks

Features

Because we are missing many functionalities in the normal MessageDlg coming with Delphi, we decided to improve the method and make a component of it, coming up with many additional features compared to the MessageDlg. Very nice is the preview option already in the object inspector.

Installation

Delphi 2 & 3: Unzip the file UserDlg.dpl to your Delphi component directory. (e.g.\..\Lib\). Go to the component menu and choose "Install package" and click on "Add" button. Choose the file UserDlg.dpl and click "OK".
The sources of the component can be read in the *.pas files... Have fun.

Info

TUserDlg has been written because we were always missing several functionalities in the MessageDlg method coming with Delphi. We think it's much easier to define a text in the object inspector than doing this by code, especially if you want to display longer texts.
TUserDlg is cardware. Do with it whatever you want. All you have to do for complete legal use is sending us a postcard from you country or town. You'll find our addresses further down.

For us, this is an appreciation that may encourage us for writing other components. If you do so, you may use the component in the way you like. You can change the source of the component and add other features if you want, but the authors do not take any warranty for bad use or eventual program crashes or data loss. If you change the source, be fare enough to leave the names and copyrights of us in the source header. Send us a copy of the sources as we will integrate it in the component. We would prefer that you wouldn't publish new versions without contacting us.

For any comments or suggestions, you may get in contact with the authors by email.

Usage

Just drop the component on your form. Assign values to the properties Title, Message and Buttons and have a look at it by clicking on Preview. For calling the Userdialog from within your programm, just make a UserDlg1.Show. The Return-value will be the button the user clicked on. For more details, have a look at the properties explained below. Have Fun.

Properties

property About ;
Description: Shows a dialog about the authors and features of UserDlg. Works only at design time.

property BackColor : TColor ;
The Backcolor of the dialog. By default, it has the standard background color that is defined in Windows. Use the font property to change the look of the message.

property Buttons : TStringList ;
Enter the captions for your user defined buttons. For each line you enter a caption, a button will be displayed in the dialog.
The buttons are numerated beginning by 0, representing the first button in the TStringList.

property ButtonsCursor : TCursor ;
You may modify the mouse cursor when it is moved over a button

property ButtonsMinWidth : integer ;
Indicates the minimum width of the buttons. By default, UserDlg defines the width of the buttons in function of the caption that is displayed on the buttons. Well, small captions like "No" will define a very small button of a few pixels only that look really ugly. By setting the ButtonsMinWidth property, a button always has a minimum width.

property ButtonsSameWidth : boolean ;
As described in ButtonsMinWidth property above, UserDlg calculates the width of a button in function of its caption. By setting ButtonsSameWidth to true, all buttons will have the same width: the one with the largest caption.

property ButtonsShowGlyph : boolean ;
If set to true, the default Delphi glyphs will appear on the buttons, depending on what caption the buttons have. For example a button with the caption "Cancel" will get a glyph.

property Cancel : integer ;
Set a number greater or equal to 0 for being able to quit the dialog by pressing ESC. The number you enter is the x^th button in then Buttons property. Notice, that the first button has number 0. An invalid entry of Cancel will be ignored and you won't be able of closing the dialog by pressing the ESC button. Also see the Default property.

property CustomIcon : TPicture ;
If you set the Icon property to icCustom, then you can indicate a custom picture that will be displayed in the upper left corner of the dialog. You are not limited to only ICO files, but you can use any file format that is understood by Delphi. The picture file will, after compiling, be included in the EXE file.
If the Icon property is set to a different value than icCustom, the CustomIcon property won't have any effect.

property CustomWAV : string ;
If you set the WAV property to wavFile or wavResource, you may indicate a custom WAV sound that will be played by displaying the dialog.
If your choose wavFile, notice that the WAV will not be included in the EXE file as does the CustomIcon. So, if you hand your application to a third party and you have custom WAV files, these files must be copied too. Also be aware of always having the WAV files in the same directory as your EXE file, and don't use absolute path information, or otherwise your application won't probably run on another computer. Simply type the name of your WAV file and be sure of having the WAV in the application directory, and everything works fine.
If you choose wavResource, then the value property indicates the name of a WAV sound contained in a ResourceFile. For this, you must include the resource file in your project. Unfortunately, it is impossile to listen to thes resource sounds when making a preview in design time.

property Default : integer ;
If you enter a value greate or equal to 0, this x^th button in the buttons TStringList will be focused when showing the dialog. By pressing the ENTER key has the same effect than clicking on the x^th button. If you enter an invalid number for Default, the first button in the list will have the focus. Notice that the buttons begin numerating by 0. Also see the Cancel property.

property Font : TFont ;
Select the font of your text in the dialog.

property Icon : TDefaultIcons ;
Choose out either one of the Windows Default icons (the same as MessageDlg method can use), either no icon at all (icNone) or use a user defined icon (icCustom). This custom icon must be defined in the CustomIcon property.

property Message : TStringList ;
Here comes the message of your dialog. You can break lines manually, but you don't have to. The UserDlg will then break the lines automatically and ensures that the dialog always has a nice look. It is a good idea of not breaking the lines manually, especially if you are using parameters in your message.

property Params : TStringList ;
One of the biggest features in the UserDlg component. You are allowed to use parameters in your message. Parameters are defined just in the same way like in the TQuery component, namly by inserting a double point : in front of a variable name. In the Params property you then may define values for these parameters, either at design time, either at runtime.
The Params property has the following syntax: ParameterName=value. (Notice, no spaces are allowed before and after the = sign). This is the same systax that is used in Windows INI files.
At runtime, you may use the SetParam method for changing the values of a parameter. But alternatively, you may also directly change the Params property by using the TStringList methods and properties. But SetParam is much easier to use.

property Preview ;
Just a very cool and useful function. By clicking on the ... button in the object inspector, you get a preview of your dialog already at design time. (That's the way I like it) This works only at design time and doesn't return any function value. At runtime, use the Show method.

property Title : string ;
Enter the title of the dialog.

property WAV : TWAV ;
Choose out either of the Windows System sounds defined in the Control Panel at the Sounds icon, either no sound at all, or use a custom sound defined in the CustomWAV property.
If you choose wavFile, then the value in CustomWAV indicates the filename of a WAV file.
If you choose wavResource, then the value in CustomWAV indicates the name of a WAV sound contained in a ResourceFile. For this, you must include the resource file in your project. Unfortunately, it is impossile to listen to thes resource sounds when making a preview in design time.

Methods

procedure SetParam (Name : string; Value : variant) ;
If you have defined parameters in your message, you can assign values to these during runtime with this method. Name is the name of the parameter and Value is the value you want to assing to this parameter. Notice that value is of type variant, so you are limited of just using strings. If a name of a parameter is indicated that doesn't exist, it will be ignored.

function Show : integer ;
By calling this function, your dialog will be displayed at runtime. The return value is the index of the button that has been pressed, beginning the enumeration by 0. See the Buttons property for details. For having a preview at design time, use the preview property.

Authors

Thanks

We'd like to thank to Peter Theill, who's wrote nearly the whole code of the CorelButton. We only modified the code for beeing able to add glyphs to the buttons. You may take a look at Peter's website.

Also, we'd like to thank Pedro Paulo from Brasil, who gave us the idea of including sounds in a resource file. Also, see his website.

And a last thank goes to "Nick" from Denmark. It thought that including a cursor property would be very nice (well done).