{{div_begin}} [[←　16 章に戻る|Palm OS Programmer's API Reference/16]]　[[↑トップへ|Palm OS Programmer's API Reference]]　[[18 章に進む　→|Palm OS Programmer's API Reference/18]] {{div_end}} {{div_begin style="margin-bottom:-10px"}} !!!17 進捗マネージャ {{div_end}} {{div_begin "style='position:absolute;right:0px;font-size:70%;margin-right:15px;margin-top:15px;width:250px;'"}} *{{goto Progress Manager Functions,進捗マネージャ関数}} **{{goto PrgHandleEvent,PrgHandleEvent}} **{{goto PrgStartDialog,PrgStartDialog}} **{{goto PrgStartDialogV31,PrgStartDialogV31}} **{{goto PrgStopDialog,PrgStopDialog}} **{{goto PrgUpdateDialog,PrgUpdateDialog}} **{{goto PrgUserCancel,PrgUserCancel}} *{{goto Application-Defined Functions,アプリケーション定義関数}} **{{goto PrgCallbackFunc,PrgCallbackFunc}} {{div_end}} {{div_begin "style='position:relative;padding:0px;padding-right:5px;padding-left:10px;margin-right:250px;margin-top:20px;width:auto;border-right:dotted;border-right-width:2px;border-right-color:silver;'"}} この章では、進捗マネージャのための参照資源を提供します。 *{{goto Progress Manager Functions,進捗マネージャ関数}} *{{goto Application-Defined Functions,アプリケーション定義関数}} ヘッダ ファイル {{span style='color:blue;font-family:monospace;',Progress.h}} がこの章で説明される API を宣言しています。進捗マネージャについての更なる情報は、''Palm OS Programmer's Companion, vol. I'' の{{goto p4,「プログレス ダイアログ」|Palm OS Programmer's Companion Volume I/4-3}}を参照してください。 !!{{anchor Progress Manager Functions}}進捗マネージャ関数 {{goto top,^TOP^}} !{{anchor PrgHandleEvent}}PrgHandleEvent 関数 {{goto top,^TOP^}} '''目的''' アクティブな進捗ダイアログに関連するエベントを処理します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' Boolean PrgHandleEvent ( ProgressPtr prgGP, EventType *eventP ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ prgGP}} **{{goto PrgStartDialog,PrgStartDialog()}} によって作成される進捗構造体へのポインタ *{{span style='color:blue;font-family:monospace;',→ eventP}} **イベントへのポインタ。{{span style='color:blue;font-family:monospace;',NULL}} イベントを渡すことで、この関数にただちに {{goto PrgCallbackFunc,PrgCallbackFund()}} 関数を呼び出させて、ダイアログを更新させることができます（例えば、{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} を呼び出した後）。 '''返り値''' システムがイベントを処理した場合は、{{span style='color:blue;font-family:monospace;',true}} を返します。{{span style='color:blue;font-family:monospace;',false}} を返す場合、ユーザが {{goto PrgUserCancel,PrgUserCancel()}} を呼び出すことによってダイアログをキャンセルしたかどうかをチェックすべきです。 '''コメント''' 進捗ダイアログを持つとき、{{goto SysHandleEvent,SysHandleEvent()|Palm OS Programmer's API Reference/54}} の代わりに、この関数を使用します。{{span style='color:blue;font-family:monospace;',PrgHandleEvent}} は必要に応じて内部的に {{span style='color:blue;font-family:monospace;',SysHandleEvent}} を呼び出します。 この関数を使用するとき、ダイアログがエラーを表示していない限り、システムの自動 Power-off 機能は自動的に使用不可になることに注意してください。この関数はまた、{{span style='color:blue;font-family:monospace;',appStopEvent}} イベントをも無効にします。 ダイアログの更新が保留されている（例えば、{{goto PrgUpdateDialog,PrgUpdateDialog()}} 呼び出しから）場合、この関数はイベントを処理し、ダイアログを更新します。このプロセスの一部として、{{goto PrgStartDialog,PrgStartDialog()}} 呼び出しの中で指定された {{span style='color:blue;font-family:monospace;',textCallback}} 関数が呼び出されます。{{span style='color:blue;font-family:monospace;',textCallback}} 関数は、新しいメッセージを持つ {{span style='color:blue;font-family:monospace;',PrgCallbackData}} 構造体の中の {{span style='color:blue;font-family:monospace;',textP}} バッファを進捗ダイアログの中に表示させるべきです。オプションとして、{{span style='color:blue;font-family:monospace;',bitmapId}} フィールドに更新ダイアログの中のアイコンを持たせることができます。{{span style='color:blue;font-family:monospace;',textCallback}} 関数についての更なる情報は、{{goto Application-Defined Functions,「アプリケーション定義関数」}}を参照してください。 '''互換性''' {{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。 '''参照''' {{goto PrgStartDialog,PrgStartDialog()}}, {{goto PrgStopDialog,PrgStopDialog()}}, {{goto PrgUpdateDialog,PrgUpdateDialog()}}, {{goto PrgUserCancel,PrgUserCancel()}} !{{anchor PrgStartDialog}}PrgStartDialog 関数 {{goto top,^TOP^}} '''目的''' 更新することができる進捗ダイアログを表示します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' ProgressPtr PrgStartDialog ( const Char *title, PrgCallbackFunc textCallback, void *userDataP ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ title}} **進捗ダイアログのためのタイトルへのポインタ。{{span style='color:blue;font-family:monospace;',progressMaxTitle}} (20) よりも長くない null で終了する文字列で無ければなりません。 *{{span style='color:blue;font-family:monospace;',→ textCallback}} **現在の進捗状況のためのテキストとアイコンを提供するコールバック関数へのポインタ。{{goto PrgCallbackFunc,PrgCallbackFunc()}} を参照してください。 *{{span style='color:blue;font-family:monospace;',→ userDataP}} **コールバック関数の中でアクセスする必要のあるデータへのポインタ。このアドレスはコールバック関数に直接渡されます。 '''返り値''' 進捗構造体へのポインタ。このポインタは他の進捗マネージャ関数に渡されなくてはならず、さらに、{{goto PrgStopDialog,PrgStopDialog()}} 呼び出しによって解放されなくてはなりません。システムが進捗構造体をあり当てることができない場合は、{{span style='color:blue;font-family:monospace;',NULL}} を返します。 '''コメント''' この関数によって作成されるダイアログは、{{goto PrgUpdateDialog,PrgUpdateDialog()}} 関数経由で他のプロセスから更新することができます。ダイアログは Cancel または OK ボタンを保持することができます。初期状態のダイアログはデフォルトでステージ 0 の状態にあり、{{span style='color:blue;font-family:monospace;',textCallback}} 関数を呼び出して初期テキストとアイコン データを進捗ダイアログのために取得します。 この関数は進捗ダイアログの背後にあるスクリーン ビットを保存し、{{span style='color:blue;font-family:monospace;',PrgStopDialog}} を呼び出すときこれらのビットは保存されます。このため、進捗ダイアログが表示されている間スクリーンへの変更は最小限にすべきであり、そうでないと、保存されるビットは現在表示されているものと一致しないかもしれません。 '''互換性''' このバージョンの関数は、{{goto 3.2 New Feature Set,3.2 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、使用可能です。それより前のシステムでは、{{span style='color:blue;font-family:monospace;',PrgStartDialog}} は {{goto PrgStartDialogV31,PrgStartDialogV31()}} で示されているプロトタイプを持ちます。 '''参照''' {{goto PrgHandleEvent,PrgHandleEvent()}}, {{goto PrgStopDialog,PrgStopDialog()}}, {{goto PrgUpdateDialog,PrgUpdateDialog()}}, {{goto PrgUserCancel,PrgUserCancel()}} !{{anchor PrgStartDialogV31}}PrgStartDialogV31 関数 {{goto top,^TOP^}} '''目的''' 更新することができる進捗ダイアログを表示します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' ProgressPtr PrgStartDialogV31 ( const Char *title, PrgCallbackFunc textCallback ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ title}} **進捗ダイアログのためのタイトルへのポインタ。{{span style='color:blue;font-family:monospace;',progressMaxTitle}} (20) より長くない null で終了する文字列でなければなりません。 *{{span style='color:blue;font-family:monospace;',→ textCallback}} **現在の進捗状態のためのテキストとアイコンを提供するコールバック関数へのポインタ。{{goto PrgCallbackFunc,PrgCallbackFunc()}} を参照してください。 '''返り値''' 進捗構造体へのポインタ。このポインタは他の進捗マネージャ関数に渡されなければならず、かつ、{{goto PrgStopDialog,PrgStoDialog()}} 呼び出しによって解放されなくてはなりません。システムが進捗構造体を割り当てできない場合は、{{span style='color:blue;font-family:monospace;',NULL}} を返します。 '''互換性''' この関数は、Palm OS 3.0 と Palm OS 3.1 で使用可能な {{goto PrgStartDialog,PrgStartDialog()}} に対応するバージョンです。 '''参照''' {{goto PrgHandleEvent,PrgHandleEvent()}}, {{goto PrgStopDialog,PrgStopDialog()}}, {{goto PrgUpdateDialog,PrgUpdateDialog()}}, {{goto PrgUserCancel,PrgUserCancel()}} !{{anchor PrgStopDialog}}PrgStopDialog 関数 {{goto top,^TOP^}} '''目的''' 進捗ダイアログによって使用されるメモリを解放し、スクリーンを初期状態に戻します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' void PrgStopDialog ( ProgressPtr prgP, Boolean force ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ prgP}} **{{goto PrgStartDialog,PrgStartDialog()}} によって作成される進捗構造体へのポインタ *{{span style='color:blue;font-family:monospace;',→ force}} **{{span style='color:blue;font-family:monospace;',true}} だと、ただちに進捗ダイアログを削除します。{{span style='color:blue;font-family:monospace;',false}} だと、エラーが表示されている場合はユーザがエラーを確認するまでシステムを待機させます。 '''返り値''' 返り値はありません。 '''コメント''' 進捗ダイアログがユーザにエラーを表示している状態である場合、この関数は、通常、ユーザがダイアログを確認してからダイアログを削除します。{{span style='color:blue;font-family:monospace;',force}} パラメータを {{span style='color:blue;font-family:monospace;',true}} にセットした場合、システムはただちにダイアログを削除します。 '''互換性''' {{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。 '''参照''' {{goto PrgHandleEvent,PrgHandleEvent()}}, {{goto PrgStartDialog,PrgStartDialog()}}, {{goto PrgUpdateDialog,PrgUpdateDialog()}}, {{goto PrgUserCancel,PrgUserCancel()}} !{{anchor PrgUpdateDialog}}PrgUpdateDialog 関数 {{goto top,^TOP^}} '''目的''' 現在の進捗ダイアログの状態を更新します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' void PrgUpdateDialog ( ProgressPtr prgGP, UInt16 err, UInt16 stage, const Char *messageP, Boolean updateNow ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ prgGP}} **{{goto PrgStartDialog,PrgStartDialog()}} によって作成される進捗構造体へのポインタ *{{span style='color:blue;font-family:monospace;',→ err}} **0 でない場合、ダイアログはエラー モードに入り、OK ボタンのみを持つエラー メッセージを表示します。 *{{span style='color:blue;font-family:monospace;',→ stage}} **進捗の現在のステージ。コールバック関数は、これを使用して、更新されるダイアログの中に表示される適切な文字列を決定することができます。 *{{span style='color:blue;font-family:monospace;',→ messageP}} **このステージのために進捗を表示するのに有用であるかもしれない臨時テキスト。ステージに基づくベース メッセージの後にそれを追加することができるコールバック関数によって使用されます。 *{{span style='color:blue;font-family:monospace;',→ updaNow}} **{{span style='color:blue;font-family:monospace;',true}} である場合、ダイアログはただちに更新されます。そうでない場合、ダイアログは次の {{goto PrgHandleEvent,PrgHandleEvent()}} 呼び出し時に更新されます。 '''返り値''' 返り値はありません。 '''コメント''' パラメータがどのように使用されるのか、コールバック関数についての更なる情報は、{{goto Application-Defined Functions,「アプリケーション定義関数」}}を参照してください。 '''互換性''' {{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。 '''参照''' {{goto PrgHandleEvent,PrgHandleEvent()}}, {{goto PrgStartDialog,PrgStartDialog()}}, {{goto PrgStopDialog,PrgStopDialog()}}, {{goto PrgUserCancel,PrgUserCancel()}} !{{anchor PrgUserCancel}}PrgUserCancel マクロ {{goto top,^TOP^}} '''目的''' ユーザが進捗ダイアログ経由で進捗をキャンセルした場合に、{{span style='color:blue;font-family:monospace;',true}} を返します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Prototype''' #define PrgUserCancel ( prgP ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',→ prgP}} **{{goto PrgStartDialog,PrgStartDialog()}} によって作成される進捗構造体へのポインタ（{{span style='color:blue;font-family:monospace;',ProgressPtr}}） '''返り値''' 進捗構造体の中の {{span style='color:blue;font-family:monospace;',cancel}} フィールドの値を（{{span style='color:blue;font-family:monospace;',UInt16}} として）返します。 '''コメント''' このマクロを使用して、ユーザが進捗をキャンセルしたかどうかをチェックすることができます。ユーザがキャンセルしていた場合、進捗ダイアログのテキストを「キャンセル中」または「接続切り離し中」またはアプリケーションにとって適切なものに変更することができます。それから、プロセスをキャンセルするか、通信セッションを終わらせるか、必要とされるなんらかの処理をすべきです。 '''互換性''' {{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。 '''参照''' {{goto PrgHandleEvent,PrgHandleEvent()}}, {{goto PrgStartDialog,PrgStartDialog()}}, {{goto PrgStopDialog,PrgStopDialog()}}, {{goto PrgUpdateDialog,PrgUpdateDialog()}} !!{{anchor anchorApplication-Defined Functions}}アプリケーション定義関数 {{goto top,^TOP^}} !{{anchor PrgCallbackFunc}}PrgCallbackFunc 関数 {{goto top,^TOP^}} '''目的''' 現在の進捗状態のためのテキストとアイコンを提供します。 '''宣言されている場所''' {{span style='color:blue;font-family:monospace;',Progress.h}} '''Progotype''' Boolean ( *PrgCallbackFunc )( PrgCallbackDataPtr cbP ) '''パラメータ''' *{{span style='color:blue;font-family:monospace;',←→ cbP}} **{{span style='color:blue;font-family:monospace;',PrgCallbackData}} 構造体へのポインタ。以下を参照してください。 '''返り値''' 進捗ダイアログが {{span style='color:blue;font-family:monospace;',PrgCallbackData}} 構造体の中で指定された値を使って更新されるべきである場合、{{span style='color:blue;font-family:monospace;',true}} を返します。{{span style='color:blue;font-family:monospace;',false}} を指定した場合、ダイアログは依然として更新されますが、デフォルトの状態メッセージを持ちます。（{{span style='color:blue;font-family:monospace;',false}} を返すことは推奨されません。） '''コメント''' これは、{{goto PrgStartDialog,PrgStartDialog()}} を呼び出すときに指定するコールバック関数です。このコールバック関数は、現在の進捗情報を進捗ダイアログの中に表示する必要があるときに、{{goto PrgHandleEvent,PrgHandleEvent()}} によって呼び出されます。 *{{span_begin style='color:blue;font-family:monospace;font-style:italic;'}}→ システムはこの関数に {{span style='font-style:normal',PrgCallbackData}} 構造体へのポインタを渡します。そのデータ構造体の中には重要なフィールド（{{span style='font-style:normal',textCallback}} 関数の中のフィールドをセットしたことを示す報告）があります。{{span_end}} *{{span style='color:blue;font-family:monospace;',← UInt16 stage}} **現在のステージ（{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} から渡されます） *{{span style='color:blue;font-family:monospace;',←→ Char *textP}} **更新されるダイアログに表示されるテキストを保持するためのバッファ。{{span style='color:blue;font-family:monospace;',stage}} フィールドの中の値に基づいて、リソース ファイルの中のメッセージを参照したいと思うかもしれません。また、文字列全体を表示されるためには、追加のテキストは {{span style='color:blue;font-family:monospace;',message}} フィールドの中に付加すべきです。返す文字列の最後には null 終端子を含んでいることを確認してください。{{span style='color:blue;font-family:monospace;',textLen}} の長さを超えてはいけません。 *{{span style='color:blue;font-family:monospace;',← UInt16 textLen}} **テキスト バッファ {{span style='color:blue;font-family:monospace;',textP}} の最大長。この値は呼び出し先によってこの関数のためにセットされるということに注意してください。{{span style='color:blue;font-family:monospace;',textP}} の中のこの長さを越えないように気をつけてください。 *{{span style='color:blue;font-family:monospace;',← Char *message}} **ダイアログの中に表示される追加のテキスト（{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} の {{span style='color:blue;font-family:monospace;',messageP}} パラメータに渡されます）。これは、{{span style='color:blue;font-family:monospace;',progressMaxMessage}} (128) よりも長くすべきではありません。 *{{span style='color:blue;font-family:monospace;',← Err error}} **現在のエラー（{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} の {{span style='color:blue;font-family:monospace;',err}} パラメータに渡されます）。 *{{span style='color:blue;font-family:monospace;',→ UInt16 bitmapId}} **進捗ダイアログの中に表示されるビットマップ（がある場合）のリソース ID。 *{{span style='color:blue;font-family:monospace;',← UInt16 canceled:1}} **ユーザがキャンセル ボタンを押している場合は、{{span style='color:blue;font-family:monospace;',true}} *{{span style='color:blue;font-family:monospace;',← UInt16 showDetails:1}} **ユーザがより詳細のための Palm デバイス上の下矢印ボタンを押した場合は、{{span style='color:blue;font-family:monospace;',true}}。（これは非標準ユーザ インターフェイス方法なので、この機能を、ユーザが通常の状態で必要とする詳細を表示するために、使用すべきではありません。通常状態ではないデバッグ目的のためのものです。） *{{span style='color:blue;font-family:monospace;',→ UInt16 textChanged:1}} **{{span style='color:blue;font-family:monospace;',true}} の場合、テキストを更新します（デフォルトでは {{span style='color:blue;font-family:monospace;',true}}）。テキストの更新を避けるためにこれを {{span style='color:blue;font-family:monospace;',false}} にセットすることができます。 *{{span style='color:blue;font-family:monospace;',← UInt16 timeOut:1}} **タイムアウトによって更新が起こされる場合、{{span style='color:blue;font-family:monospace;',true}} *{{span style='color:blue;font-family:monospace;',←→ UInt32 timeout}} **次の更新を強制するためのチック（システム チェック数）でのタイムアウト。この数のチックが経過した後、自動的に更新が引き起こされます（{{span style='color:blue;font-family:monospace;',timeOut}} フラグをセットします）。この機能を使用して、単純なアニメーション効果を出すことができます。{{span style='color:blue;font-family:monospace;',EvtGetEvent}} のためのタイムアウトをこの値以下にセットしなければならないということに注意してください。そうしないと、期待した頻度での更新イベントが起こりません。 *{{span style='color:blue;font-family:monospace;',→ UInt16 delay:1}} **{{span style='color:blue;font-family:monospace;',true}} の場合、ダイアログの更新後に 1 秒の遅延を発生します。最終進捗メッセージを表示しているときにこの値を使用し、それにより、ユーザはダイアログがクローズする前にメッセージを見る機会を得ます。このフィールドは、{{goto 3.2 New Feature Set,3.2 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、使用可能です。 *{{span style='color:blue;font-family:monospace;',← void *userDataP}} **この関数がアクセスする必要のあるいずれかのアプリケーション定義データへのポインタ。コールバック関数はあるアプリケーションにアクセスする必要があるのに、グローバルなアプリケーションへのアクセスを持たない場合、このポインタを {{goto PrgStartDialog,PrgStartDialog()}} へのパラメータとして指定します。このフィールドは、{{goto 3.2 New Feature Set,3.2 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、使用可能です。 この関数の中で、{{span style='color:blue;font-family:monospace;',textP}} バッファの値を、進捗ダイアログが更新されるときに、進捗ダイアログの中に表示したい文字列にセットします。{{span style='color:blue;font-family:monospace;',stage}} フィールドの中の値を使って、文字列リソースの中のメッセージを参照することができます。また、ベース文字列に {{span style='color:blue;font-family:monospace;',message}} フィールドの中のテキストを付加したいと思うかもしれません。通常、{{span style='color:blue;font-family:monospace;',message}} フィールドは、ユーザの選択に依存する -- 例えば電話番号、デバイス名、ネットワーク識別子などの -- 動的情報以上のものを保持します。 例えば、{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} 関数は、{{span style='color:blue;font-family:monospace;',stage}} 1 と電話番号文字列 "555-1212" で呼び出されたかもしれません。ステージに基づいて、文字列リソースの中から文字列 "ダイアル中" を見つけて、テキスト バッファ {{span style='color:blue;font-family:monospace;',textP}} の中に置く最終的なテキストとして "ダイアル中 555-1212" という形にするために、電話番号を付加するかもしれません。 さまざまなステージに対応する静的文字列をリソースの中に維持することは、アプリケーションのローカライズをより容易にします。これらの情報は、{{span style='color:blue;font-family:monospace;',messageP}} パラメータ経由で、{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} へ渡すことができます。 //---- //'''NOTE::''' この関数は、この関数が最後に呼び出された後に {{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} に渡されるパラメータが変更されている場合にのみ、呼び出されます。{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} がまったく同じパラメータで 2 度呼び出される場合、{{span style='color:blue;font-family:monospace;',textCallback}} 関数は 1 度だけ呼び出されます。 //---- ::NOTE: :::この関数は、この関数が最後に呼び出された後に {{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} に渡されるパラメータが変更されている場合にのみ、呼び出されます。{{span style='color:blue;font-family:monospace;',PrgUpdateDialog}} がまったく同じパラメータで 2 度呼び出される場合、{{span style='color:blue;font-family:monospace;',textCallback}} 関数は 1 度だけ呼び出されます。 {{div_end}} {{div_begin "style='border-top:solid;border-top-width:1px;border-top-color:silver;'"}} [[←　16 章に戻る|Palm OS Programmer's API Reference/16]]　[[↑トップへ|Palm OS Programmer's API Reference]]　[[18 章に進む　→|Palm OS Programmer's API Reference/18]] {{div_end}}