IProgressDialog (Interfaces)
Last changed: -93.87.206.141

.
Summary
Exposes methods that provide options for an application to display a progress dialog box.

C# Definition:

    [ComImport]
    [Guid("EBBC7C04-315E-11d2-B62F-006097DF5BD4")]
    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
    public interface IProgressDialog
    {
        /// <summary>
        /// Starts the progress dialog box.
        /// </summary>
        /// <param name="hwndParent">A handle to the dialog box's parent window.</param>
        /// <param name="punkEnableModless">Reserved. Set to null.</param>
        /// <param name="dwFlags">Flags that control the operation of the progress dialog box. </param>
        /// <param name="pvResevered">Reserved. Set to IntPtr.Zero</param>
        void StartProgressDialog(
            IntPtr hwndParent, //HWND
            [MarshalAs(UnmanagedType.IUnknown)]    object punkEnableModless, //IUnknown
            PROGDLG dwFlags,  //DWORD
            IntPtr pvResevered //LPCVOID
            );

        /// <summary>
        /// Stops the progress dialog box and removes it from the screen.
        /// </summary>
        void StopProgressDialog();

        /// <summary>
        /// Sets the title of the progress dialog box.
        /// </summary>
        /// <param name="pwzTitle">A pointer to a null-terminated Unicode string that contains the dialog box title.</param>
        void SetTitle(
            [MarshalAs(UnmanagedType.LPWStr)] string pwzTitle //LPCWSTR
            );

        /// <summary>
        /// Specifies an Audio-Video Interleaved (AVI) clip that runs in the dialog box. Note: Note  This method is not supported in Windows Vista or later versions.
        /// </summary>
        /// <param name="hInstAnimation">An instance handle to the module from which the AVI resource should be loaded.</param>
        /// <param name="idAnimation">An AVI resource identifier. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by hInstAnimation.</param>
        void SetAnimation(
            IntPtr hInstAnimation, //HINSTANCE
            ushort idAnimation //UINT
            );

        /// <summary>
        /// Checks whether the user has canceled the operation.
        /// </summary>
        /// <returns>TRUE if the user has cancelled the operation; otherwise, FALSE.</returns>
        /// <remarks>
        /// The system does not send a message to the application when the user clicks the Cancel button.
        /// You must periodically use this function to poll the progress dialog box object to determine
        /// whether the operation has been canceled.
        /// </remarks>
        [PreserveSig] //yes the only method with PreserveSig, every other method returns an HRESULT
        [return: MarshalAs(UnmanagedType.Bool)]
        bool HasUserCancelled();

        /// <summary>
        /// Updates the progress dialog box with the current state of the operation.
        /// </summary>
        /// <param name="dwCompleted">An application-defined value that indicates what proportion of the operation has been completed at the time the method was called.</param>
        /// <param name="dwTotal">An application-defined value that specifies what value dwCompleted will have when the operation is complete.</param>
        void SetProgress(
            uint dwCompleted, //DWORD
            uint dwTotal //DWORD
            );

        /// <summary>
        /// Updates the progress dialog box with the current state of the operation.
        /// </summary>
        /// <param name="ullCompleted">An application-defined value that indicates what proportion of the operation has been completed at the time the method was called.</param>
        /// <param name="ullTotal">An application-defined value that specifies what value ullCompleted will have when the operation is complete.</param>
        void SetProgress64(
            ulong ullCompleted, //ULONGLONG
            ulong ullTotal //ULONGLONG
            );

        /// <summary>
        /// Displays a message in the progress dialog.
        /// </summary>
        /// <param name="dwLineNum">The line number on which the text is to be displayed. Currently there are three lines—1, 2, and 3. If the PROGDLG_AUTOTIME flag was included in the dwFlags parameter when IProgressDialog::StartProgressDialog was called, only lines 1 and 2 can be used. The estimated time will be displayed on line 3.</param>
        /// <param name="pwzString">A null-terminated Unicode string that contains the text.</param>
        /// <param name="fCompactPath">TRUE to have path strings compacted if they are too large to fit on a line. The paths are compacted with PathCompactPath.</param>
        /// <param name="pvResevered"> Reserved. Set to IntPtr.Zero.</param>
        /// <remarks>This function is typically used to display a message such as "Item XXX is now being processed." typically, messages are displayed on lines 1 and 2, with line 3 reserved for the estimated time.</remarks>
        void SetLine(
            uint dwLineNum, //DWORD
            [MarshalAs(UnmanagedType.LPWStr)] string pwzString, //LPCWSTR
            [MarshalAs(UnmanagedType.VariantBool)] bool fCompactPath, //BOOL
            IntPtr pvResevered //LPCVOID
            );

        /// <summary>
        /// Sets a message to be displayed if the user cancels the operation.
        /// </summary>
        /// <param name="pwzCancelMsg">A pointer to a null-terminated Unicode string that contains the message to be displayed.</param>
        /// <param name="pvResevered">Reserved. Set to NULL.</param>
        /// <remarks>Even though the user clicks Cancel, the application cannot immediately call
        /// IProgressDialog::StopProgressDialog to close the dialog box. The application must wait until the
        /// next time it calls IProgressDialog::HasUserCancelled to discover that the user has canceled the
        /// operation. Since this delay might be significant, the progress dialog box provides the user with
        /// immediate feedback by clearing text lines 1 and 2 and displaying the cancel message on line 3.
        /// The message is intended to let the user know that the delay is normal and that the progress dialog
        /// box will be closed shortly.
        /// It is typically is set to something like "Please wait while ...". </remarks>
        void SetCancelMsg(
            [MarshalAs(UnmanagedType.LPWStr)] string pwzCancelMsg, //LPCWSTR
            object pvResevered //LPCVOID
            );

        /// <summary>
        /// Resets the progress dialog box timer to zero.
        /// </summary>
        /// <param name="dwTimerAction">Flags that indicate the action to be taken by the timer.</param>
        /// <param name="pvResevered">Reserved. Set to NULL.</param>
        /// <remarks>
        /// The timer is used to estimate the remaining time. It is started when your application
        /// calls IProgressDialog::StartProgressDialog. Unless your application will start immediately,
        /// it should call Timer just before starting the operation.
        /// This practice ensures that the time estimates will be as accurate as possible. This method
        /// should not be called after the first call to IProgressDialog::SetProgress.</remarks>
        void Timer(
            PDTIMER dwTimerAction, //DWORD
            object pvResevered //LPCVOID
            );

    }

    [ComImport]
    [Guid("F8383852-FCD3-11d1-A6B9-006097DF5BD4")]
    public class ProgressDialog
    {
    }

User-Defined Types:

PROGDLG, PDTIMER, PathCompactPath

Notes:

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.

Sample Usage:

IProgressDialog pd = (IProgressDialog)new ProgressDialog();
pd.SetTitle("Performing Operation");
pd.SetCancelMsg("Please wait while the operation is cancelled", null);
pd.StartProgressDialog(this.Handle, null, PROGDLG.Modal | PROGDLG.AutoTime | PROGDLG.NoMinimize, IntPtr.Zero);
try
{
    pd.Timer(PDTIMER.Reset, null);
    pd.SetLine(1, "Line one", false, IntPtr.Zero);
    pd.SetLine(2, "Line one", false, IntPtr.Zero);
    pd.SetProgress(4, 1000);
}
finally
{
    pd.StopProgressDialog();     
}

Documentation