Palm Programmer's Laboratory
Palm OS Programmer's API Reference/4
この章は、アテンション マネージャのための参照資源を提供します。この章は以下の内容に分かれています。
アテンション マネージャ API は、ヘッダファイル AttentionMgr.h の中で宣言されています。
アテンション マネージャについての更なる情報は、Palm OS Programmer's API Companion, vol. I の中の「ユーザに対するアテンション」 を参照してください。
- 重要
- アテンション マネージャは Palm OS 4.0 で導入されたもので、それより前のオペレーション システムでは使用できません。
アテンション マネージャ データ構造体 ^TOP^
AttnCommandType Typedef ^TOP^
目的
AttnCommandType 型定義は、AttnCallbackProc() コールバック関数へのパラメータとして、または、sysAppLaunchCmdAttention 起動コードを伴う引数の 1 つとしてのどちらかで、ユーザのアテンションを要求しているアプリケーションに送ることができるコマンドのセットを指定します。
Prototype
typedef UInt16 AttnCommandType;
以下の値は、AttnCommandType がとり得る値です。
- kAttnCommandDrawDetail
- アプリケーションはアテンション ダイアログの詳細内容を描く必要があることを示します。コマンド引数パラメータはタイプ drawDetail の構造体を指します。
- kAttnCommandDrawList
- アプリケーションはアテンション ダイアログの中に適切なリスト アイテムを描く必要があることを示します。コマンド引数パラメータはタイプ drawDetail の構造体を指します。
- kAttnCommandPlaySound
- アプリケーションはサウンドを鳴らす必要があることを示します。コマンド引数パラメータは NULL です。
- kAttnCommandCustomEffect
- アプリケーションはアプリケーション特有の特別な効果を起こす必要があることを示します。このコマンドは、kAttnFlagsCustomEffectBit がセットされたアテンション アイテムが AttnGetAttention() を呼び出したときにのみ発せられます。たいていのアプリケーションはこのようなことはしません。
- kAttnCommandGoThere
- アプリケーションにそのアイテムまでナビゲートするよう伝えます。コマンド引数パラメータは NULL です。このコマンドの受領時に、アプリケーションは共通してそれ自身を起動させるために SysAppLaunch()|Palm OS Programmer's API Reference/54 を呼び出します。
- kAttnCommandGotIt
- アプリケーションにユーザがアイテムを処分していることを知らせます。このコマンド引数パラメータはタイプ gotIt の構造体を指します。アプリケーションはこの時点でメモリをクリーン アップすることを選択するかもしれません。
- kAttnCommandSnooze
- アプリケーションにユーザが居眠りしていることを示します。このコマンド引数パラメータは NULL です。たいていのアプリケーションはこのコマンドの受信時になにもしません。このコマンドは、現在保留中、強調、目立たなくされている各アイテムのために適切なアプリケーションに渡されます。保留中のアテンション アイテムを複数持つアプリケーションは何度か呼び出されます。
- kAttnCommandIterate
- このコマンドはアテンション アイテムを列挙している最中にアプリケーションに渡されます。特に HotSync の後に有用であり、アプリケーションが各アイテムを検証して、期限切れのものや無効のものを更新したり削除したりすることを可能にします。コマンド引数パラメータはタイプ iterate の構造体を指します。
AttnCommandArgsType ^TOP^
AttnCommandArgsType 構造体は C 構造体の共用体です。どのようにその共用体の内容をやりとりするかは、その共用体がどのコマンドを伴うかしだいです。以下の表が示すように、すべてのコマンドが AttnCommandArgsType 構造体によって伴われるわけではありません。
AttnCommandType | 以下のコマンドが伴う |
---|---|
kAttnCommandDrawDetail | drawDetail |
kAttnCommandDrawList | drawList |
kAttnCommandPlaySound | ありません |
kAttnCommandCustomEffect | ありません |
kAttnCommandGoThere | ありません |
kAttnCommandGotIt | gotIt |
kAttnCommandSnooze | ありません |
kAttnCommandIterate | iterate |
AttnCommandArgsType 共用体を形成する構造体は以下の節で説明されています。
kAttnCommandDrawDetail がアプリケーションに渡されるとき、コールバック関数経由か sysAppLaunchCmdAttention 起動コードを伴うパラメータとしてのどちらかで、そのアプリケーションはアテンション ダイアログの詳細な内容を描画するする必要があります。drawDetails 構造体は kAttnCommandDrawDetail を伴い、ダイアログの内容を描画するのに必要とされる情報を提供します。
Prototype
struct AttnCommandArgsDrawDetailTag { RectangleType bounds; Boolean firstTime; AttnFlagsType flags; } drawDetail;
フィールド
- bounds
- 描画するエリアのウィンドウ相対領域を保持します。さらに、意図せず領域外に描画することを防ぐために、クリッピング (図形の余分な部分の切り落とし) 領域もこの領域にセットされます。
- firstTime
- ユーザがこのアイテムをまだ見ていない場合は true をセットします。このフィールドの値は、ユーザが以前に見ていないアテンションをなんらかの特別な方法で表示するために使用される可能性があります。さらに、firstTime はあなたのアプリケーションにあなたのアプリケーションが描画しようとしているこの領域が消去されているかどうかを示します。firstTime が false の場合、その領域は白紙であることを保証されていません; あなたのアプリケーションはその領域を消去する必要があります。
- flags
- 開発者によって渡されるカスタム フラグに組み込まれるこのアテンション試行のためのグローバル ユーザ設定。このフィールドの中の下位 16 ビットだけが意味を持ちます; このフィールドの内容をやりとりするには kAttnFlagsSoundBit (下の "AttnFlagsType" で説明されています) を使用します。
kAttnCommandDrawList がアプリケーションに渡されるとき、コールバック関数経由か sysAppLaunchCmdAttention 起動コードを伴うパラメータとしてのどちらかで、そのアプリケーションはアテンション ダイアログの中に適切なリスト アイテムを描画するする必要があります。drawList 構造体は kAttnCommandDrawList を伴い、ダイアログの内容を描画するのに必要とされる情報を提供します。
Prototype
struct AttnCommandArgsDrawListTag { RectangleType bounds; Boolean firstTime; AttnFlagsType flags; Boolean selected; } drawList;
フィールド
- bounds
- 描画するエリアのウィンドウ相対領域を保持します。さらに、意図せず領域外に描画することを防ぐために、クリッピング (図形の余分な部分の切り落とし) 領域もこの領域にセットされます。
- firstTime
- ユーザがこのアイテムをまだ見ていない場合は true をセットします。このフィールドの値は、例えばこのアテンション アイテムが初めてユーザに提示されるときにカスタム サウンドを鳴らすのに使用することができます。
- flags
- 開発者によって渡されるカスタム フラグに組み込まれるこのアテンション試行のためのグローバル ユーザ設定。このフィールドの中の下位 16 ビットだけが意味を持ちます; このフィールドの内容をやりとりするには kAttnFlagsSoundBit (下の "AttnFlagsType" で説明されています) を使用します。
- selected
- このアイテムが選択されている場合は true にセットします。これはこのフラグに基づいてあなたのコードにこのアイテムを適切に描画させようとします (通常は UI カラーを変更することによって)。
kAttnCommandGotIt がアプリケーションに渡されるとき、コールバック関数経由か sysAppLaunchCmdAttention 起動コードを伴うパラメータとしてのどちらかで、gotIt 構造体はこの構造体を伴います。この構造体は、ユーザがアテンションを書居したために kAttnCommandGotIt コマンドが生成されたのかどうか、またはただ単にシステムがあなたのアプリケーションに AttnForgetIt() が呼び出されたことを知らせているだけなのかどうかを示し増す。通常、あなたのアプリケーションが AttnForgetIt を呼び出した場合、そのアプリケーションは後者 (システムからの通知) を無視します。
Prototype
struct AttnCommandArgsGotItTag { Boolean dismissedByUser; } gotIt;
フィールド
- dismissedByUser
- true はユーザがアテンションを消去したことを意味します。false は kAttnCommandGotIt コマンドが AttnForgetIt() 呼び出しによって生成されたことを意味します。
kAttnCommandDrawList がアプリケーションに渡されるとき、コールバック関数経由か sysAppLaunchCmdAttention 起動コードを伴うパラメータとしてのどちらかで、iterate 構造体がこの構造体を伴います。この構造体は、アプリケーションがコールバックまたは起動コードを処理するのに必要とするかもしれないデータを保持します。
Prototype
struct AttnCommandArgsIterateTag { UInt32 iterationData; } iterate;
フィールド
- iterationData
- アプリケーションがコールバックまたは起動コードを処理するのに必要とするかもしれないデータ。このフィールドの値は元々 AttnIterate() に渡されたものです。
AttnFlagsType ^TOP^
デバイスがユーザのアテンションを得るためにすべきこと、すべきでないことを指定するために AttnGetAttention() と AttnUpdate() にこのタイプの値を渡します。さらに、このタイプの値はあなたのコードにコールバック関数へのパラメータとして渡され、コールバック関数が指定されていない場合は sysAppLaunchCmdAttention 起動コードとともに渡される構造体の一部として渡されます。
Prototype
typedef UInt32 AttnFlagsType;
追加ハードウェアに応じるために必要があればさらに多くのビットが定義されるかもしれないということに注意してください。
定数 | 値 | 説明 |
---|---|---|
kAttnFlagsSoundBit | 0x0001 | サウンドを鳴らします。 |
kAttnFlagsLEDBit | 0x0002 | デバイスに LED がある場合は、その LED を点滅させます。 |
kAttnFlagsVibrateBit | 0x0004 | デバイスにバイブレーションがある場合は、そのバイブレーションを動作させます。 |
kAttnFlagsCustomEffectBit | 0x0008 | アプリケーション特有のカスタム効果を引き起こします。 |
kAttnFlagsAllBits | 0xFFFF | ユーザのアテンションを得るために使用可能な手段をすべて使用します。 |
kAttnFlagsUseUserSettings | 0x0000 | システム ワイド設定がユーザのアテンションを得るために使用される手段を決定します。 |
以下の定数値は、ユーザの設定をオーバライドしてある特定の振る舞いを強制的に起こすか防ぐために使用される可能性があります:
定数 | 値 | 説明 |
---|---|---|
FlagsAlwaysSound | FlagsSoundBit | ユーザの設定に関係なくサウンドを鳴らします。 |
FlagsAlwaysLED | FlagsLEDBit | デバイスに LED がある場合は、ユーザの設定に関係なくその LED を点滅させます。 |
FlagsAlwaysVibrate | FlagsVibrateBit | デバイスにバイブレーションがある場合、ユーザの設定に関係なくそのバイブレーションを動作させます。 |
FlagsAlwaysCustomEffect | FlagsCustomEffectBit | アプリケーション特有のカスタム効果を引き起こします。 |
FlagsEverything | FlagsAllBits | ユーザの設定に関係なくユーザのアテンションを得るために使用可能な手段をすべて使用します。 |
FlagsNoSound | FlagsSoundBit << 16 | ユーザの設定に関係なくサウンドを鳴らすのを防ぎます。 |
FlagsNoLED | FlagsLEDBit << 16 | ユーザの設定に関係なく LED を点滅させるのを防ぎます。 |
FlagsNoVibrate | FlagsVibrateBit << 16 | ユーザの設定に関係なくバイブレーションを動作させるのを防ぎます。 |
FlagsNoCustomEffect | FlagsCustomEffectBit << 16 | アプリケーション特有のカスタム効果を引き起こすのを防ぎます。 |
FlagsNothing | FlagsAllBits << 16 | ユーザの設定に関係なくユーザのアテンションを得るためのメカニズムをすべて使用不能にします。 |
これらの定数は組み合わせて使用することができます。例えば、サウンドと LED の両方を使用不能にするには kAttnFlagsNoSound | kAttnFlagsNoLED を使用します。
kAttnFlagsAlwaysSound と kAttnFlagsNoSound の両方ともが与えられたアテンション アイテムにセットされていない場合、ユーザの設定がサウンドを鳴らすようになっていて、ユーザのアラーム ボリュームの設定が非 0 の場合、その場合にのみ、サウンドを鳴らします。
AttnLaunchCodeArgsType ^TOP^
コールバック関数が AttnGetAttention() 呼び出しの中で指定されておらず、アテンション マネージャがあなたのコードにアテンション ダイアログの中に詳細を描画させるか他のアテンション特有の関数を実行させる必要がある場合、アテンション マネージャは sysAppLaunchCmdAttention 起動コードをあなたのアプリケーションに送ります。この起動コードとともに、アテンション マネージャは以下の構造体へのポインタを渡します。この構造体はあなたのコードが行うことを期待されていること、この起動コードを引き起こしたアテンションを識別するものの両方を示します:
Prototype
typedef struct { AttnCommandType command; UInt32 userData; AttnCommandArgsType *commandArgsP; } AttnLaunchCodeArgsType;
フィールド
- command
- あなたのコードにリクエストされていることを示します。とり得るコマンドの完全なリストは AttnCommandType の定義の中で説明されています。
- userData
- ある特定のアテンション アイテムをこのアプリケーションによって作成された他のアテンション アイテムと区別する識別子。この識別子は、アテンション アイテムが作成されたときに指定されます。
- commandArgsP
- コマンド特有の引数へのポインタ。コマンドの引数についての説明は、各コマンドの説明を参照してください。
起動コードを処理しているとき、あなたのアプリケーションはアプリケーション グローバル変数を利用できないということに気を配ってください; 描画や他の表示で必要となるものはすべて commandArgsP を通すことで利用可能であるということが重要となります。
AttnLevelType ^TOP^
アテンション試行は強調することも目立たなくすることもできます。強調アテンション試行はダイアログを表示し、もしかするといくつかの特殊効果 - 明かりを点滅させる、バイブレーションを動作させる、サウンドを鳴らすなど - を引き起こすことによって、ユーザのアテンションを得るために大きな努力を払います。他のアラートはそれよりも重大ではなく、ユーザを混乱させるべきではありません。したがって通常、目立たないアテンション試行はアテンション インジケータを点滅させ、いくつかの特殊効果を引き起こすかもしれませんが、アテンション マネージャ ダイアログは表示しません。ユーザは適当なとき - ユーザが何が彼らのアテンションを必要としているのかを見るためにインジケータをタップできるようになる - まで彼らは仕事を行うことができます。目立たないアテンション試行は、ユーザに新しい e-mail が届いていること、記念日や誕生日が近づいていることを知らせるために使用されるかもしれません。
Prototype
typedef UInt16 AttnLevelType;
以下の 2 つの値が AttnLevelType のために定義されています:
- kAttnLevelInsistent
- 強調アテンション試行。ダイアログを表示して、オプションでいくつかの特殊効果を引き起こすことによってユーザのアテンションを得るために大きな努力を払います。
- kAttnLevelSubtle
- 目立たないアテンション試行。特殊効果を使ってユーザに通知しますが、デバイスが使用中の場合はダイアログを表示させてユーザを混乱させることはしません。
さまざまな特殊効果のためのユーザ設定は目立たないアテンション試行と強調アテンション試行に対して別々にセットすることはできません。あなたのアプリケーションが AttnLevelType に基づいてさまざまな効果を引き起こす必要がある場合、あなたの AttnGetAttention() 呼び出しの中の flags パラメータに適切な値を渡します。
アテンション マネージャ定数 ^TOP^
AttnCommandType, AttnFlagsType, and AttnLevelType で使用するために定義された定数値のほかに、アテンション マネージャは以下の定数タイプを定義します:
エラー コード定数 ^TOP^
アテンション マネージャは以下の状況で以下のエラー コードを返します。
定数 | 説明 |
---|---|
attnErrMemory | リクエストされた操作を行うにはメモリが不足しているとき、AttnGetAttention() によって返されます。 |
アテンション マネージャ描画定数 ^TOP^
以下の 4 つの定数はアテンション インジケータのスクリーン上での領域を定義します。
定数 | 値 | 説明 |
---|---|---|
kAttnIndicatorLeft | 0 | アテンション インジケータの左端の境界線。 |
kAttnIndicatorTop | 0 | アテンション インジケータの上端の境界線。 |
kAttnIndicatorWidth | 16 | アテンション インジケータの幅。 |
kAttnIndicatorHeight | 16 | アテンション インジケータの高さ。 |
以下の 2 つの定数はリスト ビューを描画するときに使用されます。アプリケーションはこれらの定数をアテンション マネージャのリスト ビューの中の情報表示をフォーマットするために使用すべきです。描画領域の最初の kAttnListMaxIconWidth ピクセルの中央にアプリケーションのスモール アイコンを表示します。それから、描画領域の左端から kAttnListTextOffset の位置に、左揃えで 2 行のアテンション説明テキストを描画します。
定数 | 値 | 説明 |
---|---|---|
kAttnListMaxIconWidth | 15 | アプリケーションのアイコンの最大幅。アイコンがこの値よりも幅が狭い場合、この幅の内側の中央に描画すべきです。 |
kAttnListTextOffset | 17 | アテンションの説明テキストの描画領域の左端からのオフセット。 |
アテンション マネージャ Feature 定数 ^TOP^
アテンション マネージャは、現在のユーザの設定とハードウェアの能力を示す Read-only の Feature ('attn', 0) を定義します。この Feature の上位 16 ビットは、ハードウェアがアラートのソートを実行する能力を持っているかどうかを示します。下位 16 ビットは、ユーザが現在アラートのソートを使用可能にしているかどうかを示します。
定数 | 値 | 説明 |
---|---|---|
kAttnFtrCreator | 'attn' | アテンション マネージャ Feature クリエイタ。 |
kAttnFtrCapabilities | 0 | アテンション マネージャ Feature 番号。 |
FtrGet で取得された値を使って処理を行うとき、その値からユーザ設定を保持しているビットとデバイスの能力を示すビットを分離するために以下の 2 つの定数を使用します。
定数 | 値 | 説明 |
---|---|---|
kAttnFlagsUserSettingsMask | kAttnFlagsAllBits | ユーザ設定を保持しているビットを分離させるためのマスク。 |
kAttnFlagsCapabilitiesMask | kAttnFlagsAllBits << 16 | デバイス能力を保持しているビットを分離させるためのマスク。 |
以下の定数はデバイス能力 (kAttnFlagsHas...) とユーザ設定 (kAttnFlagsUserWants...) を解釈するために使用することができます。
定数 | 値 | 説明 |
---|---|---|
kAttnFlagsHasLED | kAttnFlagsLEDBit << 16 | デバイスはアラートを示すためにイルミネートさせることのできる LED を持っています。 |
kAttnFlagsHasSound | kAttnFlagsSoundBit << 16 | デバイスはアラートを示すためにサウンドを鳴らす能力を持っています。 |
kAttnFlagsHasVibrate | kAttnFlagsVibrateBit << 16 | デバイスはアラートを示すためにバーブレーションする能力があります。 |
kAttnFlagsHasCustomEffect | kAttnFlagsCustomEffectBit << 16 | 使用されません。 |
kAttnFlagsUserWantsLED | kAttnFlagsLEDBit | ユーザはアラートを知らせるために LED をイルミネートさせることを望んでいます。 |
kAttnFlagsUserWantsSound | kAttnFlagsSoundBit | ユーザはアラートを知らせるために LED をサウンドを鳴らすことを望んでいます。 |
kAttnFlagsUserWantsVibrate | kAttnFlagsVibrateBit | ユーザはアラートを知らせるためにデバイスにバイブレーションさせることを望んでいます。 |
kAttnFlagsUserWantsCustomEffect | kAttnFlagsCustomEffectBit | 使用されません。 |
アテンション マネージャ関数 ^TOP^
AttnDoSpecialEffects 関数 ^TOP^
目的
アテンション マネージャの特殊効果セットを引き起こします。
宣言されている場所
AttentionMgr.h
Prototype
Err AttnDoSpecialEffects ( AttnFlagsType flags )
パラメータ
- → flags
- この特殊効果リクエストによって示される振る舞いを指定します。このフラグを形成するさまざまなビットについては、AttnFlagsType を参照してください。あなたが互換性のないフラグをセットした場合、その振る舞いは定義されません。このアテンション リクエストをユーザのプリ-セット設定に従わせるには kAttnFlagsUseUserSettings を指定します。
返り値
何の問題も起きなければ errNone を返します。アテンション リクエストに応えるにはメモリが不足していた場合、attnErrMemory を返します。
コメント
このルーチンは特殊効果を引き起こす必要のあるアプリケーションに便宜を計るために提供されます。これはアテンション マネージャの特殊効果セットの 1 つのナグ ※ と等価のことをします。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
AttnForgetIt 関数 ^TOP^
目的
アプリケーションのためにアテンション マネージャにアテンション アイテムを忘れるよう伝える手段を提供します。
宣言されている場所
AttentionMgr.h
Prototype
Boolean AttnForgetIt ( UInt16 cardNo, LocalID dbID, UInt32 userData )
パラメータ
- → cardNo
- リクエストしているアプリケーションが存在しているカードの番号。
- → dbID
- リクエストしているアプリケーションのデータベース ID。
- → userData
- このアテンション試行を同じアプリケーションによって作成された他のものと区別する識別子。この識別子は整数、ポインタ、他の 32 ビット値のいずれかになり得ます。
返り値
アイテムが削除されていた場合は true を返します。一致するアイテムが見つからなかった場合、false を返します。
コメント
通常、あなたはこの関数を、あなたのアプリケーションが "Go There" イベントをハンドルしてユーザがそのアイテムに目を通した後に呼び出します。例えば、「あなたには待機中の 3 つの e-mail メッセージがあります」という保留中の目立たないアテンションがあり、あなたがあなた自身で e-mail アプリケーションを起動して e-mail を呼んだ場合、その通知は消されるべきです。AttenForgetIt はアプリケーションがこれを行うことを可能にします。
この呼び出しはアテンション ダイアログが表示中のときに行われる可能性があるということに注意してください (おそらくアプリケーションはこの時点で十分なことを行っていないため、そのようなことは稀であると考えられますが)。この呼び出しがリスト アイテムを削除した場合、アテンション マネージャはリストを再描画するためにコールバック関数に他のアイテムを渡すかもしれません。
いずれかのインジケータが表示されているときにこの呼び出しが最後のアイテムを削除した場合、インジケータは消えます。この呼び出しが最後の未読アイテムを削除したが未読アイテムが残っている場合、インジケータは点滅から点滅なしの状態に切り替わります。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
AttnGetAttention 関数 ^TOP^
目的
ユーザのアテンションをリクエストします。
宣言されている場所
AttentionMgr.h
Prototype
Err AttnGetAttention ( UInt16 cardNo, LocalID dbID, UInt32 userData, AttnCallbackProc *callbackFnP, AttnLevelType level, AttnFlagsType flags, UInt16 nagRateInSeconds, UInt16 nagRepeatLimit )
パラメータ
- → cardNo
- リクエストを行っているアプリケーションが存在しているカードの番号。
- → dbID
- リクエストを行っているアプリケーションのデータベース ID。
- → userData
- あとでコールバック関数を通じてあなたのコードに戻されるアプリケーション特有のデータ。callbackFnP パラメータでコールバック関数が指定されていない場合、このデータは sysAppLaunchCmdAttention とともに渡されるものの中にインクルードされます。userData はあなたのアプリケーションの必要性に応じて整数、ポインタ、他のいずれかの 32 ビット値になり得ます。たいていのアプリケーションはアテンション リクエストを引き起こしたレコードのための固有 ID か他のキーを渡します。さらに、userData は与えられたアテンション試行を同じアプリケーションによって作成された他のアテンション試行と区別するするためにも使用されます。
- → callbackFnP
- アテンションが表示または削除されるときにアテンション マネージャによって呼び出されるアプリケーションによって登録される関数へのポインタ。コールバック関数のパラメータについては、下の AttnCallbackProc() を参照してください。コールバック関数を呼び出すの代わりに sysAppLaunchCmdAttention 起動コードをアテンションが表示または削除されるときにアテンション リクエストを作成するアプリケーションに送るには NULL をセットします。
- → level
- 強調の度合いを示します。AttんLevelType で定義されている値の 1 つを渡します。
- → flags
- このアテンション リクエストの振る舞いを - 必要があれば - オーバライドします。例えば、このオーバライドはサイレント アラームやノイジー アラームをオーバライドします。このフラグを形成するさまざまなビットについては、AttnFlagsType を参照してください。あなたが互換性のないフラグヲセットした場合、その振る舞いは定義されないということに注意してください。このアテンション リクエストをユーザのプリ-セット設定に従わせるには kAttnFlagsUseUserSettings をセットします。
- → nagRateInSeconds
- ナギング ※ するまでにどのくらい待つか。
- → nagRepeatLimit
- 最初の試行を除いて、何度ナグ ※ を行うか。
返り値
何の問題も起きなければ errNone を返します。アテンション リクエストに応えるにはメモリが不足していた場合、attnErrMemory を返します。
コメント
cardNo の組み合わせがアテンションが行う試行を識別します。AttnGetAttention への他の呼び出しがこれらの引数と等価の値で行われた場合、エラーが報告されます。既存のアテンション アイテムを更新または削除するには、これらと同じ値をそれぞれ AttnUpdate() または AttnForgetIt() に渡します。
AttnGetAttention への応答の中でのオペレーション システムまたはアプリケーションの振る舞いは、すでに他の要求があるかどうか、この AttnGetAttention 呼び出しに渡された強調レベルに依存にします。
- 他の要求が無い、強調アテンション リクエスト:
アテンション マネージャはユーザのアテンションを得ようとしている現在の試行の詳細を示すダイアログを表示します。 - 他の要求がある、強調アテンション リクエスト:
アテンション マネージャはユーザのアテンションを得ようとしている現在の試行の要約をアテンションを必要としている事項のリストに追加します。ダイアログが詳細形式 - 他の要求がちょうど 1 つだけ存在していた場合 - である場合、その表示はリフレッシュされ、詳細形式からリスト形式に変わります。この場合、さらにペンとキーのイベント キューも消去されて表示が変更されている間に起こるすべてのユーザ イベントは無視されます。この振る舞いには 2 つの例外が存在します: 既存のアテンションがすべて目立たないものであるか、既存の強調アテンションがすべてスヌーズ (居眠り) 状態であった場合、新しい強調アテンションはダイアログと詳細モード - リスト モードではなく - で表示します。 - 目立たないアテンション リクエスト:
アテンション マネージャはアテンション インジケータの点滅を開始し、アイテムをあとで表示するために - ダイアログが現在リスト モードで表示されているのでない限り - アテンション インジケータのリストに追加します。この処理の中で、新しい目立たないアテンション アイテムはただそのリストの中に表示されるだけです; インジケータはそのアテンションをアナウンスするために点滅することはありません。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
参照
AttnGetCounts 関数 ^TOP^
目的
現在保留中のアテンション アイテムの数を返します。
宣言されている場所
AttentionMgr.h
Prototype
UInt16 AttnGetCounts ( UInt16 cardNo, LocalID dbID, UInt16 *insistentCountP, UInt16 *subtleCountP )
パラメータ
- → cardNo
- この値が 0 の場合、すべてのカード上のアプリケーションの保留中のアテンション アイテムを数えます。そうでない場合、指定されたカード上のアプリケーションの保留中のアテンション アイテムだけを数えます。
- → dbID
- この値が 0 の場合、すべてのアプリケーションの保留中のアテンション アイテムを数えます。そうでない場合、指定されたデータベース ID を持つアプリケーションの保留中のアテンション アイテムだけを数えます。
- ← insistentCountP
- 保留中の強調アイテムの数を埋め込まれた 16 ビット符号無し値へのポインタ。あなたが保留中の強調アイテムの数を知る必要がない場合はこのパラメータに NULL を渡します。
- ← subtleCountP
- 保留中の目立たないアイテムの数を埋め込まれた 16 ビット符号無し値へのポインタ。あなたが保留中の目立たないアイテムの数を知る必要がない場合はこのパラメータに NULL を渡します。
返り値
現在保留されている強調アイテムと目立たないアイテムの両方の数を返します。
コメント
アテンション アイテムがすでに保留されている場合に異なる振る舞いをする必要がある場合にこの関数を呼び出します。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
AttnIndicatorEnable 関数 ^TOP^
目的
スクリーン上のアテンション インジケータを使用可能、使用不能にします。
宣言されている場所
AttentionMgr.h
Prototype
void AttnIndicatorEnable ( Boolean enableIt )
パラメータ
- → enableIt
- アテンション インジケータを使用可能にするには true を、使用不能にするには false を渡します。
返り値
返り値はありません。
コメント
この関数はスクリーン上のアテンション インジケータを使用可能または使用不能にするためにアプリケーションによって使用されます。以下のすべてが真である場合、インジケータは点滅するだけです:
- インジケータは使用可能な状態。
- インジケータはアテンション マネージャから点滅するよう命令されている。
- オペレーション システムはアテンション インジケータが表示されるのを防ぐようなやり方 - メニュー バーが表示されている場合や、モーダル ダイアログがフォームの上段に表示されている場合など - でディスプレイを使用しているところではない。
アテンション インジケータはデフォルトでは使用可能になっています。あなたのアプリケーションがスクリーンの上側を制御していて、アテンション インジケータが表示されるのを防ぐ必要がある場合、AttnIndicatorEnable() を呼び出して false の値を渡します。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
参照
AttnIndicatorEnabled 関数 ^TOP^
目的
スクリーン上のアテンション インジケータが現在使用可能な状態かどうかを返します。
宣言されている場所
AttentionMgr.h
Prototype
Boolean AttnIndicatorEnabled ( void )
パラメータ
ありません。
返り値
スクリーン上のアテンション インジケータが現在使用可能な状態である場合は、true を返します。そうでない場合は、false を返します。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
参照
AttnIterate 関数 ^TOP^
目的
アテンション マネージャに現在保留中の各アテンション アイテムをチェックするように命令し、指定されたカード番号とデータベース ID が一致するアテンション アイテムに対してそのアイテムのコールバック ルーチンを呼び出します。コールバック ルーチンがリクエストの中で指定されていない場合、sysAppLaunchCmdAttention 起動コードがそのアテンション リクエストを行ったアプリケーションに送られます。
宣言されている場所
AttentionMgr.h
Prototype
void AttnIterate ( UInt16 cardNo, LocalID dbID, UInt32 iterationData )
パラメータ
- → cardNo
- リクエストを行ったアプリケーションが存在しているカードの番号。
- → dbID
- リクエストを行ったアプリケーションのデータベース ID。
- → iterationData
- アプリケーションがコールバックまたは起動コードを処理するために必要とするかもしれないデータ。このパラメータについての更なる情報は、AttnCallbackProc() の説明を参照してください。
返り値
返り値はありません。
コメント
この関数は、指定されたアプリケーションによって作成されたアテンション リクエストをすべて反復処理し、アプリケーションにアテンション リクエストについて知らせるために各アテンション リクエストのコールバックまたは起動コードを使用します。アプリケーションのデータベースに影響を与える HotSync が起こったことを意味する sysAppLaunchCmdSyncNotify をアプリケーションが受け取ったとき、通常、そのアプリケーションは AttnIterate を呼び出し、それによりそのアプリケーションは HotSync の最中に削除されたかもしれないレコードのためのアテンション リクエストを削除することができます。さらに、アプリケーションは必要があれば HotSync の後に AttnGetAttention() を呼び出すこともできます。
あなたはこの関数呼び出しを使った反復処理の中で AttnForgetIt() を呼び出すことができるということに注意してください。なぜなら、その関数はレコードに削除のマークを付けるだけであり、反復処理を混乱させることがないからです。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
AttnListOpen 関数 ^TOP^
目的
アテンション ダイアログをリスト モードで表示し、ユーザがそれを消した後にそのダイアログがどのように消されたかに基づいて行動します。
宣言されている場所
AttentionMgr.h
Prototype
void AttnListOpen ( void )
パラメータ
ありません。
返り値
返り値はありません。
コメント
この関数は点滅するアテンション インジケータを提供しないアプリケーションに必要があればリストをオープンすることを許可します。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
AttnUpdate 関数 ^TOP^
目的
指定されたアテンション アイテムの 1 つまたは複数の内容を更新します。
宣言されている場所
AttentionMgr.h
Prototype
Boolean AttnUpdate ( UInt16 cardNo, LocalID dbID, UInt32 userData, AttnCallbackProc *callbackFnP, AttnFlagsType *flagsP, UInt16 *nagRateInSecondsP, UInt16 *nagRepeatLimitP )
パラメータ
- → cardNo
- リクエストを行ったアプリケーションが存在しているカードの番号。
- → dbID
- リクエストを行ったアプリケーションのデータベース ID。
- → userData
- コールバック関数を通してあなたのコードに戻されるアプリケーション特有のデータ。callbackFnP パラメータの中でコールバック関数が指定されていない場合、このデータは sysAppLaunchCmdAttention 起動コードとともに渡されるものの中にインクルードされます。userData は整数、ポインタ、あなたのアプリケーションの必要に応じて他のいずれかの 32 ビット値になることができます。たいていのアプリケーションはアテンション リクエストを引き起こしたレコードのための固有 ID か他のキーを渡します。さらに、userData は与えられたアテンション試行を同じアプリケーションによって作成された他のアテンション試行と区別するするためにも使用されます。
- → callbackFnP
- アテンションが表示または削除されるときにアテンション マネージャによって呼び出されるアプリケーションによって登録される関数へのポインタ。コールバック関数のパラメータについては、下の AttnCallbackProc() を参照してください。コールバック関数を呼び出すの代わりに sysAppLaunchCmdAttention 起動コードをアテンションが表示または削除されるときにアテンション リクエストを作成するアプリケーションに送るには NULL をセットします。
- 重要
- NULL はコールバック関数が呼び出される代わりに起動コードが送られるべきであることを意味するため、callbackFnP パラメータの元々の設定を手付かずの状態で残しておくためには使用されません。このパラメータに提供される値は常に元々のアテンション リクエストの中で提供された値を上書きします。
- → flagsP
- ユーザ指定のアテンションの振る舞いをオーバライドするために使用される可能性があるフラグのセットへのポインタ; 例えば、アラームを強制的にサイレントまたはノイジーにするため。このフラグを形成するさまざまなビットについては、AttnFlagsType を参照してください。あなたが互換性のないフラグをセットした場合、その振る舞いは定義されないということに注意してください。現在のフラグ設定を変更せずそのままにしておくには NULL を渡します。
- → nagRateInSecondsP
- ナギング ※ するまでの待機時間へのポインタ。この値を変更せずそのままにしておくには NULL を渡します。
- → nagRepeatLimitP
- ナグする最大回数へのポインタ。ナグ リピート制限を変更せずにそのままにしておくには NULL を渡します。
返り値
更新が成功した場合、true を返します。一致するアテンション アイテムが見つからなかった場合、false を返します。
コメント
この呼び出しの結果として、アイテムを再表示するためにコールバック関数が呼び出されるかもしれません。コールバック関数が指定されていない場合、代わりに sysAppLaunchCmdAttention 起動コードがあなたのアプリケーションに送られます。さらに、この呼び出しの結果として他の保留中のアテンション リクエストへのコールバックが発生するかもしれません。
あなたはアテンション マネージャに更新するよう - 再描画するためにアテンション マネージャにそれのすべてのクライアントを呼び出すよう強制することによって - 命じます。この呼び出しはアプリケーションのためにアテンション マネージャ ダイアログを取り壊したり再度オープンすること無しにアテンション アイテムのテキストを更新する手段を提供します。例えば、AttnUpdate は新たなメッセージが届いたときに「あなたには 3 つの新しい e-mail メッセージがあります」と知らせるために既存の e-mail 通知を更新するのに使用することができます。
AttnUpdate は与えられたアテンション アイテムの再描画を引き起こすかもしれませんが、アテンション アイテムが追加されたときに引き起こされる特殊効果 (がある場合でも) を引き起こしません。あなたがある特定のアイテムに対してアテンション マネージャ効果を引き起こすことを望む場合、AttnGetAttention() に続けて AttnForgetIt() を呼び出してください。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
参照
アプリケーション定義関数 ^TOP^
AttnCallbackProc 関数 ^TOP^
目的
AttnGetAttention() と AttnUpdate() に提供されるコールバック関数によって使用される関数プロトタイプを提供します。提供される関数はアテンションが表示または削除されるときにいつでもアテンション マネージャによって呼び出されます。
宣言されている場所
AttentionMgr.h
Prototype
typedef Err AttnCallbackProc( AttnCommandType command, UInt32 userData, AttnCommandArgsType *commandArgsP )
パラメータ
- → command
- このコールバック関数が何をリクエストされているのかを示します。とり得るコマンドの完全なリストは AttnCommandType の定義の中で説明されています。
- → userData
- ある特定のアテンションをこのアプリケーションによって作成された他のアテンションと区別する識別子。この識別子はアテンション アイテムが作成されたときに指定されたものです。
- → commandArgsP
- コマンド特有の引数へのポインタ。コマンドの引数の説明は、各コマンドの説明を参照してください。
返り値
コールバック関数が正しくコマンドをハンドルした場合、コールバック関数は errNone を返すべきです。そうでない場合は適切なエラー コードを返すべきです。コールバック関数が errNone ではなくエラー コードをを返す場合、アテンションはアクティブ アテンション アイテムのリストから削除されます。
コメント
与えられたアテンション アイテムに対して、アテンション マネージャがリソースにアテンション ダイアログの内容を描画される必要があるときはいつでも、また、アテンション マネージャがコード リソースにアテンション アイテムに関連する活動を知らせる必要があるときはいつでも、アテンション マネージャはアイテムを作成したコード リソースをコールバックします。アテンション マネージャのコールバックは以下の 2 つのメカニズムのうちの 1 つを使用します:
- コールバック ルーチンが与えられたアテンション アイテムに対して指定されている場合、アテンション マネージャは指定されたルーチンを呼び出します。このコールバック ルーチンはアプリケーション グローバル変数を利用できません。そのため、描画や他の表示に必要なものはすべて commandArgsP を通じて利用可能であるということが重要になります。通常、コールバック ルーチンはライブラリとシステム 拡張によって使用されます。
- コールバック ルーチンが与えられたアテンション アイテムに対して指定されていな場合、アテンション マネージャはコールバックの変わりに sysAppLaunchCmdAttention 起動コードをそのアテンション アイテムを登録したアプリケーションに送ります。起動コードが伴っているものは、上記の 3 つのパラメータを保持している AttnLaunchCodeArgsType 構造体です。通常、アプリケーションはコールバック ルーチンに制限があるために起動コード メカニズムを使用します。
- 重要
- コールバック関数が呼び出されたときに、コードリソースがロックを解除されてメモリの中を移動させられる可能性とコード リソースを保持しているデータベースが削除される可能性を処理して、そのコールバック関数が同じ場所に配置されていることを保証する責任はあなたにあります。たいていの場合、起動コードを使用していればこれらの問題は生じません。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。