Table of Contents

Class ProgressDialog

Namespace
NetEx.Dialogs.WinForms
Assembly
NetEx.Dialogs.WinForms.dll

Displays a standard dialog box that informs the user of the progress of an action. This class cannot be inherited.

[ToolboxBitmap(typeof(ProgressDialog), "ProgressDialogToolboxBitmap.png")]
public sealed class ProgressDialog : CommonDialog, IComponent, IDisposable
Inheritance
ProgressDialog
Implements
Inherited Members

Remarks

ProgressDialog supports the standard ShowDialog() method of invocation, as is standard across all dialogs using CommonDialog. However, because the dialog is typically expected to be shown in a non-modal fashion, it is recommended to use the Show() method instead.

CredentialDialog is supported on all versions of Windows starting with Windows XP.

Windows Vista introduced new visual styling for many controls and UI elements, including the progress dialog. As a result, the appearance of the dialog is different between Windows XP and later Windows versions.

Windows 7 introduced the ability to display progress indicators on a taskbar icon.As a result the progress dialog, and subsequently this ProgressDialog implementation, will automatically display progress in the host application's taskbar icon on Windows 7 or later.

Constructors

ProgressDialog()

Initializes a new instance of the ProgressDialog class.

public ProgressDialog()

Properties

Animation

Gets or sets the resource that contains an Audio-Video Interleaved (AVI) clip to run in the dialog box. Not supported in Windows Vista and later.

[Browsable(false)]
public AnimationResource? Animation { get; set; }

Property Value

AnimationResource

An AnimationResource which points to a file and the index of the animation resource within that file. The default value is null.

AutoClose

Gets or sets a value that indicates whether the dialog box should automatically close upon cancellation or completion.

public bool AutoClose { get; set; }

Property Value

bool

true if the dialog box should automatically close upon cancellation or completion; otherwise false.

AutoTime

Gets or sets a value that indicates whether the dialog box calculates the time remaining based on its active time and progress. If this property is set to true, text can only be displayed on lines 1 and 2.

public bool AutoTime { get; set; }

Property Value

bool

true if the dialog box automatically estimate the remaining time; otherwise, false. The default is true.

CancelButton

Gets or sets a value indicating whether the Cancel button is displayed in the client area of the dialog box. If set to false the operation cannot be canceled. Use this only when absolutely necessary. Only applies to Windows Vista and later.

public bool CancelButton { get; set; }

Property Value

bool

true to display a Cancel button for the dialog box; otherwise, false. The default is true.

CancelMessage

Gets or sets a message to be displayed if the user cancels the operation.

public string CancelMessage { get; set; }

Property Value

string

The progress dialog cancel message. The default value is an empty string ("").

Remarks

Even though the user clicks Cancel, the application may not immediately call Close() to close the dialog box. 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 ...".

CompactPath

Gets or sets a value indicating whether to truncate path strings for text on lines 1, 2 and 3 of the dialog box. If set to true paths are compacted with PathCompactPath.

public bool CompactPath { get; set; }

Property Value

bool

true to have path strings compacted if they are too large to fit on a line; otherwise, false. The default is true.

Maximum

Gets or sets the maximum value of the range of the progress bar within the dialog box. This property has no effect if ShowProgressBar is set to false.

public ulong Maximum { get; set; }

Property Value

ulong

The maximum value of the range of the progress bar within the dialog box. The default is 100.

MinimizeBox

Gets or sets a value indicating whether the Minimize button is displayed in the caption bar of the dialog box.

public bool MinimizeBox { get; set; }

Property Value

bool

true to display a Minimize button for the dialog box; otherwise, false. The default is true.

ProgressBarStyle

Gets or sets the manner in which progress should be indicated on the progress bar within the dialog box. This property has no effect if ShowProgressBar is set to false. Only applies to Windows Vista and later.

public ProgressBarStyle ProgressBarStyle { get; set; }

Property Value

ProgressBarStyle

One of the ProgressBarStyle values. The default value is Continuous.

Remarks

Setting this value to Blocks will have no effect, and the appearance of the progress bar will be the same as if set to Continuous.

Exceptions

InvalidEnumArgumentException

value is not a member of the ProgressBarStyle enumeration.

ShowProgressBar

Gets or sets a value indicating whether a progress bar is displayed in the client area of the dialog box.

public bool ShowProgressBar { get; set; }

Property Value

bool

true to display a progress bar for the dialog box; otherwise, false. The default is true.

Remarks

Typically, an application can quantitatively determine how much of the operation remains and periodically pass that value to the progress dialog box. The progress dialog box then uses this information to update its progress bar. You would typically set this property to false if the calling application must wait for an operation to finish but does not have any quantitative information it can use to update the dialog box.

ShowRemainingTime

Gets or sets a value indicating whether time remaining is displayed in the client area of the dialog box.

public bool ShowRemainingTime { get; set; }

Property Value

bool

true to display the time remaining for the dialog box; otherwise, false. The default is true.

Title

Gets or sets the dialog box title.

public string Title { get; set; }

Property Value

string

The dialog box title. The default value is an empty string ("").

Value

Gets or sets the current position of the progress bar within the dialog box. This property has no effect if ShowProgressBar is set to false.

[Bindable(true)]
public ulong Value { get; set; }

Property Value

ulong

The position within the range of the progress bar. The default is 0.

Methods

Close()

Closes the dialog box.

public void Close()

Dispose(bool)

Releases the unmanaged resources used by the Component and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Reset()

Resets properties to their default values.

public override void Reset()

RunDialog(nint)

When overridden in a derived class, specifies a common dialog box.

protected override bool RunDialog(nint hwndOwner)

Parameters

hwndOwner nint

A value that represents the window handle of the owner window for the common dialog box.

Returns

bool

true if the dialog box was successfully run; otherwise, false.

SetLine(int, string)

Displays a message in the dialog.

public void SetLine(int line, string message)

Parameters

line int

The line number on which the text is to be displayed. Currently there are three lines — 1, 2, and 3. If AutoTime is set to true only lines 1 and 2 can be used. The estimated time will be displayed on line 3.

message string

The message to be displayed on the line specified.

Exceptions

ArgumentOutOfRangeException

line is less than 1 or greater than 3.

Show()

Runs a common dialog box with a default owner in a non-modal fashion.

public void Show()

Show(IWin32Window?)

Runs a common dialog box with the specified owner in a non-modal fashion.

public void Show(IWin32Window? owner)

Parameters

owner IWin32Window

Any object that implements IWin32Window that represents the top-level window that will own the modal dialog box.

Events

Canceled

Occurs when the user clicks the cancel button on the ProgressDialog. The event is not raised if the dialog box was shown using ShowDialog() or one of its overloads.

public event EventHandler? Canceled

Event Type

EventHandler

Closed

Occurs when the ProgressDialog is closed. The event is not raised if the dialog box was shown using ShowDialog() or one of its overloads.

public event EventHandler? Closed

Event Type

EventHandler