Copyright © Kambiz R. Khojasteh. All rights reserved.
Get future component updates from http://www.delphiarea.com.

• Delphi 3
• Delphi 4
• Delphi 5
• Delphi 6
• Delphi 7
• Delphi 2005
• Delphi 2006
• Delphi 2007
• Delphi 2009
• Delphi 2010

DESCRIPTION

The TBackgroundWorker component allows you to run an operation on a separate, dedicated thread. Time-consuming operations like downloads and database transactions can cause your user interface (UI) to seem as though it has stopped responding while they are running. When you want a responsive UI and you are faced with long delays associated with such operations, the TBackgroundWorker component provides a convenient solution.

To execute a time-consuming operation in the background, create a TBackgroundWorker component and listen for events that report the progress of your operation and signal when your operation is finished. You can create the TBackgroundWorker component programmatically or you can drag it onto your form from the Components palette.

To set up for a background operation, add an event handler for the OnWork event. Call your time-consuming operation in this event handler. To start the operation, call Execute method. To receive notifications of progress updates, handle the OnWorkProgress event. To receive feedbacks from the operation in background, handle OnWorkFeedback event. To receive a notification when the operation is completed, handle the OnWorkComplete event.

PROPERTIES

• CancellationPending: Boolean ^(Read-only)
  Indicating whether the application has requested cancellation of the background operation.
  This property is true when Cancel method is called but the background operation has not accepted it yet.
• IsCancelled: Boolean ^(Read-only)
  Indicates whether the last background operation was cancelled.
• IsWorking: Boolean ^(Read-only)
  Indicates whether the component is running a background operation.
• ThreadID: Boolean ^(Read-only)
  Identifies the worker thread throughout the system. When the component is not running a background operation, this property is zero.
  You can use this property for debugging purposes or when calling Win32 API functions for manipulating the thread.

METHODS

• procedure Execute
  Starts execution of a background operation.
• procedure Cencel
  Requests cancellation of the background operation.
• procedure WaitFor
  Waits for the background operation to terminate.
• procedure ReportProgress(PercentDone: Integer)
  This procedure can be called only inside the OnWork event handler.
  Raises the OnWorkProgress event sometime later in the main VCL thread, but the current thread does not wait for the event to occur.
  The background operation can use this procedure to report its current progress to the main thread.
• procedure ReportProgressWait(PercentDone: Integer)
  This procedure can be called only inside the OnWork event handler.
  Raises the OnWorkProgress event in the main VCL thread, and waits for the event to occur.
  The background operation can use this procedure to report its current progress to the main thread.
• procedure ReportFeedback(FeedbackID, FeedbackValue: Integer)
  This procedure can be called only inside the OnWork event handler.
  Raises the OnWorkFeedback event sometime later in the main VCL thread, but the current thread does not wait for the event to occur.
  The background operation can use this procedure to send feedbacks to the main thread.
• procedure ReportFeedbackWait(FeedbackID, FeedbackValue: Integer)
  This procedure can be called only inside the OnWork event handler.
  Raises the OnWorkFeedback event in the main VCL thread, and waits for the event to occur.
  The background operation can use this procedure to send feedbacks to the main thread.
• procedure Synchronize(Method: TThreadMethod)
  This procedure can be called only inside the OnWork event handler.
  Calls a method in the main VCL thread and waits until the method returns.
• procedure AcceptCancellation
  This procedure can be called only inside the OnWork event handler.
  Causes a pending cancellation request be accepted and IsCancelled property set to true.
  Your background operation should check PendingCancellation periodically and when it is true, call AcceptCancellation and exit.

EVENTS

• OnWork: TWorkEvent
  procedure(Worker: TBackgroundWorker) of object
  Occurs when Execute method is called. This is where you start the operation that performs the potentially time-consuming work.

  Your code in the OnWork event handler should periodically check the CancellationPending property value and abort the operation if it is true. When this occurs, you can call AcceptCancellation method, and the IsCancelled property will be set to true.

  You must be careful not to manipulate any user-interface objects in your OnWork event handler. Instead, communicate to the user interface through the provided events.

• OnWorkComplete: TWorkCompleteEvent
  procedure(Worker: TBackgroundWorker; Cancelled: Boolean) of object
  Ocurs when background operation has been completed or has been cancelled.

  The Cancelled parameter indicates whether a cancellation request was processed by the background operation. If your code in the OnWork event handler detects a cancellation request by checking the CancellationPending property value and calling the AccceptCancellation method, the Cancelled parameter will be true.

  Be aware that your code in the OnWork event handler may finish its work as a cancellation request is being made, and your polling loop may miss CancellationPending being set to true. In this case, the Cancelled parameter will not be true, even though a cancellation request was made. This situation is called a race condition and is a common concern in multithreaded programming.

• OnWorkProgress: TWorkProgressEvent
  procedure(Worker: TBackgroundWorker; PercentDone: Integer) of object
  Occurs when the background operation reports its work progress to the main thread.
• OnWorkFeedback: TWorkFeedbackEvent
  procedure(Worker: TBackgroundWorker; FeedbackID, FeedbackValue: Integer) of object
  Occurs when the background operation sends feedback to the main thread.

HISTORY

• Version 1.1 (December 6, 2008)
  - Added ReportProgressWait, ReportFeedbackWait, and Synchronize methods.
• Version 1.0 (November 19, 2008)
  - Initial release.

LICENSE

The TBackgroundWorker component is freeware. You may copy components' files AS LONG AS YOU COPY ALL OF THEM. If you want to change the source code in order to improve the component's features, performance, etc. please send me the new source code so that I can have a look at it. The changed source code should contain descriptions what you have changed, and of course your name. The only thing you MAY NOT CHANGE is the ORIGINAL COPYRIGHT INFORMATION.

DISCLAIMER

The TBackgroundWorker component is provided "AS IS" without any warranty of any kind, either express or implied. The entire risk as to the quality and performance of the software is with you. The author is NOT liable for any DAMAGES resulting from the use and misuse of the components, especially he is NOT liable for DAMAGES that were caused BY ANY VERSION WHICH HAS NOT BEEN PROGRAMMED BY THE AUTHOR HIMSELF.