QuestionDlg function

Declaration

function QuestionDlg(const aCaption: string; const aMsg: string; 
 DlgType: TMsgDlgType; Buttons: Array of const; 
 HelpCtx: LongInt): TModalResult; overload

Arguments

Function result

The result of this function is the identifier number for the button that the user pressed to close the dialog.

Description

QuestionDlg has the same functionality as MessageDlg except for the Buttons parameter which is of a different type. You can define your own captions, return values, and optional flags in Buttons using this function.

ACaption contains the text displayed as the title for the dialog form.

AMsg contains the text displayed within the content area for the dialog form. It represents the question to be answered using the dialog.

DlgType contains a value from the TMsgDlgType enumeration, and determines the icon displayed on the dialog form. See TMsgDlgType for the values in the enumeration and their meanings.

Buttons is defined as an array of const values, and contains the numeric identifiers and optional captions and flags for the buttons displayed on the dialog. QuestionDlg examines the values in Buttons, and creates a button instance for each numeric identifier in the array. Usually, the button identifiers are specified using TModalResult constants like mrOk or mrCancel (defined in Controls); these buttons will be decorated with an icon associated with the modal result value. Other integer values can be used as well, but their buttons will not have an icon. The order of the buttons on the dialog form will be the same as the order of the numeric values in the array elements.

Each string following a numeric button identifier denotes the caption for the button. When the button identifier is one of the default TModalResult values defined in controls.pp (mrNone..mrLast), the caption can be omitted and the default caption will be used. For non-TModalResult identifiers, the caption MUST be specified. An empty string is not allowed as a caption; it will raise a run-time error.

You can mark one button as the default button by adding the 'IsDefault' option after the caption string. When the user presses the Return key, this button is triggered. An exception is raised if more than one button has the 'IsDefault' designation.

Some widgetsets provide an Escape key and/or a close button for the dialog. This results in mrCancel in the return value, even if it is not in the given button list. Use the 'IsCancel' option after the caption string to cause the button to close the dialog. An exception is raised if more than one button has the 'IsCancel' designation.

You can use both 'IsDefault' and 'IsCancel' flags values for a given button by including both strings as arguments following the caption value. Values in button flags are case-insensitive; 'IsDefault' is considered the same as 'isdefault'.

The numeric identifier for the button clicked on the dialog is returned by the QuestionDlg() function.

The overloaded routines allow a help topic to be displayed when the F1 key is pressed. HelpCtx is the numeric identifier for the help topic passed as an argument to the AskUser routine in the widgetset. HelpKeyword is a string value that identifies the help topic. Please note that HelpKeyword is not implemented in the current LCL version; the numeric help context 0 is always used in the overloaded routine.

Examples:

var
  res: TModalResult;
//...

// OK, Cancel dialog using default button captions
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, mrCancel], 0);
//...


// OK, Cancel dialog with custom button captions and accelerator keys
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, '&Do it!', mrCancel, '&Nope'], 0);
//...

// custom modal result values and captions
res := QuestionDlg('Question', 'Is it Okay?', mtConfirmation,
 [400, 'Yes!!!', 401, 'Not cool', 402, 'My mistake'], 0);  
//...

// Yes, No, Cancel with custom captions and button flags
res := QuestionDlg('COPYING', 'Abort?', mtConfirmation,
  [mrNo,'&No', mrYes,'&Yes', mrCancel, '&Cancel', 'IsDefault', 'IsCancel'], 0);

case res of
  mrYes: ShowMessage('You clicked Yes');
  mrNo: ShowMessage('You clicked No');
else
  // mrCancel
  ShowMessage('You cancelled the dialog.');
end;

See also

• MessageDlg
• InputQuery
• DefaultQuestionDialog