IProgressDialog

COM

IIDebbc7c04-315e-11d2-b62f-006097df5bd4継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アプリケーションが進行状況ダイアログボックスを表示するためのオプションを提供するメソッドを公開します。

解説(Remarks)

進行状況ダイアログボックスオブジェクトはモードレスダイアログボックスを作成し、クライアントがそのタイトル、アニメーション、テキスト行、進行状況バーを設定できるようにします。このオブジェクトはバックグラウンドスレッドで更新処理を行い、ユーザーが操作をキャンセルできるようにします。オプションとして、操作が完了するまでの残り時間を推定し、その情報をテキスト行として表示します。

通常、アプリケーションがこのインターフェイスを実装することはありません。このインターフェイスは、アプリケーションが使用するために進行状況ダイアログボックスオブジェクトによってエクスポートされます。

このインターフェイスは、アプリケーションで進行状況ダイアログボックスを表示する必要がある場合に使用します。オブジェクトを初期化するには次の手順を実行します。

CoCreateInstance を使用して、プロセス内進行状況ダイアログボックスオブジェクト(CLSID_ProgressDialog)を作成します。その IProgressDialog インターフェイス(IID_IProgressDialog)へのポインターを要求します。
IProgressDialog::SetTitle を呼び出して、ダイアログボックスのタイトルを指定します。
IProgressDialog::SetAnimation を呼び出して、操作の進行中に再生する AVI クリップを指定します。
IProgressDialog::SetCancelMsg を呼び出して、ユーザーが操作をキャンセルした場合に表示されるメッセージを指定します。

操作の進行状況を表示するには次の手順を実行します。

IProgressDialog::StartProgressDialog を呼び出して、ダイアログボックスを表示します。
操作が実行する作業の総量に数値を割り当てます。操作の進行状況を都合よく定義できる任意の数値を使用します。たとえば、操作の進行状況を完了した割合(パーセント)で指定したい場合は、この値を 100 に設定します。
IProgressDialog::Timer を呼び出して、タイマーをリセットします。このメソッドは、進行状況ダイアログオブジェクトが操作の残り時間を推定するために使用する起点を設定します。このメソッドを呼び出さない場合、起点は StartProgressDialog の呼び出しになります。
操作の進行に伴って、IProgressDialog::SetProgress を定期的に呼び出し、操作がどの程度完了したかをダイアログボックスに反映します。進行状況ダイアログオブジェクトは進行状況バーを更新し、残り時間の推定値を再計算します。都合のよい任意の数値による進捗の尺度を使用できます。ただし、4 ギガバイト(GB)を超える値を使用したい場合は、IProgressDialog::SetProgress の代わりに IProgressDialog::SetProgress64 を呼び出す必要があります。
ユーザーが キャンセル ボタンをクリックして操作をキャンセルしても、アプリケーションに通知は届きません。操作の進行に伴って、IProgressDialog::HasUserCancelled を定期的に呼び出して、ユーザーが キャンセル ボタンをクリックしたかどうかを確認します。アプリケーションは通常、IProgressDialog::SetProgress または IProgressDialog::SetProgress64 を呼び出すたびに、このメソッドを呼び出します。
ダイアログボックスには 3 行のテキストが表示されます。アプリケーションは IProgressDialog::SetLine を定期的に呼び出して、これらの行のいずれかにメッセージを表示できます。このメソッドは通常、操作の現在の状態に関する情報を提供するために使用されます。典型的なメッセージは「現在項目 XXX を処理しています...」のようなものです。メッセージは通常、1 行目と 2 行目に表示されます。3 行目にメッセージを表示できるのは、IProgressDialog::StartProgressDialog の dwFlags パラメーターに PROGDLG_AUTOTIME フラグを設定して、進行状況ダイアログオブジェクトに残り時間を推定するよう指示していない場合のみです。指示している場合、3 行目のテキスト行は推定時間の表示に使用されます。

操作が完了したら次の手順を実行します。

IProgressDialog::StopProgressDialog を呼び出して、ダイアログボックスを閉じます。
進行状況ダイアログボックスオブジェクトを解放します。

メソッド 10

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT StartProgressDialog(HWND hwndParent, IUnknown* punkEnableModless, DWORD dwFlags, void* pvResevered)

進行状況ダイアログボックスを開始します。

hwndParent	HWND	inoptional	ダイアログボックスの親ウィンドウへのハンドル。
punkEnableModless	IUnknown*	inoptional	予約済み。NULL を設定します。
dwFlags	DWORD	in	進行状況ダイアログボックスの動作を制御するフラグ。次の値の組み合わせです。 PROGDLG_NORMAL 進行状況ダイアログボックスの通常の動作。 PROGDLG_MODAL 進行状況ダイアログボックスは、hwndParent で指定されたウィンドウに対してモーダルになります。既定では、進行状況ダイアログボックスはモードレスです。 PROGDLG_AUTOTIME 残り時間を自動的に推定し、その推定値を 3 行目に表示します。このフラグを設定した場合、IProgressDialog::SetLine は 1 行目と 2 行目にテキストを表示するためにのみ使用できます。 PROGDLG_NOTIME 「残り時間」テキストを表示しません。 PROGDLG_NOMINIMIZE ダイアログボックスのキャプションバーに最小化ボタンを表示しません。 PROGDLG_NOPROGRESSBAR 進行状況バーを表示しません。通常、アプリケーションは操作の残り量を定量的に判断し、その値を IProgressDialog::SetProgress に定期的に渡すことができます。進行状況ダイアログボックスはこの情報を使用して進行状況バーを更新します。このフラグは通常、呼び出し側アプリケーションが操作の完了を待つ必要があるが、ダイアログボックスの更新に使用できる定量的な情報を持たない場合に設定します。 PROGDLG_MARQUEEPROGRESS Windows Vista 以降。進行状況バーをマーキーモードに設定します。これにより、進行状況バーはマーキー表示のように水平方向にスクロールします。進行していることを示したいが、操作に要する時間が不明な場合に使用します。 PROGDLG_NOCANCEL Windows Vista 以降。キャンセルボタンを表示しません。操作はキャンセルできません。どうしても必要な場合にのみ使用してください。
pvResevered	void*	optional	予約済み。NULL を設定します。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

vtbl 4 HRESULT StopProgressDialog()

進行状況ダイアログボックスを停止し、画面から削除します。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

vtbl 5 HRESULT SetTitle(LPWSTR pwzTitle)

進行状況ダイアログボックスのタイトルを設定します。

pwzTitle

LPWSTR

ダイアログボックスのタイトルを含む null 終端 Unicode 文字列へのポインター。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

vtbl 6 HRESULT SetAnimation(HINSTANCE hInstAnimation, DWORD idAnimation)

ダイアログボックス内で再生される Audio-Video Interleaved(AVI)クリップを指定します。

hInstAnimation	HINSTANCE	inoptional	AVI リソースの読み込み元となるモジュールへのインスタンスハンドル。
idAnimation	DWORD	in	AVI リソース識別子。この値を作成するには、MAKEINTRESOURCE マクロを使用します。コントロールは、hInstAnimation で指定されたモジュールから AVI リソースを読み込みます。

戻り値

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。Windows Vista 以降のバージョンでは、常に S_OK を返します。

解説(Remarks)

IProgressDialog::SetAnimation は、進行状況ダイアログが表示される前に呼び出すことはできません。表示されるまで、進行状況ダイアログは有効な HWND を持ちません。その HWND の存在を利用して、IProgressDialog::SetAnimation を呼び出せるかどうかを判断できます。

このメソッドは、hInstAnimation で指定されたインスタンスハンドルを取得し、アニメーションコントロールを使用して無音の AVI クリップを開いて再生します。使用できる AVI クリップの種類には、次のようないくつかの制限があります。

クリップに音声を含めることはできません。
AVI クリップのサイズは 272 × 60 ピクセルを超えることはできません。より小さい矩形も使用できますが、正しく中央揃えにならない場合があります。
AVI クリップは、非圧縮であるか、ランレングス(BI_RLE8)エンコードで圧縮されている必要があります。サポートされていない圧縮形式を使用しようとすると、アニメーションは表示されません。

vtbl 7 BOOL HasUserCancelled()

ユーザーが操作をキャンセルしたかどうかを確認します。

戻り値

型: BOOL

ユーザーが操作をキャンセルした場合は TRUE、それ以外の場合は FALSE。

解説(Remarks)

ユーザーが キャンセル ボタンをクリックしても、システムはアプリケーションにメッセージを送信しません。操作がキャンセルされたかどうかを判断するには、この関数を定期的に使用して進行状況ダイアログボックスオブジェクトをポーリングする必要があります。

vtbl 8 HRESULT SetProgress(DWORD dwCompleted, DWORD dwTotal)

進行状況ダイアログボックスを、操作の現在の状態で更新します。(IProgressDialog.SetProgress)

dwCompleted	DWORD	in	メソッドが呼び出された時点で操作のどの程度の割合が完了したかを示す、アプリケーション定義の値。
dwTotal	DWORD	in	操作が完了したときに dwCompleted が持つ値を指定する、アプリケーション定義の値。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

解説(Remarks)

都合のよい任意の数値による操作の進捗の尺度を使用します。4 ギガバイト(GB)を超える値を使用するには、代わりに IProgressDialog::SetProgress64 を呼び出すことができます。

vtbl 9 HRESULT SetProgress64(ULONGLONG ullCompleted, ULONGLONG ullTotal)

進行状況ダイアログボックスを、操作の現在の状態で更新します。(IProgressDialog.SetProgress64)

ullCompleted	ULONGLONG	in	メソッドが呼び出された時点で操作のどの程度の割合が完了したかを示す、アプリケーション定義の値。
ullTotal	ULONGLONG	in	操作が完了したときに ullCompleted が持つ値を指定する、アプリケーション定義の値。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは IProgressDialog::SetProgress とまったく同じ機能を持ちますが、1 つの DWORD(4 GB)より大きい値を使用できます。

vtbl 10 HRESULT SetLine(DWORD dwLineNum, LPWSTR pwzString, BOOL fCompactPath, void* pvResevered)

進行状況ダイアログにメッセージを表示します。

dwLineNum	DWORD	in	テキストを表示する行番号。現在は 1、2、3 の 3 行があります。IProgressDialog::StartProgressDialog が呼び出された際に dwFlags パラメーターに PROGDLG_AUTOTIME フラグが含まれていた場合、使用できるのは 1 行目と 2 行目のみです。推定時間は 3 行目に表示されます。
pwzString	LPWSTR	in	テキストを含む null 終端 Unicode 文字列。
fCompactPath	BOOL	in	パス文字列が 1 行に収まらないほど長い場合に圧縮するには TRUE にします。パスは PathCompactPath を使用して圧縮されます。
pvResevered	void*	optional	予約済み。NULL を設定します。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

解説(Remarks)

この関数は通常、「項目 XXX を現在処理しています。」のようなメッセージを表示するために使用されます。通常、メッセージは 1 行目と 2 行目に表示され、3 行目は推定時間のために予約されています。

vtbl 11 HRESULT SetCancelMsg(LPWSTR pwzCancelMsg, void* pvResevered)

ユーザーが操作をキャンセルした場合に表示するメッセージを設定します。

pwzCancelMsg	LPWSTR	in	表示するメッセージを含む null 終端 Unicode 文字列へのポインター。
pvResevered	void*	optional	予約済み。NULL を設定します。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

解説(Remarks)

ユーザーが キャンセル をクリックしても、アプリケーションはすぐに IProgressDialog::StopProgressDialog を呼び出してダイアログボックスを閉じることはできません。アプリケーションは、次に IProgressDialog::HasUserCancelled を呼び出して、ユーザーが操作をキャンセルしたことを検出するまで待つ必要があります。この遅延が大きくなる可能性があるため、進行状況ダイアログボックスは、テキストの 1 行目と 2 行目をクリアし、3 行目にキャンセルメッセージを表示することで、ユーザーに即座のフィードバックを提供します。このメッセージは、この遅延が正常であり、進行状況ダイアログボックスがまもなく閉じられることをユーザーに知らせることを目的としています。通常は「... の間、お待ちください」のようなものに設定されます。

vtbl 12 HRESULT Timer(DWORD dwTimerAction, void* pvResevered)

進行状況ダイアログボックスのタイマーをゼロにリセットします。

dwTimerAction

DWORD

タイマーが実行するアクションを示すフラグ。次のいずれかの値です。

PDTIMER_RESET

タイマーをゼロにリセットします。このメソッドが呼び出された時点から進行状況が計算されます。

PDTIMER_PAUSE

進行状況が一時停止されました。

PDTIMER_RESUME

進行状況が再開されました。

pvResevered

void*

optional

予約済み。NULL を設定します。

戻り値

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

解説(Remarks)

タイマーは残り時間の推定に使用されます。これはアプリケーションが IProgressDialog::StartProgressDialog を呼び出したときに開始されます。アプリケーションがすぐに開始しない場合は、操作を開始する直前に Timer を呼び出す必要があります。この方法により、時間の推定値が可能な限り正確になります。このメソッドは、IProgressDialog::SetProgress を初めて呼び出した後は呼び出さないでください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IProgressDialog "{EBBC7C04-315E-11D2-B62F-006097DF5BD4}"
#usecom global IProgressDialog IID_IProgressDialog "{F8383852-FCD3-11D1-A6B9-006097DF5BD4}"
#comfunc global IProgressDialog_StartProgressDialog  3 sptr,sptr,int,sptr
#comfunc global IProgressDialog_StopProgressDialog   4
#comfunc global IProgressDialog_SetTitle             5 wstr
#comfunc global IProgressDialog_SetAnimation         6 sptr,int
#comfunc global IProgressDialog_HasUserCancelled     7
#comfunc global IProgressDialog_SetProgress          8 int,int
#comfunc global IProgressDialog_SetProgress64        9 int64,int64
#comfunc global IProgressDialog_SetLine              10 int,wstr,int,sptr
#comfunc global IProgressDialog_SetCancelMsg         11 wstr,sptr
#comfunc global IProgressDialog_Timer                12 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。