NG DialogPack Guide
Advanced Features
TNGTaskDialog and TNGInputDialog components provides several events, which can be fired while dialog is executing. These events are:
•OnButtonClick - fired when standard or custom button (or command link) is clicked.
•OnRadioButtonClick - fired when radio-button is selected.
•OnVerificationClick - fired when verification check-box is checked/unchecked.
•OnExpanded - fired when additional ExpandableInformation is expanded or collapsed.
•OnTimer - fired periodically when internal timer is active.
Usually, if some of standard or custom buttons (or command links) has been clicked, the dialog is closed automatically returning associated with the button ModalResult. However, this can be prevented writing OnButtonClick event handler and assigning False value to ACanClose var event parameter. In this case, the dialog will not be closed, and will remains executing. As already has been noted above, this is also true for standard dialog window close button, which is treated as a button with mrCancel modal result.
Another event, which provides a way for controlling dialog closing is OnTimer. It has AClose var parameter, which can be set to True to close the dialog; however, unlike OnButtonClick event the default value for this parameter is False, which states that the dialog remains executing.
All other mentioned events does not provide a way to close executing dialog at all. So, among other purposes all these events can be used for changing dialog settings and appearance "on-the-fly". For example, one can write OnRadioButtonClick event handler to enable or disable dialog buttons based or change dialog Title or Text on which radio-button is selected.
Generally, the following "on-the-fly" modifications are supported:
•Dialog Title, Text and MainIcon (CustomMainIcon).
•For custom buttons: Enabled and ElevationRequired states.
•For radio-buttons: Enabled state.
•For progress-bar: all progress bar setting, such as Min, Max, Position, State and Marquee.
•ExpandedInformation.
•FooterText and FooterIcon (CustomFooterIcon).
Changing these properties from within mentioned event handlers will adjust dialog appearance immediately. All other properties does not support this concept due to WinAPI limitation; as well, they are not supported even in emulation mode for consistency with platform mode. For example, you cannot:
•Change dialog window Caption.
•Add/remove standard or custom buttons or radio-buttons. Change their captions.
•Change expandable information button captions, e.g. ExpandButtonCaption and CollapseButtonCaption properties.
•Change VerificationText.
•Change dialog Flags.
•ect.
Timer
TNGTaskDialog and TNGInputDialog components provides built-in timer support. The timer can be activated using tdfCallbackTimer flag. The timer will fire OnTimer event every 200ms during dialog execution. As specified above, "on-the-fly" dialog modification is supported within OnTimer event handler.
OnTimer event provides the following parameters:
•ATickCount parameter; this parameter specifies a period in milliseconds from the dialog execution or from the last reset.
•AReset boolean var parameter; this parameter can be set to True to reset tick count to zero. Default parameter value is False.
•AClose boolean var parameter; this parameter can be set to True to close the dialog. Default parameter value is False.
Following are some practical examples of timer usage:
•Updating progress-bar position to reflect background task execution point:
•Update remained time in dialog Title or Text and close the dialog after some timeout to continue task with default action:
•Trial application dialog, which enables "Continue trial" button only after some time:
Navigation
Navigation feature allows to implement multi-page dialogs. Such kind of dialogs usually contain Next and Previous custom buttons to allow the user to navigate between pages. Write OnButtonClick event handler and use BeginNavigate and Navigate methods to reconfigure executing dialog to show next page. Dialog modifications, made between BeginNavigate and Navigate methods are not propagated to executing dialog immediately; instead, all modifications will be applied during Navigate method call. It important to understand that the navigation is a special mode, provided by WinAPI, and thus, "on-the-fly" modification restrictions are not applied here; the user can freely add/remove buttons or radio-buttons, change dialog flags, ect.
Following is an example of code, which use navigation feature:
procedure TForm1.NGTaskDialog1ButtonClick(Sender: TObject;
AModalResult: TModalResult; ACustomButton: TNGTaskDlgButtonItem;
var ACanClose: Boolean);
begin
if AModalResult in [100, 101] then
begin
if AModalResult = 101 then
Inc(PageNum)
else
Dec(PageNum);
NGTaskDialog1.BeginNavigate;
try
SetupPage(PageNum);
finally
NGTaskDialog1.Navigate;
end;
ACanClose := False;
end;
end;
procedure TForm1.SetupPage(APageNum: Integer);
begin
NGTaskDialog1.Title := 'Multi-page dialog example. Page: ' +
IntToStr(APageNum);
case APageNum of
0: NGTaskDialog1.Text := 'This is the first page';
1: NGTaskDialog1.Text := 'This is the middle page';
2: NGTaskDialog1.Text := 'This is the last page';
end;
NGTaskDialog1.CustomButtons.Clear;
if APageNum > 0 then
with NGTaskDialog1.CustomButtons.Add do
begin
Caption := 'Previous';
ModalResult := 100;
end;
if APageNum < 2 then
with NGTaskDialog1.CustomButtons.Add do
begin
Caption := 'Next';
ModalResult := 101;
end
else
with NGTaskDialog1.CustomButtons.Add do
begin
Caption := 'Finish';
ModalResult := mrOk;
end
end;
The code above will show dialog with the following pages:
The dialog will be closed on "Finish" button click, because its ModalResult is set to mrOk.