ProgressDialog Reference

Reference for the ProgressDialog object, which handles the standard shell progress dialog (IProgressDialog).

Notation: M = method. Member names are matched case-insensitively. Where the return value is "HRESULT", it is the return value of IProgressDialog (0 = success, negative values = failure).

Table of Contents

  1. How to Obtain
  2. Methods
  3. Constants
  4. Examples

1. How to Obtain

const Progress = api.CreateObject("ProgressDialog");   // recommended
const Progress2 = te.ProgressDialog;                   // te.ProgressDialog is also the same (a new object is created on every reference)

Creating the object does not show the dialog. Call StartProgressDialog to show it, and call StopProgressDialog to close it when the work is done.

2. Methods

Name Return value Description
StartProgressDialog(hwnd, punkEnableModless, flags) HRESULT Shows the dialog. Requires 3 arguments. hwnd is the parent window (normally te.hwnd), punkEnableModless is normally null, and flags is PROGDLG_* (Chapter 3)
StopProgressDialog() HRESULT Closes the dialog. It hides the window first and then stops. Always call it to close the dialog (try … finally is recommended)
SetProgress(current, total [, mode]) none Sets the progress bar to current / total. Requires 2 or more arguments. Values are 64-bit integers. mode controls what is shown in the title bar (see below)
HasUserCancelled([current, total [, mode]]) bool Whether the user pressed "Cancel". If you pass 2 or more arguments, it also runs SetProgress(current, total, mode) before returning the result (CustomSort in sync.js and others use this form to update progress and check for cancellation at the same time)
SetLine(line, text, compactPath) HRESULT Sets a line of the body text. line is 1 to 3 (the line number). If compactPath is true, a long path is shortened with … when displayed. Requires 3 arguments
SetTitle(text) HRESULT Sets the title of the dialog
SetCancelMsg(text) HRESULT Sets the message shown after Cancel is pressed
Timer(action) HRESULT Operates the remaining-time timer. action = PDTIMER_RESET (1) resets the timer to 0
SetAnimation(hInst, resId) HRESULT Sets an animation. Effective only in builds for old operating systems (Windows 2000/XP); it does nothing in regular builds

mode of SetProgress

mode Title bar display
0 (when omitted) Unchanged (only the progress bar is updated)
1 Rewritten as NN% (not rewritten when total is 0)
2 or more Rewritten as NN% ( current / total ) (the numbers use the locale's digit grouping). However, when total is 100, only NN% is shown

Progress is calculated as the 64-bit integer expression 100 * current / total. If you specify mode, the title set with SetTitle is overwritten.

3. Constants

consts.js has no definitions for PROGDLG_*. Specify the following values as numbers (these are the Windows IProgressDialog definitions).

PROGDLG_* (flags of StartProgressDialog)

Name Value Description
PROGDLG_NORMAL 0 Standard
PROGDLG_MODAL 1 Make it modal
PROGDLG_AUTOTIME 2 Automatically show the remaining time (the standard TE scripts specify this)
PROGDLG_NOTIME 4 Do not show the remaining time
PROGDLG_NOMINIMIZE 8 Do not show the minimize button
PROGDLG_NOPROGRESSBAR 0x10 Do not show the progress bar
PROGDLG_MARQUEEPROGRESS 0x20 Marquee display for unknown progress
PROGDLG_NOCANCEL 0x40 Do not show the Cancel button

PDTIMER_*: PDTIMER_RESET = 1

The PROGDLG_* values above come from the Windows SDK definitions (the values themselves could not be confirmed in this implementation's code).

4. Examples

const Progress = api.CreateObject("ProgressDialog");
Progress.StartProgressDialog(te.hwnd, null, 2);      // PROGDLG_AUTOTIME
try {
    Progress.SetTitle("Processing");
    Progress.SetLine(1, "Processing files", true);
    const items = FV.Items();
    const nMax = items.Count;
    for (let i = 0; i < nMax; ++i) {
        // Update the progress, and leave the loop if it was cancelled
        if (Progress.HasUserCancelled(i, nMax, 2)) {
            break;
        }
        const path = items.Item(i).Path;
        Progress.SetLine(2, path, true);   // show the path in shortened form
        // ... the actual work ...
    }
} finally {
    Progress.StopProgressDialog();
}

// In an asynchronous script (the WebView2 side, such as ui.js), add await
const Progress = await api.CreateObject("ProgressDialog");
Progress.StartProgressDialog(ui_.hwnd, null, 2);
// ...
Progress.StopProgressDialog();