Input Dialog Boxes
- 6 minutes to read
An input box is a modal dialog designed to prompt a user to input one or more string values. DevExpress input boxes support skins and can validate entered values.
Create a Skinnable Input Box
Skinnable input dialog boxes allow you to keep the appearance of your application consistent. They import all look & feel settings from the TdxSkinController component if it is in an application project. To create such an input box, call one of the following global DevExpress methods declared in the dxInputDialogs unit:
- dxInputBox(string,string,string)
- Invokes a modal input dialog box that prompts a user to confirm the displayed text string or change it.
- dxInputQuery(string,string,string)
- Invokes a modal input dialog box that prompts a user to enter a string.
- dxInputQuery(string,string,string,TdxInputQueryValidationProc)
- Invokes a modal input dialog box that prompts a user to enter a string and checks if the user input is valid.
- dxInputQuery(string,string[],string[])
- Invokes a modal input dialog box that prompts a user to enter multiple text strings.
- dxInputQuery(string,string[],string[],TdxInputQueryValidationProc)
- Invokes an input dialog box that allows users to enter a string.
- dxSelectQuery(string,string,TStrings,string,Boolean,TdxInputQueryValidationProc)
- Invokes a modal input dialog box that allows users to select a value in a combo box.
Display Password Characters
An input dialog box can display password characters instead of actual user input in any text box. To display password characters in a text box, prepend an ASCII character whose number is less than 32 (for example, #31 in Delphi or /x31 in C++Builder) to the caption of the target text box as demonstrated in the following code example:
uses
dxInputDialogs; // This unit declares the dxInputQuery function
// ...
var
APrompts, AValues: array of string;
begin
SetLength(APrompts, 5);
SetLength(AValues, 5);
APrompts[0] := 'First Name:';
APrompts[1] := 'Last Name';
APrompts[2] := 'E-mail:';
APrompts[3] := #31'Password:'; // Displays user input as password characters for "Password"
APrompts[4] := #31'Repeat Password:'; // Displays user input as password characters for "Repeat Password"
dxInputQuery('New User', APrompts, AValues);
// ...
end;
Note
Displayed password characters depend on the current global look & feel settings. If the native style is enabled, a modal input dialog box displays bullets as password characters. Otherwise, the dialog box displays asterisks.
Validate User Input
You can validate user input for all or only specific text boxes displayed by an input box dialog. If user input is treated as invalid, the OK button is disabled and the Enter keystroke is ignored. The following input box creation methods can accept a validation routine as the optional AValidationProc parameter:
- dxInputQuery(string,string,string,TdxInputQueryValidationProc)
- Invokes a modal input dialog box that prompts a user to enter a string and checks if the user input is valid.
- dxInputQuery(string,string[],string[],TdxInputQueryValidationProc)
- Invokes an input dialog box that allows users to enter a string.
- dxSelectQuery(string,string,TStrings,string,Boolean,TdxInputQueryValidationProc)
- Invokes a modal input dialog box that allows users to select a value in a combo box.
A validation routine has the TdxInputQueryValidationProc type. The IsValid parameter value determines if user input is treated as valid. The ValueIndex property value indicates the currently evaluated text box value returned as the Value parameter. You can specify any condition in the validation routine for one or more user input values.
Code Example
If you need to display password characters instead of actual user input, prepend an ASCII character whose number is less than 32 (for example, #31 in Delphi or /x31 in C++Builder) to one or more values passed as the APrompts parameter. The following code example invokes a modal input dialog box with five text editors that should not be empty. The last two editors accept identical passwords.
uses
dxInputDialogs; // This unit declares the dxInputQuery function
// ...
type
TMyForm = class(TForm)
AddUserButton: TcxButton; // The button that invokes an input dialog box
dxSkinController1: TdxSkinController;
procedure AddUserButtonClick(Sender: TObject);
procedure ValidationProcedure(ValueIndex: Integer; const Value: string; var IsValid: Boolean);
private
{ Private declarations }
APassword: string; // Stores a password for comparison
public
{ Public declarations }
end;
procedure TMyForm.ValidationProcedure(ValueIndex: Integer; const Value: string; var IsValid: Boolean);
begin
if Value = '' then // The "OK" button is disabled if at least one editor is empty
IsValid := False;
if ValueIndex = 3 then
APassword := Value; // Stores a password for comparison
if ValueIndex = 4 then
if APassword <> Value then // Compares two password entries
IsValid := False; // The "OK" button is disabled if the password entries do not match
end;
procedure TMyForm.AddUserButtonClick(Sender: TObject);
var
APrompts, AValues: array of string;
begin
SetLength(APrompts, 5);
SetLength(AValues, 5);
APrompts[0] := 'First Name:';
APrompts[1] := 'Last Name';
APrompts[2] := 'E-mail:';
APrompts[3] := #31'Password:'; // Displays user input as password characters for "Password"
APrompts[4] := #31'Repeat Password:'; // Displays user input as password characters for "Repeat Password"
dxInputQuery('New User', APrompts, AValues, ValidationProcedure);
end;