Castle Game Engine: CastleProgress: Class TProgress

# Class TProgress
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleProgress ## 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.UpdateTicks 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
| `internal const DefaultUpdatePart = 100 ;`
| `internal const DefaultUpdateTicks = 250 ;`
### Methods
| `procedure Init(AMax: Cardinal; const ATitle: string; const DelayUserInterface: boolean = false);`
| `procedure Step(StepSize: Cardinal = 1);`
| `procedure Fini;`
| `constructor Create;`
### Properties
| `property UserInterface: TProgressUserInterface read FUserInterface write FUserInterface;`
| `property UpdatePart: Cardinal read FUpdatePart write FUpdatePart default DefaultUpdatePart;`
| `property UpdateTicks: TMilisecTime read FUpdateTicks write FUpdateTicks default DefaultUpdateTicks;`
| `property Position: Cardinal read FPosition write SetPosition;`
| `property Max: Cardinal read FMax;`
| `property Title: string read FTitle;`
| `property Active: boolean read FActive;`
## Description ### Fields
| `internal const DefaultUpdatePart = 100 ;`
| `internal const DefaultUpdateTicks = 250 ;`
### Methods
| `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 UpdateTicks 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.
| `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.
| `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).
| `constructor Create;`
### Properties
| `property UserInterface: TProgressUserInterface read FUserInterface write FUserInterface;`
| `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 UpdateTicks miliseconds must pass to redraw. This allows you to call Step very often, without worrying that you cause redraw too often (which would cause slowdown).
| `property UpdateTicks: TMilisecTime read FUpdateTicks write FUpdateTicks default DefaultUpdateTicks;`
| `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.
| `property Max: Cardinal read FMax;`
| `property Title: string read FTitle;`
| `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.13.0 on 2015-06-15 04:43:11