TStyledTaskDialog - Technical Reference
Overview
TStyledTaskDialog is a drop-in replacement of the VCL TTaskDialog component that shows the dialog in a VCL form (TStyledTaskDialogForm) with styled buttons, instead of the native Windows TaskDialog. It is also the engine behind the global routines StyledMessageDlg, StyledTaskMessageDlg, StyledShowMessage... and behind the Vcl.StyledMessagesHooks interposer unit.
See the TStyledTaskDialog page for the description and the examples, and the Demo page for the demo application.
Class Hierarchy
TComponent
└─ TCustomTaskDialog (Vcl.Dialogs)
└─ TTaskDialog (Vcl.Dialogs)
└─ TStyledTaskDialog (Vcl.StyledTaskDialog)
└─ TStyledAnimatedTaskDialog (Vcl.StyledAnimatedTaskDialog, needs Skia4Delphi)Units
| Unit | Content |
|---|---|
Vcl.StyledTaskDialog | TStyledTaskDialog, the global routines (StyledMessageDlg, InitializeStyledTaskDialogs...), tdiQuestion, constants |
Vcl.StyledTaskDialogFormUnit | TStyledTaskDialogForm (base form of the dialogs), RegisterTaskDialogFormClass, UnRegisterTaskDialogFormClass, UseStyledDialogForm |
Vcl.StyledTaskDialogStdUnit | TStyledTaskDialogStd, the standard (not animated) dialog form, registered by Vcl.StyledTaskDialog itself |
Skia.Vcl.StyledTaskDialogAnimatedUnit | TStyledTaskDialogAnimatedForm, the animated dialog form (Skia4Delphi) |
Vcl.StyledMessagesHooks | Interposer unit: MessageDlg, MessageDlgPos, TaskMessageDlg, TaskDlgPos, ShowMessage |
Published properties (Object Inspector)
Only the properties added by TStyledTaskDialog are listed here.
| Property | Type | Default | Description |
|---|---|---|---|
AutoClick | Boolean | False | Automatically clicks the default button after AutoClickDelay (see AutoClick guide) |
AutoClickDelay | Integer | 5000 (DEFAULT_AUTOCLICK_DELAY) | Delay in milliseconds before the automatic click |
DialogButtonsFamily | TStyledButtonFamily | '' (the one set by RegisterDefaultRenderingStyle) | StyleFamily of the dialog buttons. The class and the appearance of each button come from its ModalResult |
DialogButtonsDrawType | TStyledButtonDrawType | btRoundRect | Shape of the dialog buttons (btRect, btRoundRect, btRounded, btEllipse) |
DialogButtonsRadius | Integer | 6 (DEFAULT_RADIUS) | Corner radius of the dialog buttons |
DialogButtonsRoundedCorners | TRoundedCorners | ALL_ROUNDED_CORNERS | Which corners of the dialog buttons are rounded |
ButtonsWidth | Integer | 74 | Width of the dialog buttons (range 10..800) |
ButtonsHeight | Integer | 30 | Height of the dialog buttons (range 10..300) |
UseCommandLinks | Boolean | False | Shows the buttons as command links (it sets/clears tfUseCommandLinks in Flags) |
UseTitleInMessageDlg | Boolean | True | In the simple message dialogs shows the dialog type title (Warning, Error...) as main instruction |
AlphaBlendValue | Byte | 255 | Transparency of the dialog form (255 = opaque) |
MainIconSize | Integer | 64 (128 with Use_Large_Dialog_Icons) | Size in pixels of the main icon. A negative value raises an exception |
HideSystemCloseButton | Boolean | False | Hides the system close button (sets BorderIcons := [] on the form) |
Position | TPoint | (-1, -1) | Screen position of the dialog; (-1, -1) means "centered". Stored only if custom |
UseAnimations | Boolean | False | Uses the animated dialog form (Lottie icons). Raises EStyledTaskDialogException if Skia.Vcl.StyledTaskDialogAnimatedUnit is not in the project |
UseAnimationLoop | Boolean | False | Loops the icon animation (setting it to True also sets UseAnimations) |
UseAnimationInverse | Boolean | False | Plays the icon animation in reverse (setting it to True also sets UseAnimations) |
OnDialogShow | TTaskDialogShow | nil | procedure(const AStyledTaskDialogForm: TForm) of object, fired when the dialog form is shown (the form is passed, so you can change it: size of the system close button, controls...) |
Inherited published members (from TTaskDialog)
Buttons, Caption, CommonButtons (default [tcbOk, tcbCancel]), CustomFooterIcon, CustomMainIcon, DefaultButton (default tcbOk), ExpandButtonCaption, ExpandedText, Flags (default [tfAllowDialogCancellation]), FooterIcon, FooterText, HelpContext, MainIcon (default tdiInformation), ProgressBar, RadioButtons, Text, Title, VerificationText.
Events: OnButtonClicked, OnDialogConstructed, OnDialogCreated, OnDialogDestroyed, OnExpanded, OnHyperlinkClicked, OnNavigated, OnRadioButtonClicked, OnTimer, OnVerificationClicked.
ProgressBar has Min (0), Max (100), Position, State (pbsNormal, pbsError, pbsPaused) and MarqueeSpeed. The progress bar is shown with tfShowProgressBar (or tfShowMarqueeProgressBar for the marquee style) in Flags; tfCallbackTimer enables OnTimer.
Public properties
| Property | Type | Access | Description |
|---|---|---|---|
Handle | HWND | read/write | Window handle of the dialog form (it is reset to 0 when the dialog is closed) |
HelpFile | string | read/write | Help file used by the Help button (default: Application.HelpFile) |
MessageDefaultButton | TMsgDlgBtn | read | Default button chosen by MessageDlg-like routines |
UseMessageDefaultButton | Boolean | read | True when MessageDefaultButton must be used |
OnFindDialogButton | TOnFindDialogButtonEvent | read/write | Assigned by the dialog form: used by FindDialogButton |
ModalResult, Button, RadioButton, Expanded, URL | Inherited: result of Execute, clicked button, selected radio item... |
Public methods
| Method | Description |
|---|---|
constructor Create(AOwner: TComponent) | Takes the defaults from RegisterDefaultRenderingStyle and InitializeStyledTaskDialogs |
function Execute: Boolean / Execute(ParentWnd: HWND): Boolean | Shows the dialog (modal). The first overload is inherited. The ParentWnd is used to find the form that launched the dialog |
function FindDialogButton(const AModalResult: TModalResult): TStyledButton | Returns the styled button of the open dialog with that ModalResult (nil if not found or the dialog is not open). Useful in OnDialogShow/OnTimer to customize a button |
function IsCustomPosition: Boolean | True if Position is not (-1, -1) |
class procedure RegisterDefaultRenderingStyle(ADrawType; AFamily = DEFAULT_CLASSIC_FAMILY; ARadius = DEFAULT_RADIUS; ARoundedCorners = ALL_ROUNDED_CORNERS) | Sets the default DialogButtonsDrawType, DialogButtonsFamily, DialogButtonsRadius, DialogButtonsRoundedCorners of every dialog created afterwards |
procedure DoOnExpandButtonClicked, DoOnRadioButtonClicked, DoOnHyperlinkClicked | Overrides of the TCustomTaskDialog dynamic methods (called by the form) |
Note that RegisterDefaultRenderingStyle has no StyleClass/StyleAppearance parameters, unlike the one of TStyledButton: the class and the appearance of every dialog button are always chosen by the family from the ModalResult of the button (for example in the Bootstrap family mrOk is Success, mrNo is Danger, mrCancel is Warning).
Dialog position and owner form
- The dialog is centered on the monitor of the form that launched it (the form of the
ParentWndhandle; if it is not known, the active form, then the main form). WithtfPositionRelativeToWindowinFlagsit is centered over that form instead of the monitor. - With
Positionset, orX, Ypassed to the...Posroutines, the coordinates are relative to the work area of the same monitor; a negative coordinate means "centered" on that axis. - The launching form is only a reference for the position: the dialog is owned by
Applicationand its popup parent is the main form (if alive), so it is safe to destroy the launching form while the dialog is modal (the reference is cleared by a free notification and the dialog keeps working).
Auto-click
When AutoClick is True the default button of the dialog (the one that receives the focus) shows a progressive fill and is clicked after AutoClickDelay milliseconds. The same two properties exist on every styled button, see AutoClick guide.
Keyboard
| Key | Action |
|---|---|
Enter | Clicks the focused button (or the OK button if no button has the focus) |
Esc | Clicks the Cancel button |
Ctrl+C / Ctrl+Ins | Copies the dialog content to the clipboard in the native TaskDialog layout |
Copy to Clipboard
As with the Windows system dialogs, the text is copied with one [Section] header per part, followed by one [Caption] line per button, in the order shown on screen. Empty or hidden sections are omitted, hotkey markers (&) are removed from the captions and hyperlink tags are removed from the footer text.
[Window Title]
Confirm Delete
[Main Instruction]
Delete file
[Content]
Are you sure you want to delete this file?
[Verification Text]
Don't ask me again
[Yes]
[No]Sections: Window Title, Main Instruction, Content, Expanded Information, Footer, Verification Text (available since version 4.2.3).
Global routines (unit Vcl.StyledTaskDialog)
Message dialogs
All return the ModalResult of the clicked button. DefaultButton is a TMsgDlgBtn; when it is omitted the default button is chosen like MessageDlg does (Yes, OK, No, Cancel...).
| Routine | Description |
|---|---|
StyledMessageDlg(Msg, DlgType, Buttons, HelpCtx [, DefaultButton [, CustomButtonCaptions]]) | Replacement of MessageDlg; CustomButtonCaptions: array of string replaces the captions of the buttons, in order |
StyledMessageDlgPos(Msg, DlgType, Buttons, HelpCtx [, DefaultButton], X, Y) | Replacement of MessageDlgPos |
StyledTaskMessageDlg(Title, Msg, DlgType, Buttons, HelpCtx [, DefaultButton]) | Replacement of TaskMessageDlg: Title is the main instruction |
StyledTaskMessageDlgPos(Title, Msg, DlgType, Buttons, HelpCtx [, DefaultButton], X, Y) | Replacement of TaskDlgPos |
StyledShowMessage(Msg) / StyledShowMessageFmt(Msg, Params) | Replacement of ShowMessage / ShowMessageFmt |
DoStyledTaskMessageDlg, DoStyledTaskMessageDlgPos, DoStyledTaskMessageDlgPosHelp, DoMessageDlgPosHelp | Low-level versions with AutoClickDelay (-1 = off), UseCommandLinks and HelpFileName parameters |
Deprecated overloads (still compiled, with a compiler warning): StyledMessageDlg(Title, Msg, ...), StyledTaskDlgPos and the StyledMessageDlgPos with DefaultButton before HelpCtx. Use StyledTaskMessageDlg / StyledTaskMessageDlgPos / the new StyledMessageDlgPos instead.
Configuration
| Routine | Description |
|---|---|
InitializeStyledTaskDialogs(AUseTitleInMessageDlg: Boolean; AFont: TFont; AUseCommandLinks = False; ADialogButtonsFamily = ''; AAlphaBlendValue = 255; AButtonsWidth = 74; AButtonsHeight = 30; AAutoClickDelay = -1) | Full configuration. AFont is the DialogFont used by all dialogs (nil = Screen.MessageFont); AAutoClickDelay > 0 turns the auto-click on for the dialogs created by the routines above |
InitializeStyledTaskDialogs(ADialogButtonsFamily = ''; AUseCommandLinks = False; AAutoClickDelay = -1) | Short form: uses Screen.MessageFont |
InitializeStyledTaskDialogs(AFont: TFont) | Sets only the font (nil resets it) |
InitializeStyledTaskDialogs(AUseAnimations: Boolean) | Enables/disables the animated dialogs of the message routines (Skia4Delphi, see TStyledAnimatedTaskDialog) |
SetUseTitleInMessageDlg(AValue) | Changes only the "title in message dialogs" option |
RegisterCustomExecute(ALauncher: ITaskDialogLauncher; AButtonFamily = '') / UnregisterCustomExecute | Registers/removes the object that displays the dialogs (ITaskDialogLauncher.DoExecute). Without it, Execute falls back to the native TaskDialog |
GetDialogFont, GetDialogBtnFamily, GetDialogAlphaBlendValue | Return the global settings |
GetTaskDlgType(AIcon), GetDialogTypeTitle(DlgType), MsgDlgBtnToDefaultBtn(ABtn) | Conversion helpers |
Important: the first parameter of the full overload is a Boolean: InitializeStyledTaskDialogs(True, Screen.MessageFont, False, BOOTSTRAP_FAMILY). To set only the family use InitializeStyledTaskDialogs(BOOTSTRAP_FAMILY).
Dialog form routines (unit Vcl.StyledTaskDialogFormUnit)
| Routine | Description |
|---|---|
RegisterTaskDialogFormClass(AFormClass: TStyledTaskDialogFormClass) | Registers the form class used to show the dialogs. A class whose CanUseAnimations returns True becomes the "animated" form (used when UseAnimations is True), the others become the standard form. It also activates the styled dialogs |
UnRegisterTaskDialogFormClass(AFormClass) | Removes a registered class |
UseStyledDialogForm(AActivate: Boolean) | True: use the styled forms; False: use the native Windows TaskDialog |
AnimatedTaskDialogFormRegistered: Boolean | True if an animated form class is registered |
Constants and types
| Name | Value / meaning |
|---|---|
tdiQuestion | 5: question-mark icon (the stock TaskDialog has none; the native fallback maps it to tdiNone) |
DEFAULT_STYLEDDIALOG_ALPHABLEND | 255 |
DEFAULT_STYLEDDIALOG_MIN_WIDTH / _MIN_HEIGHT | 500 / 280 |
DEFAULT_STYLEDDIALOG_BUTTONSWIDTH / _BUTTONSHEIGHT | 74 / 30 |
MIN_STYLEDDIALOG_BUTTONSSIZE, MAX_STYLEDDIALOG_BUTTONSWIDTH, MAX_STYLEDDIALOG_BUTTONSHEIGHT | 10, 800, 300 |
DEFAULT_MAIN_ICON_SIZE | 64 (128 if Use_Large_Dialog_Icons is defined in StyledComponents.inc) |
EStyledTaskDialogException | Exception raised, for example, when animations are requested but no animated form is registered |
TTaskDialogShow | procedure(const AStyledTaskDialogForm: TForm) of Object |
TOnFindDialogButtonEvent | function(const AModalResult: TModalResult): TStyledButton of object |
ITaskDialogLauncher | Interface with DoExecute(ParentWnd, ADialogType, ATaskDialog, ADialogBtnFamily): Boolean; the default implementation is TTaskDialogLauncherHandler |
TStyledTaskDialogForm (custom dialog forms)
TStyledTaskDialogForm (a TForm) is the base class of the dialog forms. To build your own dialog, derive a form from TStyledTaskDialogStd (or TStyledTaskDialogAnimatedForm), change the layout in the designer/code and register it with RegisterTaskDialogFormClass in the initialization section (and UnregisterTaskDialogFormClass in finalization). The demo Demos\source\StyledTaskDialogAnimCustomForm.pas moves the icon to the right (ImagePanel.Align := alRight).
Main public members of the form, used by the dialog to copy the settings of the component:
| Member | Description |
|---|---|
AutoClick, AutoClickDelay | Auto-click of the default button |
ButtonsWidth, ButtonsHeight | Size of the buttons |
Buttons, RadioButtons, CommonButtons, DefaultButton, MessageDefaultButton | Buttons |
MainIcon, CustomMainIcon, MainIconSize, FooterIcon, CustomFooterIcon, FooterText | Icons and footer |
TextMessage, TitleMessage, ExpandedText, ExpandButtonCaption, Expanded, VerificationText | Texts |
ProgressBar, Flags, HelpContext, RadioButton, OnTimer | Other settings |
AnimationLoop, AnimationInverse | Animation settings (animated form) |
FindButton(AModalResult), ModalResultToCommonButton(...), SetDialogFont(AFont), SetPosition(X, Y) | Methods |
Virtual methods to override in a descendant: LoadImage, LoadCustomMainIcon, LoadCustomFooterIcon, DefaultDialogSize, GetDefaultButton, GetScaleFactor, GetReferenceWnd, SetButtonsWidth/Height and the class function CanUseAnimations.
See Also
- TStyledTaskDialog - Description and examples
- TStyledTaskDialog Demo - The demo application
- TStyledAnimatedTaskDialog - Animated dialogs with Skia4Delphi
- Vcl.StyledMessagesHooks - Replace MessageDlg/ShowMessage without changing the calls
- TStyledButton Reference - Styled button used in dialogs
- AutoClick Guide - Auto-click feature
- How to build your custom style - Custom family for the dialog buttons