ProgressDialog リファレンス

シェル標準の進捗ダイアログ(IProgressDialog)を扱う ProgressDialog オブジェクトのリファレンスです。

記法: M=メソッド。メンバー名の照合は大文字小文字を区別しません。戻り値が「HRESULT」とあるものは、IProgressDialog の戻り値(0=成功、失敗は負値)です。

目次

  1. 取得方法
  2. メソッド
  3. 定数
  4. 使用例

1. 取得方法

const Progress = api.CreateObject("ProgressDialog");   // 推奨
const Progress2 = te.ProgressDialog;                   // te.ProgressDialog も同じ(参照のたびに新規生成)

作成しただけではダイアログは表示されません。StartProgressDialog を呼んで表示し、処理が終わったら StopProgressDialog で閉じます。

2. メソッド

名前 戻り値 説明
StartProgressDialog(hwnd, punkEnableModless, flags) HRESULT ダイアログを表示する。3個の引数が必要。hwnd は親ウィンドウ(通常は te.hwnd)、punkEnableModless は通常 null、flags は PROGDLG_*(3章)
StopProgressDialog() HRESULT ダイアログを閉じる。先にウィンドウを非表示にしてから停止する。必ず呼んで閉じること(try … finally 推奨)
SetProgress(current, total [, mode]) なし 進捗バーを current / total に設定する。2個以上の引数が必要。値は 64bit 整数。mode はタイトルバーの表示(下記)
HasUserCancelled([current, total [, mode]]) bool ユーザーが「キャンセル」を押したか。引数を2個以上渡すと、SetProgress(current, total, mode) も実行してから結果を返す(sync.js の CustomSort などが、この形で進捗更新とキャンセル判定を同時に行っている)
SetLine(line, text, compactPath) HRESULT 本文の行を設定する。line は 1〜3(行番号)。compactPath は真にすると、長いパスを … で省略して表示する。3個の引数が必要
SetTitle(text) HRESULT ダイアログのタイトルを設定する
SetCancelMsg(text) HRESULT キャンセルを押した後に表示するメッセージを設定する
Timer(action) HRESULT 残り時間のタイマーを操作する。action は PDTIMER_RESET(1)でタイマーを0に戻す
SetAnimation(hInst, resId) HRESULT アニメーションを設定する。旧 OS(Windows 2000/XP)向けビルドでのみ有効で、通常のビルドでは何もしない

SetProgress の mode

mode タイトルバーの表示
0(省略時) 変更しない(進捗バーのみ更新)
1 NN% に書き換える(total が 0 のときは書き換えない)
2 以上 NN% ( 現在値 / 全体値 )(数値はロケールの桁区切り付き)に書き換える。ただし total が 100 のときは NN% のみ

進捗の計算は 64bit 整数の 100 * current / total です。mode を指定すると、SetTitle で設定したタイトルが上書きされます。

3. 定数

consts.js には PROGDLG_* の定義がありません。次の値を数値で指定してください(Windows の IProgressDialog の定義)。

PROGDLG_*(StartProgressDialog の flags)

名前 値 説明
PROGDLG_NORMAL 0 標準
PROGDLG_MODAL 1 モーダルにする
PROGDLG_AUTOTIME 2 残り時間を自動表示する(TE 標準スクリプトはこれを指定)
PROGDLG_NOTIME 4 残り時間を表示しない
PROGDLG_NOMINIMIZE 8 最小化ボタンを出さない
PROGDLG_NOPROGRESSBAR 0x10 進捗バーを出さない
PROGDLG_MARQUEEPROGRESS 0x20 進捗不明のマーキー表示
PROGDLG_NOCANCEL 0x40 キャンセルボタンを出さない

PDTIMER_*: PDTIMER_RESET = 1

上の PROGDLG_* の値は Windows SDK の定義によるものです(この実装コード内で値そのものは確認できていません)。

4. 使用例

const Progress = api.CreateObject("ProgressDialog");
Progress.StartProgressDialog(te.hwnd, null, 2);      // PROGDLG_AUTOTIME
try {
    Progress.SetTitle("処理中");
    Progress.SetLine(1, "ファイルを処理しています", true);
    const items = FV.Items();
    const nMax = items.Count;
    for (let i = 0; i < nMax; ++i) {
        // 進捗を更新し、キャンセルされたらループを抜ける
        if (Progress.HasUserCancelled(i, nMax, 2)) {
            break;
        }
        const path = items.Item(i).Path;
        Progress.SetLine(2, path, true);   // パスを省略表示
        // ... 実際の処理 ...
    }
} finally {
    Progress.StopProgressDialog();
}

// 非同期スクリプト(ui.js など WebView2 側)では await を付ける
const Progress = await api.CreateObject("ProgressDialog");
Progress.StartProgressDialog(ui_.hwnd, null, 2);
// ...
Progress.StopProgressDialog();

関連