Palm Programmer's Laboratory
Palm OS Programmer's API Reference/14
この章ではフィールド オブジェクトについて以下のことを説明します。
ヘッダファイル List.h がこの章で説明する API を宣言しています。リストについての追加情報は Palm OS Programmer's Companion, vol. I の「リスト」を参照してください。
リスト データ構造体 ^TOP^
ListAttrType 構造体 ^TOP^
目的
ListAttrType ビット フィールドはリストの可視特性を定義します。
Prototype
typedef struct {
UInt16 usable:1;
UInt16 enabled:1;
UInt16 visible:1;
UInt16 poppedUp:1;
UInt16 hasScrollBar:1.
UInt16 search:1;
UInt16 reserved:2;
} ListAttrType;
フィールド
- usable
- リストを使用可能にするためにセットします。セットされていないと、リストは現在のアプリケーション インターフェイスの一部として扱われず、画面にも表示されません。
- enable
- 使用しません。
- visible
- リスト オブジェクトを描画するときにセットし、リスト オブジェクトが消去されるときにはクリアされます。
- poppedUp
- 選択肢がポップアップ ウィンドウに表示されるよう指示するためにセットします。この属性はセットされ、内部的にクリアされます。
- hasScrollBar
- リストがスクロール バーを持つように指示するためにセットします。
- search
- インクリメンタル サーチを可能にするためにセットします。インクリメンタル サーチが可能な場合、リストが表示されているときにユーザは 5 文字までの入力を行うことでリストをナビゲートすることができます。リストは、入力された文字に一致する最初のリスト アイテムが表示されるようにスクロールします。この機能はポップアップ リストに対してと、リストがソートされていてリスト マネージャがリスト アイテムを使用可能な（つまり、LstSetListChoices() に NULL を渡さない）場合にのみ機能します。
- reserved
- システムが使用するために予約されています。
ListType 構造体 ^TOP^
目的
ListType 構造体は以下のように定義されています。
- WARNING!!!
- PalmSource 社（訳者注: 現 ACCESS 社）は、ListType 構造体に対して下位互換をサポートまたは提供していません。決してこの構造体メンバに直接アクセスしないでください。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。
Prototype
typedef struct {
UInt16 id;
RectangleType bounds;
ListAttrType attr;
Char **itemsText;
Int16 numItems;
Int16 currentItem;
Int16 topItem;
FontID font;
UInt8 reserved;
WinHandle popupWin;
ListDrawDataFuncPtr drawItemCallback;
} ListType;
フィールド
- id
- ID 値。この値はアプリケーション開発者によって指定されます。この ID 値は lstEnterEvent と lstSelectEvent のイベント データのデータの一部として含まれます。
- bounds
- リストの領域。ウィンドウに関係します。例えば、ID が kObjectID のフォームにあるオブジェクトの領域にアクセスする場合、以下のようになります。
{
RectangleType rect;
FormPtr formP = FrmGetActiveForm();
FrmGetObjectBounds(formP,
FrmGetObjectIndex(formP, kObjectID),
&rect);
}
- attr
- リスト属性です。ListAttrType を参照してください。
- itemText
- 選択肢のテキストを指す配列のポインタへのポインタです。LstGetSelectionText() を用いてアクセスします。例えば、ID が kChoiceList のリストにある itemNum によって指定される文字列にアクセスするには、以下のようにします。
{
Char *string;
Int16 itemNum;
...
string = LstGetSelectionText(GetObjectPtr(kChoicesList), itemNum);
}
where GetObjectPtr is the following:
static void *GetObjectPtr(UInt16 rsrcID){
FormPtr formP;
formP = FrmGetActiveForm();
return FrmGetObjectPtr(formP, FrmGetObjectIndex(formP, rsrcID));
}
- リスト アイテムを描くのにコールバック ルーチンを使用する場合、LstSetListChoices() に渡す itemsText ポインタがコールバック ルーチンに渡されるということに注意してください。コールバック ルーチンに itemsText を使用する Tips は ListDrawDataFuncType() のコメントを参照してください。
- numItems
- リストの選択肢の数。LstGetNumberOfItems() を用いてアクセスします。
- currentItem
- 現在選択されているリスト選択肢（0 = 最初の選択肢）。LstGetSelection() を用いてアクセスします。
- topItem
- リスト中で表示されている最初の選択肢。LstSetTopItem() を用いてセットします。
- font
- リスト テキスト文字列を描くのに使用されるフォントの ID。
- reserved
- 将来使用するために予約されています。
- popupWin
- LstPopupList() を呼び出すことでリストが表示されるときに作成されるウィンドウのハンドル
- drawItemCallback
- アイテムを描くのに使用される関数。NULL の場合、代わりにデフォルトの描画ルーチンが使用されます。LstSetDrawFunction() を用いてこのフィールドをセットします。アプリケーション定義関数 を参照してください。
リスト リソース ^TOP^
リスト リソース（tLST）とポップアップ トリガ リソース（tPUT）はアクティブなリストを表すために一緒に使用されます。詳細は、Palm OS User Interface Guidelines を参照してください。
リスト関数 ^TOP^
LstDrawList 関数 ^TOP^
目的
リスト オブジェクトの可視属性を true にセットし、リスト オブジェクトが使用可能であればそれを描きます。
宣言されている場所
List.h
Prototype
void LstDrawList ( ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
返り値はありません。
コメント
表示できる分よりも多くの選択肢がある場合、この関数は現在の選択が可視であることを保証します。現在の選択はハイライトされます。この関数は現在の選択が可視であることを保証しないということに注意してください（訳者注: 前文と矛盾している？前文の条件を満たさない場合はということか？）。可視であることを保証するためには、LstMakeItemVisible() 関数を呼び出してください。
リストが無効になっている場合、グレイ-アウトで表示されます。リストが空の場合、何も表示されません。使用可能ではない場合、何も表示されません。
参照
FrmGetObjectPtr(), LstPopupList(), LstEraseList()
LstEraseList 関数 ^TOP^
目的
リスト オブジェクトを消去します。
宣言されている場所
List.h
Prototype
void LstEraseList ( ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
返り値はありません。
コメント
visible 属性は、この関数によって、false にセットされます。
参照
FrmGetObjectPtr(), LstDrawList()
LstGetNumberOfItems 関数 ^TOP^
目的
リストにあるアイテム数を返します。
宣言されている場所
List.h
Prototype
Int16 LstGetNumberOfItems ( const ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
リストにあるアイテムの数を返します。
参照
FrmGetObjectPtr(), LstSetListChoices()
LstGetSelection 関数 ^TOP^
目的
リスト中で現在選択されている選択肢を返します。
宣言されている場所
List.h
Prototype
Int16 LstGetSelection ( const ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
リスト選択肢で現在選択されているアイテム番号を返します。リスト選択肢は 0 から始まる連続した番号を付けられています。アイテムが選択されていない場合、noListSelection を返します。
参照
FrmGetObjectPtr(), LstSetListChoices(), LstSetSelection(), LstGetSelectionText()
LstGetSelectionText 関数 ^TOP^
目的
リスト中の指定されたアイテムのテキストへのポインタを返します。指定されたアイテムが無い場合、NULL を返します。
宣言されている場所
List.h
Prototype
Char *LstGetSelectionText ( const ListType *listP, Int16 itemNum )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → itemNum
- 選択するアイテム（0 = リストの最初のアイテム）
返り値
現在の選択のテキストへのポインタを返します。選択が範囲外の場合、NULL を返します。
コメント
この関数の返り値は ListType 内部へのポインタであり、コピーではありません。この関数は、文字列の配列と LstSetListChoices() の総計が提供されている場合にのみ、使用可能です。アプリケーションがリスト テキストを動的に生成するコールバック関数を使用している場合、この関数は NULL を返します。
参照
LstGetTopItem 関数 ^TOP^
目的
最上段の可視のアイテムを返します。
宣言されている場所
List.h
Prototype
Int16 LstGetTopItem ( const ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
最初の可視のアイテムのアイテム番号を返します。
互換性
4.0 New Feature Set が存在する場合にのみ、実装されます。
参照
LstGetSelection(), LstSetTopItem()
LstGetVisibleItems 関数 ^TOP^
目的
可視のアイテムの数を返します。
宣言されている場所
List.h
Prototype
Int16 LstGetVisibleItems ( const ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
可視のアイテム数
互換性
2.0 New Feature Set が存在する場合にのみ、実装されます。
LstHandleEvent 関数 ^TOP^
目的
指定されたリストのイベントをハンドルします。ハンドルするには、リスト オブジェクトの usable と visible 属性が true にセットされていなくてはなりません。このルーチンは 2 種類のイベント penDownEvent と lstEnterEvent をハンドルします。コメントを参照してください。
宣言されている場所
List.h
Prototype
Boolean LstHandleEvent ( ListType *listP, const EventType *eventP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → eventP
- EventType 構造体へのポインタ
返り値
イベントがハンドルされた場合は、true を返します。以下の場合では、結果として true を返します。
- リストの領域内での penDownEvent
- リスト データ構造体のリスト ID と一致するリスト ID を持つ lstEnterEvent
コメント
このルーチンが penDownEvent を受け取ると、このルーチンはペンの位置がリスト オブジェクトの領域内かどうかチェックします。領域内であれば、このルーチンはペンが領域外に出るまでペンを追跡します。ペンがリストの領域内に入ってくると、lstEnterEvent がイベント キューに追加され、このルーチンは終了します。
このルーチンが lstEnterEvent を受け取ると、イベント レコードのリスト ID が指定されたリストの ID と一致するかどうかチェックします。一致する場合、このルーチンはリストの選択肢を保持しているポップアップ ウィンドウを作成し、表示してから終了します。
リストのポップアップ ウィンドウが表示されている間に penDownEent を受け取り、かつ、ペンの位置が領域外の場合、そのウィンドウは消されます。ペンの位置がウィンドウの領域内の場合、このルーチンはペンが領域外にでるまでペンを追跡します。
ペンがリスト オブジェクトの領域外に出ると、lstEnterEvent がイベント キューに追加されます。
LstMakeItemVisible 関数 ^TOP^
目的
アイテムを可視に、できれば最上段に、します。アイテムがすでに可視の場合、変更されません。
宣言されている場所
List.h
Prototype
void LstMakeItemVisible ( ListType *listP, Int16 itemNum )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → itemNum
- 選択するアイテム（0 = リストの最初のアイテム）
返り値
返り値はありません。
コメント
この関数はリストの再描画は行いません。再描画するためには、LstDrawList() を呼び出してください。
LstNewList 関数 ^TOP^
目的
新しいリスト オブジェクトを動的に作成し、それを指定されたフォームにインストールします。この関数は、新しいポップアップ トリガとそれに関連するリストを作成するのに使用できます。
宣言されている場所
List.h
Prototype
Err LstNewList ( void **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height, FontID font, Int16 visibleItems, Int16 triggerId )
パラメータ
- ←→ formPP
- 新しいリストがインストールされるフォームへのポインタへのポインタ。この値はハンドルではありません。つまり、この関数が返った後に、古い formPP 値が有効である必要はありません。その後の呼び出しでは、この関数によって常に新しい formPP 値が返されます。
- → id
- 開発者によって指定されたリストの記号的な ID。規約では、この ID はリソース ID と一致しているべきです（義務ではありません）。
- → x
- 作成されるリストの領域の左上端の、リストが現れるウィンドウに関連する、水平座標
- → y
- 作成されるリストの領域の左上端の、リストが現れるウィンドウに関連する、垂直座標
- → width
- ピクセルで表されるリストの幅。有効値は 1 - 160。
- → height
- ピクセルで表されるリストの高さ。有効値は 1 - 160。
- → visibleItems
- 同時に表示することができるリスト アイテムの数
- → triggerId
- 新しいリストに関連するポップアップ トリガの記号的な ID （この ID は開発者によって指定されます）。triggerId に対して 0 以外の値を指定すると、この関数はリストとそれに関連するポップアップ トリガの両方を作成します。リストがポップアップ リストではない場合、triggerId に対して 0 を渡してください。
返り値
エラーが無い場合は、0 を返します。
互換性
3.0 New Feature Set が存在する場合にのみ、実装されます。
参照
LstDrawList(), FrmRemoveObject()
LstPopupList 関数 ^TOP^
目的
リストのアイテムを保持している様式の（原文: modal）ウィンドウを表示します。
宣言されている場所
List.h
Prototype
Int16 LstPopupList ( ListType *listP )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
返り値
選択されたリスト アイテムを返します。選択されたアイテムが無い場合は、-1 を返します。
コメント
前のアクティブ ウィンドウを保存します。新しいポップアップ ウィンドを作成し、削除します。
参照
LstScrollList 関数 ^TOP^
目的
リストを上または下に何度かスクロールさせます。
宣言されている場所
List.h
Prototype
Boolean LstScrollList ( ListType *listP, WinDirectionType direction, Int16 itemCount )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → direction
- スクロールの方向
- → itemCount
- 指示した方向にスクロールするアイテム（訳者注: スクロールする回数のことか？）
返り値
リストが実際にスクロールされれば true を返します。そうでなければ、false を返します。リストの終わりを越えるスクロールが要求されると false を返すかもしれません。
互換性
2.0 New Feature Set が存在する場合にのみ、実装されます。
LstSetDrawFunction 関数 ^TOP^
目的
アイテムのテキスト文字列を描く代わりに各アイテムを描く関数をセットします。
宣言されている場所
List.h
Prototype
void LstSetDrawFunction ( ListType *listP, ListDrawDataFuncPtr func )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → func
- アイテムを描く関数へのポインタ
返り値
返り値はありません。
コメント
この関数は、縮められたリストが下方向にスクロールされ過ぎるのを防ぐため、topItem を調節する機能も持っています。この関数はカスタム描画機能性のために使用されます。
参照
FrmGetObjectPtr(), LstGlueGetDrawFunction(), LstSetListChoices(), ListDrawDataFuncType()
LstSetHeight 関数 ^TOP^
目的
リスト中の可視のアイテムの数をセットします。
宣言されている場所
List.h
Prototype
void LstSetHeight ( ListType *listP, Int16 visibleItems )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → visibleItems
- 一度に可視となる選択肢の数
返り値
返り値はありません。
コメント
この関数は、リストがすでに描画されている場合、リストの再描画を行いません。
参照
LstSetListChoices 関数 ^TOP^
目的
この関数に渡されたテキスト文字列ポインタの配列にリストのアイテムをセットします。この関数は古いリスト アイテムを消去します。
宣言されている場所
List.h
Prototype
void LstSetListChoices ( ListType *listP, Char **itemsText, Int16 numItems )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → itemText
- テキスト文字列の配列へのポインタ。この文字列の配列を作成する 1 つの方法は、SysFormPointerArrayToStrings() を参照してください。
- → numItems
- リストの選択肢の数
返り値
返り値はありません。
コメント
この関数を呼び出したときにリストが表示されている場合、リスト（の表示）を更新するために LstDrawList 関数を呼び出す必要があります。
- NOTE:
- この関数は itemsText 配列にある文字列をコピーするわけではありません。このことが意味するのは、この関数をリストに対して実行した後はその配列が移動されたり、割り当てを解除されたりしないことを保障しなくてはならないということです。
リストのアイテムを描画するためにコールバック ルーチンを使用する場合、単に itemsText ポインタをコールバック ルーチンに渡すだけで済み、itemsText ポインタに対してリスト マネージャ コードを使用する必要はありません。コールバック ルーチンに対して itemsText パラメータを使用する Tips については、ListDrawDataFuncType() のコメントを参照してください。
参照
FrmGetObjectPtr(), LstGlueGetItemsText(), LstSetSelection(), LstSetTopItem(), LstDrawList(), {[goto LstSetHeight,LstSetHeight()}}, LstSetDrawFunction()
LstSetPosition 関数 ^TOP^
目的
リストの位置をセットします。
宣言されている場所
List.h
Prototype
void LstSetPosition ( ListType *listP, Coord x, Coord y )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → x
- 左端
- → y
- 上端
返り値
返り値はありません。
コメント
リストは再描画されません。リストが可視のときに、この関数を呼び出してはいけません。
参照
LstSetSelection 関数 ^TOP^
目的
リストの選択をセットします。
宣言されている場所
List.h
Prototype
void LstSetSelection ( ListType *listP, Int16 itemNum )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → itemNum
- 選択されるアイテム（0 = リストの最初のアイテム, noListSelection = 選択無し）
返り値
返り値はありません。
コメント
古い選択は、あったとしても、選択が解除されます。リストが可視の場合、選択されたアイテムは視覚的に更新されます。リストは、必要があれば、リスト オブジェクトが可視で使用可能な限り、選択されたアイテムに向けてスクロールされます。
参照
FrmGetObjectPtr(), LstSetTopItem()
LstSetTopItem 関数 ^TOP^
目的
アイテムを可視にします。アイテムが、リストの最後にある場合、最上段のアイテムにはなれません。
宣言されている場所
List.h
Prototype
void LstSetTopItem ( ListType *listP, Int16 itemNum )
パラメータ
- → listP
- リスト オブジェクト（ListType）へのポインタ
- → itemNum
- 選択されるアイテム（0 = リストの最初のアイテム）。この値は有効なアイテム番号でなくてはなりません。
返り値
返り値はありません。
コメント
ディスプレイの更新は行いません。
- NOTE:
- itemNum に指定する値は 0 から アイテムの最大番号までの範囲でなければなりません。
参照
FrmGetObjectPtr(), LstGlueGetTopItem, LstSetSelection(), LstGetTopItem(), LstMakeItemVisible(), LstDrawList(), LstEraseList()
アプリケーション定義関数 ^TOP^
リストのアイテムに対して特別な描画を行う必要がある場合、リスト描画コールバック関数をセットするために LstSetDrawFunction() を呼び出します。ListDrawDataFuncType() セクションでは、リスト アイテムの描画のために提供されるコールバック関数のプロトタイプについて説明しています。
ListDrawDataFuncType 関数 ^TOP^
目的
コールバック関数は、リストのアイテムを描画するために提供されるものです。この関数は、Palm OS がリストの要素を仰臥する必要があるときにいつでも呼び出されます。コールバック関数の宣言は、ここで示すプロトタイプと一致していなくてはなりません。
宣言されている場所
List.h
Prototype
void ListDrawDataFuncType( Int16 itemNum, RectangleType *bounds, Char **itemsText )
パラメータ
- → itemNum
- 描画するアイテムの数
- → bounds
- ウィンドウに関連するリストの領域
- → itemsText
- リスト アイテムのテキストへのポインタ配列へのポインタ。これは、LstSetListChoices() を呼び出したと域に提供されるポインタです。
返り値
返り値はありません。
コメント
コールバック関数をリストに対して登録するために LstSetDrawFunction) を呼び出します。これが意味するのは、リスト アイテムを描画するために、各アイテムのテキスト文字列を表示するビルド-イン関数ではなく、登録した関数が呼び出されるということです。
コールバック関数は、リストのアイテムが描画される必要があればいつでも、呼び出されます。コールバック関数が呼び出されたとき、itemNum パラメータの値が、関数が描くべきアイテムを指定します。LstSetListChoices に提供される itemsText パラメータは、実際に文字列のリストを指している必要はありません: NULL または 描画関数に有用な何かを指すポインタを渡すこともできます。しかしながら、LstSetListChoices を呼び出す際に文字列のリストを指すポインタ以外のものを渡す場合、LstGetSelectionText() が決して呼び出されないということを保障しなくてはならないことに注意してください。なぜなら、LstGetSelectionText() は itemsText ポインタがテキスト アイテムの配列を指していると仮定しているからです。特に、リストがポップアップ トリガに関連している場合、FrmHandleEvent() が popSelectEvent をハンドルする機会を得る前に、アプリケーション コードが自身で popSelectEvent をハンドルしなくてはなりません。なぜなら、FrmHandleEvent は LstGetSelectionText を呼び出すからです。
- WARNING!
- リストがポップアップ リストの場合、そのリストを所有しているフォームは、そのリストがウィンドウに表示されている間、アクティブになりません。これが意味するのは、FrmGetActiveForm() を呼び出すことができないということです。代わりに、描画に必要となる情報にアクセスするために itemsText ポインタを使用します。フォームにアクセスしなけらばならない場合、FrmGetFormPtr() 関数を使用してください。
リスト オブジェクトは、アイテムを描画する際にどの色を使用するか、と、選択されたアイテムと選択されていないアイテムをどのように描画するかを管理するということに注意してください。ほぼすべての状況で、描画関数がこれらの詳細について関知する必要はありません。
しかしながら、アイテムが選択されているかどうか調べる必要がある場合、描画関数を呼び出すのに先立って、システムがペン カラーを 2 つの色のどちらの色にしたかという事実を信頼することができます。
- アイテムが選択されている場合、前景色は UIObjectSelectedForeground です。
- アイテムが選択されていない場合、前景色は UIObjectForeground です。
リスト アイテムに影響を与えるこの前景色を、前景色の前の値を返す WinSetForeColor()|Palm OS Programmer's API Reference/59 を呼び出すことで調べられます。前景色を以前の色にリセットするために、忘れずにもう一度 WinSetForeColor を呼び出してください。例えば、以下のようにします。
itemColor = WinSetForeColor(myColor)
WinSetForeColor(itemColor)
selectColor = UiColorGetTableEntryIndex(
UIObjectSelectedForeground)
if itemColor == selectColor
...
参照
LstSetDrawFunction(), UIColorGetTableEntryIndex(), WinSetForeColor()|Palm OS Programmer's API Reference/59
