IProgressDialog Interface

CLSID_ProgressDialog

{F8383852-FCD3-11d1-A6B9-006097DF5BD4}

IID_IProgressDialog

{EBBC7C04-315E-11d2-B62F-006097DF5BD4}

The IProgressDialog 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.

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 Audio-Video Interleaved (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 normally 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.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IProgressDialog Methods

Description

StartProgressDialog

Starts the progress dialog box.

StopProgressDialog

Stops the progress dialog box and removes it from the screen.

SetTitle

Sets the title of the progress dialog box.

SetAnimation

Specifies an AVI clip that will run in the dialog box.

HasUserCancelled

Checks whether the user has canceled the operation.

SetProgress

Updates the progress dialog box with the current state of the operation.

SetProgress64

Updates the progress dialog box with the current state of the operation.

SetLine

Displays a message.

SetCancelMsg

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

Timer

Resets the progress dialog box timer to zero.

Wrapper to create an instance of the Progress Dialog

FUNCTION IProgressDialog_CreateInstance ( _

  BYREF ppd AS DWORD _

  ) AS LONG

  LOCAL hr AS LONG
  LOCAL CLSID_ProgressDialog AS GUID
  LOCAL IID_ProgressDialog AS GUID

  CLSID_ProgressDialog = GUID$("{F8383852-FCD3-11d1-A6B9-006097DF5BD4}")
  IID_ProgressDialog = GUID$("{EBBC7C04-315E-11d2-B62F-006097DF5BD4}")
  hr = CoCreateInstance(CLSID_ProgressDialog, BYVAL %NULL, %CLSCTX_INPROC_SERVER, IID_ProgressDialog, ppd)
  FUNCTION = hr

END FUNCTION

StartProgressDialog

FUNCTION IProgressDialog_StartProgressDialog ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL hwndParent AS DWORD _

, BYVAL punkEnableModless AS DWORD _

, BYVAL dwFlags AS DWORD _

, OPTIONAL BYVAL pvResevered AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IProgressDialog_StartProgressDialog (pthis, hwndParent, punkEnableModless , dwFlags, pvResevered) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

StopProgressDialog

FUNCTION IProgressDialog_StopProgressDialog ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IProgressDialog_StopProgressDialog (pthis) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetTitle

FUNCTION IProgressDialog_SetTitle ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strTitle AS STRING _

  ) AS LONG

  LOCAL HRESULT AS LONG
  strTitle = UCODE$(strTitle & $NUL)
  CALL DWORD @@pthis[5] USING IProgressDialog_SetTitle (pthis, strTitle) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetAnimation

FUNCTION IProgressDialog_SetAnimation ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL hInstAnimation AS DWORD _

, BYVAL idAnimation AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IProgressDialog_SetAnimation (pthis, hInstAnimation, idAnimation) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

HasUserCancelled

FUNCTION IProgressDialog_HasUserCancelled ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[7] USING IProgressDialog_HasUserCancelled (pthis) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetProgress

FUNCTION IProgressDialog_SetProgress ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwCompleted AS DWORD _

, BYVAL dwTotal AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[8] USING IProgressDialog_SetProgress (pthis, dwCompleted, dwTotal) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetProgress64

FUNCTION IProgressDialog_SetProgress64 ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL ullCompleted AS QUAD _

, BYVAL ullTotal AS QUAD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[9] USING IProgressDialog_SetProgress64 (pthis, ullCompleted, ullTotal) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetLine

FUNCTION IProgressDialog_SetLine ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwLineNum AS DWORD _

, BYVAL strText AS STRING _

, BYVAL fCompactPath AS LONG _

, OPTIONAL BYVAL pvReserved AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  strText = UCODE$(strText & $NUL)
  CALL DWORD @@pthis[10] USING IProgressDialog_SetLine (pthis, dwLineNum, strText, fCompactPath, pvReserved) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetCancelMsg

FUNCTION IProgressDialog_SetCancelMsg ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strCancelMsg AS STRING _

, OPTIONAL BYVAL pvReserved AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  strCancelMsg = UCODE$(strCancelMsg) & $NUL

  CALL DWORD @@pthis[11] USING IProgressDialog_SetCancelMsg (pthis, strCancelMsg, pvReserved) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Timer

FUNCTION IProgressDialog_Timer ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwTimerAction AS DWORD _

, OPTIONAL BYVAL pvReserved AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[12] USING Proto_IProgressDialog_Timer (pthis, dwTimerAction, pvReserved) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION