delphi xe10.4 TTASKDIALOG帮助介绍-非官方

Ttaskdialog的官方帮助文件介绍了一些属性，但是找了很久没有看到事件处理函数中具体的参数介绍。实在不知道怎么使用定时关闭功能。

转发一个国外的 非官方的介绍。以做备忘。

https://specials.rejbrand.se/TTaskDialog/

InofficialTTaskDialogDocumentation

Andreas Rejbrand, 2011-02-13

Abstract

See also:Task Dialog Message Box with Fluent Interface

This document is an inofficial documentation for theTTaskDialogclass introduced in Delphi 2009, but, unfortunately, not documented by the Embarcadero team.

As the name of the class suggests, it is a wrapper for the task dialog API introduced in the Microsoft Windows Vista operating system. The lack of documentation caused quite some confusion in the Delphi community. Although any moderately competent software developer can figure out how to use the class by investigating its members and the VCL source code (using the MSDN documentation if necessary), it is convenient to have a reference to consult, so that one doesn't need to rediscover the workings of the class each time it is used.

The aim of this document is to be such a reference.

The Hello World of A Task Dialog

with TTaskDialog.Create(Self) do try Caption := 'My Application'; Title := 'Hello World!'; Text := 'I am a TTaskDialog, that is, a wrapper for the Task Dialog introduced ' + 'in the Microsoft Windows Vista operating system. Am I not adorable?'; CommonButtons := [tcbClose]; Execute; finally Free; end;

Captionis the text shown in the titlebar of the window,Titleis the header, andTextis the body matter of the dialog. Needless to say,Executedisplays the task dialog, and the result is shown below. (We will return to theCommonButtonsproperty in a section or two.)

Being A Well-Behaved Citizen

Of course, the task dialog will crash the program if running under Windows XP, where there is not task dialog API. It will also not work if visual themes are disabled. In any such case, we need to stick to the old-fashionedMessageBox. Hence, in a real application, we would need to do

if (Win32MajorVersion >= 6) and ThemeServices.ThemesEnabled then with TTaskDialog.Create(Self) do try Caption := 'My Application'; Title := 'Hello World!'; Text := 'I am a TTaskDialog, that is, a wrapper for the Task Dialog introduced ' + 'in the Microsoft Windows Vista operating system. Am I not adorable?'; CommonButtons := [tcbClose]; Execute; finally Free; end else MessageBox(Handle, 'I am an ordinary MessageBox conveying the same message in order to support' + 'older versions of the Microsoft Windows operating system (XP and below).', 'My Application', MB_ICONINFORMATION or MB_OK);

In the rest of this article, we will assume that the tax of backwards compatibility is being payed, and instead concentrate on the task dialog alone.

Types of Dialogs. Modal Results

TheCommonButtonsproperty is of typeTTaskDialogCommonButtons, defined as

TTaskDialogCommonButton = (tcbOk, tcbYes, tcbNo, tcbCancel, tcbRetry, tcbClose); TTaskDialogCommonButtons = set of TTaskDialogCommonButton;

This property determines the buttons shown in the dialog (if no buttons are added manually, as we will do later on). If the user clicks any of these buttons, the correspondingTModalResultvalue will be stored in theModalResultproperty as soon asExecutehas returned. TheMainIconproperty determines the icon shown in the dialog, and should -- of course -- reflect the nature of the dialog, as should the set of buttons. Formally an integer,MainIconcan be set to any of the valuestdiNone,tdiWarning,tdiError,tdiInformation, andtdiShield.

with TTaskDialog.Create(Self) do try Caption := 'My Application'; Title := 'The Process'; Text := 'Do you want to continue even though [...]?'; CommonButtons := [tcbYes, tcbNo]; MainIcon := tdiNone; // There is no tdiQuestion if Execute then if ModalResult = mrYes then beep; finally Free; end;

Below are samples of the remaining icon types (shield, warning, and error, respectively):

Finally, you should know that you can use theDefaultButtonproperty to set the default button in the dialog box.

with TTaskDialog.Create(Self) do try Caption := 'My Application'; Title := 'The Process'; Text := 'Do you want to continue even though [...]?'; CommonButtons := [tcbYes, tcbNo]; DefaultButton := tcbNo; MainIcon := tdiNone; if Execute then if ModalResult = mrYes then beep; finally Free; end;

Custom Buttons

You can add custom buttons to a task dialog. In fact, you can set theCommonButtonsproperty to the empty set, and rely entirely on custom buttons (and un unlimited number of such buttons, too). The following real-world example shows such a dialog box:

with TTaskDialog.Create(self) do try Title := 'Confirm Removal'; Caption := 'Rejbrand BookBase'; Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]); CommonButtons := []; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Remove'; ModalResult := mrYes; end; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Keep'; ModalResult := mrNo; end; MainIcon := tdiNone; if Execute then if ModalResult = mrYes then DoDelete; finally Free; end

Command Links

Instead of classical pushbuttons, the task dialog buttons can be command links. This is achieved by setting thetfUseCommandLinksflag (inFlags). Now you can also set theCommandLinkHint(per-button) property:

with TTaskDialog.Create(self) do try Title := 'Confirm Removal'; Caption := 'Rejbrand BookBase'; Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]); CommonButtons := []; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Remove'; CommandLinkHint := 'Remove the book from the catalogue.'; ModalResult := mrYes; end; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Keep'; CommandLinkHint := 'Keep the book in the catalogue.'; ModalResult := mrNo; end; Flags := [tfUseCommandLinks]; MainIcon := tdiNone; if Execute then if ModalResult = mrYes then DoDelete; finally Free; end

ThetfAllowDialogCancellationflag will restore the close system menu item (and titlebar button -- in fact, it will restore the entire system menu).

Don't Throw Technical Details at the End User

You can use the propertiesExpandedTextandExpandedButtonCaptionto add a piece of text (the former) that is only displayed after the user clicks a button (to the left of the text in the latter property) to request it.

with TTaskDialog.Create(self) do try Title := 'Confirm Removal'; Caption := 'Rejbrand BookBase'; Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]); CommonButtons := []; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Remove'; CommandLinkHint := 'Remove the book from the catalogue.'; ModalResult := mrYes; end; with TTaskDialogButtonItem(Buttons.Add) do begin Caption := 'Keep'; CommandLinkHint := 'Keep the book in the catalogue.'; ModalResult := mrNo; end; Flags := [tfUseCommandLinks, tfAllowDialogCancellation]; ExpandButtonCaption := 'Technical information'; ExpandedText := 'If you remove the book item from the catalogue, the corresponding *.book file will be removed from the file system.'; MainIcon := tdiNone; if Execute then if ModalResult = mrYes then DoDelete; finally Free; end

The image below shows the dialog after the user has clicked the button to reveal the additional details.

If you add thetfExpandFooterAreaflag, the additional text will instead be shown in the footer:

In any case, you can let the dialog open with the details already expanded by adding thetfExpandedByDefaultflag.

Custom Icons

You can use any custom icon in a task dialog, by using thetfUseHiconMainflag and specifying theTIconto use in theCustomMainIconproperty.

with TTaskDialog.Create(self) do try Caption := 'About Rejbrand BookBase'; Title := 'Rejbrand BookBase'; CommonButtons := [tcbClose]; Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'http://english.rejbrand.se'; Flags := [tfUseHiconMain, tfAllowDialogCancellation]; CustomMainIcon := Application.Icon; Execute; finally Free; end

Hyperlinks

You can even use HTML-like hyperlinks in the dialog (inText,Footer, andExpandedText), if you only add thetfEnableHyperlinksflag:

with TTaskDialog.Create(self) do try Caption := 'About Rejbrand BookBase'; Title := 'Rejbrand BookBase'; CommonButtons := [tcbClose]; Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'<a href="http://english.rejbrand.se">http://english.rejbrand.se</a>'; Flags := [tfUseHiconMain, tfAllowDialogCancellation, tfEnableHyperlinks]; CustomMainIcon := Application.Icon; Execute; finally Free; end

Notice, however, that nothing happens when you click the link. The action of the link must be implemented manually, which -- of course -- is a good thing. To do this, respond to theOnHyperlinkClickedevent, which is aTNotifyEvent. The URL of the link (thehrefof theaelement, that is) is stored in theURLpublic property of theTTaskDialog:

procedure TForm1.TaskDialogHyperLinkClicked(Sender: TObject); begin if Sender is TTaskDialog then with Sender as TTaskDialog do ShellExecute(0, 'open', PChar(URL), nil, nil, SW_SHOWNORMAL); end; procedure TForm1.FormCreate(Sender: TObject); begin with TTaskDialog.Create(self) do try Caption := 'About Rejbrand BookBase'; Title := 'Rejbrand BookBase'; CommonButtons := [tcbClose]; Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'<a href="http://english.rejbrand.se">http://english.rejbrand.se</a>'; Flags := [tfUseHiconMain, tfAllowDialogCancellation, tfEnableHyperlinks]; OnHyperlinkClicked := TaskDialogHyperlinkClicked; CustomMainIcon := Application.Icon; Execute; finally Free; end end;

The Footer

You can use theFooterandFooterIconproperties to create a footer. The icon property accepts the same values as theMainIconproperty.

with TTaskDialog.Create(self) do try Caption := 'My Application'; Title := 'A Question'; Text := 'This is a really tough one...'; CommonButtons := [tcbYes, tcbNo]; MainIcon := tdiNone; FooterText := 'If you do this, then ...'; FooterIcon := tdiWarning; Execute; finally Free; end

Using thetfUseHiconFooterflag and theCustomFooterIconproperty, you can use any custom icon in the footer, in the same way as you can choose your own main icon.

A Checkbox

Using theVerificationTextstring property, you can add a checkbox to the footer of the task dialog. The caption of the checkbox is the property.

with TTaskDialog.Create(self) do try Caption := 'My Application'; Title := 'A Question'; Text := 'This is a really tough one...'; CommonButtons := [tcbYes, tcbNo]; MainIcon := tdiNone; VerificationText := 'Remember my choice'; Execute; finally Free; end

You can make the checkbox initially checked by specifying thetfVerificationFlagCheckedflag. Unfortunately, due to a bug (?) in the VCL implementation of theTTaskDialog, the inclusion of this flag whenExecutehas returned doesn't reflect the final state of the checkbox. To keep track of the checkbox, the application thus needs to remember the initial state and toggle an internal flag as a response to eachOnVerificationClickedevent, which is triggered every time the state of the checkbox is changed during the modality of the dialog.

Radio Buttons

Radio buttons can be implemented in a way resembling how you add custom push buttons (or command link buttons):

with TTaskDialog.Create(self) do try Caption := 'My Application'; Title := 'A Question'; Text := 'This is a really tough one...'; CommonButtons := [tcbOk, tcbCancel]; MainIcon := tdiNone; with RadioButtons.Add do Caption := 'This is one option'; with RadioButtons.Add do Caption := 'This is another option'; with RadioButtons.Add do Caption := 'This is a third option'; if Execute then if ModalResult = mrOk then ShowMessage(Format('You chose %d.', [RadioButton.Index])); finally Free; end