Treo 600 の 5-Way Navigation に関して。

概要

キャラクターコード

KeyDownEventで発行されるchrは、

• vchrRockerUp : 上ボタン
• vchrRockerDown : 下ボタン
• vchrRockerLeft : 左ボタン
• vchrRockerRight : 右ボタン
• vchrRockerCenter : 中央ボタン

5-Way Rocker 有無の判断

UInt32 val;
if (FtrGet (hsFtrCreator, hsFtrIDNavigationSupported, &val) == errNone)
 // 5-Way Rocker あり
~

※下の方法は使えない（エラーとなるため判定できない）。

if (FtrGet (sysFileCSystem, sysFtrNumUIHardwareFlags, &val) == errNone)
{
 if (val & sysFtrNumUIHardwareHas5Way)
  // 5-Way Rocker あり
}

イベント

frmObjectFocusTakeEvent

オブジェクトがフォーカスされた

frmObjectFocusLostEvent

オブジェクトのフォーカスが解除された

関数

最も使うと思われる関数

HsNavObjectTakeFocus (frmP, objectID)

指定したオブジェクトにフォーカスを移す。

5-Way Navigation

ソニーのジョグアシストのように、5-Way Rocker での操作をシステムがアシストしてくれる機能がある。モーダルフォーム以外でこれを利用するには、設定が必要。

モードの設定

• フォーム毎に、次の2つのフォーカスモードを設定することが出来る。
  • object focus mode : システムのアシストあり
  • application focus mode : システムのアシストなし
• デフォルトのモード
  • モーダルフォーム : object focus mode
  • その他のフォーム : application focus mode
• 設定方法（後述）
  • プログラムに記述 …使い回しが効く?
  • リソースに定義 …機種の判断が不要だが、全てのオブジェクトを定義する必要がある

利用方法

• object focus mode に設定されたフォームでは、アプリケーション側が KeyDownEvent を処理しなければ（フォームの EventHandler が true を返さなければ）、デフォルトの5-Way Navigationが有効になる。

フォーカスモードの設定方法１ … プログラムに記述

プログラム内で、関数を使って記述する方法。

1. フォーム全体

   FrmSetNavState (frmP, stateFlags)

   パラメータ stateFlags
   • kFrmNavStateFlagsInteractionMode：application focus mode
   • kFrmNavStateFlagsObjectFocusMode：object focus mode
2. オブジェクト

   FrmSetNavEntry (formP, targetObjectID, afterObjectID,
                   aboveObjectID, belowObjectID, objectFlags)

   パラメータ stateFlags
   • kFrmNavObjectFlagsSkip : フォーカスをスキップする
   • kFrmNavObjectFlagsForceInteractionMode : 相互作用モード(?)
   • kFrmNavObjectFlagsIsBigButton : ビッグボタンモード
   • 0 でも問題ない。ただし、オブジェクトがフィールドやテーブルの場合は、 kFrmNavObjectFlagsForceInteractionMode にしないとオブジェクト全体がフォーカスされてしまう。
3. フォームとオブジェクトをまとめて設定

   FrmSetNavOrder (formP, navHeaderP, navOrderP)

フォーカスモードの設定方法２ … リソースに定義

モードをリソースとして定義する方法。

• モーダルフォーム以外で 5-Way Navigation を有効にするには、formNavRscType ('fnav')というリソースをフォーム毎に追加する必要がある。
• 定義する内容は、上記のプログラムに記述するものと同様。
• サンプルコード「HsNavSample」が参考になる。

書式

• ヘッダー

  UInt16 version;                  // APIのバージョン (=1)
  UInt16 numberOfObjects;          // オブジェクトの数
  UInt16 headerElementSizeInBytes; // ヘッダーサイズ (=20)
  UInt16 listElementSizeInBytes;   // リストの要素サイズ (=8)
  UInt32 navFlags;                 // フォーカスモード ※1
  UInt16 initialObjectIDHint;      // 最初にフォーカスされるオブジェクトのID
  UInt16 jumpToObjectIDHint;       // 未使用
  UInt16 bottomLeftObjectIDHint;   // 未使用
  UInt16 padding;                  // ?

• 以下はオブジェクトの数（numberOfObjects）だけ繰り返し。順番は左上から右下へ向かって横に移動（が普通だと思う）。

  UInt16 objectID;                 // オブジェクトのID
  UInt16 objectFlags;              // フラッグ ※2
  UInt16 aboveObjectID;            // １つ上のオブジェクトID（前のではない）
  UInt16 belowObjectID;            // １つ下のオブジェクトID（後のではない）

※1 navFlags に関して

• kFrmNavHeaderFlagsObjectFocusStartState(=0x00000001) ：object focus mode
• kFrmNavHeaderFlagsAppFocusStartState(=0x00000002) ：application focus mode

※2 objectFlags に関して

• kFrmNavObjectFlagsSkip(=0x0001) : フォーカスをスキップする
• kFrmNavObjectFlagsForceInteractionMode(=0x0002) : 相互作用モード(?)
• kFrmNavObjectFlagsIsBigButton(=0x8000) : ビッグボタンモード
• 0x0000 でも問題ない。ただし、オブジェクトがフィールドやテーブルの場合は、 kFrmNavObjectFlagsForceInteractionMode にしないとオブジェクト全体がフォーカスされてしまう。

CodeWarriorでの定義

• PilRC 用フォーマットで、上記リソースを作成する。
• 拡張子は「.rcp」。
• 入力する数値はHEX（16進数）。
• サンプル

  HEX "fnav" ID ListView
  0x00 0x01
  0x00 0x0b
  0x00 0x14
  0x00 0x08
  0x00 0x00 0x00 0x02
  0x03 0xf2
  0x03 0xf2
  0x03 0xea
  0x00 0x00
  
  0x03 0xfc
  0x00 0x00
  0x00 0x00
  0x03 0xf2
  
  …以下オブジェクトの数だけ繰り返し（この場合11個）

• このファイルをプロジェクトに加えて、他のものと一緒にコンパイルする。

テーブルを含むフォームで利用

KeyDownEvent の処理

• フォーカスされているオブジェクトを

  FrmGetFocus (frmP)

  で調べ、テーブルの場合だけ KeyDownEvent の処理を行う。
• テーブルの選択行（カーソル）が先頭行または最終行を超える場合には、テーブルのフォーカスを解除する。… KeyDownEvent の処理を行わなければ（EventHandler で false を返せば）勝手に解除され、上下のオブジェクトにフォーカスが移動する。
• フォーカスがテーブル以外にあるときは、KeyDownEvent の処理を行わない。

フォーカス処理

イベント

• frmObjectFocusTakeEvent
• frmObjectFocusLostEvent

に対応して、オブジェクトがテーブルの場合は、カーソルのハイライトなどの処理を行う。

その他

アプリ側で強制的にフォーカスを移動させるには

HsNavObjectTakeFocus (frmP, objectID);

を使う。

フィールドを含むフォームで利用

KeyDownEvent の処理

• アプリ側で処理することはほとんど無い。
• vchrRockerCenter の場合だけ、[OK]や[Done]などのフォームを閉じるボタンにフォーカスを移動する処理をした方が良いかもしれない。

その他のフォームでの利用

フィールドやテーブルが無い（ボタン類がメインの）フォームでは、

FrmSetNavState (frmP, kFrmNavStateFlagsObjectFocusMode);

としておけば、アプリケーション側で keyDownEvent の処理をする必要は無い。