Edit

IProgressDialog interface (shlobj_core.h)

  • Article

Exposes methods that provide options for an application to display a progress dialog box. This interface is exported by the progress dialog box object (CLSID_ProgressDialog). This object is a generic way to show a user how an operation is progressing. It is typically used when deleting, uploading, copying, moving, or downloading large numbers of files.

Inheritance

The IProgressDialog interface inherits from the IUnknown interface. IProgressDialog also has these types of members:

Methods

The IProgressDialog interface has these methods.

 
IProgressDialog::HasUserCancelled

Checks whether the user has canceled the operation.
IProgressDialog::SetAnimation

Specifies an Audio-Video Interleaved (AVI) clip that runs in the dialog box.
IProgressDialog::SetCancelMsg

Sets a message to be displayed if the user cancels the operation.
IProgressDialog::SetLine

Displays a message in the progress dialog.
IProgressDialog::SetProgress

Updates the progress dialog box with the current state of the operation. (IProgressDialog.SetProgress)
IProgressDialog::SetProgress64

Updates the progress dialog box with the current state of the operation. (IProgressDialog.SetProgress64)
IProgressDialog::SetTitle

Sets the title of the progress dialog box.
IProgressDialog::StartProgressDialog

Starts the progress dialog box.
IProgressDialog::StopProgressDialog

Stops the progress dialog box and removes it from the screen.
IProgressDialog::Timer

Resets the progress dialog box timer to zero.

Remarks

The progress dialog box object creates a modeless dialog box and allows the client to set its title, animation, text lines, and progress bar. The object then handles updating on a background thread and allows the user to cancel the operation. Optionally, it estimates the time remaining until the operation is complete and displays the information as a line of text.

Applications normally do not implement this interface. It is exported by the progress dialog box object for use by applications.

Use this interface when your application needs to display a progress dialog box. To initialize the object:

  1. Create an in-process progress dialog box object (CLSID_ProgressDialog) with CoCreateInstance. Request a pointer to its IProgressDialog interface (IID_IProgressDialog).
  2. Call IProgressDialog::SetTitle to specify the dialog box title.
  3. Call IProgressDialog::SetAnimation to specify an AVI clip to be played while the operation progresses.
  4. Call IProgressDialog::SetCancelMsg to specify the message that will be displayed if the user cancels the operation.
To display the progress of the operation:
  1. Call IProgressDialog::StartProgressDialog to display the dialog box.
  2. Assign a numerical value to the total amount of work the operation will perform. Use any number that allows you to conveniently define the progress of the operation. For example, set this value to 100 if you want to specify the progress of the operation in terms of the percent that has been completed.
  3. Call IProgressDialog::Timer to reset the timer. This method sets the starting point that the progress dialog object uses to estimate the time remaining in the operation. If you do not call this method, the starting point will be the call to StartProgressDialog.
  4. As the operation progresses, periodically call IProgressDialog::SetProgress to update the dialog box as to how much of the operation has been completed. The progress dialog object will update its progress bar and recalculate its estimate of the remaining time. You can use any numerical measure of progress that is convenient. However, if you want to use values larger than 4 gigabytes (GB), you must call IProgressDialog::SetProgress64 instead of IProgressDialog::SetProgress.
  5. Your application does not receive a notification if the user clicks the Cancel button to cancel the operation. As the operation progresses, periodically call IProgressDialog::HasUserCancelled to see if the user has clicked the Cancel button. Applications typically call this method each time they call IProgressDialog::SetProgress or IProgressDialog::SetProgress64.
  6. The dialog box displays three lines of text. An application can periodically call IProgressDialog::SetLine to display a message on one of these lines. This method is normally used to provide information on the current status of the operation. A typical message is something like: "Currently processing item XXX...". Messages are typically displayed on lines 1 and 2. You can display messages on line 3 only if you have not instructed the progress dialog object to estimate the remaining time by setting the PROGDLG_AUTOTIME flag in the dwFlags parameter of IProgressDialog::StartProgressDialog. In that case, the third text line is used to display the estimated time.
When the operation is complete:
  1. Call IProgressDialog::StopProgressDialog to close the dialog box.
  2. Release the progress dialog box object.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shlobj_core.h