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