Table of Contents

Configuring Task Dialog Content

Task dialogs work best when the most important decision is visible immediately and secondary details stay available without taking over the form. Configure the title, instruction, content, footer, optional verification text, and expanded text before calling Execute.

Command Links and Expanded Text

Use CustomButtons with tdoCommandLinks when every option needs its own descriptive row. ExpandedText, ExpandControlText, and CollapseControlText keep troubleshooting or extra context one click away.

procedure TForm1.ConfigureTaskDialog;
begin
  TMSFNCTaskDialog1.Title := 'Save changes';
  TMSFNCTaskDialog1.Instruction := 'Choose how to continue before closing this project.';
  TMSFNCTaskDialog1.Content := 'Unsaved changes will be lost if you close without saving.';
  TMSFNCTaskDialog1.Icon := tdiInformation;
  TMSFNCTaskDialog1.Options := TMSFNCTaskDialog1.Options + [tdoCommandLinks, tdoCommandLinksNoIcon];
  TMSFNCTaskDialog1.CustomButtons.Clear;
  TMSFNCTaskDialog1.CustomButtons.Add('Save and close');
  TMSFNCTaskDialog1.CustomButtons.Add('Close without saving');
  TMSFNCTaskDialog1.CustomButtons.Add('Cancel');
  TMSFNCTaskDialog1.ExpandedText := 'The project file and all open documents are checked before closing.';
  TMSFNCTaskDialog1.ExpandControlText := 'Show details';
  TMSFNCTaskDialog1.CollapseControlText := 'Hide details';
  TMSFNCTaskDialog1.Footer := 'You can change this behavior in application options.';
  TMSFNCTaskDialog1.FooterIcon := tdiWarning;
  TMSFNCTaskDialog1.VerifyText := 'Do not ask again for this project';
  TMSFNCTaskDialog1.Execute;
end;
Task dialog collapsed
Task dialog expanded

Custom Input Controls

Set InputType to titCustom and assign InputControl when the dialog needs an editor that is richer than the built-in text and list inputs. Initialize the embedded control in OnDialogCreated, when the dialog has created the host surface.

procedure TForm1.ShowColorTaskDialog;
begin
  TMSFNCTaskDialog1.Title := 'Pick a highlight color';
  TMSFNCTaskDialog1.Instruction := 'Choose the color used for highlighted rows.';
  TMSFNCTaskDialog1.Icon := tdiInformation;
  TMSFNCTaskDialog1.InputType := titCustom;
  TMSFNCTaskDialog1.InputControl := TMSFNCColorWheel1;
  TMSFNCTaskDialog1.Execute;
end;

procedure TForm1.TMSFNCTaskDialog1DialogCreated(Sender: TObject);
begin
  TTMSFNCColorWheel(TMSFNCTaskDialog1.InputControl).SelectedColor := gcDarkcyan;
end;
Task dialog with a custom color input control

Appearance and Closing Rules

Use Appearance for dialog colors and typography when the dialog needs to match an application theme. DefaultButton selects the initially focused button, and OnBeforeCloseDialog can prevent the dialog from closing until required input is present.

Build a dialog that uses command links, embeds a custom control, and prevents closing until the required field is filled:

procedure TForm1.ShowConfigDialog;
begin
  TMSFNCTaskDialog1.Title       := 'Export Settings';
  TMSFNCTaskDialog1.Instruction := 'Choose an export format and enter a file name.';

  // Command links for each format option
  TMSFNCTaskDialog1.Options := TMSFNCTaskDialog1.Options + [tdoCommandLinks];
  TMSFNCTaskDialog1.CustomButtons.Clear;
  with TMSFNCTaskDialog1.CustomButtons.Add do begin Text := 'PDF'  ; Description := 'Portable Document Format'; end;
  with TMSFNCTaskDialog1.CustomButtons.Add do begin Text := 'Excel'; Description := 'Microsoft Excel workbook'; end;

  // Custom edit control for the file name
  TMSFNCTaskDialog1.InputType    := titCustom;
  TMSFNCTaskDialog1.InputControl := EditFileName;
  TMSFNCTaskDialog1.OnDialogCreated := DoDialogCreated;

  // Expanded section with format notes
  TMSFNCTaskDialog1.ExpandedText       := 'PDF output requires a PDF reader. Excel output requires Office 2016 or later.';
  TMSFNCTaskDialog1.ExpandControlText  := 'Show format notes';
  TMSFNCTaskDialog1.CollapseControlText := 'Hide format notes';

  // Prevent close if no file name entered
  TMSFNCTaskDialog1.OnBeforeCloseDialog := DoBeforeClose;

  TMSFNCTaskDialog1.Execute;
end;

procedure TForm1.DoDialogCreated(Sender: TObject);
begin
  EditFileName.Text := 'output';
  EditFileName.SetFocus;
end;

procedure TForm1.DoBeforeClose(Sender: TObject; AModalResult: TModalResult;
  var ACanClose: Boolean);
begin
  ACanClose := EditFileName.Text <> '';
  if not ACanClose then
    ShowMessage('Enter a file name before closing.');
end;

See Also