Class TProgress

Unit

Declaration

type TProgress = class(TObject)

Description

Progress bar functionality.

This provides the functionality of a progress bar (everything that wants to signal progress should call Progress methods), but not the actual user interface. The user interface is "pluggable", that is you assign something to the Progress.UserInterface property. See the units:

  • CastleWindowProgress — show progress bar in OpenGL window

  • CastleProgressConsole — show progress bar on StdErr

  • And you can also implement progress handling yourself, e.g. using Lazarus form or using Lazarus progress bar on existing form.

This way any unit that implements some lengthy operation can call appropriate functions of the Progress object. And the final program can choose how it wants to show that progress to user (in console? in OpenGL window? etc.).

Usage example:

Progress.UserInterface := ... some TProgressUserInterface instance ...;
...
Progress.Init(100, 'Doing something time-consuming, please wait');
try
  for i := 1 to 100 do
  begin
    ... do something ...
    Progress.Step;
  end;
finally Progress.Fini; end;

Using "try ... finally ... end" above is not strictly required, but is strongly suggested. Rule of thumb says to always call Progress.Fini when you called Progress.Init.

The TProgress.Step is implemented such that you don't have to worry about calling it too often. We will not update the interface (TProgressUserInterface.Update) too often, see TProgress.UpdatePart and TProgress.UpdateDelay for details.

This unit creates one instance of the class TProgress: Progress. Usually this is what you want to use. For complicated cases, you can create and pass around more instances (e.g. from different threads, each TProgress object displaying it's state in a separate window.)

Hierarchy

  • TObject
  • TProgress

Overview

Fields

Public nested const DefaultUpdatePart = 100 ;
Public nested const DefaultUpdateDelay = 0.25 ;

Methods

Public procedure Init(AMax: Cardinal; const ATitle: string; const DelayUserInterface: boolean = false);
Public procedure Step(StepSize: Cardinal = 1);
Public procedure Fini;
Public constructor Create;

Properties

Public property UserInterface: TProgressUserInterface read FUserInterface write FUserInterface;
Public property UpdatePart: Cardinal read FUpdatePart write FUpdatePart default DefaultUpdatePart;
Public property UpdateDelay: TFloatTime read FUpdateDelay write FUpdateDelay;
Public property Position: Cardinal read FPosition write SetPosition;
Public property Max: Cardinal read FMax;
Public property Title: string read FTitle;
Public property Active: boolean read FActive;

Description

Fields

Public nested const DefaultUpdatePart = 100 ;
 
Public nested const DefaultUpdateDelay = 0.25 ;
 

Methods

Public procedure Init(AMax: Cardinal; const ATitle: string; const DelayUserInterface: boolean = false);

Start the progress bar. You can call Init only when Active = false (that is, you cannot Init while another progress is working). Initializes Max, Title, sets Position to 0 and changes Active to true.

UserInterface must be initialized (non-nil) when calling Init, and you cannot change UserInterface when progress is Active (i.e. before you call Fini).

If DelayUserInterface is set to True, a very useful optimization is performed: TProgress.Init will not immediately result in TProgressUserInterface.Init call. Instead, actual initialization of the interface will be delayed until some TProgress.Update, when UpdateDelay time will pass.

The advantage of DelayUserInterface is that if an operation will take a very short time, we will not waste time on possibly lengthy initialization of the progress bar interface. For example, CastleWindowProgress may have to capture OpenGL screen at the initialization, which takes a noticeable fraction of second by itself. So it's not sensible to init CastleWindowProgress if an entire operation between Progress.Init and Fini will take only 0.001 of second..

The only downside of DelayUserInterface is that it's not applicable to an operation with very few steps (e.g. 1) that may take a long time. If a time between Init and the first Update or Fini is really large, the progress bar will not be visible.

Public procedure Step(StepSize: Cardinal = 1);

Increments progress bar Position by StepSize. Use only when Active, that is between Init and Fini calls.

Position always stays <= Max (you can depend on this when implementaing TProgressUserInterface descendants). But it is legal to try to raise Position above Max by using this method, we will silently clamp Position to Max. This is usefull when given Max was only an approximation of needed steps.

Public procedure Fini;

Finish progress bar. You can call it only when Active = true (that is, if you called Init before). Fini changes Active to false.

Note that it's perfectly legal to call Fini before Position reaches Max (it's sensible e.g. when you're allowing user to break some lenghty operation, or when Max was only an approximation of steps needed).

Public constructor Create;
 

Properties

Public property UserInterface: TProgressUserInterface read FUserInterface write FUserInterface;
 
Public property UpdatePart: Cardinal read FUpdatePart write FUpdatePart default DefaultUpdatePart;

Define how often to redraw interface (TProgressUserInterface.Update). Position must change by (1/UpdatePart) * Max and at the same time at least UpdateDelay seconds must pass to redraw.

This allows you to call Step very often, without worrying that you cause redraw too often (which would cause slowdown).

UpdateDelay default value is DefaultUpdateDelay.

Public property UpdateDelay: TFloatTime read FUpdateDelay write FUpdateDelay;
 
Public property Position: Cardinal read FPosition write SetPosition;

Current Position of the progress bar. Always >= 0 and <= Max.

You can set this property only when Active. Setting it to something > Max will be silently clamped to Max. You can only increase it (trying to decrease it will be silently ignored, which is useful if your position information is only an approximation). In other words, setthing this property is equivalent to appropriate Step call.

Public property Max: Cardinal read FMax;
 
Public property Title: string read FTitle;
 
Public property Active: boolean read FActive;

Are we between Init and Fini calls. Init changes Active to true, Fini changes Active to false.


Generated by PasDoc 0.15.0.