public class TMtxProgressDialog : TMtxComponent
Manages and provides progress indicators of multi-threaded algorithms.
The TMtxProgressDialog component greatly simplifies the display of progress indicators and offers built-in support to cancel the execution of algorithms running in it's background thread. The progress can be indicated with events or by displaying its improvised progress dialog.
The design does not use the Synchronize procedure to update progress indicators and makes the most out of the available CPU power.
Usage example:
myProgress.DefineLoop(0, 1000-1); //how many times OnCompute should be called myProgress.OnCompute := MyCompute; //Mycompute will be called from a single background thread myProgress.OnProgressUpdate := MyProgressUpdate; //for progress indicators. Runs in main apps thread myProgress.Start;
When the processing finishes, the OnProgressUpdate will be called with TMtxProgressEvent.peCleanUp param from the main UI thread. The computation can be cancelled, by setting
myProgress.Cancel := True;
If the desire is to cancel and to block execution until all the processing has stopped call:
myProgress.Stop;
If the desire is to block execution and wait until all the processing has stopped call:
myProgress.WaitToFinish; // prefer OnProgressUpdate to detect the end (!)
The blocking calls however defeat the primary purpose of this component, which is to provide non-blocking interface to launch, track and detect the end of processing.
The component is targeted at user interaction with the UI and its one internal thread should not be used for massivally parallel computations.Use MtxVec.DoForLoop for such tasks. DoForLoop could/should/can be placed inside of MyCompute to do the actual mult-threaded computation.
Properties
| Name | Type | Description |
|---|---|---|
| BlockAssign | Boolean | Block streaming of specific properties when storing only a "template". |
| Cancel | Boolean | If true, cancel thread execution. |
| Counter | Int32 | Cycle counter. |
| EditorActive | Boolean | Returns True, if the component editor is displayed. |
| InfiniteLoop | Boolean | If Dew.Math.Controls.TMtxProgressDialog.InternalLoop is true and InfiniteLoop is set to true, the thread will be calling OnCompute event until Dew.Math.Controls.TMtxProgressDialog.Cancel is changed to true. |
| InternalLoop | Boolean | If set to true, the Dew.Math.Controls.TMtxProgressDialog.Compute event will be called Dew.Math.Controls.TMtxProgressDialog.Loops times, from Min to Max. If set to false, the OnCompute event will be called only once and the user can use any kind of processing within Dew.Math.Controls.TMtxProgressDialog.Compute event. |
| Loops | Int32 | Number of loops to execute if Dew.Math.Controls.TMtxProgressDialog.InternalLoop is true. |
| Max | Int32 | Defines the upper index for the loop. |
| Min | Int32 | Defines the lower index for the loop. |
| Priority | ThreadPriority | The priority of the executing thread. |
| Reference | TReferenceList | Stores a list of components that have to be notified, when this component is destroyed. |
| Runtime | TMtxProgressRuntime | Direct access to the underlying runtime. Exposed for advanced scenarios, but hidden from the designer to preserve the classic ProgressDialog surface. |
| ShowDialog | Boolean | If true, the component will display it's default progress dialog. |
| TerminatingException | String | Cycle counter. |
| ThreadBypass | Boolean | Bypass using thread. |
| ThreadName | String | Thread name. |
| UpdateInterval | Int32 | Defines the time interval in miliseconds between calls to OnProgressUpdate with peCycle parameter, while the background thread is executing. |
| WorkerActive | Boolean | True while a background worker is active. |
Methods
| Name | Description |
|---|---|
| AllowStreaming | Returns the negatated value of BlockAssign. |
| Assign | Assign values of all published properties from Source. |
| AssignTemplate | Assign values of "template-like" published properties from Source. |
| ctor (2) | Constructor. |
| DefineLoop | Set the range of loop with one method call. |
| DefineProgressBar | Setup progress bar control. |
| EditorClass | To be overriden in descendanr classses. |
| LoadFromStream | Load the component from Src stream. |
| LoadTemplateFromFile | Load a template from file. |
| LoadTemplateFromStream | Load a template from stream. |
| Reset | Reset is called after loading the data from stream or file. |
| SaveTemplateToFile | Save template to file. |
| SaveTemplateToStream | Save template to stream. |
| SaveToStream | Save the component to Dst stream. |
| Start | Start execting the thread. |
| Stop | Stop executing the thread. |
| Terminate | Alias for Stop. |
| WaitToFinish | Block until the background job finishes. |
Constants
| Name | Type | Description |
|---|---|---|
| Form | Form | Progress dialog form. |
Events
| Name | Description |
|---|---|
| CleanUp | Called after the thread has completed from the main thread. |
| Compute | The actual algorithm, that needs to be threaded or it's progress monitored, should be placed within this event. |
| Exception | Called if the worker raises an exception. |
| Initialize | Called as main thread is being initialized. |
| Progress | Called as progress indicator is updated. |
| ProgressUpdate | The event is called before the thread starts executing with Dew.Math.TMtxProgressEvent.peInit parameter. |