Palm Programmer's Laboratory

トップ 差分 一覧 ソース 検索 ヘルプ RSS ログイン

Palm OS Programmer's API Reference/17

←　16 章に戻る　↑トップへ　18 章に進む　→

17 進捗マネージャ

この章では、進捗マネージャのための参照資源を提供します。

ヘッダ ファイル Progress.h がこの章で説明される API を宣言しています。進捗マネージャについての更なる情報は、Palm OS Programmer's Companion, vol. I の「プログレス ダイアログ」を参照してください。

進捗マネージャ関数 ^TOP^

PrgHandleEvent 関数 ^TOP^

目的

アクティブな進捗ダイアログに関連するエベントを処理します。

宣言されている場所

Progress.h

Prototype

Boolean PrgHandleEvent (
	ProgressPtr prgGP,
	EventType *eventP
)

パラメータ

  • → prgGP
  • → eventP
    • イベントへのポインタ。NULL イベントを渡すことで、この関数にただちに PrgCallbackFund() 関数を呼び出させて、ダイアログを更新させることができます（例えば、PrgUpdateDialog を呼び出した後）。

返り値

システムがイベントを処理した場合は、true を返します。false を返す場合、ユーザが PrgUserCancel() を呼び出すことによってダイアログをキャンセルしたかどうかをチェックすべきです。

コメント

進捗ダイアログを持つとき、SysHandleEvent()|Palm OS Programmer's API Reference/54 の代わりに、この関数を使用します。PrgHandleEvent は必要に応じて内部的に SysHandleEvent を呼び出します。

この関数を使用するとき、ダイアログがエラーを表示していない限り、システムの自動 Power-off 機能は自動的に使用不可になることに注意してください。この関数はまた、appStopEvent イベントをも無効にします。

ダイアログの更新が保留されている（例えば、PrgUpdateDialog() 呼び出しから）場合、この関数はイベントを処理し、ダイアログを更新します。このプロセスの一部として、PrgStartDialog() 呼び出しの中で指定された textCallback 関数が呼び出されます。textCallback 関数は、新しいメッセージを持つ PrgCallbackData 構造体の中の textP バッファを進捗ダイアログの中に表示させるべきです。オプションとして、bitmapId フィールドに更新ダイアログの中のアイコンを持たせることができます。textCallback 関数についての更なる情報は、「アプリケーション定義関数」を参照してください。

互換性

3.0 New Feature Set が存在する場合にのみ、実装されます。

参照

PrgStartDialog(), PrgStopDialog(), PrgUpdateDialog(), PrgUserCancel()

PrgStartDialog 関数 ^TOP^

目的

更新することができる進捗ダイアログを表示します。

宣言されている場所

Progress.h

Prototype

ProgressPtr PrgStartDialog (
	const Char *title,
	PrgCallbackFunc textCallback,
	void *userDataP
)

パラメータ

  • → title
    • 進捗ダイアログのためのタイトルへのポインタ。progressMaxTitle (20) よりも長くない null で終了する文字列で無ければなりません。
  • → textCallback
    • 現在の進捗状況のためのテキストとアイコンを提供するコールバック関数へのポインタ。PrgCallbackFunc() を参照してください。
  • → userDataP
    • コールバック関数の中でアクセスする必要のあるデータへのポインタ。このアドレスはコールバック関数に直接渡されます。

返り値

進捗構造体へのポインタ。このポインタは他の進捗マネージャ関数に渡されなくてはならず、さらに、PrgStopDialog() 呼び出しによって解放されなくてはなりません。システムが進捗構造体をあり当てることができない場合は、NULL を返します。

コメント

この関数によって作成されるダイアログは、PrgUpdateDialog() 関数経由で他のプロセスから更新することができます。ダイアログは Cancel または OK ボタンを保持することができます。初期状態のダイアログはデフォルトでステージ 0 の状態にあり、textCallback 関数を呼び出して初期テキストとアイコン データを進捗ダイアログのために取得します。

この関数は進捗ダイアログの背後にあるスクリーン ビットを保存し、PrgStopDialog を呼び出すときこれらのビットは保存されます。このため、進捗ダイアログが表示されている間スクリーンへの変更は最小限にすべきであり、そうでないと、保存されるビットは現在表示されているものと一致しないかもしれません。

互換性

このバージョンの関数は、3.2 New Feature Set が存在する場合にのみ、使用可能です。それより前のシステムでは、PrgStartDialog は PrgStartDialogV31() で示されているプロトタイプを持ちます。

参照

PrgHandleEvent(), PrgStopDialog(), PrgUpdateDialog(), PrgUserCancel()

PrgStartDialogV31 関数 ^TOP^

目的

更新することができる進捗ダイアログを表示します。

宣言されている場所

Progress.h

Prototype

ProgressPtr PrgStartDialogV31 (
	const Char *title,
	PrgCallbackFunc textCallback
)

パラメータ

  • → title
    • 進捗ダイアログのためのタイトルへのポインタ。progressMaxTitle (20) より長くない null で終了する文字列でなければなりません。
  • → textCallback
    • 現在の進捗状態のためのテキストとアイコンを提供するコールバック関数へのポインタ。PrgCallbackFunc() を参照してください。

返り値

進捗構造体へのポインタ。このポインタは他の進捗マネージャ関数に渡されなければならず、かつ、PrgStoDialog() 呼び出しによって解放されなくてはなりません。システムが進捗構造体を割り当てできない場合は、NULL を返します。

互換性

この関数は、Palm OS 3.0 と Palm OS 3.1 で使用可能な PrgStartDialog() に対応するバージョンです。

参照

PrgHandleEvent(), PrgStopDialog(), PrgUpdateDialog(), PrgUserCancel()

PrgStopDialog 関数 ^TOP^

目的

進捗ダイアログによって使用されるメモリを解放し、スクリーンを初期状態に戻します。

宣言されている場所

Progress.h

Prototype

void PrgStopDialog (
	ProgressPtr prgP,
	Boolean force
)

パラメータ

  • → prgP
  • → force
    • true だと、ただちに進捗ダイアログを削除します。false だと、エラーが表示されている場合はユーザがエラーを確認するまでシステムを待機させます。

返り値

返り値はありません。

コメント

進捗ダイアログがユーザにエラーを表示している状態である場合、この関数は、通常、ユーザがダイアログを確認してからダイアログを削除します。force パラメータを true にセットした場合、システムはただちにダイアログを削除します。

互換性

3.0 New Feature Set が存在する場合にのみ、実装されます。

参照

PrgHandleEvent(), PrgStartDialog(), PrgUpdateDialog(), PrgUserCancel()

PrgUpdateDialog 関数 ^TOP^

目的

現在の進捗ダイアログの状態を更新します。

宣言されている場所

Progress.h

Prototype

void PrgUpdateDialog (
	ProgressPtr prgGP,
	UInt16 err,
	UInt16 stage,
	const Char *messageP,
	Boolean updateNow
)

パラメータ

  • → prgGP
  • → err
    • 0 でない場合、ダイアログはエラー モードに入り、OK ボタンのみを持つエラー メッセージを表示します。
  • → stage
    • 進捗の現在のステージ。コールバック関数は、これを使用して、更新されるダイアログの中に表示される適切な文字列を決定することができます。
  • → messageP
    • このステージのために進捗を表示するのに有用であるかもしれない臨時テキスト。ステージに基づくベース メッセージの後にそれを追加することができるコールバック関数によって使用されます。
  • → updaNow
    • true である場合、ダイアログはただちに更新されます。そうでない場合、ダイアログは次の PrgHandleEvent() 呼び出し時に更新されます。

返り値

返り値はありません。

コメント

パラメータがどのように使用されるのか、コールバック関数についての更なる情報は、「アプリケーション定義関数」を参照してください。

互換性

3.0 New Feature Set が存在する場合にのみ、実装されます。

参照

PrgHandleEvent(), PrgStartDialog(), PrgStopDialog(), PrgUserCancel()

PrgUserCancel マクロ ^TOP^

目的

ユーザが進捗ダイアログ経由で進捗をキャンセルした場合に、true を返します。

宣言されている場所

Progress.h

Prototype

#define PrgUserCancel (
	prgP
)

パラメータ

  • → prgP
    • PrgStartDialog() によって作成される進捗構造体へのポインタ（ProgressPtr）

返り値

進捗構造体の中の cancel フィールドの値を（UInt16 として）返します。

コメント

このマクロを使用して、ユーザが進捗をキャンセルしたかどうかをチェックすることができます。ユーザがキャンセルしていた場合、進捗ダイアログのテキストを「キャンセル中」または「接続切り離し中」またはアプリケーションにとって適切なものに変更することができます。それから、プロセスをキャンセルするか、通信セッションを終わらせるか、必要とされるなんらかの処理をすべきです。

互換性

3.0 New Feature Set が存在する場合にのみ、実装されます。

参照

PrgHandleEvent(), PrgStartDialog(), PrgStopDialog(), PrgUpdateDialog()

アプリケーション定義関数 ^TOP^

PrgCallbackFunc 関数 ^TOP^

目的

現在の進捗状態のためのテキストとアイコンを提供します。

宣言されている場所

Progress.h

Progotype

Boolean (
	*PrgCallbackFunc
)(
	PrgCallbackDataPtr cbP
)

パラメータ

  • ←→ cbP
    • PrgCallbackData 構造体へのポインタ。以下を参照してください。

返り値

進捗ダイアログが PrgCallbackData 構造体の中で指定された値を使って更新されるべきである場合、true を返します。false を指定した場合、ダイアログは依然として更新されますが、デフォルトの状態メッセージを持ちます。（false を返すことは推奨されません。）

コメント

これは、PrgStartDialog() を呼び出すときに指定するコールバック関数です。このコールバック関数は、現在の進捗情報を進捗ダイアログの中に表示する必要があるときに、PrgHandleEvent() によって呼び出されます。

  • → システムはこの関数に PrgCallbackData 構造体へのポインタを渡します。そのデータ構造体の中には重要なフィールド（textCallback 関数の中のフィールドをセットしたことを示す報告）があります。
  • ← UInt16 stage
    • 現在のステージ（PrgUpdateDialog から渡されます）
  • ←→ Char *textP
    • 更新されるダイアログに表示されるテキストを保持するためのバッファ。stage フィールドの中の値に基づいて、リソース ファイルの中のメッセージを参照したいと思うかもしれません。また、文字列全体を表示されるためには、追加のテキストは message フィールドの中に付加すべきです。返す文字列の最後には null 終端子を含んでいることを確認してください。textLen の長さを超えてはいけません。
  • ← UInt16 textLen
    • テキスト バッファ textP の最大長。この値は呼び出し先によってこの関数のためにセットされるということに注意してください。textP の中のこの長さを越えないように気をつけてください。
  • ← Char *message
    • ダイアログの中に表示される追加のテキスト（PrgUpdateDialog の messageP パラメータに渡されます）。これは、progressMaxMessage (128) よりも長くすべきではありません。
  • ← Err error
    • 現在のエラー（PrgUpdateDialog の err パラメータに渡されます）。
  • → UInt16 bitmapId
    • 進捗ダイアログの中に表示されるビットマップ（がある場合）のリソース ID。
  • ← UInt16 canceled:1
    • ユーザがキャンセル ボタンを押している場合は、true
  • ← UInt16 showDetails:1
    • ユーザがより詳細のための Palm デバイス上の下矢印ボタンを押した場合は、true。（これは非標準ユーザ インターフェイス方法なので、この機能を、ユーザが通常の状態で必要とする詳細を表示するために、使用すべきではありません。通常状態ではないデバッグ目的のためのものです。）
  • → UInt16 textChanged:1
    • true の場合、テキストを更新します（デフォルトでは true）。テキストの更新を避けるためにこれを false にセットすることができます。
  • ← UInt16 timeOut:1
    • タイムアウトによって更新が起こされる場合、true
  • ←→ UInt32 timeout
    • 次の更新を強制するためのチック（システム チェック数）でのタイムアウト。この数のチックが経過した後、自動的に更新が引き起こされます（timeOut フラグをセットします）。この機能を使用して、単純なアニメーション効果を出すことができます。EvtGetEvent のためのタイムアウトをこの値以下にセットしなければならないということに注意してください。そうしないと、期待した頻度での更新イベントが起こりません。
  • → UInt16 delay:1
    • true の場合、ダイアログの更新後に 1 秒の遅延を発生します。最終進捗メッセージを表示しているときにこの値を使用し、それにより、ユーザはダイアログがクローズする前にメッセージを見る機会を得ます。このフィールドは、3.2 New Feature Set が存在する場合にのみ、使用可能です。
  • ← void *userDataP
    • この関数がアクセスする必要のあるいずれかのアプリケーション定義データへのポインタ。コールバック関数はあるアプリケーションにアクセスする必要があるのに、グローバルなアプリケーションへのアクセスを持たない場合、このポインタを PrgStartDialog() へのパラメータとして指定します。このフィールドは、3.2 New Feature Set が存在する場合にのみ、使用可能です。

この関数の中で、textP バッファの値を、進捗ダイアログが更新されるときに、進捗ダイアログの中に表示したい文字列にセットします。stage フィールドの中の値を使って、文字列リソースの中のメッセージを参照することができます。また、ベース文字列に message フィールドの中のテキストを付加したいと思うかもしれません。通常、message フィールドは、ユーザの選択に依存する -- 例えば電話番号、デバイス名、ネットワーク識別子などの -- 動的情報以上のものを保持します。

例えば、PrgUpdateDialog 関数は、stage 1 と電話番号文字列 "555-1212" で呼び出されたかもしれません。ステージに基づいて、文字列リソースの中から文字列 "ダイアル中" を見つけて、テキスト バッファ textP の中に置く最終的なテキストとして "ダイアル中 555-1212" という形にするために、電話番号を付加するかもしれません。

さまざまなステージに対応する静的文字列をリソースの中に維持することは、アプリケーションのローカライズをより容易にします。これらの情報は、messageP パラメータ経由で、PrgUpdateDialog へ渡すことができます。

NOTE:
この関数は、この関数が最後に呼び出された後に PrgUpdateDialog に渡されるパラメータが変更されている場合にのみ、呼び出されます。PrgUpdateDialog がまったく同じパラメータで 2 度呼び出される場合、textCallback 関数は 1 度だけ呼び出されます。

←　16 章に戻る　↑トップへ　18 章に進む　→

Copyright (C) 2002-2006 PalmwareInfo
Powered by FreeStyleWiki3.6.2 with Perl5.032001

Index


メニュー

各種掲示板

検索

キーワード

Wiki

最新

2023/12/1

2021/4/5

2020/7/7

2020/5/15

2020/1/13

2019/4/1

2018/4/18

2018/4/17

Visitor:
[Today:]
[Yesterday:]