Documents

NextGrid & NextDBGrid

NextGrid

NextDBGrid

NextInspector

NextSheet

NextCollection

Misc

Labs

NxReport Project

NextGrid .NET

NxProgress Tutorial

Info

Skill:
Version: 1.0.0
Author: Wim van der Vegt
Created: 2008-09-10
Updated: 2008-09-11

TNxProgress is a component that mimics (and extends) the Windows 98 GUI for certain installers like Tweak UI.

Basically it is a list of task to perform with the option to highlight one through the Progress property. It also has a Caption and a Title property.

With additions like Ok and Cancel buttons and an input field it can be used to create very powerful progress dialogs that can be used to tell a user what he is waiting for and what the tasks program is performing for him.

As it is a dialog implemented in a component it can be previewed at design time (with some limitations as Delphi does not hide components at design-time).

All the code needed is sometime like:

NxProgress1.Show;
NxProgress1.Progress  := 1;

{ Some code }

NxProgress1.Progress  := 2;

{ Some more code }

NxProgress1.Hide;

There are a number of helper functions to simplify manipulation of the Progress property like:

Name	Meaning
None	Sets the Progress Property to 0.
First	Sets the Progress Property to 1
Last	Sets Progress Property to Lines.Count
Next	Increments the Progress Property by 1.
Increment	Increments the Progress Property.
NextIf	Conditionally Increments the Progress Property by 1.
Previous	Decrements the Progress Property by 1.
PrevioustIf	Conditionally Decrements the Progress Property by 1.
Decrement	Decrements the Progress Property.

The conditional Progress property manipulation is particular when a step needs to be skipped under certain circumstances.

TNxProgress features a TProgressBar included that is controlled through the Min, Max, Position and Smooth properties.

It is possible to update individual lines with code like

For i:=1 to 10 do 
  NxProgress1.Line[3] := Format(�Step %d of %d�,[i,10]);

To ask a user for it�s input there is a powerfull function called WaitPrompt. It takes a tag and two sets of TNxProgressOptions, one to add and one to substract from the current option.

For example:

NxProgress1.WaitPrompt(1, [poShowPrompt]);

Shows the OK button (and Cancel button if poAllowCancel is in Options at designtime) and waits for the user to press one of the Buttons visible.

There are a number of Options available:

� poAllowCancel - Shows a Cancel button when the Ok button is visible.

� poShowButtons - To prevent problems in coding the poShowButtons is automatically added when the WaitPrompt function is called. The Captions of both buttons can be controlled with the OkCaption and CancelCaption properties. The Buttons widths are controlled by the ButtonWidth property.

� poShowArrow - Shows an Arrow between the active step and the Ok Button to point the user to the action required

� poShowPrompt - Shows the Prompt property text, either Right aligned above the Ok Button or Left aligned when the Input control is visible.

� poFixedImage - Shows an Image left of the steps (in combination with the Images and ImageIndex properties).

� poAnimate - Uses the AlphaBlendValue and AlphaDelayValue properties to make the dialog transparent when it does not have focus. Note: by design this cannot work when the Dialog is modal or the Mainform is disabled.

� poModal - Emulates modal behavior.

� poDisableMainForm - Disables the Mainform, a good alternative to poModal as it still disallows the users to interact with the mainform as long as the Dialog is visible.

� poShowEdit - Shows an Input (NxEdit) control of which the Text can be get/set with the Input property.

WaitPrompt optionally uses calls the OnProgressNotify event when the value of its Tag parameter is non-zero. This feature is meant to let the program decide which button should be pressed (It could be used to implement a timeout feature for example).

The upper left corner of Image can be adjusted with the OffsetX and OffsetY properties.

The rest of the TNxProgress properties are self explaining (like AlwaysOnTop and BringToFront).

The AutoSize property should be used with care and only be active at Design Time briefly to size the dialog.

To position the dialog in the upper right corner of the screen use code like:

NxProgress1.FormLeft := Screen.Width - NxProgress1.FormWidth - 20;
NxProgress1.FormTop := 20;

Note: Some of the Options are not usefull at designtime like poShowButtons or poShowPrompt. They are to be used as parameters of WaitPrompt.

Note: Test the dialog�s size by walking the steps. As the active step is drawn with a bold font it becomes wider when active.

Samples:

Figure 1 The poShowArrow option that is meant to draw attention to a Button shown by WaitPrompt.

Figure 2 The poShowInput option used together with poShowButtons, poAllowCancel and poShowArrow.

Figure 3 A transparent Dialog at Design Time.

Documents

NxProgress Tutorial

Related Articles: