dxInputQuery(string,string[],string[],TdxInputQueryValidationProc) Method

Invokes an input dialog box that allows users to enter a string.

Declaration

function dxInputQuery(const ACaption: string; const APrompts: array of string; var AValues: array of string; AValidationProc: TdxInputQueryValidationProc): Boolean;

Parameters

Name	Type	Description
ACaption	string	The caption of the invoked input dialog box.
APrompts	string	The array of labels for displayed text editors.
AValues	string	Returns values of the text editors when a user clicks the OK button or presses the Enter key.
AValidationProc	TdxInputQueryValidationProc	The procedure that validates a value entered by a user.

Returns

Type	Description
Boolean	True if a user clicks the OK button or presses the Enter key. False if a user clicks the Cancel or Close button, or presses the Esc key.

Remarks

Call the dxInputQuery function to invoke a simple input dialog box that prompts a user to enter one or more string values. The dialog imports all look & feel settings from the TdxSkinController component if it is in an application project. If you pass a validation routine as the AValidationProc parameter, the invoked dialog box disables the OK button and ignores the Enter keystroke until a user enters all valid values into the displayed text editors.

Code Examples

Create an Input Dialog Box with Simple Validation

The following code example demonstrates a validation routine that disables the OK button and ignores the Enter keystroke if at least one of the displayed text editors is empty:

Delphi

uses
  dxInputDialogs;  // This unit declares the dxInputQuery function
// ...

procedure TMyForm.ValidationProcedure(ValueIndex: Integer; const Value: string; var IsValid: Boolean);
begin
  if Value = '' then  // Disables the "OK" button if at least one editor value is an empty string
    IsValid := False;
end;

procedure TMyForm.cxButton1Click(Sender: TObject);
var
  APrompts, AValues: array of string;
begin
  SetLength(APrompts, 2);
  SetLength(AValues, 2);
  APrompts[0] := 'First Name:';
  APrompts[1] := 'Last Name';
  dxInputQuery('New User', APrompts, AValues, ValidationProcedure);
end;

C++

#include "dxInputDialogs.hpp"  // This header declares the dxInputQuery function
// ...

void __fastcall TMyForm::ValidationProcedure(int ValueIndex, const UnicodeString Value, bool &IsValid)
{
  if(Value == "")  // Disables the "OK" button if at least one editor value is an empty string
    IsValid = false;
}

void __fastcall TMyForm::cxButton1Click(TObject *Sender)
{
  UnicodeString *APrompts = nullptr;
  UnicodeString *AValues = nullptr;

  SetLength(APrompts, 2);
  SetLength(AValues, 2);
  APrompts[0] = "First Name:";
  APrompts[1] = "Last Name:";
  dxInputQuery("New User", APrompts, 2, AValues, 2, ValidationProcedure);
}

Create a Dialog Box for Password Input

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.

Delphi

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;

C++

#include "dxInputDialogs.hpp"  // This header declares the dxInputQuery function
// ...

class TMyForm : public TForm
{
  TcxButton *AddUserButton;  // The button that invokes an input dialog box
  TdxSkinController *dxSkinController1;
  void __fastcall AddUserButtonClick(Sender: TObject);
  void __fastcall ValidationProcedure(int ValueIndex, const UnicodeString Value, bool &IsValid);
private:
  /* Private declarations */
  UnicodeString APassword;  // Stores a password for comparison
public:
  /* Public declarations */
};

void __fastcall TMyForm::ValidationProcedure(int ValueIndex, const UnicodeString Value, bool &IsValid)
{
  if (Value == "")  // The "OK" button is disabled if at least one editor is empty
    IsValid = false;
  if (ValueIndex == 3)
    APassword = Value;  // Stores a password for comparison
  if (ValueIndex == 4)
    if (APassword != Value)  // Compares two password entries
      IsValid = false;  // The "OK" button is disabled if the password entries do not match
}

void __fastcall TMyForm::AddUserButtonClick(TObject *Sender)
{
  UnicodeString *APrompts = nullptr;
  UnicodeString *AValues = nullptr;

  SetLength(APrompts, 5);
  SetLength(AValues, 5);
  APrompts[0] = "First Name:";
  APrompts[1] = "Last Name:";
  APrompts[2] = "E-mail:";
  APrompts[3] = "/x31" "Password:";  // Displays user input as password characters for "Password"
  APrompts[4] = "/x31" "Repeat Password:" // Displays user input as password characters for "Repeat Password"
  dxInputQuery("New User", APrompts, 5, AValues, 5, ValidationProcedure);
}

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.