TProgressDisplay – Documentation
Overview
This component displays a message in a panel or a form centered in the middle of any component (Parent). It 
includes a ProgressBar, an optional Abort button and some lines of text.
TProgressDisplay has the ability to be opened with a given timeout delay time. After the time out the Display will 
be automatically closed.
The TProgressDisplay will be shown non-modal so the user can be informed about any time consuming 
operations the application is processing. The dimensions of the ProgressDisplay are automatically resized to the 
display text. You can also set the message text when the control is shown so you can inform the user at any time. 
You can also define that the control is only closed when the user clicks on the abort button (see Options).
Requirements
You need Delphi 2.0, or Borland C++ Builder (Version 1.0 will do). You can use ProgressDisplay with either 
Window 95 (98)  and NT (4.0, 5.0).
Installation
Copy the files in the installation path
(For Delphi)
	cls_ProgressDisplay.dcu 	
	cls_ProgressDisplay.dcr
(For C++Builder)
	cls_ProgressDisplay.hpp
	cls_ProgressDisplay.obj
	cls_ProgressDisplay.dcr

to the place where you store your VCL classes. 
>From inside C++ Builder or Delphi select menu component and then install. Select cls_ProgressDisplay(.obj/.dcu) 
as new component and then rebuild the library. Done.
Copyright
TProgressDisplay is Freeware and Noteware for non-commercial use only.  You can use TProgressDisplay under 
the 
Following conditions:
	Freeware or Shareware package
	Sending me an email that you use TProgressDisplay in your application
	Adding a note like the following in your manual:

	This application uses TProgressDisplay © 1997 by H.P.G
	Homepage: http://members.aol.com/hpgue/hpgintl.htm
	E-Mail: hpgue@aol.com


If you want to use the component in commercial a software package please contact the author for special 
conditions and package licenses.
Usage
Use the component like any other component. Add it at design time to any form. Set the appropriated properties 
with the object inspector. 

Component
TProgressDisplay – class documentation

Properties:

? Status 
Status : TStringList
TStringList *Status
These are the text lines which will be displayd in the ProgressDisplay.
The size of the control will be changed so that the text is entirely visible.
? Caption
Caption : TCaption (String)
TCaption Caption
This is also the Status, but here given as string. You can use either Caption or status to set the display 
text.

? Options
Options :  TProgressDisplayOptions
TProgressDisplayOption=set of TProgressDisplayOptionItems;

typedef Set< TProgressDisplayOptionItems, poLockParent, poShowPercent> TProgressDisplayOptions

this options defines the behavior of the ProgressDisplay. TProgressDisplayOptionItems are defined as 
follows:

TProgressDisplayOptionItems=(
poLockParent, 
poLockApplication, 
poForbidTimer, 
poShowButton, 
poShowPercent
);

enum TProgressDisplayOptionItems 
{ 
poLockParent, 
poLockApplication, 
poForbidTimer, 
poShowButton, 
poShowPercent
};

poLockParent
if Options contains this the parents’ cursor will be automatically changed to crAppStart. This is NOT a 
flag for modal showing the control nor is the parent control really locked.

poLockApplication
if Options contains this the parents‘ cursor and the Screen’s cursor will be automatically changed to 
crAppStart. This is NOT a flag for modal showing the control nor is the parent control really locked.

doForbidTimer
Due to the limited system timers on some OSes this flag forbids the creation of a system timer. If you set 
this option a call to AsyncDisplay will always return false and the ProgressDisplay will not open only by 
the use of the OpenDisplay/Visible function.

doShowButton
If you set this an abort button will be displayed at the bottom of the ProgressDisplay and the window 
will be closed automatically if the user clicks on the button (See also OnCloseQuery event). The Caption 
of the button is for default Abort. You can change this with the AbortCaption property. 

? Types
Types : TProgressDisplayTypes
enum TProgressDisplayTypes Types 

this is a shorthand method to specify whether the control is shown in a Panel or in a Form
Note: If you use the Panel you should set the AutoScroll property of the ParentForm to false else other 
controls may be repositioned while the ProgressDisplay is shown

TProgressDisplayTypes are defined as follows:

TProgressDisplayTypes=
(
pdNormal,
pdSmall
);

enum TProgressDisplayTypes
{
	pdNormal,
pdSmall
};

pdNormal
the ProgressDisplay is shown in its’ own form.
 
pdSmall
the ProgressDisplay is shown in a Panel.

? Interval
Interval : Integer
int Interval

Value is given in milli seconds.
This property is used together with the steps property for the AsyncDisplay function.
TProgressDisplay can be opened via the AsyncDisplay method. The ProgressBar’s value will be set first 
to 0. In the specified Interval the ProgressBar’s value will be increased to 100 by # of Steps. The formula 
is simple: Interval=100/Steps. If you set the steps value too high the Interval cannot be reached. 
Example: 
Interval=500; 	// ½ second
Steps=10; 	// show 10 Steps 0%,10%,20%…100%
	AsyncDisplay(1);  // Only 1 time
TProgressDisplay tries to show 0%, 10% … 100% in the given ½ second.
You can set the Interval to 0 this means use the fastest Delay the system timer can
use. But I will recommented not to use 0 because in the future system timers can be very much faster 
than today. Use instead a value of 20 which is the fastest Delay time the system timer can currently use.
Purpose: I use the Interval/Steps/AsyncDelay just for the time when I initialize some variables so the 
user see that the application is not locked. I started the the AsyncDisplay with the Repeat Parameter (see 
AsyncDelay) very high when I process some functions where I don’t know how much time they take.
Example:
	Interval=10*1000; // 10 Seconds
	Steps=100; // 0%,1%,…100%
	AsyncDisplay(0); // Do it 32000 times ? ? infinite

	Every second the the ProgressBar’s value will be increased by 1 percent.
	So you see you can use the ProgressDisplay also as a counter.

? Visible
Visible : Boolean
bool Visible
	This property is a shorthand for the call to the OpenDisplay/CloseDisplay functions.
	See functions for further details.

? Progress
Progress : Integer
int Progress
This is the value (in percent 0..100) of the ProgressBar. You can set this value at any time whether the 
display is shown or not.
Note: If you use the AsyncDisplay function the Progress value will be changed. After a call to 
AsyncDisplay you should reinitialize the value in code.

? Steps
Steps : Integer
int Steps
	This value is used with the Interval property and AsyncDisplay function. See Interval.

? MinWidth
MinWidth : Integer
int MinWidth
Use this property to define the minimum width of the ProgressDisplay. If you change the status text lines 
in code very often the width of the Display will be automatically changed to fit make the whole text 
visible. If the text is smaller the Display will be make smaller. To prevent this set MinWidth to a 
appropriate value.

? Title
Title : String
AnsiString Title
If you set the Types property to pdNormal (default) then this value is used for the
Form‘s title.

? AbortCaption
AbortCaption : TCaption (String)
AnsiString AbortCaption 

This is the text the abort button will use. Default is Abort.

Methods:
? OpenDisplay
function OpenDisplay : Boolean;
bool __fastcall OpenDisplay(void);

this is the standard method to open the TProgressDisplay without any timeout. The ProgressDisplay will 
be shown until the destructor is called or the function CloseDisplay is called. If you set poShowButton 
in Options a click on the abort button will close the display too (See also OnCloseQuery). If this function 
returns false the  ProgressDisplay is already shown or any error occurred.
You can also use the Visible property but then you get no return value. You have to do this as follows:
(Delphi)
	ProgressDisplay1.Visible:=true;
	Application.ProgressMessages;
	if (not ProgressDisplay1.Visible) then
	begin 
		// Error
	end;

(C++Builder)
	ProgressDisplay1->Visible=true;
	Application->ProcessMessages();
	if (!(ProgressDisplay1->Visible))
{
		// Error
}

? CloseDisplay
function CloseDisplay : Boolean;
bool __fastcall CloseDisplay(void);
if the control is opened either with the OpenDisplay or AsynDisplay function CloseDisplay will close or 
hide the control. If this function returns false the ProgressDisplay is currently not shown or any error 
occurred.

? AsyncDisplay
function AsyncDisplay(RepeatTimes : Integer) : Boolean;
bool __fastcall AsyncDisplay(int RepeatTimes);

Opens the display for a specified delay time.
See also property Interval/Steps

Example:
// this will open the ProgressDisplay  for upto 10 seconds. The 
ProgressDisplay // contains also an Abort button. The 
// ProgressDisplay will be closed if either user clicks the button or 
the 
// 10 seconds have gone
// each second the Progress will be increased by 10%
(Delphi)
ProgressDisplay1.Options:=ProgressDisplay1.Options+[poShowButton]; 
// Show an Abort button
ProgressDisplay1.Options:=ProgressDisplay1.Options+[poShowPercent]; 
// Show a percentage Label
ProgressDisplay1.Steps:=10;
// Increase the Progress by 10%
ProgressDisplay1.Interval:=10 * 1000; 
// Set Interval to 10 seconds
if (ProgressDisplay1.AsyncDisplay) then
begin // okay the display has been shown
	continue what ever you want here……
end
else
begin // any error occurred with memory, ttimer etc.
end;

(C++Builder)
ProgressDisplay1->Options=ProgressDisplay1->Options << poShowButton; 
// Show an Abort button
ProgressDisplay1->Options=ProgressDisplay1->Options << poShowPercent; 
// Show a percentage Label
ProgressDisplay1->Steps=10;
// Increase the Progress by 10%
ProgressDisplay1.Interval=10 * 1000; 
// Set Interval to 10 seconds
If (ProgressDisplay1->AsyncDisplay(1))
{ // okay the message have been shown
	continue what ever you want here……
}
else
{ // any error occurred with memory, ttimer etc.
}

Events:

? OnOpen
OnOpen = TOnMsgDisplayOpenEvent;
	TOnMsgDisplayOpenEvent=procedure (Sender:TObject;OpenKind:TOpenKind) of object;

enum TOpenKind { okStandard, okAsync };
typedef void __fastcall (__closure *TOnMsgDisplayOpenEvent)(System::TObject* Sender, 
	TOpenKind OpenKind);

OnOpen is called whenever the TProgressDisplay is opened either with the OpenDisplay/Visible or 
AsyncDisplay function. The OpenKind Parameter is set to okStandard if the ProgressDisplay is opened 
via a call to OpenDisplay/Visible or to okAsync if the AsyncDisplay method is used

? OnCloseQuery
	TOnCloseQueryEvent=procedure (Sender:TObject;var CanClose : Boolean) of object;
	typedef void __fastcall (__closure *TOnCloseQueryEvent)(System::TObject* Sender, 
		bool &CanClose);

	If you set the poShowButton in Options and the user clicks on the Abort button this 
	event occurs. If you set the CanClose parameter to false the ProgressDisplay will not
	be closed.

? OnClose
	TCloseReason=(crTimeOut,crClick);
	TOnMsgDisplayCloseEvent=procedure (Sender:TObject;Reason:TCloseReason) of object;

	enum TCloseReason { crTimeOut, crClick };

typedef void __fastcall (__closure *TOnMsgDisplayCloseEvent)(System::TObject* Sender, 
		TCloseReason Reason);

The OnClose event occurs only when the user clicks on the Abort button or the time out Interval is 
reached. Calling the CloseDisplay method will not fire the OnClose event. The Reason Parameter is set to 
crTimeOut if the ProgressDisplay is closed by time out else reason is set to crClick.
Author
If you have any questions, suggestions or want to contact me send a message to the following address:
	hpgue@aol.com

Visit also my home page at
	http://members.aol.com/hpgue/hpgintl.htm


___