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:

 
clip0009

 

Update remained time in dialog Title or Text and close the dialog after some timeout to continue task with default action:

 
clip0010

 

Trial application dialog, which enables "Continue trial" button only after some time:

 
clip0011
 

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:

 

clip0012

clip0013

clip0014

 

The dialog will be closed on "Finish" button click, because its ModalResult is set to mrOk.