Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Support Forum
Download Visual Studio Add-In

Terms of Use
Privacy Policy
IProgressDialog (Interfaces)
 
.
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();     
}

Usage Examples/Links:

http://pietschsoft.com/post/2009/08/17/CSharp-IProgressDialog-Show-Native-Progress-Dialog-from-dotNet-in-Windows.aspx

Documentation

Please edit this page!

Do you have...

  • helpful tips?
  • corrections to the existing content?
  • alternate definitions?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing any supporting types needed.

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions